trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/scheduling/apps.py

@@ -0,0 +1,153 @@
+"""App config for scheduling."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+from django.apps import AppConfig
+
+logger = logging.getLogger(__name__)
+
+# Wall-clock start time (time.monotonic(), immune to system clock adjustments) for
+# each in-flight Celery task execution, keyed by task_id. Populated in
+# _on_task_prerun and consumed (popped) in _on_task_postrun — that pair always
+# brackets one execution 1:1, including retried and failed ones, so duration is
+# available for every outcome, not just success (#1917). Celery itself does not
+# set a usable `.runtime` attribute on the request for anything but the success
+# path, which is why this is timed here instead of read off `task.request`.
+_task_start_times: dict[str, float] = {}
+
+
+class SchedulingConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "trueppm_api.apps.scheduling"
+
+    def ready(self) -> None:
+        """Bridge Celery framework signals to Django signals.
+
+        Enterprise packages connect receivers to the Django signals in
+        scheduling.signals — they never need to import from Celery directly.
+
+        Every ``.connect(...)`` below now passes ``weak=False`` (#1917 fix). Celery's
+        ``Signal.connect`` defaults to a *weak* reference to the receiver, and the
+        four ``_on_task_*`` functions are closures local to this method call — with
+        no other strong reference anywhere, they were garbage-collected the moment
+        ``ready()`` returned, silently turning the whole Celery→Django task-lifecycle
+        bridge into dead code (confirmed via ``task_prerun.receivers`` showing a
+        dead weakref immediately after startup). None of ``celery_task_started`` /
+        ``_succeeded`` / ``_failed`` / ``_retried`` were ever actually being sent in
+        a real worker, which is why #1917 found no start/success/retry log lines to
+        begin with — this was the root cause, not just a missing receiver. A stable
+        ``dispatch_uid`` per connect call is required alongside ``weak=False``: without
+        it, a second ``ready()`` call (the test runner / autoreloader can trigger one)
+        would register a *second*, now-permanent strong-ref closure rather than being
+        recognized as the same receiver, doubling every log line and metric sample
+        from then on.
+        """
+        from celery.signals import task_failure, task_postrun, task_prerun, task_retry
+
+        # Register the OSS dead-letter alerting receiver (ADR-0084) and the
+        # start/success/retry structured-log receivers (#1917). Side-effect
+        # import: the @receiver decorators in receivers.py connect on load.
+        from trueppm_api.apps.observability.otel.metrics import record_task_duration
+        from trueppm_api.apps.scheduling import receivers  # noqa: F401
+        from trueppm_api.apps.scheduling.signals import (
+            celery_task_failed,
+            celery_task_retried,
+            celery_task_started,
+            celery_task_succeeded,
+        )
+        from trueppm_api.core.extension_signals import dispatch_extension_signal
+
+        self._register_workflows()
+
+        @task_prerun.connect(weak=False, dispatch_uid="scheduling.on_task_prerun")  # type: ignore[untyped-decorator]
+        def _on_task_prerun(sender: Any, task_id: str, task: Any, **kwargs: Any) -> None:
+            _task_start_times[task_id] = time.monotonic()
+            # sender=None: these signals are about a worker run, not a model row,
+            # so there is no class for the dispatcher to filter on. Receivers
+            # branch on the task_name kwarg (#3777).
+            dispatch_extension_signal(
+                celery_task_started,
+                sender=None,
+                task_id=task_id,
+                task_name=getattr(task, "name", ""),
+                args=kwargs.get("args", ()),
+                kwargs=kwargs.get("kwargs", {}),
+            )
+
+        @task_postrun.connect(weak=False, dispatch_uid="scheduling.on_task_postrun")  # type: ignore[untyped-decorator]
+        def _on_task_postrun(
+            sender: Any, task_id: str, task: Any, retval: Any, **kwargs: Any
+        ) -> None:
+            # task_postrun fires for every terminal state (success, failure, retry,
+            # rejected, ignored) — unlike celery_task_succeeded below, the duration
+            # metric is recorded for all of them so a stuck/slow retry loop is
+            # visible in the histogram too, not just clean runs.
+            state = kwargs.get("state", "") or ""
+            task_name = getattr(task, "name", "")
+            start = _task_start_times.pop(task_id, None)
+            duration = time.monotonic() - start if start is not None else 0.0
+            record_task_duration(
+                task_name=task_name,
+                duration_seconds=duration,
+                outcome=state.lower() or "unknown",
+            )
+            if state == "SUCCESS":
+                dispatch_extension_signal(
+                    celery_task_succeeded,
+                    sender=None,
+                    task_id=task_id,
+                    task_name=task_name,
+                    runtime_seconds=duration,
+                )
+
+        @task_failure.connect(weak=False, dispatch_uid="scheduling.on_task_failure")  # type: ignore[untyped-decorator]
+        def _on_task_failure(
+            sender: Any, task_id: str, exception: BaseException, **kwargs: Any
+        ) -> None:
+            import traceback as tb_module
+
+            dispatch_extension_signal(
+                celery_task_failed,
+                sender=None,
+                task_id=task_id,
+                task_name=getattr(sender, "name", ""),
+                exception=exception,
+                traceback_str="".join(
+                    tb_module.format_exception(type(exception), exception, exception.__traceback__)
+                ),
+            )
+
+        @task_retry.connect(weak=False, dispatch_uid="scheduling.on_task_retry")  # type: ignore[untyped-decorator]
+        def _on_task_retry(sender: Any, request: Any, reason: Any, **kwargs: Any) -> None:
+            dispatch_extension_signal(
+                celery_task_retried,
+                sender=None,
+                task_id=getattr(request, "id", ""),
+                task_name=getattr(sender, "name", ""),
+                attempt=getattr(request, "retries", 0),
+                exception=reason,
+            )
+
+    @staticmethod
+    def _register_workflows() -> None:
+        """Register the scheduling app's durable workflow definitions (ADR-0080 §A).
+
+        The requeue-failed-task workflow (ADR-0210) is the first consumer of the
+        durable backend. Registered here from the owning app's ``ready()`` — the
+        scheduling app owns ``FailedTask`` and already bridges Celery signals in
+        ``ready()``, so the workflow lives with its domain rather than in the
+        backend-neutral engine app. Guarded against duplicate registration because
+        ``ready()`` can run more than once under the test runner and the registry
+        raises on a duplicate name.
+        """
+        from trueppm_api.workflows.consumers.requeue_failed_task import (
+            RequeueFailedTaskWorkflow,
+        )
+        from trueppm_api.workflows.registry import WORKFLOWS
+
+        if RequeueFailedTaskWorkflow.name not in WORKFLOWS.all():
+            WORKFLOWS.register(RequeueFailedTaskWorkflow())

trueppm_api/apps/scheduling/calendars.py

@@ -0,0 +1,144 @@
+"""Composable working-calendar resolution (#906, ADR-0251).
+
+A project's effective non-working mask for CPM is the overlay (union) of several
+applied calendars: a base ``Project.calendar`` plus zero or more
+``ProjectCalendarLayer`` overlays. A day is non-working if *any* applied calendar
+marks it so — masks AND-composed, exception ranges unioned.
+
+The fold itself lives in ``trueppm_scheduler.models.Calendar.compose`` (the Apache
+package). This module is the Django-side seam: it resolves *which* calendars apply
+to a project (through a small resolver registry) and converts them to scheduler
+dataclasses via the single ``build_sched_calendar`` primitive.
+
+The resolver registry is the one-way (enterprise → core) extension point
+(ADR-0251 §6): OSS registers exactly one resolver (base + overlay layers);
+enterprise appends more (per-resource, cross-program calendars) against the same
+signature. Because composition is AND-of-masks + union-of-exceptions, any added
+resolver is always additive and order-independent, so a new source can never be a
+breaking change to an existing project's schedule.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING, Any
+
+from trueppm_api.apps.scheduling.services import build_sched_calendar
+
+if TYPE_CHECKING:
+    from trueppm_api.apps.projects.models import Calendar, Project
+
+# A resolver maps a project to the ordered Django ``Calendar`` rows it applies.
+CalendarLayerResolver = Callable[["Project"], "list[Calendar]"]
+
+_LAYER_RESOLVERS: list[CalendarLayerResolver] = []
+
+
+def register_calendar_layer_resolver(resolver: CalendarLayerResolver) -> None:
+    """Register a resolver that contributes calendars to a project's composed mask.
+
+    Idempotent: registering the same resolver twice is a no-op, so an
+    ``AppConfig.ready()`` that runs more than once (or a re-imported test module)
+    cannot double-count a source.
+    """
+    if resolver not in _LAYER_RESOLVERS:
+        _LAYER_RESOLVERS.append(resolver)
+
+
+def oss_project_layers(project: Project) -> list[Calendar]:
+    """OSS resolver: the effective base calendar plus its overlay layers, in order.
+
+    The base is resolved through the inheritance chain (ADR-0441): the project's own
+    ``calendar`` if set, else its program's, else the workspace default — computed-on-read
+    in ``apps.projects.calendar_settings`` so CPM and the serializers can never disagree
+    on which calendar a project schedules against. ``None`` up the whole chain means the
+    system default, so ``compose`` falls back to Mon-Fri/8h/UTC exactly as before.
+
+    Overlays (``ProjectCalendarLayer``, ADR-0251) still stack on top of the inherited
+    base — inheritance only decides the base; it does not change overlay composition.
+
+    Callers must have prefetched ``calendar__exceptions``,
+    ``calendar_layers__calendar__exceptions`` and — so the inherited tiers don't N+1 —
+    ``program__calendar__exceptions`` when the project may inherit from its program.
+    """
+    from trueppm_api.apps.projects.calendar_settings import resolve_effective_base_calendar
+
+    calendars: list[Calendar] = []
+    base = resolve_effective_base_calendar(project)
+    if base is not None:
+        calendars.append(base)
+    # Ordered by ProjectCalendarLayer.Meta.ordering = ["sort_order"].
+    for layer in project.calendar_layers.all():
+        calendars.append(layer.calendar)
+    return calendars
+
+
+# Registered here (module import) rather than in AppConfig.ready() because the
+# OSS resolver has no app-loading dependency — importing this module is what wires
+# it up. Enterprise registers its extra resolvers from its own AppConfig.ready().
+register_calendar_layer_resolver(oss_project_layers)
+
+
+def resolve_applied_calendars(project: Project) -> list[Calendar]:
+    """The de-duplicated, ordered list of every ``Calendar`` applied to a project.
+
+    Folds the output of every registered resolver into one ordered list, dropping
+    a calendar already contributed by an earlier resolver (the base calendar, for
+    instance, must not be counted twice if a later resolver also returns it). The
+    first occurrence — the base calendar under the OSS resolver — leads, so its
+    scalar ``hours_per_day``/``timezone`` win in :func:`compose_project_calendar`.
+    """
+    seen: set[Any] = set()
+    result: list[Calendar] = []
+    for resolver in _LAYER_RESOLVERS:
+        for cal in resolver(project):
+            if cal.id not in seen:
+                seen.add(cal.id)
+                result.append(cal)
+    return result
+
+
+def compose_project_calendar(project: Project) -> Any:
+    """Fold a project's applied calendars into one scheduler ``Calendar`` (#906).
+
+    ``working_days`` = bitwise-AND of every applied mask; ``exceptions`` = union of
+    every applied calendar's ``CalendarException`` ranges; ``hours_per_day`` /
+    ``timezone`` from the base (first) calendar. Compute-on-read (ADR-0251 §3): the
+    fold is O(layers) and the expensive per-day lookup is already indexed inside
+    the scheduler ``Calendar``. A project with no applied calendars falls back to
+    the Mon-Fri/8h/UTC default, identical to ``build_sched_calendar(None)``.
+
+    Every scheduling call site (CPM pass, Monte Carlo, program schedule) routes
+    through this one helper so composition can never drift between engines. Callers
+    must prefetch ``calendar__exceptions`` and
+    ``calendar_layers__calendar__exceptions``.
+    """
+    from trueppm_scheduler.models import Calendar as SchedCalendar
+
+    applied = resolve_applied_calendars(project)
+    return SchedCalendar.compose([build_sched_calendar(c) for c in applied])
+
+
+def project_sched_calendars(project_ids: Iterable[Any]) -> dict[str, Any]:
+    """Composed scheduler ``Calendar`` per project, keyed by ``str(project_id)`` (#4197).
+
+    One project query plus a fixed set of prefetches for any number of projects,
+    so a read that compares finishes across a page of projects or milestones in
+    working time (:mod:`.finish_reading`) composes each calendar once instead of
+    once per row. A project that no longer exists is absent from the map.
+    """
+    from trueppm_api.apps.projects.models import Project
+
+    ids = {pid for pid in project_ids if pid is not None}
+    if not ids:
+        return {}
+    projects = (
+        Project.objects.filter(pk__in=ids)
+        .select_related("calendar", "program__calendar")
+        .prefetch_related(
+            "calendar__exceptions",
+            "calendar_layers__calendar__exceptions",
+            "program__calendar__exceptions",
+        )
+    )
+    return {str(p.pk): compose_project_calendar(p) for p in projects}

trueppm_api/apps/scheduling/deadletter.py

@@ -0,0 +1,91 @@
+"""Dead-letter helper — records permanently failed Celery tasks."""
+
+from __future__ import annotations
+
+import logging
+import traceback as tb_module
+
+logger = logging.getLogger(__name__)
+
+
+def record_failed_task(
+    task_name: str,
+    task_id: str,
+    args: list[object] | tuple[object, ...],
+    kwargs: dict[str, object],
+    exception: BaseException,
+    project_id: str | None = None,
+) -> None:
+    """Write a FailedTask row for a permanently failed Celery task.
+
+    Called from the on_failure handler when max_retries is exhausted.
+    Safe to call from within a Celery worker — uses its own DB connection.
+
+    On the *terminal* transition (a FailedTask row is newly created) this fires
+    ``celery_task_permanently_failed`` so OSS logs an alert and Enterprise can
+    register PagerDuty/Slack receivers (ADR-0084). A repeat dead-letter of the
+    same ``task_id`` only bumps ``failure_count`` and does **not** re-alert, so
+    the signal means "newly dead-lettered", not "failed again". ``project_id``
+    is threaded through from the caller when known (it is not derivable here).
+    """
+    from trueppm_api.apps.scheduling.models import FailedTask, FailedTaskStatus
+    from trueppm_api.apps.scheduling.signals import celery_task_permanently_failed
+    from trueppm_api.core.extension_signals import dispatch_extension_signal
+
+    exc_type = type(exception).__qualname__
+    exc_msg = str(exception)
+    exc_tb = "".join(
+        tb_module.format_exception(type(exception), exception, exception.__traceback__)
+    )
+
+    defaults: dict[str, object] = {
+        "task_name": task_name,
+        "args": list(args) if args else [],
+        "kwargs": dict(kwargs) if kwargs else {},
+        "exception_type": exc_type,
+        "exception_message": exc_msg,
+        "traceback": exc_tb,
+        "status": FailedTaskStatus.DEAD,
+    }
+    # Only set project_id when this call actually knows it (#1917).
+    # update_or_create's defaults overwrite unconditionally, so unconditionally
+    # including a bare `None` here would erase a project attribution recorded by
+    # an earlier failure of the same task_id the moment a later re-failure's
+    # call site didn't have project_id in scope.
+    if project_id is not None:
+        defaults["project_id"] = project_id
+
+    obj, created = FailedTask.objects.update_or_create(
+        task_id=task_id,
+        defaults=defaults,
+    )
+    if not created:
+        FailedTask.objects.filter(pk=obj.pk).update(
+            failure_count=obj.failure_count + 1,
+        )
+
+    logger.error(
+        "Dead-lettered task %s (%s): %s: %s",
+        task_name,
+        task_id,
+        exc_type,
+        exc_msg,
+    )
+
+    if created:
+        # A misbehaving receiver (incl. enterprise PagerDuty/Slack) must never
+        # break the dead-letter recording path.
+        #
+        # sender=None: this signal is about a worker run, not a model row. This
+        # site is also why the Celery family could not use a class even if one
+        # were wanted — the dead-letter recorder has the task's name and no task
+        # object at all. Receivers branch on the task_name kwarg (#3777).
+        dispatch_extension_signal(
+            celery_task_permanently_failed,
+            sender=None,
+            task_id=task_id,
+            task_name=task_name,
+            exception=exception,
+            traceback_str=exc_tb,
+            project_id=project_id,
+        )

trueppm_api/apps/scheduling/finish_reading.py

@@ -0,0 +1,198 @@
+"""Compare two project finishes in working time, not by their shown day (#4178).
+
+``ScheduleResult.project_finish`` and a milestone's ``early_finish`` are *days*,
+and the engine chooses which edge of that day a zero-duration milestone sits on
+(``Task.milestone_at_day_end``, #4079). After #4173 a milestone that lands just
+after non-working time is shown at the **start of the next working day**, while
+one that follows work is shown at the **end of its day**. The end of Friday and
+the start of the following Monday are the same position in working time, so the
+shown finish can jump Friday -> Monday while the working-time finish does not move
+at all. Diffing the two shown days as calendar days reports that as a three-day
+slip — a phantom.
+
+This module turns a shown finish ``(day, at_day_start)`` into the day whose *end*
+is the same position in working time — a start-of-day finish becomes the end of
+the last working day before it — and diffs those. A finish whose shown day hops
+non-working time without moving in working time therefore gets a delta of zero.
+Every delta is still reported in calendar days, so the unit of
+``end_date_shift_threshold_days`` and of the activity feed's ``finish +Nd`` does
+not change, and a finish that is the end of its day diffs exactly as before.
+
+Why the reading is reconstructed here rather than read from the engine: the engine
+computes the project's finish *instant* internally but exposes only the day and the
+per-task ``milestone_at_day_end`` flag, and #4178 is scoped to consumers, not to the
+engine's public surface.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from datetime import date, timedelta
+from types import SimpleNamespace
+from typing import Any
+
+#: A shown finish: ``(day, at_day_start)``. ``at_day_start`` True means the finish
+#: is the *start* of ``day`` (a start-of-day milestone), False the end of it, and
+#: ``None`` that the reading is unknown — a snapshot row written before the reading
+#: was recorded (see :func:`finish_shift_days`).
+Finish = tuple[date, bool | None]
+
+#: The ``Task`` columns :func:`task_finish_at_day_start` reads. Name them in any
+#: ``.only()`` / ``.values()`` that feeds it, or each deferred read is a query.
+FINISH_READING_FIELDS: tuple[str, ...] = (
+    "is_milestone",
+    "milestone_at_day_end",
+)
+
+
+def task_finish_at_day_start(task: Any, *, milestone_at_day_end: bool | None = None) -> bool:
+    """Whether a task's ``early_finish`` is the *start* of that day.
+
+    Mirrors the engine's own rule (``trueppm_scheduler.engine._finish_instant``):
+    a milestone the engine did not put at the end of its day
+    (``milestone_at_day_end`` False) ends at the start of its day, and work always
+    ends at the end of its finish day. That holds for a completed milestone too,
+    and the flag alone decides it: the engine pins it (``_pinned_placement``) but
+    keeps it an instant — with no actuals at the start of its pinned day (#4343);
+    with actuals on its recorded day, at the edge of that day it had live (#4433),
+    so the end of the day when completed work finishing that day placed it or the
+    last live run showed it at the end of that day (#4525), the start otherwise.
+    (Before #4433 the engine never flagged a milestone pinned by actuals, and this
+    function derived an end-of-day reading from its actuals instead.)
+
+    This is the engine's *forecast* reading. The schedule-variance metrics read a
+    recorded ``actual_finish`` as the end of its day on purpose — a variance
+    convention shared by ``ProjectTaskSerializer.get_schedule_variance_days``,
+    ``program_rollup._schedule_variance_by_project`` and the sprint-close
+    milestone slip — and do not call this function for it.
+
+    ``milestone_at_day_end`` overrides the task's own flag, for reading a finish
+    the task held before a recalculation overwrote it.
+
+    ``task`` is a Django ``Task`` (milestone = ``is_milestone``) or an engine
+    ``trueppm_scheduler.Task`` from a ``ScheduleResult``, which has no
+    ``is_milestone`` and is a milestone when its ``duration`` is zero.
+    """
+    if milestone_at_day_end is None:
+        milestone_at_day_end = bool(getattr(task, "milestone_at_day_end", False))
+    is_milestone = getattr(task, "is_milestone", None)
+    if is_milestone is None:
+        is_milestone = getattr(task, "duration", None) == timedelta(0)
+    return bool(is_milestone) and not milestone_at_day_end
+
+
+def values_finish_at_day_start(row: Mapping[str, Any]) -> bool | None:
+    """:func:`task_finish_at_day_start` for a ``Task`` ``.values()`` row (#4197).
+
+    ``None`` when the row has no ``early_finish`` — there is no finish to read an
+    edge of. The row must carry :data:`FINISH_READING_FIELDS`. Used at baseline
+    capture, whose task read is a ``.values()`` query.
+    """
+    if row.get("early_finish") is None:
+        return None
+    return task_finish_at_day_start(SimpleNamespace(**{f: row[f] for f in FINISH_READING_FIELDS}))
+
+
+def latest_finish(rows: Iterable[tuple[date | None, bool, Any]]) -> Finish | None:
+    """The project finish, with its reading, from ``(early_finish, at_day_start, wbs_path)`` rows.
+
+    The day is the latest ``early_finish``, exactly as ``project_finish`` is. It is
+    the start of that day only when every task finishing that day does so at its
+    start. A summary row carries its children's rolled-up finish but not their
+    reading, so it is dropped when another row on the same day sits inside its WBS
+    subtree — a summary's finish is always one of its leaves', so this loses
+    nothing. Returns ``None`` when no row has a finish.
+    """
+    on_day: list[tuple[bool, str | None]] = []
+    day: date | None = None
+    for finish, at_start, wbs_path in rows:
+        if finish is None:
+            continue
+        path = str(wbs_path) if wbs_path else None
+        if day is None or finish > day:
+            day, on_day = finish, [(at_start, path)]
+        elif finish == day:
+            on_day.append((at_start, path))
+    if day is None:
+        return None
+    # Every proper ancestor of a path on the day: O(rows x depth), so a project
+    # whose whole plan finishes on one day does not go quadratic.
+    ancestors: set[str] = set()
+    for _, p in on_day:
+        if p:
+            parts = p.split(".")
+            ancestors.update(".".join(parts[:i]) for i in range(1, len(parts)))
+    leaves = [at_start for at_start, p in on_day if not (p and p in ancestors)]
+    return day, bool(leaves) and all(leaves)
+
+
+def schedule_result_finish(result: Any) -> Finish | None:
+    """``ScheduleResult.project_finish`` with its reading.
+
+    A ``ScheduleResult`` holds leaf tasks only (summaries are stripped before the
+    pass), so no WBS pruning is needed.
+    """
+    return latest_finish((t.early_finish, task_finish_at_day_start(t), None) for t in result.tasks)
+
+
+def working_time_end_day(finish: Finish, calendar: Any) -> date:
+    """The day whose end is the same working-time position as ``finish``.
+
+    The end of a day is that day. The start of a day is the end of the last
+    working day before it — the start of a Monday is the end of the Friday before
+    it. A finish recorded on a non-working day (a task pinned to a Saturday actual
+    finish) is kept as recorded: it is a fact the user entered, not a reading the
+    engine chose, and it cannot hop a weekend between two recalculations.
+    """
+    from trueppm_scheduler.engine import _prev_working_day
+
+    day, at_day_start = finish
+    if not at_day_start:
+        return day
+    return _prev_working_day(day - timedelta(days=1), calendar)
+
+
+def finish_shift_days(prior: Finish, new: Finish, calendar: Any | None) -> int:
+    """Signed calendar-day move of the project finish in working time.
+
+    Positive means the finish moved later. Zero for the Friday-end ->
+    Monday-start jump across a weekend that the shown day makes with no move in
+    working time (#4178). ``calendar`` is the project's
+    composed scheduler ``Calendar``; with ``None`` it falls back to the plain
+    shown-day difference.
+
+    An unknown reading (``None``, a row written before the reading was recorded)
+    cannot be told apart from either edge of its day. When the two shown days are
+    equal the finish is taken as unmoved — otherwise the first comparison after an
+    upgrade would read a start-of-day milestone against an assumed end of the same
+    day and report a phantom three-day pull-in. When the days differ, the unknown
+    side is read as the end of its day, which is how every finish was shown before
+    #4079. An install that ran an untagged main image from after #4079 (which could
+    already show a start-of-day milestone) but before this field may therefore
+    misread that one post-upgrade comparison by up to the weekend or holiday gap.
+    """
+    unknown = prior[1] is None or new[1] is None
+    if calendar is None or (unknown and prior[0] == new[0]):
+        return (new[0] - prior[0]).days
+    prior_known: Finish = (prior[0], bool(prior[1]))
+    new_known: Finish = (new[0], bool(new[1]))
+    return (
+        working_time_end_day(new_known, calendar) - working_time_end_day(prior_known, calendar)
+    ).days
+
+
+def lazy_finish_shift_days(
+    prior: Finish, new: Finish, calendar_for: Callable[[], Any | None] | None
+) -> int:
+    """:func:`finish_shift_days`, composing the calendar only when a reading needs it.
+
+    The calendar only changes the answer when one side is a known start-of-day
+    reading: two end-of-day finishes (or an unknown one, which reads as the end of
+    its day or as unmoved) diff as their shown days. So a read path that has no
+    calendar in hand — the Monte Carlo history, the ``latest`` fallback, the project
+    overview's risk premium (#4204) — pays for composing one only on a project
+    whose finish actually is a start-of-day milestone.
+    """
+    if not prior[1] and not new[1]:
+        return (new[0] - prior[0]).days
+    return finish_shift_days(prior, new, calendar_for() if calendar_for is not None else None)