trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/scheduling/views.py

@@ -0,0 +1,2908 @@
+"""Views for the scheduling app."""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from collections.abc import Callable
+from datetime import date as _date
+from datetime import datetime as _datetime
+from datetime import timedelta
+from typing import Any, cast
+
+from django.conf import settings
+from django.core.cache import cache
+from django.db import models, transaction
+from django.shortcuts import get_object_or_404
+from django.utils import timezone
+from django.utils.dateparse import parse_date, parse_datetime
+from drf_spectacular.types import OpenApiTypes
+from drf_spectacular.utils import (
+    OpenApiExample,
+    OpenApiParameter,
+    OpenApiResponse,
+    PolymorphicProxySerializer,
+    extend_schema,
+    extend_schema_view,
+    inline_serializer,
+)
+from rest_framework import serializers, status
+from rest_framework import serializers as drf_serializers
+from rest_framework.decorators import action, api_view, permission_classes, throttle_classes
+from rest_framework.generics import ListAPIView
+from rest_framework.mixins import ListModelMixin, RetrieveModelMixin
+from rest_framework.pagination import PageNumberPagination
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.throttling import ScopedRateThrottle, SimpleRateThrottle
+from rest_framework.views import APIView
+from rest_framework.viewsets import GenericViewSet
+
+from trueppm_api.apps.access.permissions import (
+    IsProjectAdmin,
+    IsProjectMember,
+    IsProjectNotArchived,
+    IsProjectScheduler,
+    IsWorkspaceOperator,
+    McpReadableViewMixin,
+    McpScope,
+    assert_project_not_archived,
+    declare_scope_in_body,
+)
+from trueppm_api.apps.idempotency.mixins import IdempotencyMixin
+from trueppm_api.apps.projects.models import (
+    Dependency,
+    EstimationMode,
+    Project,
+    Task,
+    three_point_estimates_ordered,
+)
+from trueppm_api.apps.scheduling.calendars import compose_project_calendar
+from trueppm_api.apps.scheduling.finish_reading import (
+    finish_shift_days,
+    latest_finish,
+    lazy_finish_shift_days,
+    schedule_result_finish,
+    task_finish_at_day_start,
+)
+from trueppm_api.apps.scheduling.forecast_staleness import (
+    forecast_staleness_facts,
+    forecast_staleness_for_payload,
+    forecast_staleness_from_run,
+)
+from trueppm_api.apps.scheduling.mc_admission import admit_runs, busy_response, simulation_slot
+from trueppm_api.apps.scheduling.models import (
+    FailedTask,
+    FailedTaskStatus,
+    MonteCarloRun,
+    ProjectForecastSnapshot,
+    ScheduleRequestReason,
+    VelocitySuggestion,
+)
+from trueppm_api.apps.scheduling.risk_premium import (
+    build_risk_premium,
+    delta_vs_cpm_days,
+    risk_premium_for_forecast_payload,
+    risk_premium_from_values,
+)
+from trueppm_api.apps.scheduling.serializers import (
+    FailedTaskDropSerializer,
+    FailedTaskRequeueSerializer,
+    FailedTaskSerializer,
+    MonteCarloForecastSerializer,
+    MonteCarloRunSerializer,
+    MonteCarloWhatIfRequestSerializer,
+    MonteCarloWhatIfResponseSerializer,
+    ProjectForecastSnapshotSerializer,
+    ScheduleCpmDerivationSerializer,
+    ScheduleMonteCarloDerivationSerializer,
+    VelocitySuggestionSerializer,
+)
+from trueppm_api.apps.scheduling.services import (
+    build_sched_graph,
+    build_sched_tasks,
+    enqueue_recalculate,
+    forecast_diagnostic,
+    record_monte_carlo_run,
+    resolve_cpm_status_date,
+)
+from trueppm_api.apps.scheduling.telemetry import monte_carlo_span
+from trueppm_api.workflows.consumers.requeue_failed_task import WORKFLOW_NAME as REQUEUE_WORKFLOW
+from trueppm_api.workflows.services import start_workflow
+
+logger = logging.getLogger(__name__)
+
+# Version token in the Monte Carlo read-cache key. Bump it in the same commit as
+# any engine change that moves the percentiles for an unchanged project.
+#
+# The entry lives for 24 hours (ADR-0144, #1231) and nothing else invalidates it —
+# not a task edit, not a deploy, since the cache declares no KEY_PREFIX/VERSION and
+# the key carried only the project pk. So an engine correctness fix would keep
+# serving its own pre-fix numbers to `GET /monte-carlo/latest/`, to the MCP
+# forecast tool, and to the derivation ("why") endpoint for a full day after
+# rollout, from a payload with no signal that it is stale. Bumping the token
+# retires the old keyspace at deploy instead (#2833).
+#
+# This does NOT reach the persisted `MonteCarloRun` fallback that serves once the
+# TTL expires: those rows carry no engine-version column, so a project whose last
+# run predates a fix and is never re-run keeps reporting the old answer.
+#
+# v3 (#4204): percentiles are ordered by working-time finish and every delta is
+# measured in working time; a v2 entry's `delta_vs_cpm` diffed shown days.
+MC_LATEST_CACHE_VERSION = 3
+
+
+def mc_latest_cache_key(pk: object) -> str:
+    """Read-cache key for a project's latest Monte Carlo forecast.
+
+    One definition for the write, both reads, and the tests. Three duplicated
+    f-strings is how a version bump gets applied to two of them.
+    """
+    return f"mc_latest:v{MC_LATEST_CACHE_VERSION}:{pk}"
+
+
+def _current_plan_state(pk: uuid.UUID | str) -> tuple[int | None, _datetime | None]:
+    """The project's live plan version and last CPM recalc time (#3140).
+
+    Both terms the staleness discriminant compares a run against, in one narrow
+    ``values_list`` rather than loading the row: callers that already hold the project
+    read the two attributes directly, and this exists for the ones that do not.
+
+    ``(None, None)`` when the row is gone (a concurrent hard delete), which classifies
+    the forecast as ``unknown`` rather than inventing a comparison — see
+    :func:`~.forecast_staleness.classify_forecast_staleness`.
+    """
+    # `is_deleted=False` matches every sibling project fetch in this module. It changes
+    # nothing for the current caller, which already resolved the project through a
+    # filtered fetch — it stops the helper failing open on soft-delete for the next one.
+    row = (
+        Project.objects.filter(pk=pk, is_deleted=False)
+        .values_list("last_sync_version", "recalculated_at")
+        .first()
+    )
+    return row if row is not None else (None, None)
+
+
+# Upper bound on how many parked tasks a single bulk requeue/drop touches, so a
+# "drop all" / "requeue all" over a large filtered set cannot unbounded-load the
+# DB or storm the broker (ADR-0210 §4). Oldest-first slice, with a ``capped`` flag
+# in the response so the operator knows to repeat.
+#
+# Read straight off settings, not through `getattr(..., 500)`: the fallback made the
+# knob look tunable while no settings module bound it, so the docs' claim that
+# operators could raise it was false and the 500 always won (#2880). The binding now
+# lives in settings/base.py (env: TRUEPPM_FAILED_TASK_BULK_ACTION_MAX) and a missing
+# one is an AttributeError at import — loud, and impossible to ship silently.
+FAILED_TASK_BULK_ACTION_MAX: int = settings.FAILED_TASK_BULK_ACTION_MAX
+
+# Statuses an operator can act on: a task that is already dismissed or retried is
+# terminal and is skipped by bulk actions / rejected by single actions.
+_ACTIONABLE_FAILED_STATUSES = (FailedTaskStatus.DEAD, FailedTaskStatus.PENDING_RETRY)
+
+# Shared user-facing response details.
+_NOT_FOUND_DETAIL = "Not found."
+_DATE_RANGE_EXCEEDED_DETAIL = "Project schedule exceeds the representable date range."
+
+
+@extend_schema(
+    summary="Trigger a CPM recalculation for a project",
+    request=None,
+    responses={
+        202: OpenApiResponse(
+            response=inline_serializer(
+                name="ScheduleTriggerResult",
+                fields={"queued": serializers.BooleanField()},
+            ),
+            description='Recalculation queued via the outbox; body is {"queued": true}.',
+        ),
+        403: OpenApiResponse(
+            description=(
+                "Caller lacks the Resource Manager role on the project, or the project "
+                "is archived (archived plans are read-only, and a recalculation rewrites "
+                "every task's dates). Both causes answer the same status — branch on "
+                "`detail`, not on 403 alone."
+            )
+        ),
+        404: OpenApiResponse(description="Project not found."),
+    },
+)
+@declare_scope_in_body(
+    "@api_view function: the generated WrappedAPIView carries no project_url_kwarg, so "
+    "has_permission cannot scope this POST. The gate is the explicit "
+    "IsProjectScheduler().has_object_permission(request, None, project) call in the body."
+)
+@api_view(["POST"])
+@permission_classes([IsAuthenticated, IsProjectScheduler, IsProjectNotArchived])
+def trigger_schedule(request: Request, pk: str) -> Response:
+    """Manually trigger a CPM recalculation for a project.
+
+    Requires the requesting user to hold at least the Resource Manager role on the
+    project.  The request is written to the transactional outbox and dispatched
+    immediately if the broker is available; otherwise the Beat drain task picks
+    it up within 30 seconds.
+
+    Returns 404 if the project does not exist.
+    """
+    try:
+        project = Project.objects.get(pk=pk, is_deleted=False)
+    except Project.DoesNotExist:
+        return Response({"detail": _NOT_FOUND_DETAIL}, status=status.HTTP_404_NOT_FOUND)
+
+    # Permission check against the project object.
+    if not IsProjectScheduler().has_object_permission(request, None, project):  # type: ignore[arg-type]
+        return Response({"detail": "Permission denied."}, status=status.HTTP_403_FORBIDDEN)
+
+    # ...and the archived check, in the body for the same reason the membership check
+    # is (#3414). `IsProjectNotArchived` IS declared above, but this is an `@api_view`
+    # function: the generated `WrappedAPIView` carries no `project_url_kwarg`, the route
+    # spells the project `pk`, so `_project_pk_from_view` returns None and
+    # `has_permission` returns True — and DRF never calls `has_object_permission` on a
+    # function view. The declaration read as the gate while a manual recalculation ran
+    # happily against an archived plan, rewriting every task's dates.
+    assert_project_not_archived(project.pk)
+
+    # Defer until any outer transaction commits so the ScheduleRequest row is
+    # never visible to the drain before its parent write lands.
+    project_id = str(project.pk)
+    transaction.on_commit(
+        lambda: enqueue_recalculate(project_id, reason=ScheduleRequestReason.MANUAL)
+    )
+    return Response({"queued": True}, status=status.HTTP_202_ACCEPTED)
+
+
+# The premium derivation moved to `risk_premium` when the metric was promoted off
+# this payload onto the project (#2483). Aliased rather than reimplemented so the
+# forecast panel and the Overview card can never disagree about the same gap.
+_delta_vs_cpm_days = delta_vs_cpm_days
+
+
+def _date_delta_days(
+    later: _date | None,
+    earlier: _date | None,
+    *,
+    later_at_day_start: bool | None = None,
+    earlier_at_day_start: bool | None = None,
+    calendar_for: Callable[[], Any] | None = None,
+) -> int | None:
+    """Signed delta ``later - earlier`` of two shown finishes, in working time.
+
+    Positive means ``later`` lands after ``earlier`` (the forecast slipped). Shared
+    by the what-if and history endpoints so a run-to-run / current-to-whatif delta is
+    computed one way. Each date is read with its edge of the day (a Monte Carlo
+    percentile's ``*_at_day_start``, #4204), so a percentile whose shown day hops a
+    weekend with no working-time move is 0; an unknown reading (a run persisted
+    before #4204) follows :func:`.finish_reading.finish_shift_days`. Still reported
+    in calendar days. ``None`` if either date is missing.
+    """
+    if later is None or earlier is None:
+        return None
+    return lazy_finish_shift_days(
+        (earlier, earlier_at_day_start), (later, later_at_day_start), calendar_for
+    )
+
+
+def _mc_percentile_deltas(
+    later: Any, earlier: Any, calendar_for: Callable[[], Any] | None
+) -> dict[str, int | None]:
+    """``{p50, p80, p95}`` working-time deltas between two Monte Carlo results or runs."""
+    return {
+        q: _date_delta_days(
+            getattr(later, q),
+            getattr(earlier, q),
+            later_at_day_start=getattr(later, f"{q}_at_day_start", None),
+            earlier_at_day_start=getattr(earlier, f"{q}_at_day_start", None),
+            calendar_for=calendar_for,
+        )
+        for q in ("p50", "p80", "p95")
+    }
+
+
+def _mc_deltas_vs_cpm(
+    run: Any,
+    cpm_finish: _date | None,
+    cpm_finish_at_day_start: bool | None,
+    calendar_for: Callable[[], Any] | None,
+) -> dict[str, int | None]:
+    """``{p50, p80, p95}`` of ``run`` vs the CPM finish, in working time (#4204)."""
+    return {
+        q: _delta_vs_cpm_days(
+            getattr(run, q),
+            cpm_finish,
+            percentile_at_day_start=getattr(run, f"{q}_at_day_start", None),
+            cpm_finish_at_day_start=cpm_finish_at_day_start,
+            calendar_for=calendar_for,
+        )
+        for q in ("p50", "p80", "p95")
+    }
+
+
+def _mc_run_readings(run: Any) -> dict[str, bool | None]:
+    """The four edge-of-day readings of a persisted run, for a response payload."""
+    return {
+        f: getattr(run, f)
+        for f in (
+            "p50_at_day_start",
+            "p80_at_day_start",
+            "p95_at_day_start",
+            "cpm_finish_at_day_start",
+        )
+    }
+
+
+def _cpm_finish_delta_days(earlier: Any, later: Any, calendar: Any) -> int | None:
+    """Signed shift of ``ScheduleResult.project_finish`` between two CPM passes, in working time.
+
+    Unlike :func:`_date_delta_days`, this reads each finish with its edge of the
+    day, so the shown day hopping a weekend with no working-time move is 0
+    (:mod:`.finish_reading`, #4178). Still reported in calendar days.
+    """
+    before = schedule_result_finish(earlier)
+    after = schedule_result_finish(later)
+    if before is None or after is None:
+        return None
+    return finish_shift_days(before, after, calendar)
+
+
+def _confidence_curve(histogram: list[dict[str, object]], total: int) -> list[dict[str, object]]:
+    """Cumulative P(finish ≤ date) S-curve derived from the histogram buckets.
+
+    ``histogram`` is the already-binned ``[{date, count}]`` list in ascending date
+    order; ``total`` is the number of simulated runs. Returns one ``{date, pct}``
+    point per bucket carrying the cumulative share of runs that finished on or
+    before that bucket — the same value ``MonteCarloDetailPanel`` previously
+    accumulated in the browser (#987). Bounded to the bucket count (≤30 points).
+    """
+    if total <= 0:
+        return []
+    cumulative = 0
+    curve: list[dict[str, object]] = []
+    for bucket in histogram:
+        cumulative += cast(int, bucket["count"])
+        curve.append({"date": bucket["date"], "pct": round(cumulative / total * 100, 1)})
+    return curve
+
+
+def _distribution_for_persist(payload: dict[str, Any]) -> dict[str, Any]:
+    """Shrink the distribution payload to fit MC_DISTRIBUTION_MAX_BYTES for storage (#1231).
+
+    Takes the ``{histogram_buckets, confidence_curve, sensitivity}`` slice of the
+    full result and, if its serialized size exceeds the cap, down-samples the
+    histogram (keeps every Nth bucket, always retaining the first and last so the
+    spread endpoints survive) until it fits. The confidence curve is recomputed
+    from the thinned buckets so the two stay consistent; sensitivity is left intact
+    (it is bounded by the task count, not the bucket count).
+
+    Returns a NEW dict — the caller's full ``result_dict`` (and the cache copy it
+    feeds) is never mutated, so the live view still serves the full-resolution
+    histogram while the persisted row is bounded against a pathological run.
+    """
+    dist = {
+        "histogram_buckets": payload.get("histogram_buckets", []),
+        "confidence_curve": payload.get("confidence_curve", []),
+        "sensitivity": payload.get("sensitivity", []),
+    }
+    cap = settings.MC_DISTRIBUTION_MAX_BYTES
+    if len(json.dumps(dist).encode()) <= cap:
+        return dist
+
+    buckets: list[dict[str, object]] = list(dist["histogram_buckets"])
+    total = sum(cast(int, b.get("count", 0)) for b in buckets)
+    # Increase the stride until the serialized payload fits. Always keep the first
+    # and last bucket so the distribution's min/max dates are preserved.
+    stride = 2
+    while len(json.dumps(dist).encode()) > cap and stride <= max(len(buckets), 2):
+        thinned = [b for i, b in enumerate(buckets) if i % stride == 0]
+        if buckets and buckets[-1] not in thinned:
+            thinned.append(buckets[-1])
+        dist = {
+            "histogram_buckets": thinned,
+            "confidence_curve": _confidence_curve(thinned, total),
+            "sensitivity": dist["sensitivity"],
+        }
+        stride += 1
+    return dist
+
+
+def _build_sched_deps(project_pk: str, included_ids: set[str]) -> list[Any]:
+    """Convert a project's DB dependencies to scheduler ``Dependency`` inputs.
+
+    Drops any edge whose predecessor or successor is absent from ``included_ids``:
+    cross-project dependencies and edges to non-committed (BACKLOG) tasks both dangle
+    and would make the engine reject the network as referencing an unknown task.
+    Mirrors the CPM guard in scheduling.tasks (ADR-0090) — a single-project run
+    simulates only this project's committed tasks.
+
+    Reads through ``Dependency.live``: a soft-deleted edge is a constraint the
+    user removed, and forecasting against it reports a finish the plan no longer
+    implies (#3532).
+    """
+    from trueppm_scheduler.models import Dependency as SchedDependency
+    from trueppm_scheduler.models import DependencyType
+
+    db_deps = list(
+        Dependency.live.filter(predecessor__project_id=project_pk).select_related(
+            "predecessor", "successor"
+        )
+    )
+    return [
+        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
+    ]
+
+
+def _mc_histogram(dist: list[_date]) -> list[dict[str, object]]:
+    """Bin a Monte Carlo finish-date distribution into ≤30 ascending ``{date, count}``
+    buckets.
+
+    ``dist`` is the engine's sorted finish-date sample (earliest first). Returns an
+    empty list for an empty distribution. The midpoint date of each bucket is used as
+    its label so the histogram is symmetric around the sampled span.
+    """
+    if not dist:
+        return []
+    min_ord = dist[0].toordinal()
+    max_ord = dist[-1].toordinal()
+    span = max(max_ord - min_ord, 1)
+    n_buckets = min(30, len(dist))
+    bucket_size = span / n_buckets
+    bucket_counts: dict[int, int] = {}
+    for d in dist:
+        idx = min(int((d.toordinal() - min_ord) / bucket_size), n_buckets - 1)
+        bucket_counts[idx] = bucket_counts.get(idx, 0) + 1
+    return [
+        {
+            "date": _date.fromordinal(min_ord + int((i + 0.5) * bucket_size)).isoformat(),
+            "count": bucket_counts.get(i, 0),
+        }
+        for i in range(n_buckets)
+    ]
+
+
+def _persist_mc_run_if_authorized(
+    request: Request,
+    project: Project,
+    *,
+    mc_result: Any,
+    n_simulations: int,
+    cpm_finish: _date | None,
+    task_count: int,
+    result_dict: dict[str, Any],
+    status_date: _date | None,
+    plan_version: int | None,
+    cpm_finish_at_day_start: bool | None = None,
+) -> None:
+    """Persist an author-attributed ``MonteCarloRun`` drift row for Scheduler+ callers.
+
+    The forecast *read* is intentionally open to any project member (a Viewer may pull
+    the band), but the persisted run is a different act: it attributes drift to its
+    author and grows the retained-run set (#1502). Gating the read at Member and the
+    write at Scheduler stops a Viewer/Member from spamming ``run_monte_carlo`` to
+    inflate history and pollute drift attribution over a schedule they cannot own. The
+    ``mc_latest`` cache is a per-project read cache, not per-user history, so it stays
+    refreshed for every caller — only the attributed row is gated here.
+
+    Best-effort: a write failure inside the service is logged and swallowed by
+    ``record_monte_carlo_run``; ``result_dict`` gains ``run_id`` only when persistence
+    succeeded. Mutates ``result_dict`` in place.
+    """
+    from trueppm_api.apps.access.models import Role
+    from trueppm_api.apps.access.permissions import _membership_role
+
+    # Pass project.pk (canonical UUID), not the raw URL string, so this reuses the
+    # per-request role cache the earlier object-permission check already warmed under
+    # the same key — no second membership query.
+    role = _membership_role(request, project.pk)
+    if role is None or role < Role.SCHEDULER:
+        return
+
+    # Persist the same distribution slice the cache holds, but bounded to
+    # MC_DISTRIBUTION_MAX_BYTES via down-sampling (#1231) — the cache copy is
+    # full-resolution and untouched. Stored so the histogram + tornado survive cache
+    # expiry and a past run stays viewable.
+    distribution = _distribution_for_persist(result_dict)
+    run = record_monte_carlo_run(
+        str(project.pk),
+        p50=mc_result.p50,
+        p80=mc_result.p80,
+        p95=mc_result.p95,
+        n_simulations=n_simulations,
+        cpm_finish=cpm_finish,
+        task_count=task_count,
+        user=request.user,
+        distribution=distribution,
+        # Store the reason the run is (or is not) flat alongside it, so a later
+        # read from history can still tell "no estimates anywhere" apart from
+        # "estimates exist, variance is low" — the distinction the added-time
+        # metric is built on (#2483).
+        diagnostic=result_dict.get("forecast_diagnostic"),
+        # The data date actually fed to the engine for this run (ADR-0132's
+        # never-recorded substitution, #2638) — same value already echoed on
+        # result_dict below, so the persisted row and the response agree.
+        status_date=status_date,
+        # The plan version the run was computed against (#3140) — the same value
+        # already on result_dict, so the persisted row and the cache entry give the
+        # same answer once the TTL expires and the read falls back to history.
+        plan_version=plan_version,
+        # Which edge of its shown day each finish is (#4204), so a later history or
+        # `latest` read measures its deltas in working time too.
+        readings={
+            "p50_at_day_start": mc_result.p50_at_day_start,
+            "p80_at_day_start": mc_result.p80_at_day_start,
+            "p95_at_day_start": mc_result.p95_at_day_start,
+            "cpm_finish_at_day_start": cpm_finish_at_day_start,
+        },
+    )
+    if run is not None:
+        result_dict["run_id"] = str(run.id)
+
+
+def _mc_lag_delta_kwargs() -> dict[str, int]:
+    """Request-path ``monte_carlo()`` kwargs bounding the lag-delta table (#4129).
+
+    Empty when ``MC_LAG_DELTA_CELL_CAP`` is ``None`` so the library default applies.
+    """
+    cap = getattr(settings, "MC_LAG_DELTA_CELL_CAP", None)
+    return {} if cap is None else {"max_lag_delta_cells": cap}
+
+
+class MonteCarloRunThrottle(ScopedRateThrottle):
+    """Caps synchronous Monte Carlo runs per member (#1552) to bound DoS.
+
+    ``run_monte_carlo`` executes an expensive simulation inline in the request
+    cycle, gated only by project membership. Scoped per-user via ``monte_carlo``
+    (10/min) so no single account can loop the endpoint to exhaust CPU, while a
+    human tuning estimates and re-running the forecast stays well under the cap.
+
+    ``ScopedRateThrottle`` normally reads its scope from ``view.throttle_scope``,
+    but ``run_monte_carlo`` is a function-based ``@api_view`` that cannot carry
+    that attribute, so the scope is bound from this class instead. The cache key
+    is still per-user + scope (``get_cache_key`` is inherited unchanged).
+    """
+
+    scope = "monte_carlo"
+
+    def allow_request(self, request: Request, view: APIView) -> bool:
+        # Bind the fixed scope from the class rather than off the view (an
+        # @api_view FBV has no throttle_scope), then run the grandparent's
+        # sliding-window check directly. We deliberately skip
+        # ScopedRateThrottle.allow_request (it re-reads view.throttle_scope,
+        # absent on the FBV) by calling SimpleRateThrottle explicitly instead of
+        # via super() — same resolution, but honest about the intentional skip
+        # and it doesn't trip CodeQL's "super() first arg" reliability rule.
+        self.rate = self.get_rate()
+        self.num_requests, self.duration = self.parse_rate(self.rate)
+        return SimpleRateThrottle.allow_request(self, request, view)
+
+
+@extend_schema(
+    request=OpenApiTypes.OBJECT,
+    responses={
+        200: OpenApiResponse(
+            response=MonteCarloForecastSerializer,
+            description=(
+                "Monte Carlo simulation result. Includes the engine result fields "
+                "(P50/P80/P95 finish dates, mean, std dev, etc.) plus "
+                "cpm_finish (deterministic CPM project finish, ISO 8601 or null), "
+                "p50_at_day_start/p80_at_day_start/p95_at_day_start and "
+                "cpm_finish_at_day_start (which edge of its shown day each finish is — true = "
+                "the start of the day, a start-of-day milestone finish; #4204), "
+                "delta_vs_cpm ({p50,p80,p95} signed calendar-day premium vs CPM, measured "
+                "in working time: the start of a Monday vs the end of the Friday before it "
+                "is 0), "
+                "confidence_curve ([{date, pct}] cumulative finish-by-date S-curve), "
+                "histogram_buckets ([{date, count}]), sensitivity ([{task_id, index}] "
+                "duration tornado — tasks that move the finish most, index 0..1, "
+                "ADR-0140), forecast_diagnostic ({deterministic, reason, tasks_total, "
+                "tasks_with_variance, tasks_pending_approval, agile_tasks_without_velocity, "
+                "tasks_estimates_below_plan} "
+                "— explains a flat forecast; reason is null when a real band exists), "
+                "last_run_at (ISO 8601), status_date (the data date this run was "
+                "actually computed against — project.status_date or today when unset, "
+                "ADR-0132/#2638), and the risk_premium_* family (ADR-0698): "
+                "risk_premium_state (not_run|unmeasurable|stale|zero|premium|negative — "
+                "the discriminant every client renders from, never null), "
+                "risk_premium_days, risk_premium_ratio, risk_premium_band (always null "
+                "until #2299), risk_premium_as_of, risk_premium_reason, "
+                "risk_premium_cpm_finish, risk_premium_p80. Derived at response time, "
+                "never cached, so the ratio never describes a remaining duration that "
+                "has since elapsed. Plus the forecast-staleness family (#3140): "
+                "forecast_staleness (current|project_changed|aged|unknown — the "
+                "discriminant every client renders from, never null; only `current` "
+                "means the forecast still describes the plan, and clients keep the "
+                "recompute action reachable on the other three), plan_version (the "
+                "project's sync version this run was computed against; null for runs "
+                "recorded before #3140, which classify as `unknown`, never `current`), "
+                "and plan_version_current (that version as of this response). "
+                "`project_changed` is deliberately not named `plan_changed`: the "
+                "underlying counter advances on ANY write in the project, so a "
+                "description or label edit raises it without moving a date. It is a "
+                "sound trigger for offering a recompute and NOT evidence that a "
+                "schedule value changed — do not narrate it as one."
+            ),
+        ),
+        400: OpenApiResponse(
+            response=OpenApiTypes.OBJECT,
+            description=(
+                "Cyclic dependency, invalid input, or out-of-range project span; or "
+                "an explicit n_simulations whose runs x tasks product exceeds "
+                "MC_CELL_CAP (#2839) — body {error: simulation_cell_cap_exceeded, "
+                "message, max_runs, task_count}, where max_runs is the largest count "
+                "this project admits. An omitted n_simulations is never refused for "
+                "size: it runs max_runs iterations and the 200 body's `runs` reports "
+                "the count actually simulated."
+            ),
+            examples=[
+                OpenApiExample(
+                    "simulation_cell_cap_exceeded",
+                    value={
+                        "error": "simulation_cell_cap_exceeded",
+                        "message": "1000 simulation runs over 5000 tasks exceeds ...",
+                        "max_runs": 500,
+                        "task_count": 5000,
+                    },
+                ),
+            ],
+        ),
+        402: OpenApiResponse(
+            response=OpenApiTypes.OBJECT,
+            description=(
+                "OSS simulation cap exceeded (n_simulations above MC_SIMULATION_CAP "
+                "or too many tasks)."
+            ),
+            examples=[
+                OpenApiExample(
+                    "simulation_cap_exceeded",
+                    value={
+                        "error": "simulation_cap_exceeded",
+                        "tier": "team",
+                        "message": "Simulation count exceeds the community-edition cap.",
+                    },
+                ),
+            ],
+        ),
+        403: OpenApiResponse(
+            response=OpenApiTypes.OBJECT,
+            description=(
+                "Caller is not a member of the project, or the project is archived — a "
+                "run refreshes the project's forecast cache and, for Scheduler+, "
+                "appends a drift-history row, so it is a write."
+            ),
+        ),
+        404: OpenApiResponse(
+            response=OpenApiTypes.OBJECT,
+            description="Project does not exist.",
+        ),
+        503: OpenApiResponse(
+            response=OpenApiTypes.OBJECT,
+            description=(
+                "This API process is already running MC_MAX_CONCURRENT simulations "
+                "and none finished within the wait window (#2839). Body {error: "
+                "simulation_busy, message}; retry after the Retry-After header."
+            ),
+        ),
+    },
+)
+@declare_scope_in_body(
+    "@api_view function: the generated WrappedAPIView carries no project_url_kwarg, so "
+    "has_permission cannot scope this POST. The gate is the explicit "
+    "IsProjectMember().has_object_permission(request, None, project) call in the body."
+)
+@api_view(["POST"])
+@permission_classes([IsAuthenticated, IsProjectMember, IsProjectNotArchived])
+@throttle_classes([MonteCarloRunThrottle])
+def run_monte_carlo(request: Request, pk: str) -> Response:
+    """Run a Monte Carlo probabilistic schedule simulation synchronously.
+
+    Monte Carlo is fast (< 100 ms vectorised) so this runs in the request/
+    response cycle rather than via Celery; the result is returned directly. The
+    per-project ``mc_latest`` read cache is refreshed for every caller, but a
+    persisted, author-attributed drift-history row (MonteCarloRun) is written
+    only for Scheduler+ — the forecast read is Member-level, its record is not
+    (#1502). Requests are rate-limited per user via the ``monte_carlo`` scope.
+
+    Synchronous-by-design decision (#1203): keeping this inline is only safe
+    because *every* multiplicative cost factor the run depends on is now bounded
+    by the engine — tasks (MC_TASK_CAP), simulation runs (MC_SIMULATION_CAP),
+    raw dependency edges (MAX_DEPENDENCIES), expanded edges (MAX_EXPANDED_EDGES),
+    the distinct-lag delta arrays (MC_LAG_DELTA_CELL_CAP, 5M int32 cells = ~20 MB —
+    the library's 50M-cell MAX_LAG_DELTA_CELLS is a batch-caller default), and the
+    velocity horizon (MAX_VELOCITY_SPRINTS) — and #1201 vectorised the previously O(edges x span)
+    per-edge lag precompute. With the input space bounded and the hot path
+    vectorised, the worst-case wall time stays within the request budget, so
+    moving to a Celery job (extra latency, result polling, a new failure surface)
+    would add cost without removing a real risk. The argument is about memory as
+    well as wall time (#4129): the lag-delta table scales with distinct lags x
+    span, not with runs, and was the one factor no request cap bounded (a project
+    inside every other cap peaked near 630 MB), so it is now capped at
+    MC_LAG_DELTA_CELL_CAP and the table stays at ~20 MB per simulation.
+    Concurrent-request admission is bounded per process by MC_MAX_CONCURRENT
+    (#2839, below). A project that breaches the edge
+    cap is rejected as InvalidScheduleInput (a ValueError) and surfaces below as a
+    clean 400 rather than a stalled worker.
+
+    That argument depends on cap *order*, which #3527 had to preserve deliberately.
+    Summary expansion moved onto this path, and it walks the edge list — so it now
+    runs behind ``build_sched_graph``'s own O(1) ``MAX_DEPENDENCIES`` length check
+    rather than waiting for ``_validate_project``, which the engine does not reach
+    until ``monte_carlo()`` is already called. Without that, the expensive per-edge
+    step would run ahead of the cheap guard that is supposed to bound it.
+
+    The per-dimension caps still let ``runs x tasks`` reach 5M cells (~234 MB traced
+    per simulation), so admission also caps that product (MC_CELL_CAP) and the
+    simulations one process runs at once (MC_MAX_CONCURRENT) — see
+    ``mc_admission`` (#2839).
+
+    Request body (all optional):
+        n_simulations (int): Number of simulation runs. Defaults to the largest
+            count this project's size admits — settings.MC_SIMULATION_CAP, or
+            fewer under MC_CELL_CAP on a large project; the response's ``runs``
+            reports the count simulated. An explicit value is honored exactly or
+            refused; it must not exceed either cap.
+
+    Returns 200 on success, 402 if the OSS simulation cap is exceeded,
+    400 if the schedule input is invalid (e.g. the dependency-edge cap is
+    breached) or an explicit n_simulations breaches MC_CELL_CAP, 503 if the
+    process has no free simulation slot, 404 if the project does not exist,
+    403 if the caller lacks read access.
+    """
+    from trueppm_scheduler.engine import CyclicDependencyError, SimulationCapExceeded, monte_carlo
+    from trueppm_scheduler.models import Project as SchedProject
+
+    try:
+        project = (
+            Project.objects.select_related("calendar", "program__calendar")
+            # calendar__exceptions + calendar_layers__calendar__exceptions:
+            # compose_project_calendar reads the base calendar's exceptions (#1491)
+            # AND every applied overlay's (#906); prefetch both to avoid an N+1.
+            .prefetch_related(
+                "tasks",
+                "calendar__exceptions",
+                "calendar_layers__calendar__exceptions",
+                # ADR-0441: the resolver reads the program calendar's exceptions when a
+                # project inherits its base calendar from the program.
+                "program__calendar__exceptions",
+            )
+            .get(pk=pk, is_deleted=False)
+        )
+    except Project.DoesNotExist:
+        return Response({"detail": _NOT_FOUND_DETAIL}, status=status.HTTP_404_NOT_FOUND)
+
+    if not IsProjectMember().has_object_permission(request, None, project):  # type: ignore[arg-type]
+        return Response({"detail": "Permission denied."}, status=status.HTTP_403_FORBIDDEN)
+
+    # Same #3414 shape as `trigger_schedule`: the declared `IsProjectNotArchived` cannot
+    # fire on an `@api_view` function whose route spells the project `pk`. A run is not a
+    # pure read — it refreshes the project's `mc_latest` cache and, for Scheduler+,
+    # appends an author-attributed `MonteCarloRun` row, so an archived plan's forecast
+    # history could be extended indefinitely after it was frozen.
+    assert_project_not_archived(project.pk)
+
+    cap: int | None = settings.MC_SIMULATION_CAP
+    # A JSON `null` (or absent) body parses to request.data == None; the body is
+    # documented as fully optional, so fall back to the default rather than
+    # letting None.get(...) raise AttributeError → 500 (#2310).
+    body = request.data if isinstance(request.data, dict) else {}
+    # Absent means "the admissible maximum for this project's size" (#2839), which
+    # `admit_runs` resolves once the network size is known; an explicit value is
+    # honored exactly or refused, never silently shrunk.
+    n_explicit = "n_simulations" in body
+    raw_n = body.get("n_simulations", cap or 1_000)
+    # int() coerces without raising on a JSON bool (bool is an int subtype) or a
+    # JSON float (silently truncated) — neither is the documented integer
+    # contract, so reject both before the cast rather than trusting int() to
+    # catch them (#4208). Digit strings ("100") stay allowed for callers that
+    # send n_simulations as text.
+    if isinstance(raw_n, bool) or not isinstance(raw_n, (int, str)):
+        return Response(
+            {"detail": "n_simulations must be an integer."},
+            status=status.HTTP_400_BAD_REQUEST,
+        )
+    try:
+        n_simulations: int = int(raw_n)
+    except (TypeError, ValueError):
+        return Response(
+            {"detail": "n_simulations must be an integer."},
+            status=status.HTTP_400_BAD_REQUEST,
+        )
+    if n_simulations < 1:
+        return Response(
+            {"detail": "n_simulations must be a positive integer."},
+            status=status.HTTP_400_BAD_REQUEST,
+        )
+
+    # The plan version this run is about to be computed against (#3140) — the
+    # project's ADR-0686 sync sequence, already on the instance loaded above, so
+    # this costs nothing. Read HERE, before the committed task set is loaded
+    # below, and the ordering is the correctness property: a write that lands
+    # between this line and the query leaves the run recorded against the older
+    # version and therefore reading stale. Capturing it afterwards would claim
+    # the run covered a write it never saw — false-fresh, the one direction that
+    # loses the user the Rerun action.
+    plan_version = project.last_sync_version
+
+    # Shared converter (#1491): includes the calendar's CalendarException
+    # holiday/shutdown ranges, which the previous inline construction dropped —
+    # so Monte Carlo silently scheduled straight through configured holidays.
+    sched_calendar = compose_project_calendar(project)
+
+    # Monte Carlo simulates committed delivery only — BACKLOG cards are not
+    # part of the forecast. ADR-0057 / Task.committed.
+    # select_related("sprint"): build_sched_tasks reads sprint.start_date for the
+    # ADR-0168 sprint-window floor; load it with the task to avoid an N+1.
+    db_tasks = list(Task.committed.filter(project=project).select_related("sprint"))
+
+    # Shared converter (ADR-0132): the deterministic CPM pass and Monte Carlo
+    # build their scheduler input through one function, so a field can never reach
+    # one engine and not the other — the drift that caused #1185 (MC had silently
+    # dropped planned_start). build_sched_tasks honors the planned_start floor for
+    # every task (the #1185 fix, now centralized) and withholds pending three-point
+    # estimates in SUGGEST_APPROVE mode.
+    suggest_approve = project.estimation_mode == EstimationMode.SUGGEST_APPROVE
+    sched_tasks = build_sched_tasks(db_tasks, suggest_approve=suggest_approve)
+
+    included_ids = {str(t.id) for t in db_tasks}
+    sched_deps = _build_sched_deps(pk, included_ids)
+
+    # Shared graph shaping (#3527): summary (phase) rows are grouping nodes, not
+    # schedulable work (ADR-0105), so they are stripped and their edges fanned down
+    # to leaves before the simulation — exactly as the deterministic CPM pass does.
+    # Sharing only build_sched_tasks was not enough: every phase used to enter the
+    # simulation as a never-started, unconstrained block floored at the data date,
+    # and the longest one became the simulated finish. That made the forecast flat,
+    # unrelated to the network, and pushed *further out* by recording real progress.
+    # Inside a try, like every other engine call here: build_sched_graph raises
+    # InvalidScheduleInput (a ValueError) for a Start-to-Start/Start-to-Finish link
+    # from a summary, a breached edge cap, or a malformed WBS. The project exception
+    # handler only reclassifies malformed-UUID ValueErrors, so an unguarded raise
+    # would be a 500 — and this endpoint promises a clean 400 for exactly these.
+    try:
+        graph = build_sched_graph(db_tasks, sched_tasks, sched_deps)
+    except (CyclicDependencyError, ValueError) as exc:
+        # codeql[py/stack-trace-exposure] -- intentional user-facing validation message
+        return Response({"detail": str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+
+    # Agile-aware Monte Carlo (#411, ADR-0065/0106): feed the team's completed-sprint
+    # throughput to the engine so SCRUM/story-point tasks sample sprints-to-completion
+    # from real velocity variance. Without this the engine's velocity path can never
+    # fire — every story falls back to its deterministic placeholder duration (1 day),
+    # so an all-agile project (e.g. a board-driven program project) forecasts a single
+    # flat date with no uncertainty. ([], None) when there is no velocity signal, which
+    # leaves a waterfall/PERT project's forecast unchanged.
+    from trueppm_api.apps.projects.services import scheduler_velocity_inputs
+
+    velocity_samples, sprint_length_days = scheduler_velocity_inputs(
+        project.pk, sched_calendar.working_days
+    )
+
+    # Data date for the forecast (ADR-0132): the project's explicit status date, or
+    # today when unset — so Monte Carlo never schedules remaining work in the past
+    # and pins completed work to its actuals. Named so the resolved value can be
+    # persisted on the run and echoed in the response (#2638) — previously this
+    # substitution happened inline and was never recorded anywhere.
+    mc_status_date = project.status_date or timezone.localdate()
+
+    # runs x n_tasks admission (#2839): the per-dimension caps let the product reach
+    # 5M cells (~234 MB traced per simulation); MC_CELL_CAP bounds the product.
+    admission = admit_runs(len(graph.tasks), n_simulations if n_explicit else None)
+    if admission.refusal is not None:
+        return admission.refusal
+    n_simulations = admission.runs
+
+    sched_project = SchedProject(
+        id=str(project.pk),
+        name=project.name,
+        start_date=project.start_date,
+        tasks=graph.tasks,
+        dependencies=graph.dependencies,
+        calendar=sched_calendar,
+        status_date=mc_status_date,
+        velocity_samples=velocity_samples or None,
+        sprint_length_days=sprint_length_days,
+    )
+
+    try:
+        # Manual Monte Carlo span (#709): times the simulation inline in the request
+        # cycle and records the run count; a no-op span unless OTel is configured.
+        # The slot bounds how many simulations this process runs at once (#2839).
+        with simulation_slot() as admitted:
+            if not admitted:
+                return busy_response()
+            with monte_carlo_span(pk, simulation_count=n_simulations):
+                mc_result = monte_carlo(
+                    sched_project,
+                    runs=n_simulations,
+                    max_runs=cap,
+                    max_tasks=settings.MC_TASK_CAP,
+                    **_mc_lag_delta_kwargs(),
+                )
+    except SimulationCapExceeded as exc:
+        return Response(
+            # codeql[py/stack-trace-exposure] -- intentional user-facing validation message
+            {
+                "error": "simulation_cap_exceeded",
+                "tier": "team",
+                "message": str(exc),
+            },
+            status=status.HTTP_402_PAYMENT_REQUIRED,
+        )
+    except (CyclicDependencyError, ValueError) as exc:
+        # codeql[py/stack-trace-exposure] -- intentional user-facing validation message
+        return Response({"detail": str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+    except OverflowError:
+        # Defense in depth: the engine's MAX_PROJECT_SPAN_DAYS guard makes this
+        # unreachable for any realistic start date, but never let a date-range
+        # overflow surface as a 500 (OverflowError is not a ValueError).
+        return Response(
+            {"detail": _DATE_RANGE_EXCEEDED_DETAIL},
+            status=status.HTTP_400_BAD_REQUEST,
+        )
+
+    dist = mc_result.distribution
+    histogram = _mc_histogram(dist)
+
+    # The deterministic CPM spine is the max early_finish of the committed tasks
+    # already loaded above — no extra query. It anchors delta_vs_cpm (the risk
+    # premium each percentile adds over the deterministic finish) and is itself
+    # the project's deterministic schedule finish (#987 — single source, no
+    # duplicate project field). Computed before result_dict so the cached latest
+    # payload carries it.
+    cpm_finish = max(
+        (t.early_finish for t in db_tasks if t.early_finish is not None),
+        default=None,
+    )
+    # Which edge of that day the CPM finish is (#4204) — the same reading rule as
+    # every other project finish (#4178), from the rows already in memory. A
+    # percentile is compared with it in working time, so a start-of-Monday
+    # milestone finish is not three days of risk premium over the end of Friday.
+    cpm_reading = latest_finish(
+        (t.early_finish, task_finish_at_day_start(t), t.wbs_path) for t in db_tasks
+    )
+    cpm_finish_at_day_start = cpm_reading[1] if cpm_reading is not None else None
+
+    # `last_run_at` lets the frontend surface a "Last run: 2h ago" freshness
+    # signal and decide whether to nudge a rerun (#335). Captured at cache-write
+    # time so it always tracks the most recent successful simulation, never the
+    # cache read. Held as a datetime as well as an ISO string because the risk
+    # premium ages the run against it (ADR-0698).
+    run_at = timezone.now()
+    result_dict = {
+        **mc_result.to_dict(),
+        "cpm_finish": cpm_finish.isoformat() if cpm_finish else None,
+        "cpm_finish_at_day_start": cpm_finish_at_day_start,
+        "delta_vs_cpm": _mc_deltas_vs_cpm(
+            mc_result, cpm_finish, cpm_finish_at_day_start, lambda: sched_calendar
+        ),
+        "confidence_curve": _confidence_curve(histogram, len(dist)),
+        "histogram_buckets": histogram,
+        # Why the forecast has (or lacks) a band, so the UI can explain a flat
+        # result instead of presenting a misleadingly precise single date (#1340).
+        # Computed from the already-loaded committed task set + estimation mode +
+        # velocity signal — no extra query.
+        "forecast_diagnostic": forecast_diagnostic(
+            # The LEAF rows, not every committed row (#3527): the diagnostic explains
+            # what the simulation did, and a summary is not in the simulated network.
+            # Counting phases made `tasks_total` overstate the run and let a
+            # fully-complete project miss `all_complete` — a summary's stored
+            # percent_complete is 0, so every phase read as incomplete work.
+            graph.leaf_db_tasks,
+            suggest_approve=suggest_approve,
+            has_velocity_signal=bool(velocity_samples),
+            deterministic=(mc_result.p50 == mc_result.p80 == mc_result.p95),
+        ),
+        "last_run_at": run_at.isoformat(),
+        # The plan version this run was computed against (#3140), captured above
+        # before the task set was read. Carried on the cache entry — not only on
+        # the persisted row below — because a run triggered by a *Member* refreshes
+        # the cache but persists no attributed row (#1502), so for those runs the
+        # cache entry is the only place this observation exists. Unlike the
+        # risk-premium family, this is not derivable at read time from anything.
+        "plan_version": plan_version,
+        # The data date this run was actually computed against (ADR-0132, #2638):
+        # the project's explicit status_date, or today when unset. Carried on the
+        # cache entry too (it is part of ``result_dict``) so a cached read states
+        # the same provenance as a fresh run, and on the persisted MonteCarloRun
+        # row below so history stays re-derivable after the fact.
+        "status_date": mc_status_date.isoformat(),
+    }
+    cache.set(mc_latest_cache_key(pk), result_dict, timeout=86400)
+
+    # Persist a forecast-drift history row (ADR-0175, #961) only for Scheduler+
+    # callers; the read is Member-level but the attributed write is not (#1502).
+    _persist_mc_run_if_authorized(
+        request,
+        project,
+        mc_result=mc_result,
+        n_simulations=n_simulations,
+        cpm_finish=cpm_finish,
+        # The size of the network actually simulated (#3527) — summaries are
+        # stripped before the run, so counting them here would describe an input
+        # the engine never saw.
+        task_count=len(graph.tasks),
+        result_dict=result_dict,
+        status_date=mc_status_date,
+        plan_version=plan_version,
+        cpm_finish_at_day_start=cpm_finish_at_day_start,
+    )
+    # Added time (#2531, ADR-0698) rides the response but NOT the cache entry above.
+    # Two of its terms depend on when the response is built rather than when the run
+    # happened: `ratio` divides by the duration remaining as of today, which collapses
+    # to null once the CPM finish passes, and `state` flips to `stale` with age. A
+    # premium frozen at cache-write would keep reporting a share of a remainder that
+    # has since elapsed, so it is derived per response instead.
+    current_plan_version, current_recalculated_at = _current_plan_state(pk)
+    return Response(
+        {
+            **result_dict,
+            **risk_premium_from_values(
+                p80=mc_result.p80,
+                cpm_finish=cpm_finish,
+                taken_at=run_at,
+                diagnostic=result_dict["forecast_diagnostic"],
+                today=timezone.localdate(),
+                p80_at_day_start=mc_result.p80_at_day_start,
+                cpm_finish_at_day_start=cpm_finish_at_day_start,
+                calendar_for=lambda: sched_calendar,
+            ),
+            # Staleness is re-read rather than assumed `current` (#3140). The project's
+            # version is fetched again here because a synced write can land *during* the
+            # simulation, and that run genuinely does not cover it — telling the user so
+            # immediately is the whole point of the discriminant. One indexed pk read on
+            # an endpoint that just ran a Monte Carlo simulation is not a cost worth
+            # trading a false `current` for.
+            **forecast_staleness_facts(
+                plan_version=plan_version,
+                plan_version_current=current_plan_version,
+                taken_at=run_at,
+                recalculated_at=current_recalculated_at,
+                today=timezone.localdate(),
+            ),
+        }
+    )
+
+
+class MonteCarloLatestView(McpReadableViewMixin, APIView):
+    """Return the cached result of the most recent MC simulation for this project.
+
+    Returns 200 with the full result dict if a cached result exists, or 404 if
+    no simulation has been run since the 24-hour cache TTL last expired.
+
+    Permission: Member (any role ≥ Viewer).
+    """
+
+    # ADR-0678 (#2482): projects/<pk>/monte-carlo/latest/
+    mcp_scope = McpScope.PATH
+
+    mcp_compute_heavy = True  # part of the F4 compute-heavy MCP tool set (#1808)
+    # Route is `projects/<pk>/…`, so `pk` names the PROJECT here (#2745). Without
+    # this the project-scoped classes below resolve nothing and `has_permission`
+    # returns True for everyone — the gate reads as live in review and enforces
+    # nothing. Declared per view because `pk` means something else on other routes.
+    project_url_kwarg = "pk"
+    permission_classes = [IsAuthenticated, IsProjectMember, IsProjectNotArchived]
+
+    @extend_schema(
+        summary="Latest cached Monte Carlo forecast for the project",
+        responses={
+            200: OpenApiResponse(
+                response=MonteCarloForecastSerializer,
+                description=(
+                    "The most recent Monte Carlo result for the project. Keys: p50/p80/p95 "
+                    "(ISO-8601 finish dates), p50/p80/p95_at_day_start and cpm_finish, "
+                    "cpm_finish_at_day_start (which edge of its shown day each finish is; "
+                    "null on a run persisted before #4204), delta_vs_cpm ({p50, p80, p95} "
+                    "calendar-day deltas vs the CPM finish, measured in working time), "
+                    "runs (n_simulations), "
+                    "confidence_curve, histogram_buckets, sensitivity, last_run_at, "
+                    "status_date (the data date this run was computed against — "
+                    "project.status_date or today when unset, ADR-0132/#2638; null for "
+                    "runs persisted before #2638), from_history (true when served from a "
+                    "persisted run after the 24h cache TTL expired), and the risk_premium_* "
+                    "family (ADR-0698): "
+                    "risk_premium_state (not_run|unmeasurable|stale|zero|premium|negative — "
+                    "the discriminant every client renders from, never null), "
+                    "risk_premium_days, risk_premium_ratio, risk_premium_band (always null "
+                    "until #2299), risk_premium_as_of, risk_premium_reason, "
+                    "risk_premium_cpm_finish, risk_premium_p80. The premium is derived on "
+                    "every response and is never stored in the cache entry. Legacy runs with "
+                    "no stored distribution return empty "
+                    "confidence_curve/histogram_buckets/sensitivity arrays. "
+                    "Plus the forecast-staleness family (#3140): forecast_staleness "
+                    "(current|project_changed|aged|unknown — never null; only `current` "
+                    "means the forecast still describes the plan, and a client keeps the "
+                    "recompute action reachable on the other three), plan_version (the "
+                    "project's sync version this run was computed against — unlike the "
+                    "risk_premium family this one IS carried on the cache entry and the "
+                    "persisted row, because it is a run-time observation that cannot be "
+                    "re-derived later; null for runs recorded before #3140, which "
+                    "classify as `unknown`, never `current`), and plan_version_current "
+                    "(that version as of this response). `project_changed` is "
+                    "deliberately not named `plan_changed`: the underlying counter "
+                    "advances on ANY write in the project, so a description or label "
+                    "edit raises it without moving a date. It is a sound trigger for "
+                    "offering a recompute and NOT evidence that a schedule value "
+                    "changed — do not narrate it as one."
+                ),
+            ),
+            404: OpenApiResponse(
+                response=OpenApiTypes.OBJECT,
+                description="No simulation result available for this project ({detail}).",
+            ),
+        },
+    )
+    def get(self, request: Request, pk: str) -> Response:
+        """Return the latest cached Monte Carlo result for the project.
+
+        Falls back to the most recent persisted ``MonteCarloRun`` when the 24-hour
+        cache has expired (ADR-0175): the latest forecast now survives past the
+        TTL. As of #1231 the run also persists its distribution, so when present the
+        fallback returns the real ``histogram_buckets``/``confidence_curve``/
+        ``sensitivity`` instead of empty arrays — the histogram survives cache
+        expiry. Legacy runs (no persisted distribution) still fall back to empty,
+        and the frontend renders the empty-state prose for them.
+        """
+        project = get_object_or_404(Project, pk=pk, is_deleted=False)
+        self.check_object_permissions(request, project)
+        cached = cache.get(mc_latest_cache_key(pk))
+        if cached is not None:
+            # Added time is layered on at read time, never taken from the entry — the
+            # entry has no premium keys to take (ADR-0698 §2). A cached forecast can be
+            # served for 24 hours, and both `risk_premium_ratio` (a share of the
+            # duration still remaining today) and `risk_premium_state` (which ages into
+            # `stale`) would be wrong by the time it is read back.
+            return Response(
+                {
+                    **cached,
+                    **risk_premium_for_forecast_payload(
+                        cached,
+                        today=timezone.localdate(),
+                        calendar_for=lambda: compose_project_calendar(project),
+                    ),
+                    # Same read-time discipline, different reason (#3140): the entry
+                    # carries the plan version the run SAW, and the project has been free
+                    # to move for up to 24 hours since. `project` is already loaded, so
+                    # the comparison costs nothing. An entry written before #3140 has no
+                    # `plan_version` key and classifies as `unknown` — honest, and it
+                    # self-heals on the next run, which is why `MC_LATEST_CACHE_VERSION`
+                    # is deliberately NOT bumped here: unlike the #2833 engine fix, no
+                    # cached *number* is wrong, only unplaceable.
+                    **forecast_staleness_for_payload(
+                        cached,
+                        plan_version_current=project.last_sync_version,
+                        recalculated_at=project.recalculated_at,
+                        today=timezone.localdate(),
+                    ),
+                }
+            )
+
+        latest = MonteCarloRun.objects.filter(project_id=pk).order_by("-taken_at").first()
+        if latest is None:
+            return Response(
+                {"detail": "No simulation result available."},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        # cpm_finish + delta_vs_cpm survive the TTL because both are persisted on the
+        # run (ADR-0175). The distribution (#1231) now survives too when persisted:
+        # use the stored buckets/curve/sensitivity, falling back to empty arrays for
+        # legacy runs that pre-date persistence (the frontend shows the empty-state
+        # prose then). Response shape is unchanged (snake_case keys).
+        dist = latest.distribution or {}
+
+        # Composed only if a start-of-day reading makes the working-time comparison
+        # need it (#4204); memoized so the deltas and the premium share one.
+        calendar_memo: list[Any] = []
+
+        def calendar_for() -> Any:
+            if not calendar_memo:
+                calendar_memo.append(compose_project_calendar(project))
+            return calendar_memo[0]
+
+        return Response(
+            {
+                # The live-run payload has carried `project_id` since #172; the
+                # from-history branch omitted it, and the client maps it straight
+                # through as a non-optional field. Harmless while nothing read it —
+                # but the added-time card's "Add estimates →" target is built from it
+                # (#2531), so past the 24h TTL that link resolved to
+                # `/projects/undefined`.
+                "project_id": str(latest.project_id),
+                "p50": latest.p50.isoformat() if latest.p50 else None,
+                "p80": latest.p80.isoformat() if latest.p80 else None,
+                "p95": latest.p95.isoformat() if latest.p95 else None,
+                "cpm_finish": latest.cpm_finish.isoformat() if latest.cpm_finish else None,
+                # null on a run persisted before #4204 (reading unknown).
+                **_mc_run_readings(latest),
+                "delta_vs_cpm": _mc_deltas_vs_cpm(
+                    latest, latest.cpm_finish, latest.cpm_finish_at_day_start, calendar_for
+                ),
+                "confidence_curve": dist.get("confidence_curve", []),
+                "runs": latest.n_simulations,
+                "histogram_buckets": dist.get("histogram_buckets", []),
+                "sensitivity": dist.get("sensitivity", []),
+                # Persisted with the run since #2483, so the "why is this flat"
+                # explanation now survives cache expiry alongside the distribution.
+                # Legacy rows have none; the client already treats an absent
+                # diagnostic as "no reason known", never as "no estimates".
+                "forecast_diagnostic": latest.diagnostic,
+                "last_run_at": latest.taken_at.isoformat(),
+                # Persisted with the run since #2638; legacy rows predate the field
+                # and read back as null rather than a guessed value (same pattern as
+                # `diagnostic`/`distribution` above).
+                "status_date": latest.status_date.isoformat() if latest.status_date else None,
+                "from_history": True,
+                # The same call `ProjectOverviewView` makes, on the same row — so the
+                # Overview card and every forecast surface read one derivation of what
+                # a premium of 0 means, and cannot disagree (ADR-0698).
+                **build_risk_premium(latest, today=timezone.localdate(), calendar_for=calendar_for),
+                # Persisted with the run since #3140. Legacy rows carry none and classify
+                # as `unknown` rather than `current` — the client then keeps Rerun
+                # reachable and makes no staleness claim it cannot support.
+                **forecast_staleness_from_run(
+                    latest,
+                    plan_version_current=project.last_sync_version,
+                    recalculated_at=project.recalculated_at,
+                    today=timezone.localdate(),
+                ),
+            }
+        )
+
+
+# Fixed RNG seed for the what-if endpoint (#993). Both the baseline and the
+# perturbed Monte Carlo runs sample with THIS seed, so they draw the *same*
+# per-run duration samples for every unperturbed task. The delta between the two
+# forecasts therefore isolates the effect of the perturbation rather than RNG
+# noise, and the endpoint is a pure function of its inputs — the same what-if
+# query always returns the same forecast, which a reproducible "slip this task"
+# demo (and a stable test assertion) both depend on.
+WHATIF_MC_SEED = 993_993
+
+
+def _target_kind_refusal(task: Task) -> Response | None:
+    """400 for a what-if target that cannot be perturbed, else ``None``.
+
+    A milestone is a zero-duration gate. A completed task (#4515) is read with the
+    engine's ``_is_complete`` predicate (ADR-0136): an ``actual_finish`` or 100%.
+    Completed work is pinned by its actuals, so a duration shift would hand back an
+    unmoved forecast as a zero-impact what-if. The engine refuses too; this earlier
+    check keeps the 400 ahead of run admission and the busy slot.
+    """
+    if task.is_milestone:
+        return Response(
+            {"detail": "A milestone is a zero-duration gate and cannot be perturbed."},
+            status=status.HTTP_400_BAD_REQUEST,
+        )
+    if task.actual_finish is None and (task.percent_complete or 0) < 100:
+        return None
+    return Response(
+        {
+            "detail": (
+                "A completed task's dates are actuals, so a duration change "
+                "cannot move the forecast; pick a task that still has work left."
+            )
+        },
+        status=status.HTTP_400_BAD_REQUEST,
+    )
+
+
+class MonteCarloWhatIfView(McpReadableViewMixin, APIView):
+    """Non-mutating Monte Carlo what-if: perturb one task's duration, recompute (#993).
+
+    Backs the MCP ``whatif`` read tool (#504/#603): accept a ``task_id`` plus a
+    duration perturbation, run CPM + Monte Carlo **in memory without persisting
+    anything**, and return the resulting P50/P80/P95, the deterministic CPM finish,
+    whether the critical path changed, and the signed deltas versus the current
+    (unperturbed) forecast.
+
+    Why GET, not POST: the endpoint has no side effects — it writes no rows, sets no
+    cache, and enqueues no recompute — so it is a pure read/compute, correctly
+    modeled as GET. That is also what makes it reachable by an ``mcp:read`` API
+    token: ``McpReadableViewMixin`` confines token callers to safe methods, so a
+    POST could never back a *read* MCP tool. Query params carry the perturbation
+    (``?task_id=&duration_delta=`` or ``&new_duration=``).
+
+    Non-persistence guarantee: this view never calls ``.save()``,
+    ``record_monte_carlo_run``, ``cache.set``, or ``enqueue_recalculate``. The
+    perturbation is applied to freshly-built in-memory scheduler dataclasses; the
+    Django rows are only read. ``schedule()`` and ``monte_carlo()`` both operate on
+    copies and do not mutate their input project.
+
+    Permission: Member (any role >= Viewer), the same project-read gate as the
+    ``run_monte_carlo`` / latest / history forecast endpoints.
+    """
+
+    # ADR-0678 (#2482): projects/<pk>/monte-carlo/whatif/
+    mcp_scope = McpScope.PATH
+
+    mcp_compute_heavy = True  # two CPM passes + two Monte Carlo runs per call (#1808 F4)
+    # Route is `projects/<pk>/…`, so `pk` names the PROJECT here (#2745). Without
+    # this the project-scoped classes below resolve nothing and `has_permission`
+    # returns True for everyone — the gate reads as live in review and enforces
+    # nothing. Declared per view because `pk` means something else on other routes.
+    project_url_kwarg = "pk"
+    permission_classes = [IsAuthenticated, IsProjectMember, IsProjectNotArchived]
+    throttle_classes = [ScopedRateThrottle]
+    throttle_scope = "monte_carlo_whatif"
+
+    @extend_schema(
+        summary="Non-mutating Monte Carlo what-if for a single task duration change",
+        parameters=[
+            OpenApiParameter(
+                "task_id",
+                OpenApiTypes.UUID,
+                required=True,
+                description="The committed task whose duration to perturb.",
+            ),
+            OpenApiParameter(
+                "duration_delta",
+                OpenApiTypes.INT,
+                description=(
+                    "Signed day offset applied to the task's current duration "
+                    "(e.g. 5 to slip it a working week later, -2 to pull it in). "
+                    "Supply exactly one of duration_delta or new_duration."
+                ),
+            ),
+            OpenApiParameter(
+                "new_duration",
+                OpenApiTypes.INT,
+                description=(
+                    "Absolute day count to set the task's duration to (>= 0). "
+                    "Supply exactly one of duration_delta or new_duration."
+                ),
+            ),
+            OpenApiParameter(
+                "n_simulations",
+                OpenApiTypes.INT,
+                description=(
+                    "Monte Carlo iterations. Defaults to the largest count this "
+                    "project's size admits: MC_SIMULATION_CAP, or fewer under "
+                    "MC_CELL_CAP (runs x tasks) on a large project — `runs` in the "
+                    "response reports the count simulated. An explicit value is "
+                    "honored exactly or refused (402 above MC_SIMULATION_CAP, 400 "
+                    "above the size-derived maximum)."
+                ),
+            ),
+        ],
+        responses={
+            200: OpenApiResponse(
+                response=MonteCarloWhatIfResponseSerializer,
+                description=(
+                    "What-if forecast. Keys: task_id; applied ({base_duration_days, "
+                    "duration_delta_days, new_duration_days}); current and whatif (each "
+                    "{p50, p80, p95, their *_at_day_start readings, cpm_finish (ISO-8601 or "
+                    "null), cpm_finish_at_day_start, critical_path ([task_id])}); "
+                    "critical_path_changed (bool — did the set of critical tasks change); "
+                    "delta_vs_current ({p50, p80, p95, cpm_finish} signed calendar-day shifts, "
+                    "positive = later/worse, null when a date is missing; every field is measured "
+                    "in working time (#4178, #4204), so a finish that only moves from the end of "
+                    "a Friday to the start of the next Monday is 0); runs (the iteration "
+                    "count actually simulated per leg — may be below MC_SIMULATION_CAP when "
+                    "n_simulations is omitted on a large project, #2839); "
+                    "seed (fixed RNG seed shared by both runs so the delta isolates the change); "
+                    "cpm_status_date and mc_status_date (ADR-0132/#2638, floor armed on the "
+                    "CPM path by ADR-0752 §4) — the resolved data dates (project.status_date, "
+                    "or today when unset) fed to the deterministic and Monte Carlo passes "
+                    "respectively, shared by both current and whatif since this view runs both "
+                    "in one call; this view never persists, so these are the only provenance a "
+                    "caller gets for how the forecast was computed."
+                ),
+            ),
+            400: OpenApiResponse(
+                response=OpenApiTypes.OBJECT,
+                description=(
+                    "Invalid input: malformed/absent params, both or neither of "
+                    "duration_delta/new_duration, task_id not a committed task in this "
+                    "project, a milestone (zero-duration) target, a completed task (its "
+                    "dates are actuals), a summary (phase) target "
+                    "whose span is rolled up from its children and so cannot be perturbed, "
+                    "a cyclic dependency, or an out-of-range project span; or an explicit "
+                    "n_simulations above the size-derived maximum (MC_CELL_CAP, #2839) — "
+                    "body {error: simulation_cell_cap_exceeded, message, max_runs, "
+                    "task_count}."
+                ),
+            ),
+            402: OpenApiResponse(
+                response=OpenApiTypes.OBJECT,
+                description="OSS simulation cap exceeded (n_simulations or task count too high).",
+            ),
+            404: OpenApiResponse(
+                response=OpenApiTypes.OBJECT,
+                description="Project does not exist.",
+            ),
+            503: OpenApiResponse(
+                response=OpenApiTypes.OBJECT,
+                description=(
+                    "No free Monte Carlo slot in this API process (MC_MAX_CONCURRENT, "
+                    "#2839). Body {error: simulation_busy, message}; retry after "
+                    "Retry-After."
+                ),
+            ),
+        },
+    )
+    def get(self, request: Request, pk: str) -> Response:
+        """Run the perturbed forecast in memory and return the deltas (see class doc)."""
+        from trueppm_scheduler.engine import (
+            CyclicDependencyError,
+            SimulationCapExceeded,
+            monte_carlo,
+            perturb_task_duration,
+            schedule,
+        )
+        from trueppm_scheduler.models import Project as SchedProject
+
+        from trueppm_api.apps.projects.services import scheduler_velocity_inputs
+
+        req = MonteCarloWhatIfRequestSerializer(data=request.query_params)
+        req.is_valid(raise_exception=True)
+        params = req.validated_data
+        task_id = str(params["task_id"])
+
+        try:
+            project = (
+                Project.objects.select_related("calendar", "program__calendar")
+                .prefetch_related(
+                    "tasks",
+                    "calendar__exceptions",
+                    "calendar_layers__calendar__exceptions",
+                    # ADR-0441: the resolver reads the program calendar's exceptions when a
+                    # project inherits its base calendar from the program.
+                    "program__calendar__exceptions",
+                )
+                .get(pk=pk, is_deleted=False)
+            )
+        except Project.DoesNotExist:
+            return Response({"detail": _NOT_FOUND_DETAIL}, status=status.HTTP_404_NOT_FOUND)
+
+        # Object-level membership + not-archived gate (same read level as the
+        # forecast endpoints). APIView.get has no get_object(), so enforce explicitly.
+        self.check_object_permissions(request, project)
+
+        cap: int | None = settings.MC_SIMULATION_CAP
+        # None = "the admissible maximum for this project's size" (#2839), resolved by
+        # `admit_runs` once the leaf network is built below.
+        requested_runs: int | None = (
+            int(params["n_simulations"]) if "n_simulations" in params else None
+        )
+
+        # Build the baseline scheduler input exactly as run_monte_carlo does, through
+        # the shared converters (ADR-0132/#1491) so the what-if forecast is computed on
+        # the identical graph the real forecast uses — same calendar exceptions, same
+        # planned_start floors, same velocity signal.
+        sched_calendar = compose_project_calendar(project)
+        db_tasks = list(Task.committed.filter(project=project).select_related("sprint"))
+        if not db_tasks:
+            return Response(
+                {"detail": "Project has no schedulable (committed) tasks to forecast."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # The perturbation target must be one of THIS project's committed tasks. A
+        # BACKLOG card, a task in another project, or an unknown id is rejected as a
+        # clean 400 (not 404 — the project exists and the caller can read it; only the
+        # task reference is invalid) and never leaks whether the id exists elsewhere.
+        target_db = next((t for t in db_tasks if str(t.id) == task_id), None)
+        if target_db is None:
+            return Response(
+                {"detail": "task_id is not a committed task in this project."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # Milestone and completed refusals; checked before admission so the 400 wins over run
+        # admission (402/413) and a busy slot (503); see `_target_kind_refusal`.
+        if (refusal := _target_kind_refusal(target_db)) is not None:
+            return refusal
+
+        base_duration_days = int(target_db.duration)
+        if "duration_delta" in params:
+            delta_days = int(params["duration_delta"])
+        else:
+            # new_duration is absolute; convert to the equivalent signed shift so both
+            # inputs flow through one perturbation path.
+            delta_days = int(params["new_duration"]) - base_duration_days
+        new_duration_days = max(0, base_duration_days + delta_days)
+
+        suggest_approve = project.estimation_mode == EstimationMode.SUGGEST_APPROVE
+        baseline_tasks = build_sched_tasks(db_tasks, suggest_approve=suggest_approve)
+
+        included_ids = {str(t.id) for t in db_tasks}
+        sched_deps = _build_sched_deps(pk, included_ids)
+
+        # Same leaf-only shaping the real forecast uses (#3527, ADR-0105) — a what-if
+        # answered against a network containing phantom phases is not a what-if about
+        # this project's schedule.
+        try:
+            graph = build_sched_graph(db_tasks, baseline_tasks, sched_deps)
+        except (CyclicDependencyError, ValueError) as exc:
+            # codeql[py/stack-trace-exposure] -- intentional user-facing validation message
+            return Response({"detail": str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+
+        # A summary has no duration of its own — its span is rolled up from its leaves
+        # — so it is absent from the network built above, and perturbing it would
+        # silently change nothing. Refuse rather than hand back an unmoved forecast as
+        # though the delta had been applied. Checked after the shaping because that is
+        # what defines "is a summary" here, and before any simulation runs.
+        if str(target_db.id) in graph.summary_ids:
+            return Response(
+                {
+                    "detail": (
+                        "A summary task's duration is rolled up from its children and "
+                        "cannot be perturbed; pick one of its leaf tasks instead."
+                    )
+                },
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        leaf_tasks = graph.tasks
+        leaf_deps = graph.dependencies
+
+        # runs x n_tasks admission (#2839). Both simulations below share one network
+        # size (a duration perturbation adds no task), so one admission covers both.
+        admission = admit_runs(len(leaf_tasks), requested_runs)
+        if admission.refusal is not None:
+            return admission.refusal
+        n_simulations = admission.runs
+
+        velocity_samples, sprint_length_days = scheduler_velocity_inputs(
+            project.pk, sched_calendar.working_days
+        )
+
+        # The deterministic CPM and Monte Carlo both floor a null status_date at
+        # today (ADR-0752 §4, correcting ADR-0132 §1 — the CPM path used to pass
+        # a null status_date raw, meaning "no floor at all"). Both are resolved
+        # through the same shared helper so this read-time `current` block can
+        # never drift from the persisted deterministic run
+        # (`scheduling/tasks.py::_run_schedule`) on which data date it used —
+        # keeping current.cpm_finish identical to the persisted deterministic
+        # finish and current P50/P80/P95 identical to run_monte_carlo.
+        cpm_status_date = resolve_cpm_status_date(project.status_date)
+        mc_status_date = resolve_cpm_status_date(project.status_date)
+
+        def _make_project(tasks: list[Any], status_date: _date | None) -> Any:
+            return SchedProject(
+                id=str(project.pk),
+                name=project.name,
+                start_date=project.start_date,
+                tasks=tasks,
+                dependencies=leaf_deps,
+                calendar=sched_calendar,
+                status_date=status_date,
+                velocity_samples=velocity_samples or None,
+                sprint_length_days=sprint_length_days,
+            )
+
+        try:
+            # One shared Monte Carlo span (#709) over the full what-if computation —
+            # baseline + perturbed CPM and simulation — through the same helper the
+            # real forecast uses, so the span name and attributes cannot drift.
+            # One process slot (#2839) covers both simulations: they run in sequence.
+            with simulation_slot() as admitted:
+                if not admitted:
+                    return busy_response()
+                with monte_carlo_span(pk, simulation_count=n_simulations):
+                    # The ENGINE owns the perturbation (#3533). Which input a task's
+                    # sampled duration comes from is the engine's own priority rule
+                    # (velocity → PERT triple → deterministic); an API-side shift of
+                    # the fields this view happens to know about moved the CPM finish
+                    # while leaving a velocity-sampled task's bands exactly where they
+                    # were, and reported both. Passing the fully-built project — with
+                    # the velocity signal on it — is what lets the engine reach the
+                    # input it will actually sample.
+                    perturbed_tasks = perturb_task_duration(
+                        _make_project(leaf_tasks, cpm_status_date), task_id, delta_days
+                    ).tasks
+                    baseline_cpm = schedule(_make_project(leaf_tasks, cpm_status_date))
+                    perturbed_cpm = schedule(_make_project(perturbed_tasks, cpm_status_date))
+                    baseline_mc = monte_carlo(
+                        _make_project(leaf_tasks, mc_status_date),
+                        runs=n_simulations,
+                        seed=WHATIF_MC_SEED,
+                        max_runs=cap,
+                        max_tasks=settings.MC_TASK_CAP,
+                        **_mc_lag_delta_kwargs(),
+                    )
+                    perturbed_mc = monte_carlo(
+                        _make_project(perturbed_tasks, mc_status_date),
+                        runs=n_simulations,
+                        seed=WHATIF_MC_SEED,
+                        max_runs=cap,
+                        max_tasks=settings.MC_TASK_CAP,
+                        **_mc_lag_delta_kwargs(),
+                    )
+        except SimulationCapExceeded as exc:
+            return Response(
+                # codeql[py/stack-trace-exposure] -- intentional user-facing validation message
+                {"error": "simulation_cap_exceeded", "tier": "team", "message": str(exc)},
+                status=status.HTTP_402_PAYMENT_REQUIRED,
+            )
+        except (CyclicDependencyError, ValueError) as exc:
+            # codeql[py/stack-trace-exposure] -- intentional user-facing validation message
+            return Response({"detail": str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+        except OverflowError:
+            return Response(
+                {"detail": _DATE_RANGE_EXCEEDED_DETAIL},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # A membership change in the critical set is the meaningful "the shape of the
+        # plan moved" signal — compared as sets so a pure reordering along an unchanged
+        # path does not read as a change.
+        critical_path_changed = set(baseline_cpm.critical_path) != set(perturbed_cpm.critical_path)
+
+        def _leg(mc: Any, cpm: Any) -> dict[str, Any]:
+            cpm_reading = schedule_result_finish(cpm)
+            return {
+                "p50": mc.p50.isoformat(),
+                "p80": mc.p80.isoformat(),
+                "p95": mc.p95.isoformat(),
+                # Which edge of its shown day each finish is (#4204).
+                "p50_at_day_start": mc.p50_at_day_start,
+                "p80_at_day_start": mc.p80_at_day_start,
+                "p95_at_day_start": mc.p95_at_day_start,
+                "cpm_finish": cpm.project_finish.isoformat(),
+                "cpm_finish_at_day_start": cpm_reading[1] if cpm_reading is not None else None,
+                "critical_path": list(cpm.critical_path),
+            }
+
+        current = _leg(baseline_mc, baseline_cpm)
+        whatif = _leg(perturbed_mc, perturbed_cpm)
+        return Response(
+            {
+                "task_id": task_id,
+                "applied": {
+                    "base_duration_days": base_duration_days,
+                    "duration_delta_days": delta_days,
+                    "new_duration_days": new_duration_days,
+                },
+                "current": current,
+                "whatif": whatif,
+                "critical_path_changed": critical_path_changed,
+                "delta_vs_current": {
+                    # In working time (#4204), like `cpm_finish` below.
+                    **_mc_percentile_deltas(perturbed_mc, baseline_mc, lambda: sched_calendar),
+                    # Measured in working time (#4178): a what-if that only moves
+                    # a milestone finish between the end of a Friday and the start
+                    # of the next Monday is no shift, and one that moves it from the
+                    # start of Monday to the end of Monday is a real one.
+                    "cpm_finish": _cpm_finish_delta_days(
+                        baseline_cpm, perturbed_cpm, sched_calendar
+                    ),
+                },
+                "runs": n_simulations,
+                "seed": WHATIF_MC_SEED,
+                # The data dates fed to each engine for both the current and whatif
+                # passes (ADR-0132, floor armed on the CPM path by ADR-0752 §4) —
+                # this view never persists, so these are the only provenance an
+                # AI/MCP or human caller gets for how "current" was computed. Both
+                # baseline and perturbed share one resolved value per engine within
+                # a single call, so one top-level pair covers both `current` and
+                # `whatif` rather than duplicating it under each (#2638). Both are
+                # always a resolved date now (never null) — a null status_date no
+                # longer means "no floor at all" on the CPM path.
+                "cpm_status_date": cpm_status_date.isoformat(),
+                "mc_status_date": mc_status_date.isoformat(),
+            }
+        )
+
+
+# Hard ceiling on a single forecast-history response, independent of the
+# retention cap. OSS retention (MC_HISTORY_CAP=100) is already below this; the
+# ceiling only bites the Enterprise unlimited-retention case so the endpoint can
+# never stream an unbounded payload (ADR-0175).
+MC_HISTORY_RESPONSE_MAX = 500
+
+
+def _annotate_run_deltas(
+    runs: list[MonteCarloRun], calendar_for: Callable[[], Any] | None = None
+) -> None:
+    """Attach a computed-on-read ``_delta`` to each run vs the next-older run (ADR-0108).
+
+    ``runs`` is newest-first; positive days = the forecast slipped later (worse). The
+    oldest row has no predecessor, so its ``_delta`` stays ``None`` (baseline). Mutates
+    each run in place for the serializer to read. Measured in working time from each
+    run's persisted readings (#4204); ``calendar_for`` is called only when a reading
+    is a start-of-day one.
+    """
+    for i, run in enumerate(runs):
+        older = runs[i + 1] if i + 1 < len(runs) else None
+        if older is None:
+            run._delta = None  # type: ignore[attr-defined]
+        else:
+            run._delta = _mc_percentile_deltas(run, older, calendar_for)  # type: ignore[attr-defined]
+
+
+def _mc_attribution_visible(request: Request, project: Project, pk: str) -> bool:
+    """Whether the caller may see run-author attribution, per the effective audience.
+
+    Resolved per-workspace (ADR-0144): ADMIN_OWNER → role ≥ ADMIN; SCHEDULER_PLUS →
+    role ≥ SCHEDULER; NONE → never. Default ADMIN_OWNER reproduces the prior hardcoded
+    gate exactly. Drift must not become a named-individual signal below the configured
+    audience (VoC Morgan).
+    """
+    from trueppm_api.apps.access.models import Role
+    from trueppm_api.apps.access.permissions import _membership_role
+    from trueppm_api.apps.scheduling.forecast_history_settings import (
+        resolve_effective_mc_history,
+    )
+    from trueppm_api.apps.scheduling.models import MCAttributionAudience
+
+    role = _membership_role(request, pk)
+    audience = resolve_effective_mc_history(project, "mc_history_attribution_audience")
+    if audience == MCAttributionAudience.NONE:
+        return False
+    if audience == MCAttributionAudience.SCHEDULER_PLUS:
+        return role is not None and role >= Role.SCHEDULER
+    return role is not None and role >= Role.ADMIN  # ADMIN_OWNER (default)
+
+
+@extend_schema(
+    parameters=[
+        OpenApiParameter(
+            "expand",
+            str,
+            description=(
+                "Set to 'distribution' to include each run's persisted distribution "
+                "({histogram_buckets, confidence_curve, sensitivity}) payload (#1231). "
+                "Omitted by default to keep the list lightweight; distribution is null "
+                "unless expanded or for legacy runs with no stored distribution."
+            ),
+        ),
+    ],
+    responses={
+        200: OpenApiResponse(
+            response=inline_serializer(
+                name="MonteCarloHistoryResponse",
+                fields={
+                    "results": MonteCarloRunSerializer(many=True),
+                    "cap": drf_serializers.IntegerField(allow_null=True),
+                    "enabled": drf_serializers.BooleanField(),
+                },
+            ),
+            description=(
+                "Project Monte Carlo run history (ADR-0175/0143). When the "
+                "per-workspace config disables history, enabled is false and results "
+                "is empty. Each run carries P50/P80/P95, cpm_finish, n_simulations, "
+                "task_count, status_date (the data date the run was computed against "
+                "— null for runs persisted before #2638), a per-percentile delta vs "
+                "the previous run (null on the oldest row), triggered_by_name "
+                "(non-null only for the resolved attribution audience), and "
+                "distribution (only when ?expand=distribution)."
+            ),
+        ),
+        404: OpenApiResponse(
+            response=OpenApiTypes.OBJECT,
+            description="Project does not exist.",
+        ),
+    },
+)
+class MonteCarloHistoryView(APIView):
+    """Project Monte Carlo run history — forecast drift over time (ADR-0175, #961).
+
+    Returns persisted runs newest-first, capped at ``settings.MC_HISTORY_CAP``,
+    each with a computed-on-read per-percentile delta versus the immediately
+    previous (older) run. The run-author attribution (``triggered_by_name``) is
+    serialized only for Admin/Owner (role ≥ ADMIN); every other member sees the
+    drift values without attribution, so forecast drift cannot become a
+    named-individual performance signal (VoC Morgan).
+
+    Permission: Member (any role ≥ Viewer), consistent with the forecast read.
+    """
+
+    # Route is `projects/<pk>/…`, so `pk` names the PROJECT here (#2745). Without
+    # this the project-scoped classes below resolve nothing and `has_permission`
+    # returns True for everyone — the gate reads as live in review and enforces
+    # nothing. Declared per view because `pk` means something else on other routes.
+    project_url_kwarg = "pk"
+    permission_classes = [IsAuthenticated, IsProjectMember, IsProjectNotArchived]
+
+    def get(self, request: Request, pk: str) -> Response:
+        """Return the capped, newest-first run history with per-run deltas."""
+        from trueppm_api.apps.scheduling.forecast_history_settings import (
+            resolve_effective_mc_history,
+        )
+
+        project = get_object_or_404(Project, pk=pk, is_deleted=False)
+        self.check_object_permissions(request, project)
+
+        # Per-workspace forecast-history config (ADR-0144, #1232), inheritable
+        # Workspace → Program → Project. When the effective config disables history,
+        # return 200 with an empty list + enabled:false rather than 403/404 — the
+        # feature is off, not access-denied, so the FE renders a "history off" state.
+        if not resolve_effective_mc_history(project, "mc_history_enabled"):
+            return Response({"results": [], "cap": None, "enabled": False})
+
+        # The retention cap is now per-workspace-effective (clamped to
+        # MC_HISTORY_HARD_CAP in the resolver) rather than the global constant.
+        cap: int | None = resolve_effective_mc_history(project, "mc_history_retention_cap")
+        # Hard response ceiling: even when the cap is None (Enterprise unlimited
+        # *retention*), a single API response must stay bounded — keep the newest
+        # MC_HISTORY_RESPONSE_MAX rows. select_related avoids an N+1 on triggered_by
+        # when attribution is serialized.
+        limit = cap if cap is not None else MC_HISTORY_RESPONSE_MAX
+        # ?expand=distribution opts a single detail fetch into the heavier per-run
+        # distribution payload (#1231); the default list stays lightweight.
+        expand_distribution = request.query_params.get("expand") == "distribution"
+        qs = (
+            MonteCarloRun.objects.filter(project_id=pk)
+            .select_related("triggered_by")
+            .order_by("-taken_at")
+        )
+        # The distribution column is up to MC_DISTRIBUTION_MAX_BYTES per row; the
+        # serializer never reads it on the default list path, so defer it there to
+        # avoid fetching + JSON-parsing ~limit×32KB only to discard it.
+        if not expand_distribution:
+            qs = qs.defer("distribution")
+        runs = list(qs[:limit])
+        calendar_memo: list[Any] = []
+
+        def calendar_for() -> Any:
+            # Composed at most once, and only if some run's reading needs it (#4204).
+            if not calendar_memo:
+                calendar_memo.append(compose_project_calendar(project))
+            return calendar_memo[0]
+
+        _annotate_run_deltas(runs, calendar_for)
+        can_see_attribution = _mc_attribution_visible(request, project, pk)
+
+        data = MonteCarloRunSerializer(
+            runs,
+            many=True,
+            context={
+                "request": request,
+                "can_see_attribution": can_see_attribution,
+                "expand_distribution": expand_distribution,
+            },
+        ).data
+        return Response({"results": data, "cap": cap, "enabled": True})
+
+
+@extend_schema(
+    parameters=[
+        # Day-grained window, declared as `date` to match the burn-series
+        # contract (#1378) — the new 0.3 computed analytics endpoints expose
+        # since/until with one consistent type. The runtime stays lenient: a
+        # bare ISO date is the documented format, and a full ISO datetime is
+        # still accepted as a backward-compatible superset (see _parse_bound).
+        OpenApiParameter(
+            "since",
+            OpenApiTypes.DATE,
+            description="Only snapshots captured at or after this ISO 8601 date (YYYY-MM-DD).",
+        ),
+        OpenApiParameter(
+            "until",
+            OpenApiTypes.DATE,
+            description="Only snapshots captured at or before this ISO 8601 date (YYYY-MM-DD).",
+        ),
+    ],
+    responses={200: ProjectForecastSnapshotSerializer(many=True)},
+)
+class ForecastSnapshotListView(ListAPIView[ProjectForecastSnapshot]):
+    """Project-grain forecast snapshot history (ADR-0154, #388).
+
+    Returns the project's forecast snapshots newest-first (paginated), the
+    persisted record of how the CPM finish and Monte Carlo percentiles drifted
+    over time. Read-only — rows are server-generated on recompute and by the daily
+    floor; there is no write surface. ``?since=``/``?until=`` bound the window by
+    ``captured_at`` (ISO 8601 date YYYY-MM-DD, the documented format; a full ISO
+    datetime is also accepted and interpreted literally, a bare date as midnight UTC).
+
+    Permission: Member (any role ≥ Viewer), the project-read gate — consistent
+    with the Monte Carlo history read.
+    """
+
+    serializer_class = ProjectForecastSnapshotSerializer
+    # Route is `projects/<pk>/…`, so `pk` names the PROJECT here (#2745). Without
+    # this the project-scoped classes below resolve nothing and `has_permission`
+    # returns True for everyone — the gate reads as live in review and enforces
+    # nothing. Declared per view because `pk` means something else on other routes.
+    project_url_kwarg = "pk"
+    permission_classes = [IsAuthenticated, IsProjectMember, IsProjectNotArchived]
+
+    def get_queryset(self) -> models.QuerySet[ProjectForecastSnapshot]:
+        """Project-scoped, optionally date-bounded, newest-first."""
+        project = get_object_or_404(Project, pk=self.kwargs["pk"], is_deleted=False)
+        # IsProjectMember/IsProjectNotArchived are object-level — this list view has
+        # no get_object(), so enforce them explicitly against the resolved project.
+        self.check_object_permissions(self.request, project)
+
+        qs = ProjectForecastSnapshot.objects.filter(project_id=project.pk).order_by("-captured_at")
+        since = self._parse_bound(self.request.query_params.get("since"))
+        until = self._parse_bound(self.request.query_params.get("until"))
+        if since is not None:
+            qs = qs.filter(captured_at__gte=since)
+        if until is not None:
+            qs = qs.filter(captured_at__lte=until)
+        return qs
+
+    @staticmethod
+    def _parse_bound(raw: str | None) -> Any:
+        """Parse an ISO date (documented) or full datetime to a timezone-aware bound.
+
+        A bare ``YYYY-MM-DD`` is the documented since/until format (#1378),
+        interpreted as midnight in the default timezone; a full ISO datetime is
+        still accepted. ``parse_datetime`` parses a date-only string into a *naive*
+        midnight, so any naive result is made aware here — otherwise the bound
+        would be compared naive against the aware ``captured_at`` column (a Django
+        RuntimeWarning and a silent offset bug).
+        """
+        if not raw:
+            return None
+        dt = parse_datetime(raw)
+        if dt is None:
+            d = parse_date(raw)
+            if d is None:
+                return None
+            dt = _datetime(d.year, d.month, d.day)
+        if timezone.is_naive(dt):
+            dt = timezone.make_aware(dt)
+        return dt
+
+
+class FailedTaskPagination(PageNumberPagination):
+    """Bounded page-number pagination for the dead-letter queue (#1317).
+
+    The list mixin already paged through the project default, but the bound was
+    implicit; the dead-letter table can grow to thousands, so the cap is made
+    explicit here. Page-number (not cursor) is retained deliberately — the
+    inspector header shows a total ``count``, which CursorPagination omits.
+    """
+
+    page_size = 50
+    page_size_query_param = "page_size"
+    max_page_size = 200
+
+
+@extend_schema_view(
+    list=extend_schema(
+        parameters=[
+            OpenApiParameter(
+                "status",
+                str,
+                description=(
+                    "Filter by status: dead, pending_retry, dismissed, retried. "
+                    "Invalid values are ignored (no filter)."
+                ),
+            ),
+            OpenApiParameter(
+                "task_name", str, description="Case-insensitive substring match on task_name."
+            ),
+            OpenApiParameter(
+                "failed_after",
+                str,
+                description="ISO-8601; keep tasks with last_failed_at at or after this time.",
+            ),
+            OpenApiParameter(
+                "failed_before",
+                str,
+                description="ISO-8601; keep tasks with last_failed_at at or before this time.",
+            ),
+        ],
+    ),
+)
+class FailedTaskViewSet(IdempotencyMixin, ListModelMixin, RetrieveModelMixin, GenericViewSet):  # type: ignore[type-arg]
+    """Workspace-operator endpoint for dead-lettered Celery tasks.
+
+    List/detail/requeue/drop and the bulk ``requeue_all``/``drop_all``: workspace
+    operators (Django superusers, :class:`IsWorkspaceOperator`) only (#4009). The
+    serializer exposes tracebacks, args, and kwargs which may contain internal
+    paths or partial secrets and must not be visible to unprivileged members.
+
+    **Not gated on Django ``is_staff`` (#4009).** Before #4009 this viewset used
+    ``IsAdminUser``, an undocumented second admin axis that is not governed by
+    ``WorkspaceRole`` and is not self-grantable — but also not visible anywhere in
+    the RBAC docs. Moving to ``IsWorkspaceOperator`` folds dead-letter access into
+    the one stored-principal story the resource catalog and mail transport already
+    use (ADR-0034, ADR-0213 C1) and narrows the population: an ``is_staff=True``
+    account that is not also a superuser now gets 403 where it previously passed.
+
+    The list endpoint backs the dead-letter inspector (#694, ADR-0172) and
+    accepts read-only filters: ``?status=`` (one of the FailedTaskStatus
+    values), ``?task_name=`` (case-insensitive substring), and
+    ``?failed_after=`` / ``?failed_before=`` (ISO-8601, filtered on
+    ``last_failed_at``). Results keep the model default ordering
+    (``-last_failed_at``, newest failure first).
+
+    Write actions (#695, ADR-0210):
+      - ``requeue`` re-enqueues a parked task with an operator-chosen backoff,
+        round-tripping through the durable workflow backend (ADR-0080) rather than
+        the old raw ``send_task`` side channel.
+      - ``drop`` soft-removes a parked task (→ DISMISSED) with an optional audit
+        note; the row is retained so the audit survives (ADR-0084 "no silent
+        discards").
+      - ``requeue_all`` / ``drop_all`` apply the same action across the *current
+        filter set*, bounded to ``FAILED_TASK_BULK_ACTION_MAX``.
+    """
+
+    serializer_class = FailedTaskSerializer
+    permission_classes = [IsWorkspaceOperator]
+    pagination_class = FailedTaskPagination
+    queryset = FailedTask.objects.all()
+
+    def get_queryset(self) -> models.QuerySet[FailedTask]:
+        """Apply the inspector's read-only filters to the dead-letter list.
+
+        Invalid filter values are ignored rather than raising, so a malformed
+        bookmarked URL degrades to "no filter" instead of a 400 — an operator
+        diagnosing an incident should never be blocked by a bad query string.
+
+        ``select_related('resolved_by')`` avoids an N+1 on the resolved-status list
+        views (``?status=retried``/``dismissed``): the ``resolved_by_display``
+        serializer field reads the operator FK, which would otherwise lazy-load
+        once per row (ADR-0210 audit fields).
+        """
+        qs = FailedTask.objects.select_related("resolved_by")
+
+        status_filter = self.request.query_params.get("status")
+        if status_filter in FailedTaskStatus.values:
+            qs = qs.filter(status=status_filter)
+
+        task_name = self.request.query_params.get("task_name")
+        if task_name:
+            qs = qs.filter(task_name__icontains=task_name)
+
+        failed_after = parse_datetime(self.request.query_params.get("failed_after", ""))
+        if failed_after is not None:
+            qs = qs.filter(last_failed_at__gte=failed_after)
+
+        failed_before = parse_datetime(self.request.query_params.get("failed_before", ""))
+        if failed_before is not None:
+            qs = qs.filter(last_failed_at__lte=failed_before)
+
+        return qs
+
+    def _start_requeue_workflow(self, failed: FailedTask, backoff_seconds: int) -> str:
+        """Start the durable requeue workflow for one task (ADR-0210 §1).
+
+        Routes the re-enqueue through the #652 outbox-composing workflow backend
+        (``start_workflow``) rather than a raw ``send_task`` side channel, so a
+        broker outage cannot silently drop the requeue. The idempotency key ties one
+        requeue to one *observed failure* (``id`` + ``failure_count``): a
+        double-clicked or replayed requeue collides on the key and returns the
+        existing workflow instead of double-enqueuing.
+        """
+        return start_workflow(
+            REQUEUE_WORKFLOW,
+            {
+                "failed_task_id": str(failed.id),
+                "task_name": failed.task_name,
+                "args": failed.args,
+                "kwargs": failed.kwargs,
+                "backoff_seconds": backoff_seconds,
+            },
+            idempotency_key=f"requeue:{failed.id}:{failed.failure_count}",
+        )
+
+    @extend_schema(
+        request=FailedTaskRequeueSerializer,
+        responses={200: FailedTaskSerializer},
+        summary="Requeue a dead-lettered task with an operator-chosen backoff",
+    )
+    @action(detail=True, methods=["post"], permission_classes=[IsWorkspaceOperator])
+    def requeue(self, request: Request, pk: str | None = None) -> Response:
+        """Re-enqueue a parked task via the durable workflow backend (ADR-0210).
+
+        Only ``dead``/``pending_retry`` tasks are requeueable; a terminal task is a
+        400. The re-enqueue is durable (workflow outbox); the ``backoff_seconds`` is
+        a best-effort Celery countdown on the re-dispatched task.
+        """
+        failed = self.get_object()
+        if failed.status not in _ACTIONABLE_FAILED_STATUSES:
+            return Response(
+                {"detail": f"Cannot requeue a task with status '{failed.status}'."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        payload = FailedTaskRequeueSerializer(data=request.data)
+        payload.is_valid(raise_exception=True)
+        backoff_seconds = payload.validated_data["backoff_seconds"]
+
+        # Start the durable workflow first, then stamp the row: the side effect is the
+        # durable part, so if the status update failed the workflow still ran and a
+        # re-run dedupes on the idempotency key. Both commit together under
+        # ATOMIC_REQUESTS, so a mid-action error rolls the whole thing back.
+        workflow_id = self._start_requeue_workflow(failed, backoff_seconds)
+        FailedTask.objects.filter(pk=failed.pk).update(
+            status=FailedTaskStatus.RETRIED,
+            resolved_by=request.user,
+            resolved_at=timezone.now(),
+        )
+        failed.refresh_from_db()
+        logger.info(
+            "dead-letter requeue: task %s (%s) requeued by user %s, backoff=%ss, workflow=%s",
+            failed.id,
+            failed.task_name,
+            getattr(request.user, "pk", None),
+            backoff_seconds,
+            workflow_id,
+        )
+        data = dict(FailedTaskSerializer(failed).data)
+        data["workflow_id"] = workflow_id
+        return Response(data)
+
+    @extend_schema(
+        request=FailedTaskDropSerializer,
+        responses={200: FailedTaskSerializer},
+        summary="Drop (dismiss) a dead-lettered task with an optional audit note",
+    )
+    @action(detail=True, methods=["post"], permission_classes=[IsWorkspaceOperator])
+    def drop(self, request: Request, pk: str | None = None) -> Response:
+        """Soft-remove a parked task (→ DISMISSED) with an optional audit note.
+
+        The row is retained (not hard-deleted) so the note/operator/timestamp audit
+        survives; it drops out of the operator's default ``dead``/``pending_retry``
+        view. Re-dropping an already-dismissed task is an idempotent no-op.
+        """
+        failed = self.get_object()
+        payload = FailedTaskDropSerializer(data=request.data)
+        payload.is_valid(raise_exception=True)
+        note = payload.validated_data["note"]
+
+        if failed.status == FailedTaskStatus.DISMISSED:
+            return Response(FailedTaskSerializer(failed).data)
+
+        FailedTask.objects.filter(pk=failed.pk).update(
+            status=FailedTaskStatus.DISMISSED,
+            resolution_note=note,
+            resolved_by=request.user,
+            resolved_at=timezone.now(),
+        )
+        failed.refresh_from_db()
+        logger.info(
+            "dead-letter drop: task %s (%s) dropped by user %s%s",
+            failed.id,
+            failed.task_name,
+            getattr(request.user, "pk", None),
+            " with note" if note else "",
+        )
+        return Response(FailedTaskSerializer(failed).data)
+
+    @extend_schema(
+        request=FailedTaskRequeueSerializer,
+        responses={200: OpenApiResponse(description="{processed, matched, capped}")},
+        summary="Requeue every actionable task in the current filter set (bounded)",
+    )
+    @action(
+        detail=False,
+        methods=["post"],
+        url_path="requeue-all",
+        permission_classes=[IsWorkspaceOperator],
+    )
+    def requeue_all(self, request: Request) -> Response:
+        """Bulk-requeue the current filter set, bounded (ADR-0210 §4).
+
+        Applies the inspector's ``get_queryset`` filters, restricts to actionable
+        (``dead``/``pending_retry``) tasks, and processes at most
+        ``FAILED_TASK_BULK_ACTION_MAX`` (oldest-first). ``capped`` in the response
+        signals that more remain and the operator should repeat.
+        """
+        payload = FailedTaskRequeueSerializer(data=request.data)
+        payload.is_valid(raise_exception=True)
+        backoff_seconds = payload.validated_data["backoff_seconds"]
+
+        qs = self.get_queryset().filter(status__in=_ACTIONABLE_FAILED_STATUSES)
+        matched = qs.count()
+        batch = list(qs.order_by("last_failed_at")[:FAILED_TASK_BULK_ACTION_MAX])
+        for failed in batch:
+            self._start_requeue_workflow(failed, backoff_seconds)
+        if batch:
+            FailedTask.objects.filter(pk__in=[f.pk for f in batch]).update(
+                status=FailedTaskStatus.RETRIED,
+                resolved_by=request.user,
+                resolved_at=timezone.now(),
+            )
+        logger.info(
+            "dead-letter requeue_all: %d of %d task(s) requeued by user %s, backoff=%ss",
+            len(batch),
+            matched,
+            getattr(request.user, "pk", None),
+            backoff_seconds,
+        )
+        return Response(
+            {
+                "processed": len(batch),
+                "matched": matched,
+                "capped": matched > FAILED_TASK_BULK_ACTION_MAX,
+            }
+        )
+
+    @extend_schema(
+        request=FailedTaskDropSerializer,
+        responses={200: OpenApiResponse(description="{processed, matched, capped}")},
+        summary="Drop every task in the current filter set (bounded)",
+    )
+    @action(
+        detail=False,
+        methods=["post"],
+        url_path="drop-all",
+        permission_classes=[IsWorkspaceOperator],
+    )
+    def drop_all(self, request: Request) -> Response:
+        """Bulk-drop the current filter set, bounded (ADR-0210 §4).
+
+        Applies the inspector's ``get_queryset`` filters, excludes already-dismissed
+        rows, and dismisses at most ``FAILED_TASK_BULK_ACTION_MAX`` (oldest-first) in
+        a single bounded ``UPDATE`` — no per-row loop. ``capped`` signals more remain.
+        """
+        payload = FailedTaskDropSerializer(data=request.data)
+        payload.is_valid(raise_exception=True)
+        note = payload.validated_data["note"]
+
+        qs = self.get_queryset().exclude(status=FailedTaskStatus.DISMISSED)
+        matched = qs.count()
+        ids = list(
+            qs.order_by("last_failed_at").values_list("pk", flat=True)[:FAILED_TASK_BULK_ACTION_MAX]
+        )
+        processed = 0
+        if ids:
+            processed = FailedTask.objects.filter(pk__in=ids).update(
+                status=FailedTaskStatus.DISMISSED,
+                resolution_note=note,
+                resolved_by=request.user,
+                resolved_at=timezone.now(),
+            )
+        logger.info(
+            "dead-letter drop_all: %d of %d task(s) dropped by user %s",
+            processed,
+            matched,
+            getattr(request.user, "pk", None),
+        )
+        return Response(
+            {
+                "processed": processed,
+                "matched": matched,
+                "capped": matched > FAILED_TASK_BULK_ACTION_MAX,
+            }
+        )
+
+
+# ---------------------------------------------------------------------------
+# Velocity suggestions (ADR-0065)
+# ---------------------------------------------------------------------------
+
+
+@extend_schema_view(
+    list=extend_schema(
+        parameters=[
+            OpenApiParameter(
+                "task",
+                OpenApiTypes.UUID,
+                location=OpenApiParameter.QUERY,
+                required=False,
+                description="Filter to velocity suggestions for this task.",
+            ),
+            OpenApiParameter(
+                "pending",
+                OpenApiTypes.BOOL,
+                location=OpenApiParameter.QUERY,
+                required=False,
+                description=(
+                    "When true, restrict to suggestions awaiting a decision "
+                    "(neither accepted nor dismissed)."
+                ),
+            ),
+        ],
+    ),
+)
+class VelocitySuggestionViewSet(
+    IdempotencyMixin,
+    ListModelMixin,
+    RetrieveModelMixin,
+    GenericViewSet[VelocitySuggestion],
+):
+    """Velocity-calibration suggestions surfaced to the PM (ADR-0065).
+
+    Lifecycle:
+      - sprint close generates a row per task in the closing sprint via
+        ``compute_velocity_suggestions``
+      - the PM accepts (writes ``most_likely_duration`` + enqueues
+        ScheduleRequest) or dismisses (audit-only stamp) from the Task Detail
+        Drawer
+      - both terminal decisions are non-destructive: the row is preserved for
+        audit; subsequent sprint closes may add new rows (one per task per
+        sprint) but cannot overwrite a settled decision.
+
+    Auth model:
+      - list / retrieve: any project member (Viewer+) — read access is fine
+        because the surface is informational
+      - accept / dismiss: PM or above (the action either writes a CPM input or
+        records a governance decision; either way it's PM-scope)
+
+    Filtering: ``?task=<task_id>`` is the primary filter the drawer uses.
+    ``?pending=true`` restricts to suggestions awaiting a decision.
+    """
+
+    serializer_class = VelocitySuggestionSerializer
+    permission_classes = [IsAuthenticated]
+    queryset = VelocitySuggestion.objects.all()
+
+    def get_queryset(self) -> models.QuerySet[VelocitySuggestion]:
+        qs = (
+            VelocitySuggestion.objects.select_related("task", "sprint")
+            .filter(task__is_deleted=False)
+            .order_by("-created_at")
+        )
+
+        task_id = self.request.query_params.get("task")
+        if task_id:
+            qs = qs.filter(task_id=task_id)
+
+        if self.request.query_params.get("pending", "").lower() == "true":
+            qs = qs.filter(accepted_at__isnull=True, dismissed_at__isnull=True)
+
+        # Membership gate: only return rows whose task belongs to a project the
+        # caller is a member of. We rely on the access app's project-membership
+        # subquery rather than per-row checks so the list endpoint stays fast.
+        # IsAuthenticated excludes AnonymousUser before this runs; the isinstance
+        # guard is there to narrow the type for mypy.
+        from django.contrib.auth.models import AbstractBaseUser
+
+        from trueppm_api.apps.access.models import ProjectMembership
+
+        user = self.request.user
+        if not isinstance(user, AbstractBaseUser):
+            return qs.none()
+        # is_deleted=False (#819): without this, a user whose membership was
+        # soft-deleted still sees velocity suggestions for that project via the
+        # list endpoint. The accept/dismiss actions go through IsProjectAdmin
+        # which already filters soft-deleted, so the write path is safe — only
+        # the list path was leaking.
+        member_project_ids = ProjectMembership.objects.filter(
+            user=user, is_deleted=False, project__is_deleted=False
+        ).values_list("project_id", flat=True)
+        qs = qs.filter(task__project_id__in=member_project_ids)
+        return qs
+
+    @staticmethod
+    def _broadcast_settled(project_id: Any, suggestion_pk: Any, event_type: str) -> None:
+        """Announce that a velocity suggestion was accepted or dismissed (#2845).
+
+        Both decisions mutate shared state a collaborator has on screen — the
+        suggestion disappears from the pending list for everyone — and neither
+        emitted anything before. Deferred to commit and built from plain scalars so
+        the closure never re-reads an ORM instance (broadcast-check H-1). The payload
+        is ID-only: a client re-reads through the serializer, which re-applies the
+        ADR-0104 velocity gate the response itself goes through.
+        """
+        from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+        project_id_str = str(project_id)
+        suggestion_id_str = str(suggestion_pk)
+        transaction.on_commit(
+            lambda: broadcast_board_event(project_id_str, event_type, {"id": suggestion_id_str})
+        )
+
+    # ``request=None`` asserted rather than inferred (#2840): both decisions are
+    # carried by the URL alone. The pre-fix schema published no requestBody here
+    # only because VelocitySuggestionSerializer exposes no writable field — an
+    # accident of the fallback that any future writable field would have reversed.
+    # ``responses`` names the 409 the idempotency guards return so a client is not
+    # left inferring it from the prose.
+    @extend_schema(
+        summary="Accept a velocity suggestion",
+        request=None,
+        responses={
+            200: VelocitySuggestionSerializer,
+            409: OpenApiResponse(description="Suggestion has already been dismissed."),
+            422: OpenApiResponse(
+                description="Accepting would violate the task's three-point estimate ordering."
+            ),
+        },
+    )
+    @action(
+        detail=True,
+        methods=["post"],
+        permission_classes=[IsAuthenticated, IsProjectAdmin, IsProjectNotArchived],
+    )
+    def accept(self, request: Request, pk: str | None = None) -> Response:
+        """Apply the suggested duration to the task and enqueue a CPM recompute.
+
+        Idempotent: a suggestion that is already accepted returns 200 with the
+        existing row. Re-applying after dismiss is rejected with 409 so the
+        audit trail of the original decision is preserved.
+        """
+        suggestion = self.get_object()
+        # Object-level permission keys off the task's project.
+        self.check_object_permissions(request, suggestion.task)
+
+        if suggestion.accepted_at is not None:
+            # get_serializer injects request context so the serializer's ADR-0104
+            # velocity gate fires on these action responses too (#949).
+            return Response(self.get_serializer(suggestion).data)
+        if suggestion.dismissed_at is not None:
+            return Response(
+                {"detail": "Suggestion has already been dismissed."},
+                status=status.HTTP_409_CONFLICT,
+            )
+
+        task = suggestion.task
+        project_id = task.project_id
+
+        # A velocity suggestion writes most_likely_duration alone. When the task
+        # already carries a complete three-point estimate, overwriting the middle
+        # value can break the optimistic <= most_likely <= pessimistic invariant
+        # the scheduler enforces — the invalid triple then detonates the next
+        # CPM/program recompute instead of failing here (#2002). Refuse so the PM
+        # adjusts the optimistic/pessimistic estimates rather than corrupting them
+        # silently. No-op for the common case where opt/pess are unset.
+        if not three_point_estimates_ordered(
+            task.optimistic_duration,
+            suggestion.suggested_duration,
+            task.pessimistic_duration,
+        ):
+            return Response(
+                {
+                    "detail": (
+                        "Accepting this suggestion would set most likely duration to "
+                        f"{suggestion.suggested_duration} days, which violates this "
+                        "task's three-point estimate ordering (optimistic ≤ most "
+                        f"likely ≤ pessimistic; optimistic is {task.optimistic_duration}, "
+                        f"pessimistic is {task.pessimistic_duration}). Adjust the "
+                        "optimistic/pessimistic estimates first."
+                    )
+                },
+                status=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            )
+
+        with transaction.atomic():
+            task.most_likely_duration = suggestion.suggested_duration
+            task.save(update_fields=["most_likely_duration"])
+            VelocitySuggestion.objects.filter(pk=suggestion.pk).update(
+                accepted_at=timezone.now(),
+                accepted_by=request.user,
+            )
+            # CPM cascade: the new most_likely_duration shifts the Monte Carlo
+            # forecast on the next run. Enqueue inside the transaction so the
+            # request is visible to the drain only after the task save commits.
+            transaction.on_commit(
+                lambda: enqueue_recalculate(
+                    str(project_id),
+                    reason=ScheduleRequestReason.TASK_CHANGE,
+                )
+            )
+            # #2845: the recalc above does NOT cover this write. most_likely_duration
+            # is a Monte Carlo input and is absent from _CPM_DELTA_FIELDS, so the
+            # recalc's task_dates_updated delta — built from the subset of tasks whose
+            # _CPM_DELTA_FIELDS actually moved — will not carry this task unless its
+            # deterministic CPM output happens to shift for an unrelated reason. And
+            # cpm_complete, which does fire unconditionally, is explicitly documented
+            # on the client as pill-and-stats only ("the tasks cache is maintained by
+            # task_dates_updated", ADR-0091). So there was no live-update path of any
+            # kind for a field a collaborator can see change.
+            #
+            # Two events, because two things changed: the task's own field (the
+            # canonical ADR-0152 delta, which the existing frontend handler already
+            # knows how to apply) and the suggestion row settling.
+            #
+            # Scalars snapshotted before the closure, and both deferred to commit —
+            # broadcast_task_updated is best-effort and its docstring requires the
+            # caller to wrap it (broadcast-check H-1).
+            from trueppm_api.apps.sync.broadcast import broadcast_task_updated
+
+            project_id_str = str(project_id)
+            task_id_str = str(task.pk)
+            task_version = task.server_version
+            actor_id_str = str(request.user.pk)
+            transaction.on_commit(
+                lambda: broadcast_task_updated(
+                    project_id_str,
+                    task_id=task_id_str,
+                    changed_fields=["most_likely_duration"],
+                    version=task_version,
+                    actor_id=actor_id_str,
+                )
+            )
+            self._broadcast_settled(project_id, suggestion.pk, "velocity_suggestion_accepted")
+
+        suggestion.refresh_from_db()
+        # get_serializer injects request context so the serializer's ADR-0104
+        # velocity gate fires on these action responses too (#949).
+        return Response(self.get_serializer(suggestion).data)
+
+    @extend_schema(
+        summary="Dismiss a velocity suggestion",
+        request=None,
+        responses={
+            200: VelocitySuggestionSerializer,
+            409: OpenApiResponse(description="Suggestion has already been accepted."),
+        },
+    )
+    @action(
+        detail=True,
+        methods=["post"],
+        permission_classes=[IsAuthenticated, IsProjectAdmin, IsProjectNotArchived],
+    )
+    def dismiss(self, request: Request, pk: str | None = None) -> Response:
+        """Mark a suggestion as dismissed without touching the task.
+
+        Idempotent: a suggestion that is already dismissed returns 200 with the
+        existing row. Dismissing after accept is rejected with 409 to preserve
+        the original decision.
+        """
+        suggestion = self.get_object()
+        self.check_object_permissions(request, suggestion.task)
+
+        if suggestion.dismissed_at is not None:
+            # get_serializer injects request context so the serializer's ADR-0104
+            # velocity gate fires on these action responses too (#949).
+            return Response(self.get_serializer(suggestion).data)
+        if suggestion.accepted_at is not None:
+            return Response(
+                {"detail": "Suggestion has already been accepted."},
+                status=status.HTTP_409_CONFLICT,
+            )
+
+        with transaction.atomic():
+            VelocitySuggestion.objects.filter(pk=suggestion.pk).update(
+                dismissed_at=timezone.now(),
+                dismissed_by=request.user,
+            )
+            # #2845: dismissing removes the row from every other member's pending
+            # list. Wrapped in atomic() so the on_commit registration inside
+            # _broadcast_settled has a transaction to hang off — outside one it would
+            # fire immediately, before the UPDATE is durable.
+            self._broadcast_settled(
+                suggestion.task.project_id, suggestion.pk, "velocity_suggestion_dismissed"
+            )
+        suggestion.refresh_from_db()
+        # get_serializer injects request context so the serializer's ADR-0104
+        # velocity gate fires on these action responses too (#949).
+        return Response(self.get_serializer(suggestion).data)
+
+
+# ---------------------------------------------------------------------------
+# Schedule value derivation (ADR-0218, #1058)
+# ---------------------------------------------------------------------------
+
+# The CPM quantities the derivation endpoint can explain. Mirrors
+# trueppm_scheduler.Quantity so the API contract and the engine cannot drift.
+# scheduled_start (ADR-0752) is included so a consumer — human or MCP client —
+# can ask "why does this task's SPAN start here", not only its remaining-work
+# window; scheduled_finish is deliberately NOT a member (it is always
+# identical to early_finish, so asking for it twice would invite two answers).
+_CPM_DERIVATION_QUANTITIES = frozenset(
+    {
+        "early_start",
+        "early_finish",
+        "late_start",
+        "late_finish",
+        "total_float",
+        "free_float",
+        "scheduled_start",
+    }
+)
+# The Monte Carlo percentile quantities, whose derivation is the risk premium over
+# the deterministic CPM finish plus the ADR-0140 sensitivity drivers (#987).
+_MC_DERIVATION_QUANTITIES = frozenset({"p50", "p80", "p95"})
+
+
+def _build_cpm_sched_project(project: Project, pk: str) -> Any:
+    """Assemble the scheduler ``Project`` for a deterministic CPM derivation run.
+
+    Mirrors the input construction of ``scheduling.tasks._run_schedule`` — the
+    **deterministic pass that computes the stored schedule** — through the same shared
+    converters (``compose_project_calendar`` / ``build_sched_tasks`` /
+    ``build_sched_graph``), the same committed-only task set, the same
+    cross-project/non-committed edge drop, and the same data-date and velocity inputs.
+    A derivation explains a value a user is reading off a task row, and that value came
+    from ``_run_schedule``; matching anything else explains a network nobody was shown.
+
+    This docstring used to name :func:`run_monte_carlo` as the thing to mirror, which
+    is how it inherited that endpoint's defect wholesale: before #3527 neither applied
+    the ADR-0105 summary strip, so the mirror was faithful and both were wrong. Naming
+    the deterministic pass instead makes the next drift detectable, because
+    ``_run_schedule`` is the only one of the three whose output is persisted and
+    therefore independently checkable.
+
+    A summary row is consequently absent from the returned graph, and a derivation
+    request naming one now gets the ``UnknownTaskError`` 404 — correct, because a
+    summary's dates are rolled up from its leaves and were never produced by a CPM pass
+    that could be explained.
+    """
+    from trueppm_scheduler.models import Project as SchedProject
+
+    from trueppm_api.apps.projects.services import scheduler_velocity_inputs
+
+    sched_calendar = compose_project_calendar(project)
+    db_tasks = list(Task.committed.filter(project=project).select_related("sprint"))
+    suggest_approve = project.estimation_mode == EstimationMode.SUGGEST_APPROVE
+    sched_tasks = build_sched_tasks(db_tasks, suggest_approve=suggest_approve)
+
+    included_ids = {str(t.id) for t in db_tasks}
+    # Was a second, byte-identical copy of _build_sched_deps' body (#3527). Behaviour
+    # was the same, so nothing was wrong today — but a duplicated edge filter is the
+    # very drift class this issue is an instance of, and the next change to the edge
+    # rules (soft-deleted dependencies, #3532) would have had to find both.
+    #
+    # #3532 is that next change, and it landed on the deduplicated shape: the
+    # soft-delete filter lives once, in _build_sched_deps' Dependency.live read, and
+    # the derivation inherits it here rather than carrying its own copy.
+    sched_deps = _build_sched_deps(pk, included_ids)
+
+    velocity_samples, sprint_length_days = scheduler_velocity_inputs(
+        project.pk, sched_calendar.working_days
+    )
+
+    graph = build_sched_graph(db_tasks, sched_tasks, sched_deps)
+
+    return SchedProject(
+        id=str(project.pk),
+        name=project.name,
+        start_date=project.start_date,
+        tasks=graph.tasks,
+        dependencies=graph.dependencies,
+        calendar=sched_calendar,
+        status_date=resolve_cpm_status_date(project.status_date),
+        velocity_samples=velocity_samples or None,
+        sprint_length_days=sprint_length_days,
+    )
+
+
+class ScheduleDerivationView(McpReadableViewMixin, APIView):
+    """The server-computed *why* behind a computed schedule value (ADR-0218, #1058).
+
+    ``GET /projects/<pk>/schedule/derivation/?task_id=<id>&quantity=<quantity>``
+
+    Returns the derivation of a single computed value — the driving predecessor/
+    successor chain, the binding constraint, each term's lag and calendar-snap
+    contribution, and which CPM pass (forward/backward/float) set it. The
+    derivation is computed server-side from the engine's own pass data by
+    :func:`trueppm_scheduler.derive_value`; it is never recomputed in the browser
+    and nothing is fabricated (rule 120) — a contribution is emitted only for a
+    constraint the engine actually evaluates.
+
+    For a Monte Carlo percentile quantity (``p50``/``p80``/``p95``) the "why" is
+    the deterministic ``cpm_finish``, the signed ``delta_vs_cpm`` risk premium, and
+    the ADR-0140 sensitivity drivers of the latest persisted run (#987) — the
+    existing engine output surfaced honestly, not a second recomputation.
+
+    RBAC: any project member (Viewer+) may read a derivation; ``McpReadableViewMixin``
+    additionally exposes it to an ``mcp:read`` API token confined to safe methods,
+    so an AI/MCP agent can cite the *why* alongside the value.
+    """
+
+    # ADR-0678 (#2482): projects/<pk>/schedule/derivation/
+    mcp_scope = McpScope.PATH
+
+    # Route is `projects/<pk>/…`, so `pk` names the PROJECT here (#2745). Without
+    # this the project-scoped classes below resolve nothing and `has_permission`
+    # returns True for everyone — the gate reads as live in review and enforces
+    # nothing. Declared per view because `pk` means something else on other routes.
+    project_url_kwarg = "pk"
+    permission_classes = [IsAuthenticated, IsProjectMember, IsProjectNotArchived]
+
+    # A CPM quantity runs a full ``schedule()`` pass inside ``derive_value`` on every
+    # call (no precomputed result is passed), so this is as compute-heavy as its
+    # Monte Carlo siblings and was missed by #1808's enumeration (#2839). The scope
+    # bounds human callers; ``mcp_compute_heavy`` stacks the tighter per-token bucket.
+    mcp_compute_heavy = True
+    throttle_classes = [ScopedRateThrottle]
+    throttle_scope = "cpm_on_read"
+
+    @extend_schema(
+        operation_id="project_schedule_derivation",
+        summary="Derivation (the why) of a computed schedule value",
+        parameters=[
+            OpenApiParameter(
+                name="task_id",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                required=True,
+                description="The task whose computed value is being explained.",
+            ),
+            OpenApiParameter(
+                name="quantity",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                required=True,
+                description=(
+                    "Which computed value to explain: a CPM quantity "
+                    "(early_start, early_finish, late_start, late_finish, "
+                    "total_float, free_float, scheduled_start) or a Monte Carlo "
+                    "percentile (p50, p80, p95). CPM quantities return {task_id, task_name, "
+                    "quantity, value, pass, is_critical, binding, contributions[]}, "
+                    "each contribution carrying its source task, dep_type, lag_days, "
+                    "imposed_date, calendar_days_added, slack_days, and is_binding. "
+                    "Percentiles return {quantity, value, value_at_day_start, cpm_finish, "
+                    "cpm_finish_at_day_start, delta_vs_cpm_days (measured in working time, "
+                    "#4204), drivers[]} from the latest simulation."
+                ),
+            ),
+        ],
+        responses={
+            200: OpenApiResponse(
+                response=PolymorphicProxySerializer(
+                    component_name="ScheduleDerivationResponse",
+                    serializers=[
+                        ScheduleCpmDerivationSerializer,
+                        ScheduleMonteCarloDerivationSerializer,
+                    ],
+                    # Neither shape carries a field naming which one it is — the
+                    # caller already knows, from the `quantity` query param it sent,
+                    # which shape comes back. A discriminator field would have to be
+                    # fabricated onto the wire payload, which ADR-0218's "nothing is
+                    # fabricated" rule (rule 120) forbids just to satisfy
+                    # client-generator tooling.
+                    resource_type_field_name=None,
+                ),
+                description=(
+                    "The derivation of the requested value. A CPM quantity returns "
+                    "ScheduleCpmDerivationResponse; a Monte Carlo percentile "
+                    "(p50/p80/p95) returns ScheduleMonteCarloDerivationResponse, which "
+                    "additionally carries forecast_staleness "
+                    "(current|project_changed|aged|unknown), plan_version and "
+                    "plan_version_current (#3140), so a cited percentile states whether "
+                    "the run it comes from still describes the current plan rather than "
+                    "presenting a superseded value with full derivation confidence. "
+                    "`project_changed` means the project was written to (or its CPM "
+                    "output recomputed) since the run — grounds for rerunning, NOT "
+                    "evidence that a schedule date changed."
+                ),
+            ),
+            400: OpenApiResponse(
+                description="Missing/unknown quantity, or invalid schedule input."
+            ),
+            404: OpenApiResponse(
+                description="Unknown project or task, or no simulation available."
+            ),
+        },
+    )
+    def get(self, request: Request, pk: str) -> Response:
+        from trueppm_scheduler.derive import UnknownTaskError, derive_value
+        from trueppm_scheduler.engine import CyclicDependencyError
+
+        quantity = request.query_params.get("quantity")
+        if not quantity:
+            return Response(
+                {"detail": "The 'quantity' query parameter is required."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        if quantity not in _CPM_DERIVATION_QUANTITIES and quantity not in _MC_DERIVATION_QUANTITIES:
+            allowed = ", ".join(sorted(_CPM_DERIVATION_QUANTITIES | _MC_DERIVATION_QUANTITIES))
+            return Response(
+                {"detail": f"Unknown quantity {quantity!r}; must be one of: {allowed}."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        project = get_object_or_404(
+            Project.objects.select_related("calendar", "program__calendar").prefetch_related(
+                "tasks",
+                "calendar__exceptions",
+                "calendar_layers__calendar__exceptions",
+                # ADR-0441: the resolver reads the program calendar's exceptions when a
+                # project inherits its base calendar from the program.
+                "program__calendar__exceptions",
+            ),
+            pk=pk,
+            is_deleted=False,
+        )
+        # 404 (not 403) for a non-member: the object-scope oracle keeps a project's
+        # existence from leaking to a non-member (mirrors MonteCarloLatestView).
+        self.check_object_permissions(request, project)
+
+        if quantity in _MC_DERIVATION_QUANTITIES:
+            return self._monte_carlo_derivation(project, quantity)
+
+        task_id = request.query_params.get("task_id")
+        if not task_id:
+            return Response(
+                {"detail": "The 'task_id' query parameter is required for a CPM quantity."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # _build_cpm_sched_project now shapes the graph (#3527), so it can raise the
+        # engine's InvalidScheduleInput. It is inside the try for the same reason
+        # derive_value is: an unguarded ValueError here becomes a 500, and this view
+        # already documents a 400 for "invalid schedule input".
+        try:
+            sched_project = _build_cpm_sched_project(project, pk)
+            if not sched_project.tasks:
+                return Response(
+                    {"detail": "Project has no committed tasks to schedule."},
+                    status=status.HTTP_404_NOT_FOUND,
+                )
+            derivation = derive_value(sched_project, task_id, quantity)
+        except UnknownTaskError:
+            return Response(
+                {"detail": f"Task {task_id!r} is not in the scheduled network."},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        except (CyclicDependencyError, ValueError) as exc:
+            # codeql[py/stack-trace-exposure] -- intentional user-facing validation message
+            return Response({"detail": str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+        except OverflowError:
+            return Response(
+                {"detail": _DATE_RANGE_EXCEEDED_DETAIL},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        return Response(derivation.to_dict())
+
+    def _monte_carlo_derivation(self, project: Project, quantity: str) -> Response:
+        """Derive a Monte Carlo percentile from the latest run (#987).
+
+        The percentile's "why" is the deterministic ``cpm_finish`` it is measured
+        against, the signed ``delta_vs_cpm`` days of risk premium, and the ADR-0140
+        sensitivity drivers (the tasks whose duration most moves the finish). All
+        three are already computed on the run — this surfaces them, it does not
+        recompute the forecast.
+
+        Reads the shared ``mc_latest`` cache first, falling back to the most recent
+        persisted ``MonteCarloRun`` — the same order as ``MonteCarloLatestView``.
+        The cache-first read matters since #1502: a Member/Viewer-triggered run
+        refreshes the cache but persists no attributed row, and the derivation is
+        part of the open read surface, so it must see cache-only forecasts.
+        """
+        # This endpoint exists so an agent can cite the *why* beside the value
+        # (ADR-0218). A percentile whose run predates the current plan is a stale
+        # citation delivered with full derivation confidence, so the staleness
+        # discriminant travels with the derivation too (#3140) — otherwise
+        # `get_monte_carlo_forecast` and `get_schedule_derivation` report opposite
+        # trustworthiness for one run.
+        # Read off the project `get()` already loaded — it is fetched without
+        # `.only()`/`.defer()`, so both columns are in memory and this costs nothing.
+        # `_current_plan_state` exists for the caller that does NOT hold the row.
+        pk = project.pk
+        plan_version_current = project.last_sync_version
+        recalculated_at = project.recalculated_at
+        today = timezone.localdate()
+        cached = cache.get(mc_latest_cache_key(pk))
+        if cached is not None:
+            return Response(
+                {
+                    "quantity": quantity,
+                    "value": cached.get(quantity),
+                    "pass": "monte_carlo",
+                    "cpm_finish": cached.get("cpm_finish"),
+                    "value_at_day_start": cached.get(f"{quantity}_at_day_start"),
+                    "cpm_finish_at_day_start": cached.get("cpm_finish_at_day_start"),
+                    "delta_vs_cpm_days": (cached.get("delta_vs_cpm") or {}).get(quantity),
+                    "drivers": cached.get("sensitivity", []),
+                    "runs": cached.get("runs"),
+                    "last_run_at": cached.get("last_run_at"),
+                    **forecast_staleness_for_payload(
+                        cached,
+                        plan_version_current=plan_version_current,
+                        recalculated_at=recalculated_at,
+                        today=today,
+                    ),
+                }
+            )
+        latest = MonteCarloRun.objects.filter(project_id=pk).order_by("-taken_at").first()
+        if latest is None:
+            return Response(
+                {"detail": "No simulation result available; run a Monte Carlo forecast first."},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        percentile_date = {"p50": latest.p50, "p80": latest.p80, "p95": latest.p95}[quantity]
+        dist = latest.distribution or {}
+        return Response(
+            {
+                "quantity": quantity,
+                "value": percentile_date.isoformat() if percentile_date else None,
+                "pass": "monte_carlo",
+                "cpm_finish": latest.cpm_finish.isoformat() if latest.cpm_finish else None,
+                "value_at_day_start": getattr(latest, f"{quantity}_at_day_start"),
+                "cpm_finish_at_day_start": latest.cpm_finish_at_day_start,
+                "delta_vs_cpm_days": _delta_vs_cpm_days(
+                    percentile_date,
+                    latest.cpm_finish,
+                    percentile_at_day_start=getattr(latest, f"{quantity}_at_day_start"),
+                    cpm_finish_at_day_start=latest.cpm_finish_at_day_start,
+                    calendar_for=lambda: compose_project_calendar(project),
+                ),
+                # ADR-0140 tornado: the tasks whose duration variance drives the
+                # finish — the honest "why" behind a probabilistic date.
+                "drivers": dist.get("sensitivity", []),
+                "runs": latest.n_simulations,
+                "last_run_at": latest.taken_at.isoformat(),
+                **forecast_staleness_from_run(
+                    latest,
+                    plan_version_current=plan_version_current,
+                    recalculated_at=recalculated_at,
+                    today=today,
+                ),
+            }
+        )