trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/observability/views.py

@@ -0,0 +1,537 @@
+"""Health endpoints for Beat liveness + dead-letter observability (ADR-0081, ADR-0084)."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+from django.conf import settings
+from django.db.models import Count
+from django.http import HttpResponse
+from django.utils import timezone
+from drf_spectacular.utils import OpenApiResponse, extend_schema, inline_serializer
+from rest_framework import serializers, status
+from rest_framework.decorators import api_view, permission_classes, throttle_classes
+from rest_framework.permissions import AllowAny
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.throttling import ScopedRateThrottle, SimpleRateThrottle
+from rest_framework.views import APIView
+
+from trueppm_api.apps.access.permissions import IsWorkspaceOperator
+from trueppm_api.apps.observability.models import BeatHeartbeat, PurgeRun
+from trueppm_api.apps.observability.selectors import (
+    get_readiness,
+    get_system_health,
+    notification_email_signals,
+)
+from trueppm_api.apps.observability.serializers import (
+    PurgeRunQueuedSerializer,
+    PurgeRunRequestSerializer,
+    RetentionImpactQuerySerializer,
+    RetentionImpactSerializer,
+    RetentionStateSerializer,
+    RetentionUpdateSerializer,
+    TelemetryTestExportResultSerializer,
+)
+from trueppm_api.apps.observability.services import (
+    apply_retention_update,
+    compute_impact,
+    get_retention_state,
+    run_telemetry_test_export,
+    start_purge_run,
+)
+from trueppm_api.apps.scheduling.models import FailedTask, FailedTaskStatus
+from trueppm_api.core.throttling import ReadyzRateThrottle
+
+# Matches trueppm_api.apps.observability.tasks._SINGLETON_KEY — the single row.
+_SINGLETON_KEY = 1
+
+# Prometheus 0.0.4 text exposition content type. Hard-coded rather than importing
+# prometheus_client — no metrics client is a dependency (ADR-0084).
+_PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
+
+_DEAD_LETTER_METRIC = "trueppm_task_dead_letter_parked"
+
+# Outbound-email health gauges (#2886). Before these, no Prometheus rule in the
+# chart referenced email at all — the only email-failure signal in the product was
+# the System Health card, which an operator has to be looking at. Served as
+# Prometheus text exposition on the same pattern as the dead-letter gauge (derived
+# on read from committed rows, so a value recorded by the Celery worker is visible
+# from the web process) and kept in sync with the chart's PromQL by
+# scripts/check-helm-metric-names.py.
+_EMAIL_FAILED_METRIC = "trueppm_email_sends_failed_recent"
+_EMAIL_SENT_METRIC = "trueppm_email_sends_delivered_recent"
+_EMAIL_QUEUED_AGING_METRIC = "trueppm_email_queue_aging"
+_EMAIL_TRANSPORT_UNAVAILABLE_METRIC = "trueppm_email_transport_unavailable"
+
+
+def _escape_label_value(value: str) -> str:
+    """Escape a Prometheus label value (backslash, double-quote, newline)."""
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+
+
+@extend_schema(
+    summary="Readiness probe (dependency-aware)",
+    description=(
+        'Returns **200** with `{"status": "ok", "checks": {...}, "migration_state": '
+        '"in_sync"}` only when every hard dependency answers a live round-trip: the '
+        "primary database (a bounded `SELECT 1`), the Valkey/Redis cache (a "
+        "write-then-read), and the migration state. Returns **503** with the failing "
+        "dependency marked `fail` otherwise. The migration check keeps a rolling "
+        "upgrade from routing traffic to a pod whose schema and code disagree, in "
+        "both directions: `migration_state` is `behind` when this image ships "
+        "migrations the database has not applied (mid-upgrade), `ahead` when the "
+        "database records migrations this image does not ship (the image was rolled "
+        "back without restoring the schema), `unknown` when the check itself failed, "
+        "and `in_sync` otherwise. `ahead` is not a data-compatibility verdict — a "
+        "downgrade across a destructive migration still needs a restore from backup — "
+        "and an operator performing a classified additive-only rollback can re-open "
+        "readiness for it with `TRUEPPM_READYZ_ALLOW_DB_AHEAD` without hiding the "
+        "reported state. "
+        "Unlike the shallow `/api/v1/health/` liveness probe — which always returns "
+        "200 while the process is up — this endpoint gates a pod out of the Service's "
+        "endpoints when its database or cache is dead. No authentication required, so "
+        "kubelet can call it; the body carries only coarse `ok`/`fail` per dependency "
+        "plus the coarse migration-state enum, and never any connection string, host, "
+        "migration name, or driver error text. Rate-limited on its own scope "
+        "(`TRUEPPM_THROTTLE_READYZ_RATE`, generous by default) rather than exempted "
+        "from throttling entirely, because unlike `/health/` it does real database "
+        "and cache work per call (#2820)."
+    ),
+    responses={
+        200: inline_serializer(
+            "ReadyzResponse",
+            {
+                "status": serializers.CharField(),
+                "checks": serializers.DictField(child=serializers.CharField()),
+                "migration_state": serializers.CharField(),
+            },
+        ),
+        503: OpenApiResponse(description="One or more dependencies are unavailable."),
+    },
+    auth=[],
+    tags=["meta"],
+)
+@api_view(["GET"])
+@permission_classes([AllowAny])
+@throttle_classes([ReadyzRateThrottle])
+def readyz(_request: Request) -> Response:
+    """Report dependency-aware readiness for Kubernetes readiness/startup probes.
+
+    Deliberately unauthenticated: kubelet issues probe requests with no
+    credentials, and the dependency-aware ``/health/system/`` endpoint is
+    ``IsWorkspaceOperator``-gated (superuser only, #4009) so it cannot serve as a
+    probe (#1894). Safe to expose
+    because the response is coarse — ``ok``/``fail`` per dependency plus a
+    four-value ``migration_state`` enum, with no infrastructure detail — and the
+    probes themselves are read-only round-trips.
+
+    ``migration_state`` is additive (#2806): ``checks`` keeps its existing keys and
+    ``ok``/``fail`` values, so a probe or scraper reading only ``status``/``checks``
+    is unaffected.
+
+    Rate-limited on its own scope (``ReadyzRateThrottle``, #2820) instead of the
+    full throttle exemption ``/health/``/``/edition/`` get: unlike those two this
+    view does a real database and cache round-trip per call, so an unauthenticated
+    caller who reaches the pod IP directly (the probe path bypasses the Ingress)
+    must not be able to drive unbounded load with zero rate limit.
+    """
+    ready, checks, migration_state = get_readiness()
+    return Response(
+        {
+            "status": "ok" if ready else "fail",
+            "checks": checks,
+            "migration_state": migration_state,
+        },
+        status=status.HTTP_200_OK if ready else status.HTTP_503_SERVICE_UNAVAILABLE,
+    )
+
+
+@extend_schema(
+    summary="Celery Beat heartbeat status",
+    description=(
+        "Returns the last recorded Celery Beat heartbeat and whether it is stale "
+        "(older than TRUEPPM_BEAT_STALE_SECONDS). Responds **200** when fresh and "
+        "**503** when stale or never recorded, so status-code-driven monitoring "
+        "(e.g. Prometheus with a bearer token) can alert without parsing the body. "
+        "Requires a workspace operator (superuser) account — it exposes operational "
+        "state. Basic unauthenticated liveness lives at `/api/v1/health/`."
+    ),
+    responses={
+        200: inline_serializer(
+            "BeatHealthResponse",
+            {
+                "last_heartbeat": serializers.DateTimeField(allow_null=True),
+                "stale": serializers.BooleanField(),
+            },
+        ),
+        503: OpenApiResponse(description="Heartbeat is stale or has never been recorded."),
+    },
+    tags=["meta"],
+)
+@api_view(["GET"])
+@permission_classes([IsWorkspaceOperator])
+def beat_health(_request: Request) -> Response:
+    """Report Beat liveness for admin diagnostics and token-auth monitoring.
+
+    Staleness is computed on read so the endpoint works precisely when Beat and
+    the workers are down — the one detector that survives total task-infra death.
+    """
+    row = BeatHeartbeat.objects.filter(singleton_key=_SINGLETON_KEY).first()
+    if row is None:
+        return Response(
+            {"last_heartbeat": None, "stale": True},
+            status=status.HTTP_503_SERVICE_UNAVAILABLE,
+        )
+
+    age_seconds = (timezone.now() - row.last_heartbeat).total_seconds()
+    stale = age_seconds > settings.TRUEPPM_BEAT_STALE_SECONDS
+    return Response(
+        {"last_heartbeat": row.last_heartbeat, "stale": stale},
+        status=status.HTTP_503_SERVICE_UNAVAILABLE if stale else status.HTTP_200_OK,
+    )
+
+
+@extend_schema(
+    summary="Dead-letter parked-task metrics (Prometheus)",
+    description=(
+        "Prometheus 0.0.4 text exposition of permanently dead-lettered Celery "
+        "tasks currently awaiting operator action, labelled by `task_name`. "
+        "Derived on read from the `FailedTask` table — no metrics client or "
+        "scrape agent runs in-process (ADR-0084). A gauge, not a counter: the "
+        "value falls when a task is dismissed, retried, or purged. Requires a "
+        "workspace operator (superuser) account; scrape with a bearer token. The "
+        "OSS receiver also emits a structured WARNING log line per new dead-letter, so "
+        "log-based alerting works without scraping this endpoint."
+    ),
+    responses={
+        200: OpenApiResponse(description="Prometheus text-format dead-letter gauge."),
+    },
+    tags=["meta"],
+)
+@api_view(["GET"])
+@permission_classes([IsWorkspaceOperator])
+def dead_letter_metrics(_request: Request) -> HttpResponse:
+    """Expose the parked dead-letter gauge in Prometheus text format.
+
+    Cross-process correct: the count is read from committed `FailedTask` rows,
+    so it reflects dead-letters recorded by the Celery worker even though this
+    endpoint is served by the web process (an in-process counter would not).
+    """
+    rows = (
+        FailedTask.objects.filter(status=FailedTaskStatus.DEAD)
+        .values("task_name")
+        .annotate(n=Count("id"))
+        .order_by("task_name")
+    )
+
+    lines = [
+        f"# HELP {_DEAD_LETTER_METRIC} Permanently dead-lettered Celery tasks "
+        "currently awaiting operator action, by task name.",
+        f"# TYPE {_DEAD_LETTER_METRIC} gauge",
+    ]
+    for row in rows:
+        label = _escape_label_value(row["task_name"])
+        lines.append(f'{_DEAD_LETTER_METRIC}{{task_name="{label}"}} {row["n"]}')
+
+    body = "\n".join(lines) + "\n"
+    return HttpResponse(body, content_type=_PROMETHEUS_CONTENT_TYPE)
+
+
+@extend_schema(
+    summary="Outbound-email health metrics (Prometheus)",
+    description=(
+        "Prometheus 0.0.4 text exposition of outbound-email health, so a dead SMTP "
+        "relay pages someone instead of waiting to be noticed on the System Health "
+        "page (#2886). Four gauges, all derived on read from committed state — no "
+        "metrics client or scrape agent runs in-process (ADR-0084):\n\n"
+        "- `trueppm_email_sends_failed_recent` — notification emails that "
+        "permanently failed (attempts exhausted) in the last hour.\n"
+        "- `trueppm_email_sends_delivered_recent` — notification emails delivered in "
+        "the last hour. Paired with the above, `failed > 0 and delivered == 0` is the "
+        "dead-relay fingerprint.\n"
+        "- `trueppm_email_queue_aging` — emails still queued more than an hour after "
+        "the notification was created, i.e. the drain is not completing rows at all.\n"
+        "- `trueppm_email_transport_unavailable` — `1` when the workspace has an SMTP "
+        "transport configured whose stored credential will not decrypt, so no mail "
+        "can be sent until an operator re-enters it; `0` otherwise.\n\n"
+        "Requires a workspace operator (superuser) account; scrape with a bearer "
+        "token. Needs its own scrape job — these are not OTLP metrics."
+    ),
+    responses={
+        200: OpenApiResponse(description="Prometheus text-format outbound-email gauges."),
+    },
+    tags=["meta"],
+)
+@api_view(["GET"])
+@permission_classes([IsWorkspaceOperator])
+def email_metrics(_request: Request) -> HttpResponse:
+    """Expose the outbound-email health gauges in Prometheus text format.
+
+    Cross-process correct for the same reason the dead-letter gauge is: every value
+    is read from committed rows (or, for the transport gauge, from the stored
+    ciphertext plus the live encryption key), so a failure recorded by the Celery
+    worker is visible from the web process serving this endpoint.
+    """
+    from trueppm_api.apps.notifications.email_backend import TRANSPORT_UNDECRYPTABLE
+
+    signals = notification_email_signals()
+    unavailable = 1 if signals["transport"] == TRANSPORT_UNDECRYPTABLE else 0
+
+    gauges: list[tuple[str, str, int]] = [
+        (
+            _EMAIL_FAILED_METRIC,
+            "Notification emails that permanently failed to send in the last hour.",
+            int(signals["failed_recent"]),
+        ),
+        (
+            _EMAIL_SENT_METRIC,
+            "Notification emails successfully delivered in the last hour.",
+            int(signals["sent_recent"]),
+        ),
+        (
+            _EMAIL_QUEUED_AGING_METRIC,
+            "Notification emails still queued more than an hour after creation.",
+            int(signals["queued_aging"]),
+        ),
+        (
+            _EMAIL_TRANSPORT_UNAVAILABLE_METRIC,
+            "1 when the configured SMTP credential cannot be decrypted, else 0.",
+            unavailable,
+        ),
+    ]
+
+    lines: list[str] = []
+    for name, help_text, value in gauges:
+        lines.extend(
+            [
+                f"# HELP {name} {help_text}",
+                f"# TYPE {name} gauge",
+                f"{name} {value}",
+            ]
+        )
+
+    body = "\n".join(lines) + "\n"
+    return HttpResponse(body, content_type=_PROMETHEUS_CONTENT_TYPE)
+
+
+@extend_schema(
+    summary="System health overview (operator dashboard)",
+    description=(
+        "Aggregated, read-only snapshot of the durable-execution layer for the "
+        "workspace-admin System Health dashboard (#692, ADR-0172): five component "
+        "status cards (outbox dispatcher, Celery Beat, dead-letter alerting, "
+        "notification dispatcher, retention purge), the Beat heartbeat panel and "
+        "configured schedule, a dead-letter summary, the read-only retention "
+        "configuration, and the read-only telemetry (OpenTelemetry exporter) "
+        "posture — export enabled flag, endpoint, protocol, sampler, and per-signal "
+        "toggles (never the OTLP headers, which carry the export token), and the "
+        "security posture — whether rate limiting is on, and `client_address`: "
+        "which address the per-IP throttles keyed THIS request on under "
+        "`TRUEPPM_NUM_PROXIES`, with the raw peer and `X-Forwarded-For` chain it "
+        "was resolved from and a `status` verdict, so an operator can check the "
+        "proxy-depth setting against the path their own request took. Composes "
+        "existing committed state and settings — no payloads or task "
+        "arguments are exposed here. Always responds 200 with statuses in the body "
+        "(unlike `/health/beat/`, which is a 200/503 probe). Requires a workspace "
+        "operator (superuser) account."
+    ),
+    responses={
+        200: inline_serializer(
+            "SystemHealthResponse",
+            {
+                "generated_at": serializers.DateTimeField(),
+                "components": serializers.ListField(child=serializers.DictField()),
+                "beat": serializers.DictField(),
+                "scheduled_tasks": serializers.ListField(child=serializers.DictField()),
+                "dead_letter": serializers.DictField(),
+                "retention": serializers.ListField(child=serializers.DictField()),
+                "telemetry": serializers.DictField(),
+                "security": serializers.DictField(),
+            },
+        ),
+    },
+    tags=["meta"],
+)
+@api_view(["GET"])
+@permission_classes([IsWorkspaceOperator])
+def system_health(request: Request) -> Response:
+    """Return the aggregated System Health overview payload.
+
+    All figures are read from committed rows, so they reflect work done by the
+    Celery worker and Beat processes even though this is served by the web
+    process. Safe to poll on the dashboard's 10 s refresh — see
+    ``observability.selectors.get_system_health`` for the query budget.
+    """
+    return Response(get_system_health(request))
+
+
+@extend_schema(
+    methods=["GET"],
+    summary="Retention policy editor state",
+    description=(
+        "Returns the editable retention policy for the six operational tables "
+        "(event history, task runs, webhook deliveries, import requests, sync "
+        "batches, soft-deleted projects) with estimated row counts and sizes, the "
+        "purge schedule, and the "
+        "seven most recent purge runs. Row counts and sizes are PostgreSQL "
+        "estimates. Workspace operators tune these from Settings → System health → "
+        "Retention & purge (ADR-0173). Requires a workspace operator (superuser) "
+        "account."
+    ),
+    responses={200: RetentionStateSerializer},
+    tags=["meta"],
+)
+@extend_schema(
+    methods=["PATCH"],
+    summary="Update retention policy and schedule",
+    description=(
+        "Persist retention-window overrides and/or the purge schedule, then return "
+        "the refreshed editor state. Lowering a window makes more data purge-eligible "
+        "on the next run — irreversible. Requires a workspace operator (superuser) "
+        "account."
+    ),
+    request=RetentionUpdateSerializer,
+    responses={200: RetentionStateSerializer},
+    tags=["meta"],
+)
+@api_view(["GET", "PATCH"])
+@permission_classes([IsWorkspaceOperator])
+def retention_settings(request: Request) -> Response:
+    """Read or update the retention policy + schedule (ADR-0173 §G).
+
+    Overrides layer over the ADR-0081 settings defaults — an absent override means
+    the deployment's configured default is used, so behaviour is unchanged until an
+    operator saves a value here.
+    """
+    if request.method == "PATCH":
+        serializer = RetentionUpdateSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        apply_retention_update(serializer.validated_data)
+
+    return Response(RetentionStateSerializer(get_retention_state()).data)
+
+
+@extend_schema(
+    summary="Estimate purge impact at a proposed retention window",
+    description=(
+        "Returns how many rows (and best-effort bytes) would become purge-eligible "
+        "for `key` at the proposed `value` (its native unit — days, or hours for sync "
+        "batches). A pure count: nothing is deleted. Backs the dirty-state "
+        "irreversibility warning when an operator lowers a window. Requires a "
+        "workspace operator (superuser) account."
+    ),
+    parameters=[RetentionImpactQuerySerializer],
+    responses={200: RetentionImpactSerializer},
+    tags=["meta"],
+)
+@api_view(["GET"])
+@permission_classes([IsWorkspaceOperator])
+def retention_impact(request: Request) -> Response:
+    """Count rows that would become purge-eligible at a proposed window."""
+    query = RetentionImpactQuerySerializer(data=request.query_params)
+    query.is_valid(raise_exception=True)
+    rows, eligible_bytes = compute_impact(
+        query.validated_data["key"], query.validated_data["value"]
+    )
+    return Response({"eligible_rows": rows, "eligible_bytes": eligible_bytes})
+
+
+@extend_schema(
+    summary="Run a purge now (or dry-run)",
+    description=(
+        "Dispatch the retention purge coordinator across all six operational tables. "
+        "`dry_run=true` counts eligible rows without deleting. Best-effort dispatch: "
+        "returns 202 with the new run's id; the run completes asynchronously and "
+        "appears in the recent-runs log. Requires a workspace operator (superuser) "
+        "account."
+    ),
+    request=PurgeRunRequestSerializer,
+    responses={202: PurgeRunQueuedSerializer},
+    tags=["meta"],
+)
+@api_view(["POST"])
+@permission_classes([IsWorkspaceOperator])
+def retention_runs(request: Request) -> Response:
+    """Queue a manual purge or dry-run; returns 202 with the run id (ADR-0173 §G).
+
+    Rejects with 409 when a run started within the coordinator's lock window is
+    still in progress — an end-to-end single-flight guard on top of the worker-side
+    Redis lock, so a rapid double-click can't mint duplicate runs. The window bound
+    (not "any RUNNING row") prevents a worker that died mid-run from blocking all
+    future runs with a permanently-RUNNING orphan.
+    """
+    in_flight_cutoff = timezone.now() - timedelta(seconds=settings.RETENTION_PURGE_INFLIGHT_SECONDS)
+    if PurgeRun.objects.filter(
+        state=PurgeRun.State.RUNNING, started_at__gte=in_flight_cutoff
+    ).exists():
+        return Response(
+            {"detail": "A purge run is already in progress."},
+            status=status.HTTP_409_CONFLICT,
+        )
+
+    serializer = PurgeRunRequestSerializer(data=request.data)
+    serializer.is_valid(raise_exception=True)
+    run = start_purge_run(dry_run=serializer.validated_data["dry_run"])
+    return Response(
+        {"queued": True, "run_id": str(run.id)},
+        status=status.HTTP_202_ACCEPTED,
+    )
+
+
+class TelemetryTestThrottle(ScopedRateThrottle):
+    """Scoped throttle for the telemetry test-export probe (rate ``telemetry_test``).
+
+    Bounds how often an admin can trigger an outbound canary / reachability probe,
+    so the button can't be looped to pin request workers against a dead collector
+    (each call holds a worker for up to TELEMETRY_TEST_EXPORT_TIMEOUT_SECONDS).
+
+    ``ScopedRateThrottle`` normally reads its scope from ``view.throttle_scope``,
+    but this is a function-based ``@api_view`` that cannot carry that attribute, so
+    the scope is bound from this class instead (mirrors ``MonteCarloRunThrottle``,
+    #1552). Without this override ``self.scope`` resolves to ``None`` and the
+    throttle silently no-ops.
+    """
+
+    scope = "telemetry_test"
+
+    def allow_request(self, request: Request, view: APIView) -> bool:
+        # Bind the fixed class scope rather than off the view (an @api_view FBV has
+        # no throttle_scope), then run the sliding-window check directly via
+        # SimpleRateThrottle — deliberately skipping ScopedRateThrottle.allow_request
+        # (it re-reads the absent view.throttle_scope). Same resolution as the
+        # scheduling app's precedent, honest about the intentional skip.
+        self.rate = self.get_rate()
+        self.num_requests, self.duration = self.parse_rate(self.rate)
+        return SimpleRateThrottle.allow_request(self, request, view)
+
+
+@extend_schema(
+    summary="Test the OpenTelemetry export path",
+    description=(
+        "Verify OTLP export from inside the app (#2110). When export is enabled it "
+        "emits a single synthetic **canary span** (`trueppm.telemetry.canary`) through "
+        "a one-off exporter built from the same settings and reports whether the "
+        "collector accepted it; when an endpoint is set but export is switched off, it "
+        "runs a bounded TCP reachability probe instead. Config is never editable here "
+        "(ADR-0223) and the OTLP bearer token is never returned. Takes no request body. "
+        "Always responds 200 — the probe outcome (`success` / `reachable` / `failure`) "
+        "is in the body. Requires a workspace operator (superuser) account."
+    ),
+    request=None,
+    responses={200: TelemetryTestExportResultSerializer},
+    tags=["meta"],
+)
+@api_view(["POST"])
+@permission_classes([IsWorkspaceOperator])
+@throttle_classes([TelemetryTestThrottle])
+def telemetry_test_export(request: Request) -> Response:
+    """Probe the configured OTLP export path and report an honest outcome (#2110).
+
+    Any request body is ignored — the target is read only from settings, which is
+    what closes the SSRF surface (the caller chooses nothing). The failure ``detail``
+    is a canned sentence, never ``str(exc)``, so a transport error can't leak the
+    export bearer token.
+    """
+    result = run_telemetry_test_export()
+    return Response(TelemetryTestExportResultSerializer(result).data)

trueppm_api/apps/profiles/apps.py

@@ -0,0 +1,15 @@
+"""App config for the profiles app (ADR-0129).
+
+Holds per-user *app* preferences (not collaborative domain data). Currently a
+single field — ``default_landing`` — that drives the role-based app front door.
+"""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class ProfilesConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "trueppm_api.apps.profiles"
+    verbose_name = "User profiles"

trueppm_api/apps/profiles/constants.py

@@ -0,0 +1,54 @@
+"""Canonical view-key vocabulary for per-user nav customization (ADR-0139).
+
+The web nav (``packages/web/src/features/shell/methodologyTabs.ts``) owns the
+*display* registry (grouping, labels, icons). This module is the server-side
+source of truth for *which* view keys a user is allowed to hide, so the API can
+validate ``UserProfile.hidden_views`` and MCP/API clients can enumerate the
+vocabulary without scraping the web bundle.
+
+``overview`` is intentionally absent — it is the always-on landing surface
+(ADR-0030) and may never be hidden; keeping it unhideable is the structural
+guarantee that a user's nav can never be emptied. ``settings`` is also absent —
+it is an admin surface, not a hideable workflow view.
+
+Both are *band members* on the web since ADR-0942 (they used to stand outside every
+band, which is the only reason they were unhideable). Their absence here is therefore
+no longer a structural consequence of anything — it is an authored decision on both
+sides, and the thing that keeps the two sides honest is
+``contracts/hideable-views.json``: this set and the web's ``HIDEABLE_VIEW_KEYS`` each
+assert against it, in pytest and in vitest respectively. Adding a hideable view means
+editing all three; any one alone fails a pipeline. Prose asking to "keep the two lists
+in sync" is what let the web derive this set from band membership in the first place.
+
+A key absent here is rejected with a 400 by
+``UserProfileSerializer.validate_hidden_views``.
+"""
+
+from __future__ import annotations
+
+# Grouped for readability only — the *rendered* band of a key is methodology-adaptive on
+# the web (ADR-0195: Board joins the DELIVER circuit on AGILE/HYBRID, stays in TRACK on
+# WATERFALL). Hideability is per-key and independent of band, so this set is unchanged by
+# that layout — and by ADR-0942's retaxonomy, which moved four keys between bands and
+# added none: every key below is hideable on every methodology.
+HIDEABLE_VIEW_KEYS: frozenset[str] = frozenset(
+    {
+        # PLAN band
+        "schedule",
+        "grid",
+        "calendar",
+        # DELIVER band (AGILE/HYBRID) — Backlog · Sprints · Board (ADR-0195)
+        "product-backlog",
+        "sprints",
+        "board",
+        # TRACK band
+        "today",
+        "risk",
+        "reports",
+        "activity",
+        # Unified Assets surface (#971, ADR-0215) — trails TRACK on the web.
+        "assets",
+        # WORKSPACE scope band (ADR-0942) — Team, beside the unhideable Settings.
+        "resources",
+    }
+)

trueppm_api/apps/profiles/migrations/0001_initial.py

@@ -0,0 +1,55 @@
+import uuid
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="UserProfile",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                (
+                    "default_landing",
+                    models.CharField(
+                        choices=[
+                            ("auto", "Automatic (based on your role)"),
+                            ("my_work", "My Work"),
+                            ("project_overview", "Project Overview"),
+                            ("portfolio", "Portfolio"),
+                        ],
+                        default="auto",
+                        help_text=(
+                            "Which screen the app opens on. 'auto' uses the role-based policy."
+                        ),
+                        max_length=20,
+                    ),
+                ),
+                (
+                    "user",
+                    models.OneToOneField(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="profile",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "user profile",
+                "verbose_name_plural": "user profiles",
+            },
+        ),
+    ]