trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/timetracking/models.py

@@ -0,0 +1,178 @@
+"""Time-tracking domain models — logged effort and the running timer (ADR-0185 §2).
+
+``TimeEntry`` is the durable, sync-eligible fact; ``ActiveTimer`` is transient live
+state. The split is deliberate (ADR-0185 §2): a ticking timer is derived state, not a
+logged fact, so it is *not* a ``VersionedModel`` and a stopped timer is hard-deleted,
+not soft-deleted. Nothing here broadcasts — a time entry mutates no shared board state
+(ADR-0185 §5).
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from django.conf import settings
+from django.core.validators import MaxValueValidator, MinValueValidator
+from django.db import models
+from django.utils import timezone
+
+from trueppm_api.apps.projects.models import VersionedModel
+
+
+class TimeEntrySource(models.TextChoices):
+    """Provenance of a logged entry — drives the UI/undo affordance."""
+
+    MANUAL = "manual", "Manual"
+    TIMER = "timer", "Timer"
+
+
+class TimeEntry(VersionedModel):
+    """A contributor's logged effort against a task (ADR-0185 §2).
+
+    The durable, sync-eligible record of *where a user's hours went*. The row is owned
+    by the logger: ``user`` is server-set to ``request.user`` and is never client-
+    supplied, so the entry is IDOR-safe by construction. Duration is canonical integer
+    ``minutes`` (1..1440) to avoid the decimal-hours rounding drift the constraint
+    exists to prevent — the client formats ``h:mm``.
+
+    There is **no** uniqueness constraint on ``(user, task, entry_date)``: a contributor
+    may legitimately log multiple entries against the same task on the same day (two
+    sessions). The weekly grid aggregates them.
+    """
+
+    task = models.ForeignKey(
+        "projects.Task",
+        on_delete=models.CASCADE,
+        related_name="time_entries",
+    )
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="time_entries",
+    )
+    minutes = models.PositiveIntegerField(
+        validators=[MinValueValidator(1), MaxValueValidator(1440)],
+    )
+    entry_date = models.DateField(default=timezone.localdate)
+    note = models.CharField(max_length=500, blank=True)
+    source = models.CharField(
+        max_length=10,
+        choices=TimeEntrySource.choices,
+        default=TimeEntrySource.MANUAL,
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    # Soft-delete accountability (issue #1888). The base ``VersionedModel.soft_delete()``
+    # only flips ``is_deleted``, so a removed entry left no trace of *when* or *by whom*
+    # — and the task activity stream, which filtered ``is_deleted=False``, silently
+    # dropped its ``time_logged`` event too. That is an EVM/billing integrity gap: logged
+    # hours could be revised or removed with no record. These fields let the stream
+    # synthesize a ``time_deleted`` event, mirroring the ``TaskComment``/``TaskAttachment``
+    # soft-delete precedent. ``deleted_by`` is the acting user (always the owner — entries
+    # are self-scoped) and SET_NULLs on account deletion, so the event actor goes null.
+    deleted_at = models.DateTimeField(null=True, blank=True)
+    deleted_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="deleted_time_entries",
+    )
+
+    class Meta:
+        db_table = "timetracking_time_entry"
+        indexes = [
+            # Header today/week rollup + weekly grid read.
+            models.Index(fields=["user", "entry_date"]),
+            # Grid cell (task, date) upsert/aggregate.
+            models.Index(fields=["user", "task", "entry_date"]),
+            # Per-project sync delta pull (task → server_version).
+            models.Index(fields=["task", "server_version"]),
+            models.Index(fields=["task", "sync_seq"]),
+        ]
+
+    def __str__(self) -> str:
+        return f"TimeEntry({self.user_id}, {self.minutes}m, {self.entry_date})"
+
+    def soft_delete(self, *, actor: Any | None = None) -> None:
+        """Stamp ``deleted_at``/``deleted_by`` before delegating to the base soft-delete.
+
+        Mirrors ``Dependency.soft_delete()``'s stamping (issue #1888): the base
+        ``VersionedModel.soft_delete()`` persists the whole row, so setting these two
+        fields first writes them in the same UPDATE that flips ``is_deleted``. Without
+        the timestamp the activity stream could not order or surface the ``time_deleted``
+        event, so a removed entry vanished from the ``time_logged`` feed with no trace.
+        """
+        self.deleted_at = timezone.now()
+        self.deleted_by = actor
+        super().soft_delete()
+
+
+class ActiveTimer(models.Model):
+    """The running stopwatch — transient live state, deliberately NOT versioned (ADR-0185 §2).
+
+    Elapsed time is derived (``now - started_at``); the row carries no logged fact, so
+    syncing it as versioned WatermelonDB rows would churn for a value the client
+    recomputes locally. The ``OneToOneField(user)`` is the singleton guarantee — a user
+    has at most one running timer at the DB level (cleaner than a partial unique on a
+    status flag). ``stop`` finalizes it into a ``TimeEntry`` and *deletes* this row
+    (no tombstone to sync); it is recovered after a reload via ``GET /me/timer/``.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    user = models.OneToOneField(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="active_timer",
+    )
+    task = models.ForeignKey(
+        "projects.Task",
+        on_delete=models.CASCADE,
+        related_name="+",
+    )
+    started_at = models.DateTimeField()
+    note = models.CharField(max_length=500, blank=True)
+
+    class Meta:
+        db_table = "timetracking_active_timer"
+
+    def __str__(self) -> str:
+        return f"ActiveTimer({self.user_id} -> {self.task_id})"
+
+
+class TimesheetSubmission(models.Model):
+    """A contributor's "I marked this week done" signal — a per-user-per-week marker (ADR-0224).
+
+    Deliberately **not** a :class:`VersionedModel` (mirrors :class:`ActiveTimer`): submitting a
+    week is an inherently *online* action on a web-first surface, and the row carries no field a
+    client edits offline, so WatermelonDB version/tombstone machinery would churn sync for a
+    boolean-shaped signal. It is the whole submission state machine 0.4 ships — no approver, no
+    lock, no return; the 0.5 approval epic (#100) reads or extends this row's existence +
+    ``submitted_at`` as its "Submitted" signal without migrating :class:`TimeEntry`.
+
+    ``week_start`` is canonicalized to the ISO Monday by the view before write, so the
+    ``(user, week_start)`` uniqueness cannot fragment into off-by-a-day rows. Un-submit hard-
+    deletes the row (no tombstone — not sync-eligible).
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="timesheet_submissions",
+    )
+    week_start = models.DateField()
+    submitted_at = models.DateTimeField()
+
+    class Meta:
+        db_table = "timetracking_timesheet_submission"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["user", "week_start"],
+                name="uniq_timesheet_submission_user_week",
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"TimesheetSubmission({self.user_id}, week of {self.week_start})"

trueppm_api/apps/timetracking/serializers.py

@@ -0,0 +1,175 @@
+"""Serializers for the time-tracking REST surface (ADR-0185 §4)."""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+from typing import Any
+
+from django.conf import settings
+from django.utils import timezone
+from rest_framework import serializers
+
+from trueppm_api.apps.timetracking.models import ActiveTimer, TimeEntry
+
+
+def _backdate_window_days() -> int:
+    """Manual-entry backdate window (settings ``TIMETRACKING_BACKDATE_DAYS``, default 60)."""
+    return int(getattr(settings, "TIMETRACKING_BACKDATE_DAYS", 60))
+
+
+def _timer_max_minutes() -> int:
+    return int(getattr(settings, "TIMETRACKING_TIMER_MAX_MINUTES", 600))
+
+
+class TimeEntrySerializer(serializers.ModelSerializer[TimeEntry]):
+    """Read/write serializer for a single :class:`TimeEntry` (create + author-only PATCH).
+
+    ``task``, ``user``, ``source``, ``server_version`` and ``created_at`` are read-only:
+    the task comes from the nested route (not the body), the owner is server-set
+    (IDOR-safe), and provenance is server-decided. Only ``minutes``/``entry_date``/
+    ``note`` are writable. ``validate_entry_date`` enforces the no-future / backdate-
+    window rule (ADR-0185 §Consequences) — it applies only to manual writes, since timer
+    entries set ``entry_date`` in the service and never pass through this serializer.
+    """
+
+    class Meta:
+        model = TimeEntry
+        fields = [
+            "id",
+            "task",
+            "user",
+            "minutes",
+            "entry_date",
+            "note",
+            "source",
+            "server_version",
+            "created_at",
+        ]
+        read_only_fields = [
+            "id",
+            "task",
+            "user",
+            "source",
+            "server_version",
+            "created_at",
+        ]
+
+    def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
+        """Reject logging time against a *phase* (ADR-0293) — code ``time_log_on_phase``.
+
+        A phase is a rollup: its effort is the sum of its children's logged time, so a
+        direct entry against the phase itself would double-count. The target task is
+        the nested-route task on create (passed in context by the view) or the entry's
+        own task on PATCH. Enforced here so an MCP/agent caller is blocked identically
+        to the UI (ADR-0112). Non-phase leaves — including a leaf-with-subtasks — accept
+        time as before.
+        """
+        from trueppm_api.apps.projects.models import task_is_phase
+
+        task = self.context.get("task") or getattr(self.instance, "task", None)
+        if task is not None and task_is_phase(task):
+            raise serializers.ValidationError(
+                serializers.ErrorDetail(
+                    "Time cannot be logged against a phase — it rolls up the logged "
+                    "time of its child tasks. Log against a leaf task instead.",
+                    code="time_log_on_phase",
+                )
+            )
+        return attrs
+
+    def validate_entry_date(self, value: date) -> date:
+        today = timezone.localdate()
+        # Allow one day past the server's local date. "Today" is the *contributor's* calendar
+        # day, and their timezone can be up to ~a day ahead of the server's (e.g. any zone vs a
+        # UTC-configured server, the default). Without this grace an ahead-of-server user
+        # logging "today" would hit a spurious 400 (#1926). Genuine future-dated logging is
+        # still blocked (client offers no future day) and >1 day ahead exceeds any real skew.
+        if value > today + timedelta(days=1):
+            raise serializers.ValidationError("Entry date cannot be in the future.")
+        window = _backdate_window_days()
+        if value < today - timedelta(days=window):
+            raise serializers.ValidationError(
+                f"Entry date cannot be more than {window} days in the past."
+            )
+        return value
+
+
+class TimeEntryWeeklySerializer(serializers.ModelSerializer[TimeEntry]):
+    """Enriched read serializer for the weekly cross-project grid (ADR-0185 §4).
+
+    Carries the task and project labels the grid renders so the client needs no second
+    round-trip. The viewset ``select_related("task", "task__project")``, so these nested
+    reads add no per-row query (N+1-safe — asserted by ``assertNumQueries``).
+    """
+
+    task_short_id = serializers.CharField(source="task.short_id", read_only=True)
+    task_name = serializers.CharField(source="task.name", read_only=True)
+    project = serializers.UUIDField(source="task.project_id", read_only=True)
+    project_code = serializers.CharField(source="task.project.code", read_only=True)
+    project_name = serializers.CharField(source="task.project.name", read_only=True)
+
+    class Meta:
+        model = TimeEntry
+        fields = [
+            "id",
+            "task",
+            "task_short_id",
+            "task_name",
+            "project",
+            "project_code",
+            "project_name",
+            "minutes",
+            "entry_date",
+            "note",
+            "source",
+            "server_version",
+            "created_at",
+        ]
+
+
+class ActiveTimerSerializer(serializers.ModelSerializer[ActiveTimer]):
+    """Read serializer for the running timer (``GET /me/timer/`` active branch).
+
+    ``elapsed_seconds`` and ``stale`` are server-computed from the authoritative
+    ``started_at`` clock so every device agrees regardless of when it last polled.
+    ``stale`` flips once elapsed exceeds the ceiling, prompting the UI rather than
+    silently logging a weekend (ADR-0185 §2).
+    """
+
+    task_short_id = serializers.CharField(source="task.short_id", read_only=True)
+    task_name = serializers.CharField(source="task.name", read_only=True)
+    project = serializers.UUIDField(source="task.project_id", read_only=True)
+    elapsed_seconds = serializers.SerializerMethodField()
+    stale = serializers.SerializerMethodField()
+
+    class Meta:
+        model = ActiveTimer
+        fields = [
+            "id",
+            "task",
+            "task_short_id",
+            "task_name",
+            "project",
+            "started_at",
+            "elapsed_seconds",
+            "note",
+            "stale",
+        ]
+
+    def get_elapsed_seconds(self, obj: ActiveTimer) -> int:
+        return int((timezone.now() - obj.started_at).total_seconds())
+
+    def get_stale(self, obj: ActiveTimer) -> bool:
+        return self.get_elapsed_seconds(obj) > _timer_max_minutes() * 60
+
+
+class TimerStartSerializer(serializers.Serializer):  # type: ignore[type-arg]
+    """Validate the ``POST /me/timer/start`` body (ADR-0185 §4).
+
+    Only ``task`` (uuid) and an optional ``note`` are accepted. Task resolution,
+    membership scoping (404), and the ``can_log_time`` role gate (403) are enforced in
+    the view against a membership-scoped queryset so existence is never leaked.
+    """
+
+    task = serializers.UUIDField()
+    note = serializers.CharField(required=False, allow_blank=True, max_length=500, default="")

trueppm_api/apps/timetracking/services.py

@@ -0,0 +1,211 @@
+"""Service layer for time tracking (ADR-0185 Durable Execution §4).
+
+Every operation here is a **synchronous** DB transaction with no async side effect:
+no Celery ``.delay()``, no ``broadcast_board_event()``, no CPM recompute. A time entry
+never touches ``Task`` dates, so it cannot trigger a schedule recalculation. There is
+nothing to dead-letter and nothing to broadcast (ADR-0185 §5) — the negative is
+deliberate.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import TYPE_CHECKING, Any
+
+from django.conf import settings
+from django.db import transaction
+from django.utils import timezone
+
+from trueppm_api.apps.timetracking.models import ActiveTimer, TimeEntry, TimeEntrySource
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import User as _User
+
+    from trueppm_api.apps.projects.models import Task
+
+
+def _timer_max_minutes() -> int:
+    """The stale-timer ceiling (settings ``TIMETRACKING_TIMER_MAX_MINUTES``, default 600)."""
+    return int(getattr(settings, "TIMETRACKING_TIMER_MAX_MINUTES", 600))
+
+
+def _member_can_still_log_time(user: _User, project_id: Any) -> bool:
+    """Role >= Member on ``project_id`` right now, with no ``request`` in hand (#4318).
+
+    Mirrors ``can_user_log_time`` (``access/permissions.py``), which is the
+    authoritative predicate everywhere a request is available — but this service
+    layer only ever has a ``user``, so it re-derives the role directly from a live
+    (non-soft-deleted) ``ProjectMembership`` row rather than through the
+    request-cached helper. A boolean, not a raise: both ``start_timer``'s
+    second-start and ``stop_timer`` *decide* what to do with a timer whose access
+    has lapsed (discard it) rather than refuse the request outright — see each
+    function's docstring for why discard, not a 403, is the answer both places.
+    """
+    from trueppm_api.apps.access.models import ProjectMembership, Role
+
+    role = (
+        # project__is_deleted (#4577): ``_membership_role`` floors it, so a trashed
+        # project confers no role there — and this mirror must agree, or a timer
+        # left running on a trashed project would still finalize into it.
+        ProjectMembership.objects.filter(
+            project_id=project_id, user=user, is_deleted=False, project__is_deleted=False
+        )
+        .values_list("role", flat=True)
+        .first()
+    )
+    return role is not None and role >= Role.MEMBER
+
+
+def _project_is_archived_now(project_id: Any) -> bool:
+    """Direct, request-less archived check (#4318).
+
+    Mirrors ``_is_project_archived`` (``access/permissions.py``), which is
+    request-cached and unavailable here for the same reason
+    :func:`_member_can_still_log_time` re-derives role directly instead of calling
+    the request-cached ``_membership_role``.
+    """
+    from trueppm_api.apps.projects.models import Project
+
+    return Project.objects.filter(pk=project_id, is_archived=True).exists()
+
+
+def log_time(
+    *,
+    user: _User,
+    task: Task,
+    minutes: int,
+    entry_date: date | None = None,
+    note: str = "",
+    source: str = TimeEntrySource.MANUAL,
+) -> TimeEntry:
+    """Create a logged :class:`TimeEntry`.
+
+    ``user`` is the server-set owner (never client-supplied); the caller resolves it
+    from ``request.user``. ``entry_date`` defaults to the caller's local "today"
+    (``timezone.localdate()``), matching ``/me/work``'s today bucket.
+    """
+    return TimeEntry.objects.create(
+        user=user,
+        task=task,
+        minutes=minutes,
+        entry_date=entry_date or timezone.localdate(),
+        note=note,
+        source=source,
+    )
+
+
+@transaction.atomic
+def start_timer(*, user: _User, task: Task, note: str = "") -> tuple[ActiveTimer, TimeEntry | None]:
+    """Start a running timer for ``user``.
+
+    Second-start (#1415): if a timer is already running it is atomically stopped and
+    logged first, and the finalized :class:`TimeEntry` is returned alongside the new
+    timer (the UI surfaces it in the undo toast). The ``OneToOneField(user)`` guarantees
+    a single live timer, so this can never leave two rows. ``select_for_update`` locks
+    the existing timer row so a concurrent double-start serializes rather than racing.
+
+    **The existing timer is re-checked before it is finalized (#4318).** A member who
+    starts a timer on project A, loses write access there (archived, removed, or
+    demoted below Member), and then legitimately starts a *new* timer on project B
+    must not have project A's stale timer silently logged as a ``TimeEntry`` — that
+    would create a write on a project they can no longer write to, through a path
+    (starting work elsewhere) that has nothing to do with project A. So this applies
+    the same **discard** semantics the ``ProjectMembership`` revocation hook uses
+    (``access/signals.py``): if project A is archived, or the caller can no longer
+    log time there, the existing ``ActiveTimer`` row is simply deleted, with no
+    ``TimeEntry`` created. The common case (membership still live) is unaffected —
+    the prior timer is finalized exactly as before. This deliberately never *raises*:
+    a stale timer on an unrelated, inaccessible project must not block a legitimate
+    new start on a project the caller can still write to.
+    """
+    finalized: TimeEntry | None = None
+    existing = (
+        ActiveTimer.objects.select_for_update().select_related("task").filter(user=user).first()
+    )
+    if existing is not None:
+        existing_project_id = existing.task.project_id
+        if _project_is_archived_now(existing_project_id) or not _member_can_still_log_time(
+            user, existing_project_id
+        ):
+            existing.delete()
+        else:
+            finalized = _finalize(existing)
+    timer = ActiveTimer.objects.create(
+        user=user,
+        task=task,
+        started_at=timezone.now(),
+        note=note,
+    )
+    return timer, finalized
+
+
+@transaction.atomic
+def stop_timer(*, user: _User) -> TimeEntry | None:
+    """Stop ``user``'s running timer, finalize it into a :class:`TimeEntry`, delete the row.
+
+    Returns ``None`` when no timer is running (or when the timer is discarded —
+    see below) so the caller can respond ``409`` — a duplicate stop is a no-op,
+    never a double-log or a 500. ``select_for_update`` makes concurrent stops
+    serialize: the loser finds no row and gets ``None``.
+
+    **Re-checks the archived-project gate and live Member+ role before finalizing
+    (#4318).** This is defence-in-depth, not the primary control: a ``ProjectMembership``
+    revocation (removal, or demotion below Member) deletes the user's ``ActiveTimer`` rows
+    outright via the ``pre_save`` eviction hook in ``access/signals.py`` — the discard
+    decision made for #4318 — so in the common revoked-member case there is no row left
+    here to stop, and the caller already gets the existing ``409``. What this still catches:
+    an **archived** project, which does not touch membership and so never fires that hook,
+    and any ``ActiveTimer`` that predates it.
+
+    **Discard, never raise, on either check — round 2 of #4318.** The first pass raised
+    ``PermissionDenied`` (403) here, which was itself a bug: raising left the
+    ``ActiveTimer`` row in place, so a timer on a now-archived project could **never**
+    be stopped — every retry re-hit the same 403, and the web client
+    (``useActiveTimer.ts``) restores the optimistically-cleared timer into its cache on
+    any non-409 error, so the chip reappeared and the user was stuck retrying forever.
+    Deleting the row and returning ``None`` instead routes through the exact same,
+    already-handled path as "no timer is running": the view answers the ordinary
+    ``409``, which the client already clears silently, no restore and no error toast.
+    This is the same resolution ``start_timer``'s second-start discard and the
+    ``ProjectMembership`` revocation hook both already use — one semantics (discard a
+    timer whose access has lapsed) applied everywhere it can arise, rather than two
+    different outcomes for the same underlying situation. Deliberately does **not**
+    raise after the delete, even just to signal the refusal for observability: this
+    function runs inside ``@transaction.atomic`` under ``ATOMIC_REQUESTS``, and DRF's
+    exception handler calls ``set_rollback()`` for any raised ``APIException`` — which
+    would roll back the very delete meant to free the caller from this state.
+    """
+    timer = ActiveTimer.objects.select_for_update().select_related("task").filter(user=user).first()
+    if timer is None:
+        return None
+    project_id = timer.task.project_id
+    if _project_is_archived_now(project_id) or not _member_can_still_log_time(user, project_id):
+        timer.delete()
+        return None
+    return _finalize(timer)
+
+
+def _finalize(timer: ActiveTimer) -> TimeEntry:
+    """Convert a running timer into a logged ``TimeEntry`` and delete the timer row.
+
+    Elapsed seconds are rounded to the nearest minute (floored at 1 so a sub-minute
+    timer still logs something) and **capped** at the stale ceiling so a timer left
+    running over a weekend logs the ceiling, not thousands of minutes. The cap is also
+    clamped to the model's 1440-minute maximum to preserve the row invariant even if the
+    ceiling is misconfigured above 24 h. The entry dates to ``localdate(started_at)`` so
+    a timer crossing midnight is attributed to the day the work started. Must be called
+    inside a transaction (``start_timer`` / ``stop_timer`` provide it).
+    """
+    elapsed_seconds = (timezone.now() - timer.started_at).total_seconds()
+    minutes = max(1, round(elapsed_seconds / 60))
+    minutes = min(minutes, _timer_max_minutes(), 1440)
+    entry = TimeEntry.objects.create(
+        user_id=timer.user_id,
+        task_id=timer.task_id,
+        minutes=minutes,
+        entry_date=timezone.localdate(timer.started_at),
+        note=timer.note,
+        source=TimeEntrySource.TIMER,
+    )
+    timer.delete()
+    return entry

trueppm_api/apps/timetracking/urls.py

@@ -0,0 +1,47 @@
+"""URL patterns for the time-tracking app (ADR-0185 §4)."""
+
+from __future__ import annotations
+
+from django.urls import path
+
+from trueppm_api.apps.timetracking.views import (
+    MeTimeEntryDetailView,
+    MeTimeEntryWeeklyView,
+    MeTimerStartView,
+    MeTimerStopView,
+    MeTimerView,
+    MeTimesheetSubmitView,
+    TaskTimeEntryView,
+)
+
+urlpatterns = [
+    # Per-task, caller-scoped create + list.
+    path(
+        "tasks/<uuid:task_pk>/time-entries/",
+        TaskTimeEntryView.as_view(),
+        name="task-time-entries",
+    ),
+    # Weekly cross-project rollup (grid + header). Registered before the detail
+    # route; the trailing-uuid detail route cannot shadow the bare list path.
+    path(
+        "me/time-entries/",
+        MeTimeEntryWeeklyView.as_view(),
+        name="me-time-entries",
+    ),
+    # Author-only edit/delete.
+    path(
+        "me/time-entries/<uuid:pk>/",
+        MeTimeEntryDetailView.as_view(),
+        name="me-time-entry-detail",
+    ),
+    # Weekly submission marker — submit / un-submit (ADR-0224).
+    path(
+        "me/timesheets/<str:week_start>/submit",
+        MeTimesheetSubmitView.as_view(),
+        name="me-timesheet-submit",
+    ),
+    # Running timer (user singleton).
+    path("me/timer/", MeTimerView.as_view(), name="me-timer"),
+    path("me/timer/start", MeTimerStartView.as_view(), name="me-timer-start"),
+    path("me/timer/stop", MeTimerStopView.as_view(), name="me-timer-stop"),
+]