trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/sync/views.py

@@ -0,0 +1,957 @@
+"""REST views for the sync app — offline delta pull endpoint."""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import TYPE_CHECKING, Any, cast
+
+from django.conf import settings
+from django.db import IntegrityError, transaction
+from django.db.models import BooleanField, Prefetch
+from django.db.models.expressions import RawSQL
+from drf_spectacular.types import OpenApiTypes
+from drf_spectacular.utils import (
+    OpenApiParameter,
+    OpenApiResponse,
+    extend_schema,
+    inline_serializer,
+)
+from rest_framework import serializers, status
+from rest_framework.exceptions import NotFound, PermissionDenied, ValidationError
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.throttling import BaseThrottle, ScopedRateThrottle
+from rest_framework.views import APIView
+
+from trueppm_api.apps.access.models import ProgramMembership, ProjectMembership, Role
+from trueppm_api.apps.access.permissions import IsNotTokenAuthenticated, _membership_role
+from trueppm_api.apps.idempotency.mixins import IdempotencyMixin
+from trueppm_api.apps.integrations.models import TaskLink
+from trueppm_api.apps.projects.models import (
+    Calendar,
+    Dependency,
+    Label,
+    Program,
+    Project,
+    RetroActionItem,
+    RetroVisibility,
+    Risk,
+    Sprint,
+    SprintRetro,
+    Task,
+    TaskCustomFieldValue,
+    TaskRecurrenceRule,
+    TaskRelation,
+    TaskSuggestedAssignee,
+)
+from trueppm_api.apps.sync.pagination import SyncCursor, SyncSource, paginate_changes
+from trueppm_api.apps.sync.serializers import (
+    SyncCalendarSerializer,
+    SyncDependencySerializer,
+    SyncLabelSerializer,
+    SyncMembershipSerializer,
+    SyncProgramMembershipSerializer,
+    SyncProgramSerializer,
+    SyncProjectSerializer,
+    SyncPullResponseSerializer,
+    SyncRetroActionItemSerializer,
+    SyncRiskSerializer,
+    SyncSprintRetroSerializer,
+    SyncSprintSerializer,
+    SyncTaskLinkSerializer,
+    SyncTaskRecurrenceRuleSerializer,
+    SyncTaskRelationSerializer,
+    SyncTaskSerializer,
+    SyncTaskSuggestedAssigneeSerializer,
+    SyncTimeEntrySerializer,
+    SyncUploadRequestSerializer,
+    SyncUploadResponseSerializer,
+)
+from trueppm_api.apps.sync.ws_auth import TICKET_TTL_SECONDS, issue_ticket
+from trueppm_api.apps.timetracking.models import TimeEntry
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import User as _User
+
+
+class WebSocketTicketView(IdempotencyMixin, APIView):
+    """Mint a short-lived, single-use ticket for the WebSocket handshake (ADR-0141).
+
+    Browsers cannot set an ``Authorization`` header on a WebSocket upgrade, so the
+    credential must ride in the URL. A raw JWT there leaks into every access log
+    (#818); a ticket that is single-use and expires in
+    :data:`~trueppm_api.apps.sync.ws_auth.TICKET_TTL_SECONDS` seconds is useless
+    once logged. The client POSTs here, then opens the socket with ``?ticket=``.
+
+    Authentication only — authorization (project membership/role) is enforced by
+    the consumer on connect. No project scope is required to mint a ticket.
+
+    **A personal access token may not mint a ticket (#4462).** Every real client
+    that opens a project socket — the web app and the mobile offline layer — mints
+    its ticket through the browser/app session's JWT; nothing in this codebase
+    mints one with a bearer PAT. A leaked PAT minting a ticket would open a live
+    WebSocket with no termination path of its own: revoking the token afterward
+    does not reach a socket that is already open, because the consumer resolves
+    its user once at connect and never re-checks the credential that opened it.
+    ``IsNotTokenAuthenticated`` closes that off at the one point it is cheap to
+    close — before the ticket exists.
+    """
+
+    permission_classes = [IsAuthenticated, IsNotTokenAuthenticated]
+    throttle_classes = [ScopedRateThrottle]
+    throttle_scope = "ws_ticket"
+    # Stateless mint — the generic Idempotency-Key path adds nothing.
+    idempotency_exempt = True
+
+    @extend_schema(
+        summary="Issue a WebSocket connection ticket",
+        responses={
+            200: inline_serializer(
+                name="WebSocketTicketResponse",
+                fields={
+                    "ticket": serializers.CharField(
+                        help_text="Single-use opaque ticket to pass as the "
+                        "`?ticket=` query parameter when opening the socket.",
+                    ),
+                    "expires_in": serializers.IntegerField(
+                        help_text="Seconds until the ticket expires.",
+                    ),
+                },
+            ),
+        },
+        description="Issue a single-use WebSocket connection ticket (ADR-0141).",
+    )
+    def post(self, request: Request) -> Response:
+        ticket = issue_ticket(str(request.user.pk))
+        return Response({"ticket": ticket, "expires_in": TICKET_TTL_SECONDS})
+
+
+class ProjectSyncView(IdempotencyMixin, APIView):
+    """Pull-only delta sync endpoint for the mobile offline store.
+
+    Returns all rows (live and soft-deleted) whose ``sync_seq`` is strictly
+    greater than `since` for the given project, formatted for WatermelonDB's
+    synchronize() helper.
+
+    ``sync_seq`` — not ``server_version`` — is the cursor (ADR-0686, #2491). It is
+    drawn from the project's own monotonic sequence, so every synced row in the
+    project is totally ordered against every other one and the project-wide
+    maximum is a meaningful checkpoint. ``server_version`` counts a single row's
+    saves; comparing it against that maximum let a frequently-edited row raise the
+    checkpoint above every other row's counter and drop those rows from the delta
+    permanently.
+
+    The response ``timestamp`` is read *before* the delta queries, so a write that
+    lands during the pull always draws a cursor above it. Such a row is delivered by
+    this response or the next one — never dropped — at the cost of an occasional
+    re-delivery, which WatermelonDB's upsert absorbs. Clients therefore need no
+    retry or reconciliation logic for a mid-pull write; adopt ``timestamp`` as the
+    next ``since`` and the delta is complete. It is read once per *paging session*,
+    not per request: continuation pages echo the value pinned in the cursor (#2568).
+    See the comment at the watermark read for why the ordering, and not a transaction
+    isolation level, is what guarantees this.
+
+    Usage:
+        GET /api/v1/projects/{pk}/sync/?since=0
+    """
+
+    # Exempt from the generic Idempotency-Key path (ADR-0170): the upload POST is already
+    # idempotent by client_batch_id (SyncBatch dedup, ADR-0082); the generic header would
+    # be redundant and the sync protocol uses its own batch id.
+    idempotency_exempt = True
+    permission_classes = [IsAuthenticated]
+
+    @extend_schema(
+        summary="Pull the offline sync delta for a project",
+        parameters=[
+            OpenApiParameter(
+                name="since",
+                type=OpenApiTypes.INT,
+                location=OpenApiParameter.QUERY,
+                required=False,
+                default=0,
+                description=(
+                    "WatermelonDB high-water mark — an opaque cursor, not a row "
+                    "version. Returns only rows changed strictly after this point. "
+                    "Omit (or pass `0`) for a full initial sync; passing the "
+                    "previous response's `timestamp` fetches just the delta since "
+                    "then. Omitting it silently triggers a full re-sync."
+                ),
+            ),
+            OpenApiParameter(
+                name="cursor",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                required=False,
+                description=(
+                    "Opaque pagination continuation token (#1013). Omit on the "
+                    "first request; on each subsequent request pass the previous "
+                    "response's `next_cursor`. Keep `since` constant for the whole "
+                    "paging session. Loop until `next_cursor` is null / `has_more` "
+                    "is false, then adopt `timestamp` as the next `since`."
+                ),
+            ),
+            OpenApiParameter(
+                name="page_size",
+                type=OpenApiTypes.INT,
+                location=OpenApiParameter.QUERY,
+                required=False,
+                description=(
+                    "Maximum rows returned across all collections in one page. "
+                    "Defaults to `TRUEPPM_SYNC_PULL_PAGE_SIZE`; clamped to "
+                    "`TRUEPPM_SYNC_PULL_MAX_PAGE_SIZE`."
+                ),
+            ),
+        ],
+        responses={200: SyncPullResponseSerializer},
+    )
+    def get(self, request: Request, pk: str) -> Response:
+        # Validate `since` parameter.
+        since_raw = request.query_params.get("since", "0")
+        try:
+            since = int(since_raw)
+            if since < 0:
+                raise ValueError
+        except (ValueError, TypeError) as err:
+            raise ValidationError({"since": "Must be a non-negative integer."}) from err
+
+        # Validate the optional continuation cursor and page size (#1013).
+        cursor_raw = request.query_params.get("cursor")
+        cursor = SyncCursor.decode(cursor_raw) if cursor_raw else None
+        page_size = self._resolve_page_size(request)
+
+        # Resolve project — 404 if missing or soft-deleted.
+        try:
+            project = Project.objects.get(pk=pk, is_deleted=False)
+        except Project.DoesNotExist as err:
+            raise NotFound("Project not found.") from err
+
+        # RBAC — any project member (Viewer+) may pull.
+        caller_role = _membership_role(request, project.pk)
+        if caller_role is None:
+            from rest_framework.exceptions import PermissionDenied
+
+            raise PermissionDenied("You must be a member of this project.")
+
+        # Read the high-water mark BEFORE the delta queries. This ORDERING is the
+        # whole guarantee — not an isolation level. ATOMIC_REQUESTS does wrap this
+        # request in a transaction, but at PostgreSQL's default READ COMMITTED, and
+        # nothing here or in settings raises that: every statement below still takes
+        # its own fresh snapshot, so being in a transaction pins nothing. REPEATABLE
+        # READ would add nothing either, and an earlier version of this comment
+        # claimed a wrapper that never existed at all (#2613).
+        #
+        # Two facts close the TOCTOU window:
+        #
+        #  1. A write landing after this read draws sync_seq > timestamp, so it is
+        #     either carried by this response anyway (harmless — upsert) or caught
+        #     by the next pull, whose `since` is this timestamp. Reading the
+        #     watermark first errs toward re-delivery; reading it last is lossy.
+        #  2. A write that already committed is fully visible. Allocation UPDATEs
+        #     the project row and holds its write lock to commit (sync/sequence.py),
+        #     so allocations are totally ordered by commit: observing
+        #     last_sync_version == W means every allocation <= W has committed —
+        #     each one together with the row it stamped.
+        #
+        # Fact 2 rests on a WRITER-side precondition: the allocator bump and the row
+        # write must land in one transaction. ATOMIC_REQUESTS supplies it for every
+        # HTTP write and the batch writers open an explicit atomic(); a synced write
+        # in autocommit would violate it, and no reader isolation level can
+        # compensate — a snapshot cannot reveal an uncommitted row whose already-
+        # committed allocator bump the reader can see. Tracked in #2617.
+        #
+        # The value is taken off the Project row fetched above rather than re-read,
+        # so the snapshot instant is the RBAC fetch — earlier still, which only
+        # widens the margin. Do NOT add a refresh_from_db() here: re-reading the
+        # allocator after the delta queries is exactly the lossy order, and would
+        # publish a checkpoint over rows this response could not carry.
+        #
+        # One watermark per *session*, not per request (#2568) — which preserves the
+        # ordering above rather than weakening it: a continuation page's checkpoint was
+        # read before page 1's delta queries, so it precedes every query in the drain.
+        # On a continuation page the checkpoint is read back off the cursor: recomputing
+        # it would
+        # publish a value above rows written mid-drain into a collection the pager
+        # had already passed, and the client adopting the last page's `timestamp`
+        # would filter those rows out of every future pull. Pinning page 1's value
+        # errs the safe way — such rows simply arrive on the next pull, and rows
+        # this drain did deliver above the pin are re-delivered under upsert.
+        #
+        # The cursor is unsigned, so `w` is also ceiling-checked against the live
+        # sequence. `i` and `v` are stream *positions* the pager re-derives and
+        # bounds naturally, but `w` is a checkpoint the client is told to persist
+        # and echo back as `since` indefinitely — a junk value is permanent for
+        # that device rather than transient. The check is free here (the watermark
+        # is an attribute of the project row already fetched above) and rejects
+        # nothing legitimate, because the sequence only ever increases. It is
+        # deliberately NOT mirrored in UserProgramSyncView, whose watermark costs
+        # two aggregates over the caller's whole accessible set: paying them per
+        # page would reinstate the O(pages x rows) cost this fix removed, to guard
+        # a value that can only ever corrupt the tampering client's own cursor.
+        if cursor is not None:
+            timestamp = cursor.watermark
+            if timestamp > self._watermark(project):
+                raise ValidationError({"cursor": "Malformed pagination cursor."})
+        else:
+            timestamp = self._watermark(project)
+
+        # Retros are visibility-gated per ADR-0071 §3. A VIEWER on a TEAM_ONLY
+        # retro does not receive the retro's raw notes — the sync filters them
+        # out at the queryset level. The sync protocol delivers tombstones for
+        # visibility-removed rows so WatermelonDB can drop them client-side.
+        retro_qs = SprintRetro.objects.filter(sprint__project=project, sync_seq__gt=since)
+        if caller_role < Role.MEMBER:
+            retro_qs = retro_qs.exclude(team_visibility=RetroVisibility.TEAM_ONLY)
+
+        retro_action_item_qs = RetroActionItem.objects.filter(
+            retro__sprint__project=project, sync_seq__gt=since
+        ).select_related("retro")
+        if caller_role < Role.MEMBER:
+            retro_action_item_qs = retro_action_item_qs.exclude(
+                retro__team_visibility=RetroVisibility.TEAM_ONLY
+            )
+
+        # Ordered sync sources: (collection, base queryset, serializer). Each base
+        # queryset carries the project scope, the `sync_seq__gt=since` floor,
+        # and any RBAC/visibility filters. The pager (#1013) drains them in this
+        # fixed order, keyset-seeking on (sync_seq, id) within each, so the
+        # response is bounded by page_size without skipping or duplicating rows.
+        # The order is stable across pages — do not reorder without a protocol bump.
+        sources: list[SyncSource] = [
+            (
+                "projects",
+                Project.objects.filter(pk=project.pk, sync_seq__gt=since),
+                SyncProjectSerializer,
+            ),
+            (
+                "tasks",
+                # is_phase annotation (ADR-0293): EXISTS a direct non-subtask child.
+                # Mirrors the projects app's annotate_tasks_queryset is_phase shape so
+                # offline clients receive the same computed rollup flag. Static SQL
+                # literal, empty params — no user input interpolated; the ltree
+                # operator can't be expressed in the ORM.
+                Task.objects.filter(project=project, sync_seq__gt=since)
+                .annotate(
+                    # nosemgrep: avoid-raw-sql
+                    is_phase=RawSQL(
+                        "EXISTS("
+                        "  SELECT 1 FROM projects_task c"
+                        "  WHERE c.project_id = projects_task.project_id"
+                        "    AND c.is_deleted = false"
+                        "    AND c.is_subtask = false"
+                        "    AND c.id != projects_task.id"
+                        "    AND c.wbs_path IS NOT NULL"
+                        "    AND projects_task.wbs_path IS NOT NULL"
+                        "    AND c.wbs_path ~ (projects_task.wbs_path::text || '.*{1}')::lquery"
+                        ")",
+                        [],
+                        output_field=BooleanField(),
+                    )
+                )
+                .prefetch_related(
+                    # label_ids array (ADR-0400) — filter tombstoned labels so a
+                    # deleted label never rides a task's sync payload; O(1) per page.
+                    Prefetch("labels", queryset=Label.objects.filter(is_deleted=False)),
+                    # custom_fields map (#2143, ADR-0528) rides the task like label_ids;
+                    # select_related feeds the field-type resolver + person avatar O(1).
+                    Prefetch(
+                        "custom_field_values",
+                        queryset=TaskCustomFieldValue.objects.select_related("field", "value_user"),
+                    ),
+                ),
+                SyncTaskSerializer,
+            ),
+            (
+                "dependencies",
+                # Same-project edges only. Cross-project edges (ADR-0120) are
+                # deliberately excluded from the single-project offline delta:
+                # their successor task lives in a project this client may not have
+                # synced, and the offline WASM recompute is single-project. Offline
+                # cross-project scheduling arrives with the program-sync slice
+                # (D3/D4); until then the sync payload stays byte-identical to the
+                # pre-cross-project behaviour.
+                Dependency.objects.filter(
+                    predecessor__project=project,
+                    successor__project=project,
+                    sync_seq__gt=since,
+                ).select_related("predecessor"),
+                SyncDependencySerializer,
+            ),
+            (
+                "calendars",
+                # prefetch_related("exceptions") feeds the nested read-only
+                # exceptions array on SyncCalendarSerializer (ADR-0193) without a
+                # per-calendar lazy load — parity with CalendarViewSet and
+                # N+1-safe for the future program-sync multi-calendar slice.
+                Calendar.objects.filter(
+                    pk=project.calendar_id, sync_seq__gt=since
+                ).prefetch_related("exceptions")
+                if project.calendar_id
+                else Calendar.objects.none(),
+                SyncCalendarSerializer,
+            ),
+            (
+                "memberships",
+                ProjectMembership.objects.filter(project=project, sync_seq__gt=since),
+                SyncMembershipSerializer,
+            ),
+            (
+                "risks",
+                Risk.objects.filter(project=project, sync_seq__gt=since).prefetch_related("tasks"),
+                SyncRiskSerializer,
+            ),
+            (
+                "sprints",
+                Sprint.objects.filter(project=project, sync_seq__gt=since),
+                SyncSprintSerializer,
+            ),
+            ("sprint_retros", retro_qs, SyncSprintRetroSerializer),
+            ("retro_action_items", retro_action_item_qs, SyncRetroActionItemSerializer),
+            (
+                "task_suggested_assignees",
+                TaskSuggestedAssignee.objects.filter(task__project=project, sync_seq__gt=since),
+                SyncTaskSuggestedAssigneeSerializer,
+            ),
+            (
+                "task_links",
+                TaskLink.objects.filter(task__project=project, sync_seq__gt=since),
+                SyncTaskLinkSerializer,
+            ),
+            (
+                "task_recurrence_rules",
+                TaskRecurrenceRule.objects.filter(
+                    task__project=project, sync_seq__gt=since
+                ).select_related("task"),
+                SyncTaskRecurrenceRuleSerializer,
+            ),
+            (
+                # Time entries are scoped to the CALLER's own rows (ADR-0185 §6): the
+                # per-project delta never leaks a colleague's entries, mirroring the
+                # /me/ REST surface's non-surveillance discipline. A soft-deleted entry
+                # yields a tombstone through the standard _collect path.
+                "time_entries",
+                TimeEntry.objects.filter(
+                    task__project=project,
+                    user=cast("_User", request.user),
+                    sync_seq__gt=since,
+                ).select_related("task"),
+                SyncTimeEntrySerializer,
+            ),
+            (
+                # Label catalog (ADR-0400) — appended to preserve the stable protocol
+                # order. Assignment is NOT a source here; it rides Task.label_ids.
+                "labels",
+                Label.objects.filter(project=project, sync_seq__gt=since),
+                SyncLabelSerializer,
+            ),
+            (
+                # Informational task relations (ADR-0455) — appended LAST to preserve
+                # the stable protocol order. Same-project relations only: a
+                # cross-project relation's counterpart task may live in a project
+                # this client has not synced (mirrors the Dependency same-project
+                # scoping above). Pull-only, like Dependency — never in the upload
+                # WRITABLE_COLLECTIONS. The delta joins via ``source`` since
+                # TaskRelation carries no direct project FK.
+                "task_relations",
+                TaskRelation.objects.filter(
+                    source__project=project,
+                    target__project=project,
+                    sync_seq__gt=since,
+                ).select_related("source"),
+                SyncTaskRelationSerializer,
+            ),
+        ]
+
+        changes, next_cursor, has_more = paginate_changes(
+            sources,
+            cursor=cursor,
+            page_size=page_size,
+            collect=self._collect,
+            watermark=timestamp,
+            version_field="sync_seq",
+        )
+
+        return Response(
+            {
+                "changes": changes,
+                "timestamp": timestamp,
+                "next_cursor": next_cursor.encode() if next_cursor is not None else None,
+                "has_more": has_more,
+            }
+        )
+
+    @staticmethod
+    def _resolve_page_size(request: Request) -> int:
+        """Clamp the requested ``page_size`` to ``[1, MAX]`` with a sane default (#1013).
+
+        A missing or non-numeric value falls back to the default rather than 400ing:
+        the pager is a transport optimization, not a contract the client must satisfy.
+        """
+        default = getattr(settings, "TRUEPPM_SYNC_PULL_PAGE_SIZE", 1000)
+        maximum = getattr(settings, "TRUEPPM_SYNC_PULL_MAX_PAGE_SIZE", 5000)
+        raw = request.query_params.get("page_size")
+        if raw is None:
+            return default
+        try:
+            requested = int(raw)
+        except (ValueError, TypeError):
+            return default
+        return max(1, min(requested, maximum))
+
+    def get_throttles(self) -> list[BaseThrottle]:
+        """POST gets the dedicated upload throttle; GET keeps the default `user`
+        scope (#2939 — same defect class #2878 fixed in four other views: a bare
+        list here *replaces* ``DEFAULT_THROTTLE_CLASSES`` instead of adding to it,
+        so this branch resolved to no throttle at all on the delta-export pull,
+        the largest read surface in the API). Mobile sync is high-frequency by
+        design, so it is bounded by the generous default (1000/min per account,
+        ``TRUEPPM_THROTTLE_USER_RATE``) rather than a dedicated tighter scope —
+        that is a real decision, not an oversight, and now it is enforced.
+        """
+        if self.request.method == "POST":
+            from trueppm_api.apps.sync.throttles import SyncUploadThrottle
+
+            return [SyncUploadThrottle()]
+        return super().get_throttles()
+
+    @extend_schema(
+        request=SyncUploadRequestSerializer,
+        responses={
+            200: SyncUploadResponseSerializer,
+            403: OpenApiResponse(
+                description=(
+                    "Not a project member, below the Team Member role (Viewer), project "
+                    "archived, or a row the caller may not write: per-row edit/delete "
+                    "rights, a field-level policy such as PM-only estimates or backlog "
+                    "fields, or creating a task from a role that cannot author the plan "
+                    "(the Scheduler band and Enterprise 2xx-band roles). The whole batch "
+                    "is rolled back."
+                )
+            ),
+            409: OpenApiTypes.OBJECT,
+        },
+        description=(
+            "Upload a WatermelonDB delta batch. Carries a client_batch_id for "
+            "all-or-nothing, idempotent replay (ADR-0082)."
+        ),
+    )
+    def post(self, request: Request, pk: str) -> Response:
+        """Upload a WatermelonDB delta batch with transactional atomicity (ADR-0082).
+
+        The batch carries a client-generated ``client_batch_id``. The first
+        request to win the unique-constraint race applies the delta and records
+        the batch + its response in one atomic transaction (all-or-nothing); a
+        retry carrying the same id within the freshness window replays the stored
+        response without re-applying. See ADR-0082 §D for the full algorithm.
+        """
+        from trueppm_api.apps.access.models import Role
+        from trueppm_api.apps.sync.models import SyncBatch, SyncBatchStatus
+        from trueppm_api.apps.sync.throttles import sync_batch_concurrency_slot
+
+        envelope = SyncUploadRequestSerializer(data=request.data)
+        envelope.is_valid(raise_exception=True)
+        client_batch_id = envelope.validated_data["client_batch_id"]
+        # The high-water mark the client last pulled — the default per-row base for the
+        # field-level conflict guard (#1718). Advisory only: absent → last-writer-wins.
+        last_pulled_at = envelope.validated_data.get("last_pulled_at")
+        # Feed the RAW changes map (not envelope.validated_data["changes"]) to
+        # apply_task_changes so it stays the single authority for the writable-
+        # collection whitelist (ADR-0082 §B). The typed nested serializer (#786)
+        # documents the shape but ignores unknown collection keys; passing the raw
+        # map keeps the explicit "unsupported collection → 400" guard byte-identical
+        # for existing clients rather than silently dropping the foreign collection.
+        # The envelope serializer above already rejected a non-mapping body with a
+        # 400 ("Expected a dictionary, but got list"), so the raw body is provably a
+        # mapping by here — narrowed rather than re-guarded.
+        changes = cast("dict[str, Any]", request.data)["changes"]
+
+        try:
+            project = Project.objects.get(pk=pk, is_deleted=False)
+        except Project.DoesNotExist as err:
+            raise NotFound("Project not found.") from err
+
+        # RBAC: only project members with a write role may push. Per-row
+        # ownership (Member edits own tasks; Scheduler cannot edit content) is
+        # enforced inside apply_task_changes, mirroring IsProjectMemberWriteOrOwn.
+        # Creating a row also requires the plan-authoring rule (IsProjectPlanAuthor
+        # on REST create), so the Scheduler band cannot create either.
+        role = _membership_role(request, project.pk)
+        if role is None:
+            raise PermissionDenied("You must be a member of this project.")
+        if role < Role.MEMBER:
+            raise PermissionDenied("You need at least Team Member role to upload changes.")
+
+        # Archived projects are hard read-only (#530) — mirror IsProjectNotArchived,
+        # which gates every REST write. Without this, the upload path would be a
+        # back-channel to mutate an archived project.
+        if project.is_archived:
+            raise PermissionDenied(
+                "This project is archived and cannot be modified. Unarchive it first."
+            )
+
+        ttl = getattr(settings, "TRUEPPM_SYNC_BATCH_RETENTION_HOURS", 24)
+
+        # Fast path: a fresh, completed duplicate replays its stored response.
+        # Scoped to (project, actor) so a member can never replay another
+        # project's — or another *user's* — batch by reusing its client_batch_id.
+        # The stored response carries that actor's task ids, server_versions, and
+        # watermark; cross-actor replay would leak it (#894, #887 IDOR guard).
+        existing = SyncBatch.objects.filter(  # type: ignore[misc]
+            project=project, actor_user=request.user, client_batch_id=client_batch_id
+        ).first()
+        if (
+            existing is not None
+            and existing.status == SyncBatchStatus.COMPLETED
+            and existing.is_fresh(ttl_hours=ttl)
+        ):
+            return Response(existing.response_body, status=existing.response_status)
+
+        # Bound simultaneously in-flight heavy batch applies for this user (#1756).
+        # Wraps the whole apply — including the IntegrityError re-run — so one
+        # logical upload holds exactly one slot. Placed AFTER the fast-path replay
+        # so a cheap idempotent retry never consumes a slot. Raises 429 (Throttled)
+        # when the per-user concurrency cap is exceeded; fails open on Redis error.
+        with sync_batch_concurrency_slot(request.user.pk):
+            try:
+                return self._apply_and_record(
+                    request, project, role, client_batch_id, changes, last_pulled_at
+                )
+            except IntegrityError:
+                # A concurrent duplicate committed between our check and create, or a
+                # stale row exists. Re-fetch (project + actor-scoped) and resolve.
+                existing = SyncBatch.objects.filter(  # type: ignore[misc]
+                    project=project, actor_user=request.user, client_batch_id=client_batch_id
+                ).first()
+                if existing is None:
+                    raise  # genuinely unexpected — surface it
+                if existing.is_fresh(ttl_hours=ttl):
+                    if existing.status == SyncBatchStatus.COMPLETED:
+                        return Response(existing.response_body, status=existing.response_status)
+                    # Fresh but still pending: a true concurrent race whose winner has
+                    # not committed yet. Ask the client to retry — the next attempt
+                    # hits the fast-path replay.
+                    return Response(
+                        {"detail": "This batch is already being processed; retry shortly."},
+                        status=status.HTTP_409_CONFLICT,
+                    )
+                # Expired row is blocking a re-run: drop it and apply once more. After
+                # the freshness window the same client_batch_id is allowed to re-run.
+                existing.delete()
+                return self._apply_and_record(
+                    request, project, role, client_batch_id, changes, last_pulled_at
+                )
+
+    def _apply_and_record(
+        self,
+        request: Request,
+        project: Project,
+        role: int,
+        client_batch_id: Any,
+        changes: dict[str, Any],
+        last_pulled_at: int | None = None,
+    ) -> Response:
+        """Apply the delta and snapshot the response inside one atomic batch.
+
+        The SyncBatch row is the **first** write so the unique constraint
+        serializes concurrent duplicates. Any failure (RBAC, validation, DB)
+        rolls back the row writes *and* the batch row together — nothing commits,
+        and the client re-uploads the whole batch under the same id.
+        """
+        from trueppm_api.apps.scheduling.services import enqueue_recalculate
+        from trueppm_api.apps.sync.broadcast import broadcast_board_event
+        from trueppm_api.apps.sync.models import SyncBatch, SyncBatchStatus
+        from trueppm_api.apps.sync.sequence import coalesce_sync_seq
+        from trueppm_api.apps.sync.upload import apply_task_changes
+
+        with transaction.atomic():
+            batch = SyncBatch.objects.create(
+                client_batch_id=client_batch_id,
+                project=project,
+                actor_user=request.user,  # type: ignore[misc]
+                status=SyncBatchStatus.PENDING,
+            )
+            # Draw one sync_seq per project for the whole batch rather than one
+            # per row (#1527, ADR-0686). The allocations run inside this atomic
+            # block, so a rollback discards them with the rows.
+            with coalesce_sync_seq():
+                applied = apply_task_changes(
+                    project=project,
+                    request=request,
+                    role=role,
+                    changes=changes,
+                    last_pulled_at=last_pulled_at,
+                )
+            body = {
+                "client_batch_id": str(client_batch_id),
+                "applied": {
+                    "tasks": {
+                        "created": applied.created,
+                        "updated": applied.updated,
+                        "deleted": applied.deleted,
+                    }
+                },
+                # Per-row lost-update conflicts (#1718): rows that were NOT applied
+                # because a concurrent writer changed an overlapping field. The client
+                # reloads these and reapplies; empty on the common no-conflict batch.
+                "conflicts": {"tasks": applied.conflicts},
+                "timestamp": applied.max_version,
+            }
+            batch.status = SyncBatchStatus.COMPLETED
+            batch.response_body = body
+            batch.response_status = status.HTTP_200_OK
+            batch.save(update_fields=["status", "response_body", "response_status"])
+
+            # Side effects on commit, mirroring single-row writes (inbound_sync):
+            # one coalesced CPM recalc + one coalesced board event, so web clients
+            # react and a rolled-back batch broadcasts nothing.
+            #
+            # A delta batch can carry up to TRUEPPM_SYNC_BATCH_MAX_ROWS (500) rows.
+            # Emitting one broadcast per applied row (the previous behavior) issued
+            # up to 500 async_to_sync(group_send) round-trips at commit on a single
+            # upload — under a reconnect storm this overflowed the channel-layer
+            # inbox and dropped presence/CPM events (#809). Coalesce into a single
+            # tasks_bulk_mutated event (same pattern as sprint-close carry-over,
+            # projects/tasks.py); the web handler invalidates the whole task query
+            # on it, so per-row granularity is not needed.
+            project_id = str(project.pk)
+            if applied.changed:
+                transaction.on_commit(partial(enqueue_recalculate, project_id))
+            mutated_ids = [task_id for _event_type, task_id in applied.events]
+            if mutated_ids:
+                # default-arg binding (not closure capture) so a future branch
+                # can't late-bind the ids — matches the carry-over pattern.
+                def _broadcast_bulk(pid: str = project_id, ids: list[str] = mutated_ids) -> None:
+                    broadcast_board_event(pid, "tasks_bulk_mutated", {"task_ids": ids})
+
+                transaction.on_commit(_broadcast_bulk)
+
+        return Response(body, status=status.HTTP_200_OK)
+
+    @staticmethod
+    def _collect(qs: Any, serializer_class: Any) -> dict[str, Any]:
+        """Split a queryset into WatermelonDB 'updated' and 'deleted' buckets.
+
+        All changed rows are returned in 'updated' (upsert semantics).
+        Soft-deleted rows have their IDs returned in 'deleted' as well.
+        'created' is always empty — WatermelonDB upserts handle insert/update.
+        """
+        rows = list(qs)
+        live = [r for r in rows if not r.is_deleted]
+        deleted_ids = [str(r.pk) for r in rows if r.is_deleted]
+        return {
+            "created": [],
+            "updated": serializer_class(live, many=True).data,
+            "deleted": deleted_ids,
+        }
+
+    @classmethod
+    def _watermark(cls, project: Project) -> int:
+        """Return the project's sync cursor high-water mark (ADR-0686, #2491).
+
+        ``Project.last_sync_version`` is the allocator every synced row in this
+        project drew its ``sync_seq`` from (``apps/sync/sequence.py``), so it is
+        by construction greater than or equal to every row's cursor — the safe
+        upper bound the client adopts as its next ``since``.
+
+        It used to cache ``MAX(server_version)`` over a 14-table ``UNION ALL``
+        (ADR-0142). The cache was faithful; the value was not a valid ordering,
+        because ``server_version`` counts one row's own saves. The union, its
+        ``SYNC_WATERMARK_USE_COLUMN`` fallback, and the receiver-vs-union
+        conformance test are gone with it: there is nothing left to derive the
+        column from, and nothing left to drift.
+        """
+        return int(project.last_sync_version)
+
+
+class UserProgramSyncView(IdempotencyMixin, APIView):
+    """Pull-only delta sync for the caller's Program + ProgramMembership rows.
+
+    The project-scoped :class:`ProjectSyncView` cannot reach user-scoped Program
+    rows (ADR-0070 §Sync): the ``Project.program`` FK syncs offline so the program
+    badge renders on cached projects, but the program list itself does not — on a
+    job site the program layer vanishes and the user falls back to a flat project
+    list. This endpoint closes that gap, delivering Program and ProgramMembership
+    deltas for every program the caller is a member of. It is the 0.4 follow-up
+    ADR-0070 §Sync flagged; no new ADR (see the updated §Sync note).
+
+    Scope is derived entirely from the caller's own live memberships, so — unlike
+    the project endpoint — there is **no path parameter to tamper with**: no IDOR
+    surface. All co-members of the caller's programs are returned (parity with the
+    project endpoint, which returns every ``ProjectMembership`` for the project),
+    which lets the client enforce offline program RBAC and render the roster.
+
+    Tombstones: a program soft-deleted while the caller is still a member, and any
+    co-member membership soft-deleted, are delivered as ``deleted`` ids.
+
+    Known v1 limitation (mirrors ``ProjectSyncView``): if the caller's *own*
+    membership is soft-deleted (they are removed from a program), that row drops
+    out of the accessible set and its tombstone is never delivered — the online
+    path 403s on the next access and the client evicts the stale program on a full
+    re-sync. Full write-side offline for programs is out of scope for v1 (reads
+    first, per #561).
+
+    Usage:
+        GET /api/v1/sync/user/programs/?since=0
+    """
+
+    # Read-only pull; the generic Idempotency-Key path adds nothing (parity with
+    # ProjectSyncView.get, ADR-0170).
+    idempotency_exempt = True
+    permission_classes = [IsAuthenticated]
+
+    @extend_schema(
+        summary="Pull the offline sync delta for the caller's programs",
+        parameters=[
+            OpenApiParameter(
+                name="since",
+                type=OpenApiTypes.INT,
+                location=OpenApiParameter.QUERY,
+                required=False,
+                default=0,
+                description=(
+                    "WatermelonDB high-water mark. Returns only Program / "
+                    "ProgramMembership rows whose `server_version` is strictly "
+                    "greater than this value. Omit (or pass `0`) for a full initial "
+                    "sync; adopt the previous response's `timestamp` for the delta."
+                ),
+            ),
+            OpenApiParameter(
+                name="cursor",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                required=False,
+                description=(
+                    "Opaque pagination continuation token (#1013). Omit on the "
+                    "first request; on each subsequent request pass the previous "
+                    "response's `next_cursor`. Keep `since` constant for the whole "
+                    "paging session. Loop until `has_more` is false, then adopt "
+                    "`timestamp` as the next `since`."
+                ),
+            ),
+            OpenApiParameter(
+                name="page_size",
+                type=OpenApiTypes.INT,
+                location=OpenApiParameter.QUERY,
+                required=False,
+                description=(
+                    "Maximum rows returned across both collections in one page. "
+                    "Defaults to `TRUEPPM_SYNC_PULL_PAGE_SIZE`; clamped to "
+                    "`TRUEPPM_SYNC_PULL_MAX_PAGE_SIZE`."
+                ),
+            ),
+        ],
+        responses={200: SyncPullResponseSerializer},
+    )
+    def get(self, request: Request) -> Response:
+        # Validate `since` — identical contract to ProjectSyncView.
+        since_raw = request.query_params.get("since", "0")
+        try:
+            since = int(since_raw)
+            if since < 0:
+                raise ValueError
+        except (ValueError, TypeError) as err:
+            raise ValidationError({"since": "Must be a non-negative integer."}) from err
+
+        cursor_raw = request.query_params.get("cursor")
+        cursor = SyncCursor.decode(cursor_raw) if cursor_raw else None
+        page_size = ProjectSyncView._resolve_page_size(request)
+
+        # Accessible set: programs the caller has a live membership on, kept as a
+        # queryset so Postgres evaluates it as a single subquery in the delta reads
+        # rather than round-tripping every id into Python.
+        accessible_ids = ProgramMembership.objects.filter(
+            user=cast("_User", request.user), is_deleted=False
+        ).values("program_id")
+
+        # Snapshot the high-water mark BEFORE the delta queries. server_version is
+        # monotonic, so a write landing after this snapshot moves the row forward in
+        # (server_version, id) order — delivered this pull (re-applied under upsert)
+        # or the next (its version > timestamp = next since); never lost. This is
+        # the same concurrency argument pagination.py makes, and the same
+        # watermark-before-rows ordering ProjectSyncView relies on. Neither view
+        # opens a REPEATABLE READ block; both run at READ COMMITTED, and the
+        # ordering — not the isolation level — is what closes the window.
+        #
+        # This slice keys on sync_seq, drawn from the installation-wide program
+        # sequence (ADR-0747, #2498). It used to key on the per-row server_version
+        # and carried the ordering defect ADR-0686 fixed for projects: a hot program
+        # raised the watermark above a cold program's row counters and those rows
+        # dropped out of the delta permanently. The project sequence could not fix
+        # it — programs have no single owning row — so program-scoped writes order
+        # against one installation counter instead, which restores a scalar cursor's
+        # validity without changing the wire contract.
+        #
+        # As in ProjectSyncView, the watermark is session state: a continuation page
+        # echoes the cursor's pinned value instead of recomputing one that could sit
+        # above an already-drained collection's mid-drain write (#2568).
+        timestamp = cursor.watermark if cursor is not None else self._watermark(accessible_ids)
+
+        # Program rows include soft-deleted ones so a program deleted while the
+        # caller is still a member arrives as a tombstone. Memberships cover every
+        # co-member of the caller's programs (offline RBAC + roster), soft-deleted
+        # rows included. Order is fixed — do not reorder without a protocol bump.
+        sources: list[SyncSource] = [
+            (
+                "programs",
+                Program.objects.filter(id__in=accessible_ids, sync_seq__gt=since),
+                SyncProgramSerializer,
+            ),
+            (
+                "program_memberships",
+                ProgramMembership.objects.filter(program_id__in=accessible_ids, sync_seq__gt=since),
+                SyncProgramMembershipSerializer,
+            ),
+        ]
+
+        changes, next_cursor, has_more = paginate_changes(
+            sources,
+            cursor=cursor,
+            page_size=page_size,
+            collect=ProjectSyncView._collect,
+            watermark=timestamp,
+            # Must match the delta filter above: the pager orders on this column
+            # and the sources floor on it. Ordering on one while filtering the
+            # other pages a stream the floor does not bound (ADR-0747, #2498).
+            version_field="sync_seq",
+        )
+
+        return Response(
+            {
+                "changes": changes,
+                "timestamp": timestamp,
+                "next_cursor": next_cursor.encode() if next_cursor is not None else None,
+                "has_more": has_more,
+            }
+        )
+
+    @staticmethod
+    def _watermark(accessible_ids: Any) -> int:
+        """The installation-wide program sequence's high-water mark (ADR-0747, #2498).
+
+        ``ProgramSyncSequence.value`` is the allocator every synced ``Program`` and
+        ``ProgramMembership`` row drew its ``sync_seq`` from, so it is by
+        construction greater than or equal to every row's cursor — the safe upper
+        bound the client adopts as its next ``since``. One row read, no aggregate.
+
+        It used to be ``MAX(server_version)`` across the caller's programs and their
+        memberships. That value was faithful and was not a valid ordering:
+        ``server_version`` counts a single row's saves, so a frequently-edited
+        program raised the checkpoint above every other program's row counter and
+        dropped those rows from the delta permanently (#2498) — the same defect
+        ADR-0686 fixed for projects, one level up.
+
+        ``accessible_ids`` is no longer read: the checkpoint is a property of the
+        installation's write log, not of the caller's accessible set. Scoping it per
+        caller is what made it a maximum-over-many-rows in the first place. The
+        parameter is kept so the call site and ``ProjectSyncView._watermark`` keep
+        one shape.
+        """
+        from trueppm_api.apps.sync.models import ProgramSyncSequence
+
+        value = (
+            ProgramSyncSequence.objects.filter(pk=ProgramSyncSequence.SINGLETON_PK)
+            .values_list("value", flat=True)
+            .first()
+        )
+        return value or 0