trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/settings/base.py

@@ -0,0 +1,2605 @@
+"""Base Django settings shared across all environments."""
+
+from __future__ import annotations
+
+import logging
+import os
+from datetime import timedelta
+from pathlib import Path
+
+import environ
+from django.core.exceptions import ImproperlyConfigured
+
+from trueppm_api.core.demo_read_only import (
+    parse_demo_access_gate,
+    parse_demo_login_hint,
+    parse_demo_read_only,
+    parse_demo_reset_schedule,
+)
+from trueppm_api.core.ratelimit import apply_rate_limit_disable, resolve_rate_limit_enabled
+from trueppm_api.core.refresh_cookie_policy import resolve_refresh_cookie_samesite
+from trueppm_api.core.storage_config import S3_STORAGE_BACKENDS, build_s3_storage_options
+from trueppm_api.core.valkey_config import parse_sentinels
+
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
+
+env = environ.Env()
+
+# ---------------------------------------------------------------------------
+# Core
+# ---------------------------------------------------------------------------
+
+SECRET_KEY = env("SECRET_KEY", default="django-insecure-change-me-in-prod")
+
+# Dedicated JWT signing key (#2247). Defaults to SECRET_KEY so a default install
+# stays single-knob, but can be set independently via JWT_SIGNING_KEY to:
+#   (a) limit the blast radius of a SECRET_KEY leak — a leaked SECRET_KEY alone
+#       can no longer forge access/refresh tokens for any user; and
+#   (b) give operators a deliberate "log everyone out now" lever: rotating
+#       JWT_SIGNING_KEY invalidates every outstanding token without also
+#       rotating the general Django secret (which would churn CSRF/session
+#       signing too).
+# When set explicitly it is strength-validated in prod exactly like SECRET_KEY
+# (see core.security_checks.validate_signing_key); when it defaults to SECRET_KEY
+# the SECRET_KEY validation already covers it. Rotation runbook:
+# packages/website/src/content/docs/administration/secret-rotation.md.
+JWT_SIGNING_KEY = env("JWT_SIGNING_KEY", default=SECRET_KEY)
+
+DEBUG = False
+
+ALLOWED_HOSTS: list[str] = []
+
+# ---------------------------------------------------------------------------
+# Applications
+# ---------------------------------------------------------------------------
+
+DJANGO_APPS = [
+    # django.contrib.admin, but with HardenedAdminSite as the default site
+    # (#3557) -- off unless TRUEPPM_DJANGO_ADMIN_ENABLED, and when on, its login
+    # carries the API login's throttles, audit lines and policy seam. Django's
+    # documented hook for swapping the default site is an AdminConfig subclass in
+    # INSTALLED_APPS; the app itself (label "admin", its migrations) is unchanged.
+    "trueppm_api.core.admin_site.HardenedAdminConfig",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    "django.contrib.postgres",
+    # SITE_ID = 1 (below) is already set; allauth.socialaccount's SocialApp is an
+    # M2M to Site, so the sites framework must be installed (ADR-0517 §1).
+    "django.contrib.sites",
+]
+
+THIRD_PARTY_APPS = [
+    "rest_framework",
+    "rest_framework_simplejwt",
+    # Refresh-token revocation (#910): provides OutstandingToken + BlacklistedToken
+    # so refresh-token rotation (BLACKLIST_AFTER_ROTATION) and logout actually
+    # revoke the old token instead of letting it live out its full TTL. The
+    # auth_views blacklist() calls are no-ops without this app installed.
+    "rest_framework_simplejwt.token_blacklist",
+    "allauth",
+    "allauth.account",
+    # ADR-0517: adopt allauth.socialaccount as the provider *registry* only — our
+    # own hardened views in apps/sso drive the flow (egress, alg allow-list, Fernet
+    # secret, JWT bridge). We do NOT mount allauth.urls. openid_connect covers every
+    # OIDC IdP (as named APPS keyed by our registry slug); github is the one non-OIDC
+    # OAuth2 IdP that motivated the re-platform (#2108).
+    "allauth.socialaccount",
+    "allauth.socialaccount.providers.openid_connect",
+    "allauth.socialaccount.providers.github",
+    "channels",
+    "drf_spectacular",
+    # Serves the Swagger UI / ReDoc static bundles from Django static ('self')
+    # so the /api/docs/ and /api/schema/swagger-ui/ pages render under the strict
+    # CSP without a CDN. Must precede any app that would shadow its static files.
+    "drf_spectacular_sidecar",
+    "simple_history",
+]
+
+LOCAL_APPS = [
+    "trueppm_api.apps.access",
+    "trueppm_api.apps.projects",
+    "trueppm_api.apps.resources",
+    "trueppm_api.apps.scheduling",
+    "trueppm_api.apps.sync",
+    "trueppm_api.apps.history",
+    "trueppm_api.apps.msproject",
+    "trueppm_api.apps.jiraimport",
+    "trueppm_api.apps.csvimport",
+    "trueppm_api.apps.webhooks",
+    "trueppm_api.apps.taskruns",
+    "trueppm_api.apps.notifications",
+    "trueppm_api.apps.integrations",
+    "trueppm_api.apps.observability",
+    "trueppm_api.apps.workflow_engine",
+    "trueppm_api.apps.idempotency",
+    "trueppm_api.apps.workspace",
+    "trueppm_api.apps.teams",
+    "trueppm_api.apps.profiles",
+    "trueppm_api.apps.timetracking",
+    "trueppm_api.apps.sso",
+    "trueppm_api.apps.agents",
+]
+
+INSTALLED_APPS = DJANGO_APPS + THIRD_PARTY_APPS + LOCAL_APPS
+
+# ---------------------------------------------------------------------------
+# Middleware
+# ---------------------------------------------------------------------------
+
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    # Serve collected static files from the ASGI app itself (#1603). We run under
+    # `uvicorn ...asgi:application` in dev and prod — not `manage.py runserver` —
+    # so Django's dev static handler never engages and there is no nginx/CDN in the
+    # request path. Without this, every /static/ request 404s: Django admin CSS and
+    # the Swagger UI / ReDoc bundles (served same-origin under our strict CSP) both
+    # fail. WhiteNoise must sit immediately after SecurityMiddleware (its documented
+    # position) so it can short-circuit static requests before the rest of the stack.
+    "whitenoise.middleware.WhiteNoiseMiddleware",
+    # Assign each request a correlation id and bind it to the logging contextvar
+    # (#1899) so every log record emitted while handling the request carries it,
+    # and echo it back on the response. Placed high — but after WhiteNoise, which
+    # short-circuits static requests that need no id — so the id is set before any
+    # downstream middleware or view can log.
+    "trueppm_api.apps.observability.logging.RequestIDMiddleware",
+    # CSP header on every response (#897). Placed high so the header is attached
+    # even for early short-circuit responses (redirects, errors).
+    "trueppm_api.core.csp.ContentSecurityPolicyMiddleware",
+    # Reject NUL bytes in /api/ query strings before the view opens its
+    # ATOMIC_REQUESTS transaction (#2229) — a NUL in a text DB filter otherwise
+    # raises an uncaught psycopg DataError (500). Placed inside RequestID/CSP so
+    # the 400 still carries the correlation id and CSP header, but before Session
+    # so a garbage request skips session/auth work.
+    "trueppm_api.core.middleware.RejectNullBytesMiddleware",
+    # Demo read-only mode (interactive-demo design #3912, #3924): refuse every unsafe /api/ request
+    # unless it is one of the three auth writes. Sits BEFORE Session/Auth so anonymous
+    # POSTs (password-reset request, SSO, inbound integrations) are refused too, and
+    # before the view's ATOMIC_REQUESTS transaction so a refusal costs no DB work. It
+    # must not move below AuthenticationMiddleware: a role-aware position is exactly
+    # the "authority derived from the account" design this mode exists to avoid. A
+    # no-op unless DEMO_READ_ONLY is set.
+    "trueppm_api.core.demo_read_only.DemoReadOnlyMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "allauth.account.middleware.AccountMiddleware",
+    "simple_history.middleware.HistoryRequestMiddleware",
+    "django.contrib.messages.middleware.MessageMiddleware",
+    "django.middleware.clickjacking.XFrameOptionsMiddleware",
+    # Write queued agent-action audit rows after the view's ATOMIC_REQUESTS
+    # transaction has closed (#3017, ADR-0902). A refusal audit written inside that
+    # transaction is discarded by the set_rollback() DRF performs for every
+    # APIException, which is why the log contained only successes. Placed LAST so its
+    # response half runs FIRST on the way out — as close to the view as a middleware
+    # can be, while still being outside the transaction.
+    "trueppm_api.apps.agents.middleware.AgentActionAuditMiddleware",
+]
+
+ROOT_URLCONF = "trueppm_api.urls"
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.debug",
+                "django.template.context_processors.request",
+                "django.contrib.auth.context_processors.auth",
+                "django.contrib.messages.context_processors.messages",
+            ],
+        },
+    },
+]
+
+WSGI_APPLICATION = "trueppm_api.wsgi.application"
+ASGI_APPLICATION = "trueppm_api.asgi.application"
+
+# ---------------------------------------------------------------------------
+# Database
+# ---------------------------------------------------------------------------
+
+DATABASES = {
+    "default": env.db("DATABASE_URL", default="postgres://trueppm:trueppm@db:5432/trueppm")
+}
+DATABASES["default"]["CONN_MAX_AGE"] = 60
+# Wrap every request in a transaction so transaction.on_commit() defers
+# callbacks to after commit rather than firing immediately in autocommit mode.
+DATABASES["default"]["ATOMIC_REQUESTS"] = True
+
+# ---------------------------------------------------------------------------
+# File / object storage (#775)
+# ---------------------------------------------------------------------------
+
+# Default file-storage backend. TaskAttachment.file is stored here. The
+# FileSystemStorage default is fine for local dev, but a containerized prod
+# deploy must point this at a remote object-storage backend (S3/MinIO via
+# django-storages) or attachment uploads are lost on every pod restart. prod.py
+# refuses to boot on the local default unless the operator explicitly opts in.
+STORAGES = {
+    "default": {
+        "BACKEND": env(
+            "TRUEPPM_DEFAULT_FILE_STORAGE",
+            default="django.core.files.storage.FileSystemStorage",
+        ),
+    },
+    "staticfiles": {
+        "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
+    },
+}
+
+# S3 / MinIO options, attached ONLY for an S3-family backend — a FileSystemStorage
+# deploy must not be handed S3 kwargs it would reject. See core.storage_config for
+# why this plumbing is required rather than cosmetic (#2559): the backend the docs
+# recommend reads its bucket from Django settings, not the environment, so setting
+# TRUEPPM_DEFAULT_FILE_STORAGE alone booted and then failed on the first upload.
+if STORAGES["default"]["BACKEND"] in S3_STORAGE_BACKENDS:
+    STORAGES["default"]["OPTIONS"] = build_s3_storage_options(os.environ)
+
+# Where FileSystemStorage writes task attachments. Django's own default is "",
+# which resolves upload paths against the process CWD — /app in the container
+# image, whose root filesystem is read-only on both supported production paths
+# (Helm readOnlyRootFilesystem, compose read_only). Every upload therefore failed
+# at write time with EROFS while the boot guard reported the deployment healthy
+# (#3184). TRUEPPM_MEDIA_ROOT was already read by scripts/backup.sh and
+# scripts/restore.sh but by nothing in Django, so the variable the backup tooling
+# documents now actually decides where the files it archives live.
+#
+# The default is the path the chart's persistence.media PVC and the compose
+# `media` volume both mount. It is deliberately outside BASE_DIR: BASE_DIR
+# resolves inside the read-only venv when the app is pip-installed, exactly as
+# STATIC_ROOT's comment below notes. settings/dev.py overrides it to a
+# repo-local directory so a workstation and pytest never need /var/lib.
+MEDIA_ROOT = Path(env("TRUEPPM_MEDIA_ROOT", default="/var/lib/trueppm/media"))
+
+# Operator opt-in to run prod on local-disk attachment storage (e.g. when it is
+# backed by a persistent volume). Consumed by validate_attachment_storage.
+ALLOW_LOCAL_ATTACHMENT_STORAGE = env.bool("TRUEPPM_ALLOW_LOCAL_ATTACHMENT_STORAGE", default=False)
+
+# Operator opt-in confirming the configured STORAGES['default']['BACKEND'] signs
+# its .url() output with a real time-limited URL, for a backend not on
+# security_checks.storage_backend_supports_signed_urls's allow-list (#573,
+# MED-2). Default False: the TaskAttachmentViewSet.signed_url action refuses
+# with 501 rather than hand out a stable indefinite-lifetime URL labeled as
+# time-limited for any backend it can't positively identify as signing-capable.
+ATTACHMENT_STORAGE_SIGNS_URLS = env.bool("TRUEPPM_ATTACHMENT_STORAGE_SIGNS_URLS", default=False)
+
+# Operator opt-in to run prod against a DATABASE_URL without sslmode=require (e.g.
+# when TLS to the database is enforced at the network layer). Consumed by the
+# unencrypted-DB boot guard in settings/prod.py.
+ALLOW_UNENCRYPTED_DB = env.bool("TRUEPPM_ALLOW_UNENCRYPTED_DB", default=False)
+
+# Operator acknowledgment that ALLOWED_HOSTS is a bare "*" in prod (#3515).
+# Consumed by the wildcard-host boot guard in settings/prod.py, which otherwise
+# refuses to start: "*" is the one value that disables host validation outright,
+# and host validation is the only bound on the absolute URLs the API builds.
+ALLOW_WILDCARD_ALLOWED_HOSTS = env.bool("TRUEPPM_ALLOW_WILDCARD_HOSTS", default=False)
+
+# Whether /admin/ answers at all (#3557). Default OFF everywhere except the dev
+# settings module, which flips it back on for a developer workstation.
+#
+# Django admin is a plain Django view, so none of the API's login defenses reach
+# it by inheritance: DRF throttles apply to DRF views only, the auth audit lines
+# are emitted by our own login view, and the enterprise local_login_allowed seam
+# is consulted there too. Left unhardened it is a second password door onto a
+# known-present superuser (the create_admin bootstrap makes one on first deploy)
+# with none of the first door's controls. The chart's nginx denies /admin/ by
+# default, but Docker Compose and bare-metal deploys route to the API directly
+# and have no such edge.
+#
+# Off-by-default is the primary control, because the strongest statement about a
+# surface almost nobody uses is that it is not there. HardenedAdminSite raises
+# Http404 for every /admin/ path when this is False -- a 404, not a 403, so the
+# surface is not even advertised. An operator who genuinely needs the admin sets
+# this to true and gets the hardened door rather than the bare one: the same
+# "login"/"login_account" throttle buckets as the API login, the same
+# auth.login_failed / auth.login_succeeded lines, and the same policy seam.
+DJANGO_ADMIN_ENABLED = env.bool("TRUEPPM_DJANGO_ADMIN_ENABLED", default=False)
+
+# Interactive-demo read-only mode (#3912, #3924). When true,
+# DemoReadOnlyMiddleware refuses every unsafe HTTP method under /api/ except login,
+# token refresh and logout, regardless of role or permission class. Off by default; a
+# normal install is unaffected. Parsed strictly rather than with env.bool(): env.bool
+# reads any unrecognized string (a typo like "ture") as False, which would silently
+# disable the one control the demo's safety rests on. An unrecognized value here
+# refuses to boot instead.
+DEMO_READ_ONLY: bool = parse_demo_read_only(os.environ.get("TRUEPPM_DEMO_READ_ONLY"))
+
+# External access gate declared in front of a demo host (#3969, ADR-1197 D8 resolution
+# of 2026-09-21). A gate such as Cloudflare Access collects a visitor's email address
+# before any TruePPM code runs; this is how the deployment says so, and it is surfaced
+# only while DEMO_READ_ONLY is on (see the edition view). IT IS AN OPERATOR ASSERTION
+# THAT NOTHING VERIFIES -- the gate is configured in a third-party dashboard outside
+# the cluster, so neither setting it nor clearing it proves anything about what is
+# actually in front of this pod. Unset on every normal install, which is the point:
+# the disclosure is conditional, never a blanket claim.
+DEMO_ACCESS_GATE: dict[str, str | None] | None = parse_demo_access_gate(
+    os.environ.get("TRUEPPM_DEMO_ACCESS_GATE_PROVIDER"),
+    os.environ.get("TRUEPPM_DEMO_ACCESS_GATE_PRIVACY_URL"),
+)
+
+# Global rate-limiting kill switch (ADR-0604, extends ADR-0208). Operator-only
+# escape hatch to disable ALL DRF throttling — used by the k6 perf:load job to
+# measure raw throughput, and by an operator load-testing / debugging a real
+# deployment. Disabling requires BOTH TRUEPPM_RATE_LIMIT_ENABLED=false AND the
+# acknowledgment sentinel, in every environment; an unacknowledged disable is
+# refused (limits stay ON) and logged at CRITICAL, so a stray env var can never
+# silently open a DoS path. See trueppm_api.core.ratelimit for the full rationale.
+# The effective throttle neutralization runs after REST_FRAMEWORK is defined
+# (search "apply_rate_limit_disable" below). Surfaced read-only to admins via
+# /health/system/ and a banner; never a UI/API toggle (ADR-0497).
+RATE_LIMIT_ENABLED, _rate_limit_switch_message = resolve_rate_limit_enabled(
+    requested_enabled=env.bool("TRUEPPM_RATE_LIMIT_ENABLED", default=True),
+    ack=env("TRUEPPM_RATE_LIMIT_DISABLE_ACK", default=""),
+)
+_settings_log = logging.getLogger("trueppm.settings")
+if _rate_limit_switch_message:
+    _settings_log.critical(_rate_limit_switch_message)
+
+# The shared credential the interactive demo's login page prints (#3926, ADR-1197 D3).
+# "username:password"; unset on every normal install. Read here rather than derived from
+# any real password variable so nothing can promote a live secret to published copy by
+# accident. /api/v1/edition/ emits it ONLY while DEMO_READ_ONLY is true.
+#
+# Parsed strictly only where it MATTERS. Refusing to boot on a malformed value is right
+# for a demo — the one credential it advertises being a typo makes the demo unusable —
+# and wrong for a production install, where a leftover variable is inert and crashing
+# the process over it is an outage caused by something that does nothing. What the
+# `else` branch must not be is silent: hint-set-while-mode-off is exactly the state
+# "a real account's password is sitting in a writable install's environment", and
+# nothing else anywhere would say so.
+_demo_login_hint_raw = os.environ.get("TRUEPPM_DEMO_LOGIN_HINT")
+DEMO_LOGIN_HINT: dict[str, str] | None = (
+    parse_demo_login_hint(_demo_login_hint_raw) if DEMO_READ_ONLY else None
+)
+if not DEMO_READ_ONLY and _demo_login_hint_raw and _demo_login_hint_raw.strip():
+    _settings_log.warning(
+        "TRUEPPM_DEMO_LOGIN_HINT is set but TRUEPPM_DEMO_READ_ONLY is not true. The "
+        "value is IGNORED and never served, but a published credential is sitting in "
+        "this install's environment. Unset it unless this really is a demo."
+    )
+
+# The reset CronJob's own cadence, restated so the demo bar and login page can say
+# "resets daily at HH:MM" from the value that actually drives the CronJob rather than
+# a hardcoded number (#4152, ADR-1197 D9). The chart renders this empty whenever
+# demo.reset is disabled, so `None` here already means "no schedule to state" without
+# a second demo-mode gate — but /api/v1/edition/ still gates emission on DEMO_READ_ONLY,
+# like the hint and the access gate, so the field says nothing on a normal install even
+# if the variable were somehow left set.
+DEMO_RESET_SCHEDULE: str | None = parse_demo_reset_schedule(
+    os.environ.get("TRUEPPM_DEMO_RESET_SCHEDULE")
+)
+
+# Origins trusted for cross-origin POST / CSRF — required when the web app is
+# served from a different origin than the API (split dev setup or subdomain
+# split). Empty by default (same-origin reverse-proxy deploy).
+CSRF_TRUSTED_ORIGINS = env.list("CSRF_TRUSTED_ORIGINS", default=[])
+
+# Public origin the web app is served from, e.g. "https://app.example.com". Used
+# to build absolute deep-links into emails/notifications (ADR-0165, #1158) — the
+# API otherwise has no notion of where the frontend lives. Empty by default
+# (zero-config): when unset, email bodies render without a link rather than emit a
+# broken relative URL. Trailing slash is stripped at use; do not include a path.
+# Env var standardized on the TRUEPPM_ prefix pre-0.3 (#1325, #1355); the legacy
+# bare name remains a fallback so existing deploys keep working. ``or`` (not a
+# nested default) so an *empty* TRUEPPM_ value — e.g. the chart's documented
+# ``TRUEPPM_FRONTEND_BASE_URL: ""`` default — falls through to a legacy override
+# rather than shadowing it. Empty means "no deep-links", so the fallthrough is
+# also semantically correct.
+FRONTEND_BASE_URL = env("TRUEPPM_FRONTEND_BASE_URL", default="") or env(
+    "FRONTEND_BASE_URL", default=""
+)
+
+# Public origin of the API itself, used only to derive the OIDC ``redirect_uri``
+# (ADR-0187): ``{TRUEPPM_PUBLIC_API_BASE_URL}/api/v1/auth/oidc/callback/``. The
+# operator copies this exact value into their IdP's allowed-redirect list. Empty
+# by default (zero-config): the SSO views fall back to the request's absolute URI,
+# correct for a single-origin dev setup; set it explicitly behind a reverse proxy
+# so the allow-listed value is deterministic. Trailing slash is stripped at use.
+TRUEPPM_PUBLIC_API_BASE_URL = env("TRUEPPM_PUBLIC_API_BASE_URL", default="")
+
+# ---------------------------------------------------------------------------
+# Cache / Channels / Celery  (all backed by Redis)
+# ---------------------------------------------------------------------------
+
+REDIS_URL = env("REDIS_URL", default="redis://redis:6379")
+
+# --- Valkey topology (ADR-0716, #2554) ------------------------------------
+# Sentinel mode is EXPERIMENTAL as of 0.4: the wiring below is unit-tested, but no
+# live-quorum failover has been exercised (the bundled dev stack is single-node).
+# Setting TRUEPPM_VALKEY_SENTINELS switches every consumer to Sentinel mode; left
+# empty (the default) everything below derives from REDIS_URL exactly as before,
+# so an existing deploy needs no config change. Sentinel is a *block* rather than
+# per-role URL overrides because the blocking constraint is that neither
+# channels-redis nor the Django cache can express Sentinel as a URL at all — see
+# ADR-0716 for the rejected alternatives. Cluster mode is unsupported: a clustered
+# endpoint exposes only db 0 and we use four (0 Celery, 1 Channels, 2 cache, 3
+# notification throttles).
+VALKEY_SENTINELS_RAW = env("TRUEPPM_VALKEY_SENTINELS", default="")
+VALKEY_MASTER_NAME = env("TRUEPPM_VALKEY_MASTER_NAME", default="")
+VALKEY_PASSWORD = env("TRUEPPM_VALKEY_PASSWORD", default="")
+# Sentinel nodes commonly carry a different password from the data nodes (often
+# none at all), so this is deliberately separate rather than reusing the above.
+VALKEY_SENTINEL_PASSWORD = env("TRUEPPM_VALKEY_SENTINEL_PASSWORD", default="")
+VALKEY_USE_TLS = env.bool("TRUEPPM_VALKEY_USE_TLS", default=False)
+
+try:
+    VALKEY_SENTINELS: list[tuple[str, int]] = parse_sentinels(VALKEY_SENTINELS_RAW)
+except ValueError:
+    # A malformed entry must not raise out of settings import — that surfaces as an
+    # unreadable traceback before Django can report anything. Fall back to
+    # single-endpoint mode and let core.valkey_checks emit trueppm.valkey.E002,
+    # which names the bad entry and refuses the boot cleanly.
+    VALKEY_SENTINELS = []
+
+VALKEY_SENTINEL_MODE = bool(VALKEY_SENTINELS)
+
+# Shared cache backend (Valkey/Redis db 2 — db 1 is the channel layer, db 0 is
+# Celery). Backs the short-lived, single-use OIDC login state / PKCE verifier /
+# nonce (ADR-0187 §Durable Execution) and the DRF scoped throttles, both of which
+# must be consistent across worker processes in a multi-worker deploy. ``dev.py``
+# overrides this to LocMemCache so a local run / pytest needs no separate cache
+# service (single process, so per-process memory is sufficient there).
+# In Sentinel mode the backend swaps to our own RedisCache subclass (ADR-0716) —
+# Django's built-in has no Sentinel support, and subclassing it is ~30 lines
+# against adding django-redis, which ADR-0065/0068 declined.
+CACHES = {
+    "default": (
+        {
+            "BACKEND": "trueppm_api.core.valkey_cache.SentinelRedisCache",
+            # LOCATION is ignored by that backend (topology comes from the
+            # TRUEPPM_VALKEY_* settings) but Django requires the key present.
+            "LOCATION": "",
+        }
+        if VALKEY_SENTINEL_MODE
+        else {
+            "BACKEND": "django.core.cache.backends.redis.RedisCache",
+            "LOCATION": f"{REDIS_URL}/2",
+        }
+    ),
+}
+
+# channels-redis accepts Sentinel ONLY as a dict host — it can never be carried in
+# a URL, which is the single fact that made Sentinel unreachable before ADR-0716.
+_CHANNEL_HOST: dict[str, object] | str = (
+    {
+        "sentinels": VALKEY_SENTINELS,
+        "master_name": VALKEY_MASTER_NAME,
+        "db": 1,
+        **({"password": VALKEY_PASSWORD} if VALKEY_PASSWORD else {}),
+        **(
+            {"sentinel_kwargs": {"password": VALKEY_SENTINEL_PASSWORD}}
+            if VALKEY_SENTINEL_PASSWORD
+            else {}
+        ),
+    }
+    if VALKEY_SENTINEL_MODE
+    else f"{REDIS_URL}/1"
+)
+
+CHANNEL_LAYERS = {
+    "default": {
+        "BACKEND": "channels_redis.core.RedisChannelLayer",
+        "CONFIG": {
+            "hosts": [_CHANNEL_HOST],
+            "capacity": 1500,
+            "expiry": 10,
+        },
+    },
+}
+
+# Legacy WebSocket ?token=<jwt> handshake (ADR-0141, #1723). The single-use
+# ?ticket= scheme replaced it: a raw JWT in the URL leaks verbatim into
+# reverse-proxy / ingress / Daphne access logs (the credential-in-URL class of
+# #818). The fallback shipped deprecated-but-live for one release; it is now
+# OFF by default and must be explicitly opted into by an operator who still has
+# clients on the old path. It is removed entirely next release.
+TRUEPPM_WS_LEGACY_TOKEN_AUTH_ENABLED: bool = env.bool(
+    "TRUEPPM_WS_LEGACY_TOKEN_AUTH_ENABLED", default=False
+)
+
+# Celery accepts a sentinel:// URL, but ONLY together with a master_name in the
+# transport options — the URL alone silently connects to whichever sentinel
+# answers rather than to the primary. Broker and result backend take separate
+# option dicts; setting only broker_transport_options is the common half-fix and
+# leaves the result backend pointed at a sentinel port (ADR-0716).
+if VALKEY_SENTINEL_MODE:
+    _sentinel_authority = ";".join(
+        f"sentinel://{f':{VALKEY_PASSWORD}@' if VALKEY_PASSWORD else ''}{host}:{port}"
+        for host, port in VALKEY_SENTINELS
+    )
+    CELERY_BROKER_URL = _sentinel_authority
+    CELERY_RESULT_BACKEND = _sentinel_authority
+    _celery_transport_options: dict[str, object] = {
+        "master_name": VALKEY_MASTER_NAME,
+        "db": 0,
+    }
+    if VALKEY_SENTINEL_PASSWORD:
+        _celery_transport_options["sentinel_kwargs"] = {"password": VALKEY_SENTINEL_PASSWORD}
+    CELERY_BROKER_TRANSPORT_OPTIONS = _celery_transport_options
+    CELERY_RESULT_BACKEND_TRANSPORT_OPTIONS = _celery_transport_options
+else:
+    CELERY_BROKER_URL = f"{REDIS_URL}/0"
+    CELERY_RESULT_BACKEND = f"{REDIS_URL}/0"
+    # Bound the redelivery window on the non-sentinel path (#3188). Tasks carry
+    # acks_late=True + reject_on_worker_lost=True in 60+ places, so a worker
+    # killed mid-task does not LOSE the work — the broker redelivers it. But
+    # Kombu's Redis transport hides an unacked message for `visibility_timeout`
+    # seconds first, and its default is 3600. A worker SIGKILLed during a
+    # rolling upgrade therefore left that task invisible for up to an hour, with
+    # nothing in the queue depth or the task list to say why. This block set
+    # transport options only on the sentinel path, so the default applied to
+    # every ordinary deploy.
+    #
+    # 900s is chosen against the longest task we actually run rather than a
+    # round number: MS Project import and workspace export are the multi-minute
+    # ones. It MUST exceed the longest task's runtime — a visibility timeout
+    # shorter than the work redelivers a task that is still running, which turns
+    # one slow import into two concurrent ones. Raise it if you raise
+    # terminationGracePeriodSeconds on the worker past this.
+    CELERY_BROKER_TRANSPORT_OPTIONS = {"visibility_timeout": 900}
+
+CELERY_ACCEPT_CONTENT = ["json"]
+CELERY_TASK_SERIALIZER = "json"
+CELERY_RESULT_SERIALIZER = "json"
+CELERY_TIMEZONE = "UTC"
+from celery.schedules import crontab  # noqa: E402 — must follow REDIS_URL
+
+CELERY_BEAT_SCHEDULE = {
+    # Retention purge coordinator (ADR-0173): one self-gating task that purges the
+    # six operational tables (event history, task runs, webhook deliveries, import
+    # requests, sync batches, soft-deleted projects) as a single unified run,
+    # recorded in PurgeRun. Fires every 30 min and no-ops outside the
+    # operator-configured window (Settings → System health → Retention & purge).
+    # Replaces the former per-table nightly purge entries — the per-table tasks
+    # remain dispatchable but are no longer independently scheduled.
+    "retention-purge-coordinator": {
+        "task": "retention.run_purge",
+        "schedule": crontab(minute="*/30"),
+    },
+    # Outbox drain: dispatches pending ScheduleRequest rows every 30 seconds.
+    # Also recovers orphaned dispatched rows (worker died before completing).
+    "drain-schedule-queue": {
+        "task": "scheduling.drain_schedule_queue",
+        "schedule": 30.0,
+    },
+    # Nightly cleanup: deletes done/dead ScheduleRequest rows older than 7 days.
+    "schedule-requests-purge-nightly": {
+        "task": "scheduling.purge_old_schedule_requests",
+        # 02:15 UTC — between the two existing purge jobs.
+        "schedule": crontab(hour=2, minute=15),
+    },
+    # Config-change notice outbox drain (#3009, ADR-1174): recovers rows whose
+    # worker was lost and dispatches notices whose on-commit dispatch stranded.
+    "drain-config-notice-requests": {
+        "task": "projects.drain_config_notice_requests",
+        "schedule": 30.0,
+    },
+    # Nightly cleanup: deletes done/dead ConfigNoticeRequest rows older than 7 days.
+    "config-notice-requests-purge-nightly": {
+        "task": "projects.purge_old_config_notice_requests",
+        "schedule": crontab(hour=2, minute=55),
+    },
+    # Nightly cleanup: deletes acknowledged / auto-resolved CrossProjectSlipConflict
+    # rows 90 days past their resolution (ADR-0120 D4). Unresolved + unacknowledged
+    # conflicts are kept indefinitely — they are still live.
+    "purge-resolved-slip-conflicts-nightly": {
+        "task": "scheduling.purge_resolved_slip_conflicts",
+        # 02:25 UTC — after the Monte Carlo purge.
+        "schedule": crontab(hour=2, minute=25),
+    },
+    # Nightly cleanup: reaps WebSocket replay-buffer rows (BoardEvent) older than
+    # TRUEPPM_BOARD_EVENT_RETENTION_HOURS so the buffer stays bounded (ADR-0236,
+    # #321). Standalone rather than in the ADR-0173 operator coordinator: the
+    # buffer is internal transport plumbing, deliberately not surfaced as an
+    # operator-tunable retention row.
+    "purge-board-events-nightly": {
+        "task": "sync.purge_board_events",
+        # 02:35 UTC — after the slip-conflict purge.
+        "schedule": crontab(hour=2, minute=35),
+    },
+    # Nightly cleanup: trims project Monte Carlo run history to the newest
+    # MC_HISTORY_CAP rows per project (ADR-0175, #961). No-ops when the cap is
+    # None (Enterprise unlimited).
+    "purge-monte-carlo-runs-nightly": {
+        "task": "scheduling.purge_old_monte_carlo_runs",
+        # 02:20 UTC — right after the schedule-requests purge.
+        "schedule": crontab(hour=2, minute=20),
+    },
+    # Daily forecast-snapshot floor: guarantees ≥1 ProjectForecastSnapshot per
+    # active project per day and backfills any recompute capture missed by a broker
+    # blip / worker death (ADR-0154, #388). The durability backstop for capture.
+    "capture-daily-forecast-floor": {
+        "task": "scheduling.capture_daily_forecast_floor",
+        # 00:30 UTC — early, before the nightly purges, so every project has a row.
+        "schedule": crontab(hour=0, minute=30),
+    },
+    # Nightly cleanup: applies the tiered retention curve to project forecast
+    # snapshots — all <90 d, weekly to 1 y, monthly forever (ADR-0154, #388).
+    "prune-forecast-snapshots-nightly": {
+        "task": "scheduling.prune_forecast_snapshots",
+        # 04:15 UTC — after the other nightly purge jobs.
+        "schedule": crontab(hour=4, minute=15),
+    },
+    # Webhook delivery drain: re-enqueues stranded PENDING deliveries whose
+    # initial .delay() call was lost (e.g. broker down at creation time).
+    "drain-webhook-queue": {
+        "task": "webhooks.drain_webhook_queue",
+        "schedule": 30.0,
+    },
+    # MS Project import drain: dispatches pending ImportRequest rows every 30 s.
+    # Also recovers orphaned dispatched rows (worker died mid-import).
+    "drain-import-queue": {
+        "task": "msproject.drain_import_queue",
+        "schedule": 30.0,
+    },
+    # Jira import drain: dispatches pending JiraImportRequest rows every 30 s and
+    # recovers orphaned dispatched rows (worker died mid-import).
+    "drain-jira-import-queue": {
+        "task": "jira.drain_import_queue",
+        "schedule": 30.0,
+    },
+    # CSV/Excel import drain: dispatches pending CsvImportRequest rows every 30 s
+    # and recovers orphaned dispatched rows (worker died mid-import). Kept
+    # separate from the MSP and Jira drains per ADR-0259/ADR-0632 so no drain has
+    # to branch on file type.
+    "drain-csv-import-queue": {
+        "task": "csv.drain_import_queue",
+        "schedule": 30.0,
+    },
+    # Template-apply drain (ADR-0789, #2729): dispatches pending
+    # TemplateApplication rows every 30 s and recovers ones whose worker died
+    # mid-apply. This is what makes enqueue_template_apply's best-effort
+    # .delay() durable — without it, a broker outage at dispatch time would
+    # leave an application pending forever and the Start sheet polling nothing.
+    "drain-template-apply-queue": {
+        "task": "templates.drain_apply_queue",
+        "schedule": 30.0,
+    },
+    # Sprint close drain: dispatches pending SprintCloseRequest rows every 30 s.
+    # Also recovers IN_FLIGHT rows orphaned past the 5-minute window.
+    "drain-sprint-close-requests": {
+        "task": "projects.drain_sprint_close_requests",
+        "schedule": 30.0,
+    },
+    # Daily burndown snapshot: writes yesterday's row for every ACTIVE sprint
+    # — covers days with no task status changes (signal handler covers today).
+    "update-sprint-burndown-snapshots": {
+        "task": "projects.update_sprint_burndown_snapshots",
+        "schedule": crontab(hour=1, minute=0),
+    },
+    # Nightly cleanup: deletes COMPLETED/FAILED SprintCloseRequest rows >7 days.
+    "purge-sprint-close-requests": {
+        "task": "projects.purge_sprint_close_requests",
+        # 03:00 UTC — after other nightly purge jobs.
+        "schedule": crontab(hour=3, minute=0),
+    },
+    # Notification email outbox drain: send queued notification emails every 30 s.
+    # Fan-outs also nudge it on commit, so this tick is the durability backstop, not
+    # the latency path (ADR-0087 §Amendment #4191).
+    "drain-notification-emails": {
+        "task": "notifications.drain_notification_emails",
+        "schedule": 30.0,
+    },
+    # Nightly archive: notifications older than 90 days with is_read=True become
+    # is_archived=True. Keeps the unread-bell query path on a shallow index.
+    "archive-old-notifications": {
+        "task": "notifications.archive_old_notifications",
+        # 03:15 UTC — after other nightly purge/archive jobs.
+        "schedule": crontab(hour=3, minute=15),
+    },
+    # Daily stale-task detection (ADR-0200): nudge assignees of non-terminal tasks
+    # that have sat in their status past the project's stale_task_threshold_days
+    # (default 7). Dedupes against existing unread task.stale notifications.
+    "detect-stale-tasks": {
+        "task": "notifications.detect_stale_tasks",
+        # 05:30 UTC — after the nightly purges/archive, so the scan reads settled
+        # state and lands a fresh nudge before the working day starts.
+        "schedule": crontab(hour=5, minute=30),
+    },
+    # Scheduled digests (ADR-0663, #2407): hourly sweep that sends each opted-in
+    # user's weekly program-health / overallocation digest when the current hour
+    # matches their own slot in their own timezone. Hourly (not weekly) because
+    # the schedule is a per-user property — one cluster-wide weekly entry would be
+    # 3 a.m. for half the recipients. Runs at minute 10 so it does not contend
+    # with generate-recurring-occurrences at minute 0.
+    "send-scheduled-digests": {
+        "task": "notifications.send_scheduled_digests",
+        "schedule": crontab(minute=10),
+    },
+    # Nightly cleanup: drop digest ledger rows past the 90-day retention window
+    # (ADR-0663 §Durable Execution item 6). Longer than the 7-day convention
+    # because the ledger's job is to remember a weekly send.
+    "purge-old-digest-runs": {
+        "task": "notifications.purge_old_digest_runs",
+        # 03:20 UTC — between archive-old-notifications (03:15) and the 04:00
+        # workflow purge.
+        "schedule": crontab(hour=3, minute=20),
+    },
+    # Beat liveness heartbeat: a single worker writes BeatHeartbeat.last_heartbeat
+    # every 30 s. GET /api/v1/health/beat/ reads it to detect a dead Beat (ADR-0081).
+    "beat-heartbeat": {
+        "task": "beat.heartbeat",
+        "schedule": 30.0,
+    },
+    # Secondary in-cluster stale-heartbeat detector: logs WARNING when the heartbeat
+    # is older than TRUEPPM_BEAT_STALE_SECONDS. The /health/beat/ endpoint is the
+    # primary (external) detector; this serves adopters with no external monitoring.
+    "beat-check-stale-heartbeat": {
+        "task": "beat.check_stale_heartbeat",
+        "schedule": 60.0,
+    },
+    # Workflow step-outbox drain: re-dispatch stranded WorkflowOutboxRow rows
+    # every 30 s and recover rows orphaned by a dead worker (ADR-0080 §D).
+    "drain-workflow-outbox": {
+        "task": "workflows.outbox_drain",
+        "schedule": 30.0,
+    },
+    # Workflow sleep-timer drain: fire due WorkflowTimer rows and wake their
+    # sleeping workflows. 60 s cadence — sleep durations are minute-grained.
+    "drain-workflow-timers": {
+        "task": "workflows.timer_drain",
+        "schedule": 60.0,
+    },
+    # Nightly cleanup: terminal workflow outbox rows >7 days and history past
+    # the configurable retention window.
+    "purge-workflow-records": {
+        "task": "workflows.purge_old_records",
+        # 04:00 UTC — after the other nightly purge jobs.
+        "schedule": crontab(hour=4, minute=0),
+    },
+    # Hourly cleanup: deletes stored Idempotency-Key rows older than
+    # IDEMPOTENCY_RETENTION_HOURS. Hourly (not nightly) so the 24h contract holds —
+    # a nightly job would let rows live up to ~48h (ADR-0170).
+    "idempotency-keys-purge-hourly": {
+        "task": "idempotency.purge_old_keys",
+        "schedule": crontab(minute=5),
+    },
+    # Workspace invite email outbox drain: send queued invite emails every 30 s.
+    # create_invite also nudges it on commit, so this tick is the durability
+    # backstop, not the latency path (ADR-0087 §Amendment #4191).
+    "drain-invite-emails": {
+        "task": "workspace.drain_invite_emails",
+        "schedule": 30.0,
+    },
+    # Nightly cleanup: expire overdue pending invites and delete terminal invites
+    # older than INVITE_RETENTION_DAYS (ADR-0087 §Durable Execution item 6).
+    "purge-stale-invites": {
+        "task": "workspace.purge_stale_invites",
+        # 04:15 UTC — after the other nightly purge jobs.
+        "schedule": crontab(hour=4, minute=15),
+    },
+    # Re-dispatch workspace export jobs orphaned by a broker outage at on_commit
+    # (ADR-0174 §Durable Execution item 2; 5-min orphan window inside the task).
+    "drain-workspace-exports": {
+        "task": "workspace.drain_workspace_exports",
+        "schedule": 30.0,
+    },
+    # Nightly: delete export jobs past their download-link expiry and their files
+    # (ADR-0174 §Durable Execution item 6).
+    "purge-expired-exports": {
+        "task": "workspace.purge_expired_exports",
+        # 04:20 UTC — after purge-stale-invites.
+        "schedule": crontab(hour=4, minute=20),
+    },
+    # Re-dispatch project export bundle jobs orphaned by a broker outage at on_commit
+    # (ADR-0219 §Durable Execution item 2; 5-min orphan window inside the task).
+    "drain-project-exports": {
+        "task": "projects.drain_project_exports",
+        "schedule": 30.0,
+    },
+    # Nightly: delete project export jobs past their download-link expiry and their
+    # files (ADR-0219 §Durable Execution item 6; shares TRUEPPM_EXPORT_RETENTION_DAYS).
+    "purge-expired-project-exports": {
+        "task": "projects.purge_expired_project_exports",
+        # 04:25 UTC — after the workspace export purge.
+        "schedule": crontab(hour=4, minute=25),
+    },
+    # Re-dispatch program export bundle jobs orphaned by a broker outage at on_commit
+    # (ADR-0219 §Durable Execution item 2, program grain #1958).
+    "drain-program-exports": {
+        "task": "projects.drain_program_exports",
+        "schedule": 30.0,
+    },
+    # Nightly: delete program export jobs past their download-link expiry and their
+    # files (ADR-0219 §Durable Execution item 6; shares TRUEPPM_EXPORT_RETENTION_DAYS).
+    "purge-expired-program-exports": {
+        "task": "projects.purge_expired_program_exports",
+        # 04:30 UTC — after the project export purge.
+        "schedule": crontab(hour=4, minute=30),
+    },
+    # Re-dispatch program seed IMPORT jobs orphaned by a broker outage at on_commit
+    # (ADR-0726 §Durable Execution item 2). Deliberately a separate drain from the
+    # export one: same shape, different table and different terminal semantics.
+    "drain-program-imports": {
+        "task": "projects.drain_program_imports",
+        "schedule": 30.0,
+    },
+    # Nightly: delete terminal program seed import jobs past retention and their
+    # stored payloads (ADR-0726 §Durable Execution item 6; shares
+    # TRUEPPM_IMPORT_RETENTION_DAYS with the MS Project import outbox).
+    "purge-expired-program-imports": {
+        "task": "projects.purge_expired_program_imports",
+        # 04:35 UTC — after the program export purge.
+        "schedule": crontab(hour=4, minute=35),
+    },
+    # Nightly: delete paste-many/cascade ⌘Z undo ledger rows past
+    # TRUEPPM_BATCH_OPERATION_RETENTION_DAYS, undone or not (ADR-0810, #2756).
+    "purge-expired-batch-operations": {
+        "task": "projects.purge_expired_batch_operations",
+        # 04:40 UTC — after the program import purge.
+        "schedule": crontab(hour=4, minute=40),
+    },
+    # Lazily materialize upcoming recurring-task occurrences within the
+    # TRUEPPM_RECURRENCE_HORIZON_DAYS look-ahead. Hourly: occurrences are date-grained,
+    # and a missed tick self-heals on the next one (idempotent). See ADR-0090 / #736.
+    "generate-recurring-occurrences": {
+        "task": "projects.generate_recurring_occurrences",
+        "schedule": crontab(minute=0),
+    },
+    # Nightly: flush expired OutstandingToken/BlacklistedToken rows so the JWT
+    # blacklist tables stay bounded to roughly the active-session window (#910).
+    # No-ops when the token_blacklist app is not installed.
+    "flush-expired-blacklisted-tokens": {
+        "task": "access.flush_expired_blacklisted_tokens",
+        # 04:30 UTC — after the other nightly purge jobs.
+        "schedule": crontab(hour=4, minute=30),
+    },
+    # Nightly: hard-delete per-row soft-deleted tombstones (is_deleted=True) from
+    # live projects older than TRUEPPM_TOMBSTONE_RETENTION_DAYS (default 90 days).
+    # Tombstones are kept so mobile sync clients receive deletion signals; once the
+    # retention window passes there is no further sync value in the row (#1321).
+    "reap-domain-tombstones-nightly": {
+        "task": "sync.reap_domain_tombstones",
+        # 03:30 UTC — between the sprint-close and workflow purge windows.
+        "schedule": crontab(hour=3, minute=30),
+    },
+    # External task sync (ADR-0097 §4, #1419). Outbox drain for user-scoped
+    # read-only Jira pulls: dispatches PENDING ExternalSyncRequest rows and
+    # recovers orphaned DISPATCHED ones. 300 s cadence — a personal read-only
+    # pull is not latency-critical (the POST .../sync/ trigger dispatches
+    # immediately via on_commit; this is the broker-outage backstop).
+    "drain-external-sync": {
+        "task": "integrations.drain_external_sync",
+        "schedule": 300.0,
+    },
+    # Opt-in low-frequency poll (ADR-0097 §4). Default-off per connection
+    # (config["poll_enabled"], set from the Connected Accounts toggle); fans out
+    # zero pulls until a user turns it on. 15 minutes is also the per-connection
+    # rate ceiling once one does: the outbox's one-PENDING-row-per-(user, source)
+    # constraint coalesces, so an opted-in connection can never exceed one pull
+    # per tick no matter how many sources or ticks are in flight.
+    "poll-external-sources": {
+        "task": "integrations.poll_external_sources",
+        "schedule": crontab(minute="*/15"),
+    },
+    # Nightly: hard-delete terminal (done/dead) ExternalSyncRequest outbox rows
+    # older than 7 days and long-stale ExternalWorkItem cache rows (ADR-0097
+    # §Durable Execution #6).
+    "purge-external-sync-nightly": {
+        "task": "integrations.purge_external_sync",
+        # 03:45 UTC — after the domain-tombstone reap.
+        "schedule": crontab(hour=3, minute=45),
+    },
+}
+
+# ---------------------------------------------------------------------------
+# Auth / Passwords
+# ---------------------------------------------------------------------------
+
+AUTH_PASSWORD_VALIDATORS = [
+    {"NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator"},
+    {"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator"},
+    {"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"},
+    {"NAME": "django.contrib.auth.password_validation.NumericPasswordValidator"},
+]
+
+# Self-service password reset (ADR-0209). Django's stateless
+# ``PasswordResetTokenGenerator`` (default_token_generator) rejects tokens older
+# than this window in ``check_token``. 30 minutes is the value surfaced in the
+# reset-email copy and on the "sent" / "expired" screens — short enough to bound a
+# leaked-link window, long enough for a user to act on the email.
+PASSWORD_RESET_TIMEOUT = env.int("TRUEPPM_PASSWORD_RESET_TIMEOUT", default=1800)
+
+# ---------------------------------------------------------------------------
+# SimpleJWT token lifetimes + httpOnly refresh-cookie migration (#897)
+# ---------------------------------------------------------------------------
+
+# Short access-token TTL bounds the blast radius of a leaked in-memory access
+# token; the SPA transparently refreshes via the httpOnly cookie on 401. A
+# 7-day refresh TTL is the session length — long enough to avoid daily re-login,
+# short enough that a stolen refresh token (cookie) self-expires within a week.
+# Rotation + (optional) blacklist further limit replay of a leaked refresh token.
+SIMPLE_JWT = {
+    # Sign tokens with the dedicated JWT key (#2247). Defaults to SECRET_KEY, so
+    # existing deploys are unaffected; set JWT_SIGNING_KEY to separate the two.
+    "SIGNING_KEY": JWT_SIGNING_KEY,
+    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=15),
+    "REFRESH_TOKEN_LIFETIME": timedelta(days=7),
+    "ROTATE_REFRESH_TOKENS": True,
+    # Blacklisting requires the token_blacklist app + its migrations, now shipped
+    # in INSTALLED_APPS by default (#910), so rotation actually revokes the prior
+    # refresh token. The refresh/logout views still tolerate the app's absence so
+    # an operator who removes it (lean OSS deploy) degrades gracefully to
+    # TTL-only expiry rather than erroring.
+    "BLACKLIST_AFTER_ROTATION": True,
+}
+
+# httpOnly refresh-cookie attributes (#897). The refresh token rides in this
+# cookie instead of the JSON body so JavaScript (and therefore XSS) cannot read
+# it. Attributes are env-overridable so a non-HTTPS local dev server can still
+# complete the flow.
+#
+# SameSite=Strict is safe here: the refresh request is a same-origin XHR from the
+# SPA, which Strict permits, while it blocks the cookie on any cross-site request
+# — the CSRF mitigation for this path (see core/auth_views.py).
+#
+# Env vars standardized on the TRUEPPM_ prefix pre-0.3 (#1325, #1355); the legacy
+# bare names remain fallbacks so existing deploys keep working.
+AUTH_REFRESH_COOKIE_NAME = env(
+    "TRUEPPM_AUTH_REFRESH_COOKIE_NAME",
+    default=env("AUTH_REFRESH_COOKIE_NAME", default="trueppm_refresh"),
+)
+# Path-scoped so the cookie is never sent on ordinary API calls. It must cover
+# *every* endpoint that needs to read it, which is both the refresh endpoint and
+# ``/api/v1/auth/logout/`` — scoping it to the refresh endpoint alone (the
+# pre-#2999 default) meant the browser never sent it to logout, so
+# ``CookieTokenLogoutView`` read ``None`` and revoked nothing (RFC 6265 §5.1.4).
+# ``/api/v1/auth/`` is the narrowest prefix covering both.
+AUTH_REFRESH_COOKIE_PATH = env(
+    "TRUEPPM_AUTH_REFRESH_COOKIE_PATH",
+    default=env("AUTH_REFRESH_COOKIE_PATH", default="/api/v1/auth/"),
+)
+#
+# The resolved value is validated, not passed through verbatim (#3556): refresh
+# and logout are authenticated by this cookie alone (no CSRF token, no
+# double-submit), so SameSite is the only unconditional CSRF control on them.
+# ``None`` requires the acknowledgment sentinel below or it is refused and
+# forced back to ``Strict``; ``Lax`` is accepted but logs a WARNING naming what
+# it gives up. See ``core/refresh_cookie_policy.py`` for the full resolution.
+_refresh_cookie_samesite_resolution = resolve_refresh_cookie_samesite(
+    requested=env(
+        "TRUEPPM_AUTH_REFRESH_COOKIE_SAMESITE",
+        default=env("AUTH_REFRESH_COOKIE_SAMESITE", default="Strict"),
+    ),
+    ack=env("TRUEPPM_AUTH_REFRESH_COOKIE_SAMESITE_NONE_ACK", default=""),
+)
+AUTH_REFRESH_COOKIE_SAMESITE = _refresh_cookie_samesite_resolution.value
+if _refresh_cookie_samesite_resolution.warning:
+    _settings_log.warning(_refresh_cookie_samesite_resolution.warning)
+if _refresh_cookie_samesite_resolution.critical:
+    _settings_log.critical(_refresh_cookie_samesite_resolution.critical)
+# Default Secure=True; dev settings flip this to False for plain-HTTP localhost.
+AUTH_REFRESH_COOKIE_SECURE = env.bool(
+    "TRUEPPM_AUTH_REFRESH_COOKIE_SECURE",
+    default=env.bool("AUTH_REFRESH_COOKIE_SECURE", default=True),
+)
+
+# Refresh-session lifetimes for the "remember me" choice (#2246, ADR-0544).
+# The login checkbox now drives which of these two the refresh token gets:
+#   - checked  → REFRESH_TOKEN_REMEMBER_LIFETIME: a long-lived, *persistent* cookie
+#     (survives browser close) for a trusted device.
+#   - unchecked (default) → REFRESH_TOKEN_SESSION_LIFETIME: a *session* cookie that
+#     dies on browser close, with a short sliding idle bound for a machine left open.
+# SIMPLE_JWT["REFRESH_TOKEN_LIFETIME"] (7d) stays as the LEGACY default: it is used
+# only when rotating a pre-#2246 token that carries no "remember" claim, so existing
+# sessions are never forcibly logged out (they adopt the new model at next login).
+REFRESH_TOKEN_REMEMBER_LIFETIME = timedelta(
+    days=env.int("TRUEPPM_REFRESH_TOKEN_REMEMBER_DAYS", default=30)
+)
+REFRESH_TOKEN_SESSION_LIFETIME = timedelta(
+    hours=env.int("TRUEPPM_REFRESH_TOKEN_SESSION_HOURS", default=12)
+)
+
+# ---------------------------------------------------------------------------
+# Django session + CSRF cookie hardening (#2248)
+# ---------------------------------------------------------------------------
+# These cookies are effectively exercised only by the Django admin site — the SPA
+# authenticates with the JWT bearer/refresh-cookie scheme above and the DRF
+# browsable API is disabled (JSON-only renderer). Django's implicit defaults for
+# these three already match what we want, but pin them explicitly so the posture
+# is auditable and cannot silently change across a Django upgrade. `*_SECURE` is
+# intentionally NOT pinned here: it stays False in dev (plain-HTTP localhost) and
+# prod.py sets both to True.
+SESSION_COOKIE_HTTPONLY = True
+SESSION_COOKIE_SAMESITE = "Lax"
+CSRF_COOKIE_SAMESITE = "Lax"
+# CSRF_COOKIE_HTTPONLY stays False (Django default): the token must be readable by
+# JavaScript to be echoed in the X-CSRFToken header. This is the standard,
+# correct posture and is not a leak — the CSRF cookie is not a credential.
+
+# ---------------------------------------------------------------------------
+# Content-Security-Policy (#897)
+# ---------------------------------------------------------------------------
+
+# Strict CSP, assembled into a header by core.csp.ContentSecurityPolicyMiddleware.
+# script-src 'self' (no inline / no hash) is possible because the theme-init
+# script was moved to an external file (web/public/theme-init.js). connect-src
+# carries wss: for the WebSocket collaboration channel; the host is overridable
+# per deploy. style-src keeps 'unsafe-inline' because the SPA emits inline style
+# attributes (Tailwind/JS-driven) — tightening this is tracked separately.
+_CSP_SELF = "'self'"
+CSP_CONNECT_SRC = env.list("CSP_CONNECT_SRC", default=[_CSP_SELF, "wss:"])
+CSP_DIRECTIVES: dict[str, list[str]] = {
+    "default-src": [_CSP_SELF],
+    "script-src": [_CSP_SELF],
+    "style-src": [_CSP_SELF, "'unsafe-inline'", "fonts.googleapis.com"],
+    "font-src": ["fonts.gstatic.com"],
+    "img-src": [_CSP_SELF, "data:"],
+    "connect-src": CSP_CONNECT_SRC,
+    "frame-ancestors": ["'none'"],
+    "base-uri": ["'none'"],
+    "form-action": [_CSP_SELF],
+}
+
+# ---------------------------------------------------------------------------
+# Internationalization
+# ---------------------------------------------------------------------------
+
+LANGUAGE_CODE = "en-us"
+TIME_ZONE = "UTC"
+USE_I18N = True
+USE_TZ = True
+
+# ---------------------------------------------------------------------------
+# Static files
+# ---------------------------------------------------------------------------
+
+STATIC_URL = "static/"
+# Allow an explicit env override so the app can write static files to a
+# writable path when installed as a pip package (where BASE_DIR resolves
+# inside the read-only venv).
+STATIC_ROOT = Path(env("STATIC_ROOT", default=str(BASE_DIR / "staticfiles")))
+
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+
+
+def _package_version() -> str:
+    """The installed distribution version, or a dev placeholder off-package.
+
+    Read from installed metadata rather than hard-coded so it cannot drift from
+    `pyproject.toml`; a source checkout that was never `pip install -e`'d has no
+    metadata, and "dev" is a more honest answer there than a stale literal.
+
+    Normalized to PEP 440 here because the metadata spelling belongs to the build
+    backend: hatchling <=1.32.0 wrote "0.4.0b1", 1.32.1 writes pyproject's
+    "0.4.0-beta.1" verbatim, and `pip install -e` builds with whichever is newest.
+    Without this the published schema version flips on an upstream release.
+    """
+    try:
+        from importlib.metadata import version
+
+        from packaging.version import Version
+
+        return str(Version(version("trueppm-api")))
+    except Exception:
+        return "dev"
+
+
+# ---------------------------------------------------------------------------
+# Edition detection
+# Set TRUEPPM_EDITION=enterprise in the enterprise Helm chart to activate
+# enterprise landing logic in the frontend. The /api/v1/edition/ endpoint
+# reads this setting and returns it to unauthenticated clients so the React
+# shell can make the post-login redirect decision without importing enterprise
+# code (ADR-0029).
+# ---------------------------------------------------------------------------
+
+TRUEPPM_EDITION: str = env("TRUEPPM_EDITION", default="community")
+
+# Build identity surfaced on /api/v1/edition/ so a bug report can name the exact
+# build it came from (#2392). The version tracks the package version; the SHA is
+# injected by the image build (Helm sets TRUEPPM_BUILD_SHA from the CI commit)
+# and is empty on a source checkout, where the version alone is enough.
+TRUEPPM_VERSION: str = env("TRUEPPM_VERSION", default=_package_version())
+TRUEPPM_BUILD_SHA: str = env("TRUEPPM_BUILD_SHA", default="")
+
+# ---------------------------------------------------------------------------
+# OpenTelemetry observability foundation (ADR-0223, #708)
+#
+# OPT-IN, no default endpoint. Telemetry is enabled only when an OTLP endpoint
+# is configured AND the master switch is on; with no endpoint the provider is a
+# strict no-op (no SDK objects, no export threads, zero per-request cost). We
+# read the well-known upstream OTEL_* env vars so operators reuse the names they
+# already know from every other OTel-emitting service in their cluster, and add
+# a few TRUEPPM_OTEL_* switches for behaviour the standard vars don't express.
+# The bootstrap in trueppm_api.apps.observability.otel consumes these settings.
+# ---------------------------------------------------------------------------
+
+# The gate: an empty endpoint means telemetry is off. No default is provided on
+# purpose — export must be a deliberate operator choice, never a silent egress.
+OTEL_EXPORTER_OTLP_ENDPOINT: str = env("OTEL_EXPORTER_OTLP_ENDPOINT", default="")
+# "grpc" (default, port 4317) or "http/protobuf" (port 4318).
+OTEL_EXPORTER_OTLP_PROTOCOL: str = env("OTEL_EXPORTER_OTLP_PROTOCOL", default="grpc")
+# Passed through verbatim to the exporter, e.g. "authorization=Bearer <token>"
+# for a SaaS OTLP backend. Comma-separated key=value pairs per the OTel spec.
+OTEL_EXPORTER_OTLP_HEADERS: str = env("OTEL_EXPORTER_OTLP_HEADERS", default="")
+# Resource service.name. Defaults to the service, not the pod.
+OTEL_SERVICE_NAME: str = env("OTEL_SERVICE_NAME", default="trueppm-api")
+# Master kill switch, AND-ed with endpoint presence. Lets an operator leave the
+# endpoint configured (e.g. in a shared ConfigMap) while disabling export here.
+TRUEPPM_OTEL_ENABLED: bool = env.bool("TRUEPPM_OTEL_ENABLED", default=True)
+# Independent signal toggles (only consulted when telemetry is enabled overall).
+TRUEPPM_OTEL_TRACES_ENABLED: bool = env.bool("TRUEPPM_OTEL_TRACES_ENABLED", default=True)
+TRUEPPM_OTEL_METRICS_ENABLED: bool = env.bool("TRUEPPM_OTEL_METRICS_ENABLED", default=True)
+# Trace sampler selection, using the standard upstream env var names. Because the
+# TracerProvider is built by hand (not via the SDK auto-config path), these would
+# otherwise be silently ignored; the bootstrap reads them to build a Sampler so
+# operators can throttle DB-span-dominated trace volume without a code change.
+# Recognized samplers: always_on (default), always_off, traceidratio,
+# parentbased_always_on, parentbased_always_off, parentbased_traceidratio.
+# The arg carries the ratio (0.0–1.0) for the ratio-based samplers.
+OTEL_TRACES_SAMPLER: str = env("OTEL_TRACES_SAMPLER", default="parentbased_always_on")
+OTEL_TRACES_SAMPLER_ARG: str = env("OTEL_TRACES_SAMPLER_ARG", default="")
+# Wall-clock bound (seconds) for the admin telemetry test-export probe (#2110):
+# caps the one-off canary export and the TCP reachability probe so a dead collector
+# can never hang the request thread. Well under the gunicorn worker timeout.
+TELEMETRY_TEST_EXPORT_TIMEOUT_SECONDS: int = env.int(
+    "TRUEPPM_TELEMETRY_TEST_EXPORT_TIMEOUT_SECONDS", default=5
+)
+# Live export-health recording (ADR-0601, #2109). When on (default), each pod that
+# runs an OSS OTLP exporter wraps it in a best-effort recorder that publishes
+# per-signal success/error/count into Valkey /2, so the System Health Telemetry
+# card can show a cluster-wide live strip ("last export 8s ago · 1,204 spans /
+# 60s") aggregated across the worker/beat pods that actually export. Purely
+# additive and non-fatal: a recorder or Valkey failure never affects export. Set
+# false to skip installing the wrappers entirely (the card falls back to the
+# config-only posture). Requires the Valkey /2 DB to run maxmemory-policy
+# noeviction — the same requirement the throttle counters already impose.
+TRUEPPM_OTEL_EXPORT_HEALTH_ENABLED: bool = env.bool(
+    "TRUEPPM_OTEL_EXPORT_HEALTH_ENABLED", default=True
+)
+# Optional stable per-pod identity for the export-health record. On Kubernetes the
+# hostname already IS the pod name, so the default (socket.gethostname():pid) is a
+# no-config stable identity; the Helm chart injects this via the downward API
+# (metadata.name) for a stable, human-readable label.
+TRUEPPM_POD_NAME: str = env("TRUEPPM_POD_NAME", default="")
+# Live export-health thresholds, in seconds. Defaults suit the standard 60s metric
+# export interval; tune only for unusual cadences. INVARIANT: STALENESS must exceed
+# HEALTHY_WITHIN — a record must stay live long enough to be seen as idle/stalled
+# before it expires, or an overdue signal is masked as a premature `never` (the app
+# logs a warning if this ordering is violated; it does not clamp).
+#   STALENESS: per-pod record TTL / how long a pod counts as live after its last
+#     export attempt. Beyond it (no export at all) the signal reads `never`.
+#   HEALTHY_WITHIN: a success within this window ⇒ healthy; beyond it (still live) ⇒
+#     stalled (metrics) / idle (traces).
+#   WINDOW: the rolling window the exported-item counts cover; the card labels the
+#     strip from this value ("last 60s"), so changing it re-labels the UI.
+TRUEPPM_OTEL_EXPORT_HEALTH_STALENESS_SECONDS: int = env.int(
+    "TRUEPPM_OTEL_EXPORT_HEALTH_STALENESS_SECONDS", default=600
+)
+TRUEPPM_OTEL_EXPORT_HEALTH_HEALTHY_WITHIN_SECONDS: int = env.int(
+    "TRUEPPM_OTEL_EXPORT_HEALTH_HEALTHY_WITHIN_SECONDS", default=150
+)
+TRUEPPM_OTEL_EXPORT_HEALTH_WINDOW_SECONDS: int = env.int(
+    "TRUEPPM_OTEL_EXPORT_HEALTH_WINDOW_SECONDS", default=60
+)
+# Actor attributes on the HTTP server span (#2880). When on (default), each request
+# span carries trueppm.user.id (the acting account's opaque UUID) and
+# trueppm.user.role (the symbolic project role the request was authorized under), so
+# a trace can be attributed to a who and a permission level without opening the
+# payload. NOTHING else about the person is ever exported under trueppm.user.* — no
+# email, username, display name, or client IP. Set false where a per-user identifier
+# must not leave the instance even to a self-hosted collector; resource identity
+# (trueppm.project.id / .program.id / .task.id) is unaffected either way.
+TRUEPPM_OTEL_ACTOR_ATTRIBUTES_ENABLED: bool = env.bool(
+    "TRUEPPM_OTEL_ACTOR_ATTRIBUTES_ENABLED", default=True
+)
+
+# ---------------------------------------------------------------------------
+# Structured logging + trace correlation (ADR-0223, #1899)
+#
+# The base config emits human-readable console lines that still carry the OTel
+# trace_id/span_id/request_id inline, so a developer sees the same correlation
+# context locally. prod.py flips this to single-line JSON (TRUEPPM_LOG_JSON) for a
+# collector to index. The level honours DJANGO_LOG_LEVEL (default INFO) — the same
+# well-known name operators set on every other Django service. Trace correlation
+# (not OTLP log export, which is #711) means a log line can be pivoted straight to
+# the trace exported for the same request.
+# ---------------------------------------------------------------------------
+
+DJANGO_LOG_LEVEL: str = env("DJANGO_LOG_LEVEL", default="INFO")
+# JSON is opt-in in the base config so dev stays readable; prod.py sets this True.
+TRUEPPM_LOG_JSON: bool = env.bool("TRUEPPM_LOG_JSON", default=False)
+
+from trueppm_api.apps.observability.logging import (  # noqa: E402
+    build_logging_config,
+)
+
+LOGGING = build_logging_config(level=DJANGO_LOG_LEVEL, json_output=TRUEPPM_LOG_JSON)
+
+# ---------------------------------------------------------------------------
+# Integration credential encryption key (ADR-0049 §3)
+#
+# Fernet key used to encrypt the PAT secrets stored in
+# trueppm_api.apps.integrations.IntegrationCredential.secret_ciphertext.
+# Production deployments source this from a Kubernetes Secret via the Helm
+# chart; the empty default fails loud (ImproperlyConfigured) the first time
+# the helper is called, which is what we want — better than silently storing
+# unencrypted PATs in dev because someone forgot to set the env var.
+#
+# Generate one with:
+#   python -c "from cryptography.fernet import Fernet; \
+#              print(Fernet.generate_key().decode())"
+# ---------------------------------------------------------------------------
+
+INTEGRATION_ENCRYPTION_KEY: str = env(
+    "INTEGRATION_ENCRYPTION_KEY",
+    default="",
+)
+
+# Hostnames exempted from the SSRF egress deny-list (apps/integrations/http). An
+# operator escape hatch for a trusted internal host the operator runs themselves —
+# chiefly an in-cluster identity provider whose OIDC issuer resolves to a private
+# ClusterIP (e.g. Keycloak at ``keycloak.sso.svc``), which the deny-list would
+# otherwise block, making in-cluster SSO impossible. Empty by default keeps the
+# standard "every resolved address must be globally routable" posture. Exact,
+# case-insensitive hostname match — no wildcards. Config-only, never
+# request-derived. NOTE: the allow-list is consulted by *every* egress caller (PAT
+# verification, git-link refresh, webhooks, SMTP relay, SSO), so an allow-listed
+# host is reachable through the user-influenceable URL surfaces too — only list a
+# host at least as trusted as the SSO issuer. See ADR-0590 and the "Running the
+# identity provider inside your cluster" section of
+# packages/website/src/content/docs/administration/single-sign-on.md.
+EGRESS_ALLOWLISTED_HOSTS: list[str] = env.list("TRUEPPM_EGRESS_ALLOWLISTED_HOSTS", default=[])
+
+# Per-provider base-URL allow-list for user-connected external task sources
+# (ADR-0097 / ADR-0589). Read at ``apps/integrations/providers.py:85`` and named in
+# the rejection message an operator sees when their self-hosted Jira/GitLab host is
+# refused — but bound by NO settings module until #2860, so setting the documented
+# env var did nothing and the escape hatch the message points at did not exist.
+#
+# The allow-list fails CLOSED, so the bug was the inverse of a security hole: an
+# operator with a legitimately self-hosted instance could not connect it at all, and
+# the error told them to set a variable that was never read. Documented in four
+# places (configuration.md, connected-accounts.md, ADR-0589, changelog.d/2270)
+# throughout.
+#
+# Distinct from EGRESS_ALLOWLISTED_HOSTS above, which is the SSRF deny-list escape
+# hatch consulted by *every* egress caller. This one only widens which base URLs a
+# user may attach a personal credential to; a host listed here still passes through
+# the SSRF-guarded http helper on every fetch.
+INTEGRATION_ALLOWED_HOSTS: list[str] = env.list("TRUEPPM_INTEGRATION_ALLOWED_HOSTS", default=[])
+
+# Age in seconds past which a connected external-source connection's cache is
+# "stale" for the My Work on-open refresh (ADR-0097 §4 "on-open refresh-if-
+# stale"; #1921). Reuses the same order of magnitude as the manual-refresh
+# cooldown (ADR-0097 §Resolution #5, `services.MANUAL_SYNC_COOLDOWN_SECONDS`)
+# rather than inventing an unrelated number — a connection synced within this
+# window is fresh enough that another My Work load should not re-trigger a
+# pull. Configurable per-operator: a slower Jira instance or a rate-sensitive
+# token may want a wider floor.
+TRUEPPM_EXTERNAL_SYNC_ON_OPEN_STALE_SECONDS: int = env.int(
+    "TRUEPPM_EXTERNAL_SYNC_ON_OPEN_STALE_SECONDS", default=300
+)
+
+# ---------------------------------------------------------------------------
+# Monte Carlo simulation caps (OSS tier)
+# Set to None for unlimited (Enterprise overrides these in enterprise settings).
+# ---------------------------------------------------------------------------
+
+MC_SIMULATION_CAP: int | None = 1_000
+# Raised 500 -> 5000 (#823): the OSS scaling story is "10k tasks", but the MC
+# endpoint returned HTTP 402 for any project over 500 tasks, so Monte Carlo was
+# silently unavailable for realistic large projects. The vectorised numpy path
+# (scheduler/engine.py) is O(runs x tasks x edges) and handles a 5000-task x
+# 1000-run simulation in a few seconds. Operators on constrained hardware can
+# lower this; Enterprise overrides it in enterprise settings.
+MC_TASK_CAP: int | None = 5_000
+
+# Request-path ceiling on the Monte Carlo lag-delta table (#4129):
+# (distinct dependency type/lag/calendar-pair keys) x (working-day span) cells, each a
+# 4-byte int32, so 5M cells is ~20 MB per simulation (the what-if endpoint runs two
+# in sequence, never concurrently). The scheduler library default is 50M cells
+# (~200 MB) because a batch caller owns the machine; a synchronous endpoint shares a
+# pod with concurrent requests and MC_TASK_CAP / MC_SIMULATION_CAP do not bound this
+# product, so a project that passed every other cap could peak near 630 MB. Above the
+# cap the run is refused as a 400 naming the lag variety. None = the library default.
+MC_LAG_DELTA_CELL_CAP: int | None = 5_000_000
+
+# Request-path ceiling on the PRODUCT runs x n_tasks (#2839). MC_SIMULATION_CAP and
+# MC_TASK_CAP bound each dimension, but the simulation keeps three (runs, n_tasks)
+# float64 matrices live at once plus temporaries, so its memory and its (vectorized,
+# ~linear) wall time follow the product. At 5,000 x 1,000 = 5M cells one simulation
+# peaked at ~234 MB traced / ~336 MB RSS, on the single default API worker
+# (processes.api.workers: 1, 2 GiB limit) that also serves every WebSocket, and the
+# what-if endpoint runs two back to back. 2.5M cells halves that (~117 MB traced,
+# ~168 MB peak RSS at the measured ~67 B/cell — size limits against RSS),
+# still runs the full 1,000 iterations up to 2,500 tasks, and gives a project at
+# MC_TASK_CAP 500 — the percentile resolution of a 500-sample run is 0.2%, well
+# inside the day granularity the forecast reports. An omitted n_simulations scales
+# down to fit (the response's `runs` reports it); an explicit one above the
+# size-derived maximum is refused 400 rather than silently shrunk. Not an edition
+# gate: it protects the worker, so Enterprise keeps it unless its hardware differs.
+# None = no product cap.
+MC_CELL_CAP: int | None = 2_500_000
+
+# Simulations one API process runs at once (#2839). Sync views run one thread per
+# request under ASGI, so concurrent runs in one worker are real; MC_CELL_CAP bounds
+# each, this bounds how many stack. 2 x ~117 MB keeps a full-size burst far inside
+# the 2 GiB default worker limit. A request waits up to 10 s for a slot, then gets
+# 503 + Retry-After. Per process, so N workers admit N x this. None = unbounded.
+MC_MAX_CONCURRENT: int | None = 2
+
+# Project Monte Carlo run-history retention (ADR-0175, #961): the nightly purge
+# keeps the newest MC_HISTORY_CAP MonteCarloRun rows per project so a PM can read
+# finish-date forecast drift over time. None = unlimited (Enterprise overrides it
+# — unbounded history + cross-program rollup is the portfolio upsell).
+MC_HISTORY_CAP: int | None = 100
+
+# Per-run distribution persistence (#1231, ADR-0144). The full
+# {histogram_buckets, confidence_curve, sensitivity} payload is stored on
+# MonteCarloRun.distribution so the histogram survives cache expiry. Bounded at
+# 32 KB: a payload over this is down-sampled (every Nth histogram bucket) before
+# persist so a pathological high-bucket run cannot bloat the row. The cache copy
+# is unaffected by the down-sample.
+MC_DISTRIBUTION_MAX_BYTES: int = 32_768
+
+# Absolute upper bound on the per-workspace forecast-history retention cap
+# (ADR-0144). The per-workspace mc_history_retention_cap is clamped to this on
+# read so an operator (or future Enterprise override) cannot configure an
+# unbounded per-project history that the nightly purge would never trim.
+MC_HISTORY_HARD_CAP: int = 500
+
+# Tiered retention curve for project-grain forecast snapshots (ADR-0154, #388).
+# The nightly prune keeps every snapshot younger than ``daily_days``, then thins to
+# one-per-ISO-week up to ``weekly_days``, then one-per-calendar-month beyond that
+# (kept forever — the cold tail is ~12 rows/project/year). Operators can tune the
+# two windows; the per-period keeper is always the newest row in that bucket.
+FORECAST_SNAPSHOT_RETENTION: dict[str, int] = {
+    "daily_days": 90,
+    "weekly_days": 365,
+}
+
+# ---------------------------------------------------------------------------
+# Upload caps (ADR-0075, task attachments)
+# ---------------------------------------------------------------------------
+
+# Hard 100 MB ceiling matches the TaskAttachment cap (ADR-0075 locked
+# constraint #4). The serializer also enforces this, but the setting must
+# fire FIRST — without it, Django buffers the entire body to /tmp before
+# the serializer runs, which lets an authenticated Member spam 100 MB+
+# multipart bodies and exhaust worker time + disk. Operators should also
+# set nginx `client_max_body_size: 100m` so over-sized requests are
+# rejected at the edge, not after Django finishes parsing them.
+DATA_UPLOAD_MAX_MEMORY_SIZE = 100 * 1024 * 1024  # 100 MB
+FILE_UPLOAD_MAX_MEMORY_SIZE = 2_621_440  # 2.5 MB (Django default; explicit)
+
+# Days a public share link lasts when the mint request omits ``expires_at`` (#3177).
+# An explicit null still means "never expires" — this is a default, not a ceiling, so
+# standing embeds and wallboards stay possible. Set to 0 to restore the pre-#3177
+# behavior in which an omitted expiry meant never.
+TRUEPPM_SHARE_LINK_DEFAULT_EXPIRY_DAYS = env.int(
+    "TRUEPPM_SHARE_LINK_DEFAULT_EXPIRY_DAYS", default=90
+)
+
+# Per-file cap for MS Project (.mpp/.xml) imports. Lower than the 100 MB
+# attachment ceiling on purpose: unlike attachments (FileField → disk), an
+# import is read fully into memory and stored base64-encoded in a single
+# ImportRequest DB row (~+33%), so a 50 MB upload already costs ~67 MB of
+# memory and row size. 50 MB is the practical MS Project file ceiling
+# (larger schedules degrade in Project itself). The global
+# DATA_UPLOAD_MAX_MEMORY_SIZE and nginx client_max_body_size (both 100 MB)
+# remain the hard edge cap — do not configure this above them.
+MSPROJECT_MAX_UPLOAD_MB: int = env.int("MSPROJECT_MAX_UPLOAD_MB", default=50)
+
+# Max number of tasks (also applied to resources and dependency links) a single
+# MS Project import may contain (#1721). The upload SIZE cap alone is not enough:
+# a 50 MB MSPDI XML can encode ~1M tasks, and the importer builds one Task object
+# per task, computes WBS over all of them, then bulk-creates the lot — a
+# worker-memory / transaction-time DoS well within the byte ceiling. Rejecting
+# outright (like the risk-CSV importer's MAX_ROWS) is safer than partially
+# processing. 20k tasks is far above any realistic hand-authored schedule while
+# bounding the object graph a single request can materialize.
+MSPROJECT_MAX_ROWS: int = env.int("MSPROJECT_MAX_ROWS", default=20_000)
+
+# batch_size for the import bulk_create() calls (#1721). Without it, Django emits
+# one giant multi-row INSERT that pins the whole task/dependency set in a single
+# statement (and can exceed PostgreSQL parameter limits); chunking bounds the
+# per-statement memory and parameter count. Shared by the MS Project and Jira
+# import paths (both persist through msproject.importer.import_project).
+IMPORT_BULK_BATCH_SIZE: int = env.int("IMPORT_BULK_BATCH_SIZE", default=500)
+
+# Hard cap on the XML MPXJ streams to stdout when converting a .mpp (#1722). A
+# decompression-bomb .mpp within the 50 MB upload cap can expand to multi-GB XML;
+# buffering it unbounded (the old capture_output=True) OOMs the worker. We stream
+# stdout and abort past this many bytes. 512 MB is generous headroom for a
+# legitimate 50 MB .mpp (MSPDI XML is ~5-10x the binary) while still bounded.
+MPXJ_MAX_OUTPUT_MB: int = env.int("MPXJ_MAX_OUTPUT_MB", default=512)
+
+# Per-file cap for CSV/Excel imports (#743). Much lower than the MS Project
+# ceiling on purpose: a spreadsheet migration is a hand-maintained sheet, not a
+# generated plan, and 10 MB is already far past what any real one weighs. The
+# same base64-in-a-DB-row cost applies (~+33%).
+CSV_IMPORT_MAX_UPLOAD_MB: int = env.int("CSV_IMPORT_MAX_UPLOAD_MB", default=10)
+
+# Max data rows a single CSV/Excel import may contain (#743). The byte cap alone
+# is not enough — a 10 MB CSV can encode well over a million short rows, and the
+# parser builds one TaskData per row before anything is written. Rows past the
+# cap are reported back as `truncated_rows` rather than silently dropped.
+CSV_IMPORT_MAX_ROWS: int = env.int("CSV_IMPORT_MAX_ROWS", default=5_000)
+
+# The tested-comfortable Schedule size (#3388, administration/sizing.md
+# "Tested envelope"): whole-project load is measured at 1.85s at 1,000 tasks and
+# breaches at 2,000 (60s) — a cliff, not a slope. CSV_IMPORT_MAX_ROWS (5,000) is
+# far above this, so nothing stops an import from landing a project past the
+# ceiling it cannot comfortably open. This is a *warn, do not block* line, not a
+# correctness limit — someone on better hardware may legitimately want more —
+# so it is only ever surfaced as advisory fields on the import preview response
+# (`exceeds_recommended_ceiling`) and read client-side against the already-loaded
+# Schedule task count. Configurable because the comfortable figure is
+# hardware-dependent and is expected to move as #3383 lands.
+SCHEDULE_TASK_CEILING: int = env.int("TRUEPPM_SCHEDULE_TASK_CEILING", default=1_000)
+
+# Decompression-bomb ceiling for .xlsx uploads (#743). An .xlsx is a zip of XML:
+# openpyxl inherits XXE hardening from defusedxml automatically, but nothing in
+# that stack bounds the *inflated* size, so a 1 MB upload can expand to
+# gigabytes and OOM the worker. The parser sums the zip central directory's
+# declared sizes — cheap, and before any XML is touched — and rejects above this.
+CSV_IMPORT_MAX_UNCOMPRESSED_MB: int = env.int("CSV_IMPORT_MAX_UNCOMPRESSED_MB", default=100)
+
+# JVM max-heap (-Xmx) for the MPXJ subprocess (#1722). Bounding the JVM heap is a
+# second line of defense: even if MPXJ tries to build a giant in-memory model
+# from a bomb file, the JVM dies with an OutOfMemoryError (caught as a non-zero
+# exit) instead of driving the host into swap.
+MPXJ_MAX_HEAP_MB: int = env.int("MPXJ_MAX_HEAP_MB", default=512)
+
+# Max size of an uploaded Jira XML export (#1664). Jira issue-navigator exports
+# are small relative to .mpp files; the 25 MB default is generous for the minimal
+# import slice and stays well under the DATA_UPLOAD_MAX_MEMORY_SIZE hard cap.
+JIRA_IMPORT_MAX_UPLOAD_MB: int = env.int("JIRA_IMPORT_MAX_UPLOAD_MB", default=25)
+
+# Max number of issues a single Jira XML import may contain (#1721). Same
+# rationale as MSPROJECT_MAX_ROWS: the byte cap does not bound the derived task
+# count, and every issue becomes a Task object built and bulk-created through the
+# shared importer. Rejected outright over the limit.
+JIRA_IMPORT_MAX_ROWS: int = env.int("JIRA_IMPORT_MAX_ROWS", default=20_000)
+
+# Max size of an uploaded JSON program seed (ADR-0109, #615). Seeds are bounded
+# (the largest bundled sample is a few hundred KB); 5 MB is generous headroom
+# while bounding the memory a single authenticated import request can consume.
+SEED_MAX_UPLOAD_MB: int = env.int("SEED_MAX_UPLOAD_MB", default=5)
+
+# Max seed imports one account may have queued or running at once (#2615). The
+# ``seed_import`` throttle bounds the *rate* of job creation; it does not bound
+# how many of those jobs are outstanding, because the per-program in-flight
+# de-dupe in ``enqueue_program_import`` can never match on this path — the
+# request creates a fresh Program three lines earlier, so a brand-new program
+# has no prior job to de-dupe against. Without a per-user ceiling, six requests
+# a minute sustained becomes an unbounded worker backlog of full subtree builds.
+SEED_IMPORT_MAX_CONCURRENT_JOBS: int = env.int("SEED_IMPORT_MAX_CONCURRENT_JOBS", default=3)
+
+# ---------------------------------------------------------------------------
+# Django REST Framework
+# ---------------------------------------------------------------------------
+
+# The tightest scoped-throttle tier, shared by the handful of single-shot
+# endpoints whose per-call cost — one outbound egress probe or one double
+# CPM + Monte Carlo pass — makes even a modest loop abusive. Kept as one named
+# constant so the rate lives in a single place rather than a repeated literal.
+_STRICT_ABUSE_RATE = "6/min"
+
+# The remaining scoped-throttle tiers, from the general per-user default down
+# to the credential-shaped endpoints (login, password reset, invite resend).
+# Named once for the same reason as _STRICT_ABUSE_RATE above.
+# Trusted-proxy depth, validated here rather than left to DRF (#4020). A negative
+# value makes DRF's ``addrs[-min(NUM_PROXIES, len(addrs))]`` index from the LEFT —
+# the client-written end of X-Forwarded-For — or raise IndexError on a one-entry
+# header, so it is never a working configuration; refuse to boot on it.
+_NUM_PROXIES = env.int("TRUEPPM_NUM_PROXIES", default=1)
+if _NUM_PROXIES < 0:
+    raise ImproperlyConfigured(
+        f"TRUEPPM_NUM_PROXIES must be 0 or a positive integer (got {_NUM_PROXIES}). "
+        "It is the number of reverse proxies in front of Django; see "
+        "administration/networking.md."
+    )
+
+_STANDARD_RATE = "60/min"
+_MODERATE_RATE = "20/min"
+_STRICT_RATE = "10/min"
+_RELAXED_RATE = "120/min"
+_STRICTEST_RATE = "5/min"
+
+REST_FRAMEWORK = {
+    # JWT + owner-scoped API token in the base/prod posture (#2248, #2547). The SPA
+    # authenticates with the bearer access token; there is no Django-session login
+    # path for the API and the browsable API is disabled (JSON-only renderer below),
+    # so SessionAuthentication would be an unused second auth surface (and its CSRF
+    # coupling) in production. Dev settings re-add SessionAuthentication so
+    # `client.force_login()` in the test suite can populate request.user.
+    #
+    # OwnerScopedApiTokenAuthentication is listed first (mirroring
+    # McpReadableViewMixin.get_authenticators' ordering): it returns None for any
+    # bearer that isn't one of our tppm_-prefixed tokens, so JWT still gets a turn
+    # for every human/SPA request. It only accepts an owner-scoped Personal Access
+    # Token carrying the legacy:full scope — project/program-scoped integration
+    # tokens and mcp:read-only tokens are rejected here and keep authenticating only
+    # via the narrow surfaces that reference ProjectApiTokenAuthentication directly
+    # (TaskSyncView, the acceptance-result view, the MCP-readable viewsets).
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "trueppm_api.apps.projects.authentication.OwnerScopedApiTokenAuthentication",
+        "rest_framework_simplejwt.authentication.JWTAuthentication",
+    ],
+    "DEFAULT_PERMISSION_CLASSES": [
+        "rest_framework.permissions.IsAuthenticated",
+    ],
+    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
+    "PAGE_SIZE": 50,
+    # API-only service: render JSON, nothing else. DRF's default renderer set
+    # includes BrowsableAPIRenderer, which content-negotiates on the request
+    # Accept header and, for a serializer-less GenericViewSet, calls
+    # get_serializer() to build its HTML form — firing DRF's
+    # `assert self.serializer_class is not None` (an unhandled 500) whenever a
+    # caller sends `Accept: text/html`. A fuzzer (or any browser) trivially
+    # trips this on every serializer-less action. Restricting to JSONRenderer
+    # turns those requests into a clean 406 and removes the whole class of bug
+    # (#2213). Set unconditionally (not DEBUG-gated) because the nightly fuzz
+    # and the test suite run under dev settings with DEBUG=True — the browsable
+    # API is redundant with the drf-spectacular Swagger UI anyway.
+    "DEFAULT_RENDERER_CLASSES": [
+        "rest_framework.renderers.JSONRenderer",
+    ],
+    # Custom handler translates a malformed UUID (bad path segment or query param)
+    # into 404/400 instead of the 500 DRF's default returns for the Django
+    # ValidationError / uuid.UUID ValueError those raise (#2125).
+    "EXCEPTION_HANDLER": "trueppm_api.core.exception_handlers.trueppm_exception_handler",
+    # Tolerant OPTIONS metadata: DRF's default calls get_serializer() while
+    # building action metadata, which asserts (→ 500) on serializer-less
+    # GenericViewSets. This subclass degrades that to empty action metadata (#2229).
+    "DEFAULT_METADATA_CLASS": "trueppm_api.core.metadata.TolerantMetadata",
+    "DEFAULT_FILTER_BACKENDS": [
+        "rest_framework.filters.SearchFilter",
+        "rest_framework.filters.OrderingFilter",
+    ],
+    # Custom AutoSchema documents a 429 response on rate-limited operations (#1333);
+    # throttling is a view attribute invisible to the schema post-processing hooks.
+    "DEFAULT_SCHEMA_CLASS": "trueppm_api.core.openapi.TruePPMAutoSchema",
+    # General default throttle (#1080). Every endpoint that does NOT declare its
+    # own throttle_classes gets the baseline "anon"/"user" rate below — the
+    # general DoS / resource-starvation protection a self-hoster expects. The
+    # ProbeExempt* classes are the stock DRF anon/user throttles with one
+    # override: they never count the unauthenticated /api/v1/health/ and
+    # /api/v1/edition/ probe endpoints, which Kubernetes hits on a tight
+    # liveness/readiness loop (the reason a bare AnonRateThrottle was previously
+    # avoided — now solved by the exemption). A view that sets its own
+    # throttle_classes (login, refresh, monte_carlo, etc. below) REPLACES this
+    # default rather than stacking on top of it, so those endpoints keep only
+    # their specific, stricter scope.
+    "DEFAULT_THROTTLE_CLASSES": [
+        "trueppm_api.core.throttling.ProbeExemptAnonRateThrottle",
+        "trueppm_api.core.throttling.ProbeExemptUserRateThrottle",
+    ],
+    # Trusted-proxy depth for client-IP extraction (#1080). Without this DRF keys
+    # the anon throttle on the client-supplied X-Forwarded-For header verbatim, so
+    # an attacker could rotate XFF to mint a fresh anon identity per request and
+    # bypass the anon limit entirely. NUM_PROXIES tells DRF how many trusted proxies
+    # sit in front of the app (the standard Helm chart has a single ingress → 1), so
+    # it reads the real client IP from a trusted position and ignores attacker-
+    # prepended entries. Set to the deployment's actual proxy depth via env; 0 means
+    # "no proxy, use REMOTE_ADDR". The authenticated "user" scope keys on the account
+    # id and is unaffected.
+    #
+    # Wrong in EITHER direction is silent (#4020): too low collapses every per-IP
+    # throttle into one shared bucket, too high lets a client pick its own bucket
+    # via X-Forwarded-For. Nothing here can know the real topology, so the check is
+    # a readback — GET /api/v1/health/system/ → security.client_address shows the
+    # address THIS request was keyed on. See administration/networking.md.
+    "NUM_PROXIES": _NUM_PROXIES,
+    "DEFAULT_THROTTLE_RATES": {
+        # General default rates for the ProbeExempt* classes above. Env-tunable
+        # so operators can tighten or loosen the baseline without a rebuild.
+        # "anon" bounds unauthenticated traffic per client IP; "user" bounds an
+        # authenticated account. Both are generous enough that a normal
+        # interactive client never trips them.
+        "anon": env("TRUEPPM_THROTTLE_ANON_RATE", default=_STANDARD_RATE),
+        "user": env("TRUEPPM_THROTTLE_USER_RATE", default="1000/min"),
+        # /api/v1/readyz (#2820). Unlike /health/ and /edition/, readyz is not
+        # free — every call does a real database round-trip and a real cache
+        # round-trip — and it used to be FULLY exempt from the shared throttle
+        # (the same exemption /health/ and /edition/ still get), which meant an
+        # unauthenticated caller who found the pod IP directly (the probe path
+        # bypasses the Ingress) could drive unbounded database load with no rate
+        # limit at all. A dedicated scope, not the shared "anon" bucket: readyz
+        # traffic comes from kubelet hitting the pod IP directly rather than
+        # through the Ingress, so its source IP is the node, not an end user's,
+        # and sharing "anon" would let a legitimate probe loop compete with real
+        # anonymous traffic in both directions. The default is generous enough
+        # that no documented probe configuration comes close to tripping it —
+        # see administration/probes.md for the numbers this assumes — while
+        # still bounding an outright flood from an unauthenticated source.
+        "readyz": env("TRUEPPM_THROTTLE_READYZ_RATE", default="2000/min"),
+        "login": _STRICT_RATE,
+        # Per-account login lockout (#1717). The "login" scope above keys on the
+        # client IP, so it only bounds guesses per source address; a distributed
+        # credential-stuffing attack from a rotating IP pool gets the full per-IP
+        # allowance from every fresh IP and is unbounded in aggregate against one
+        # account. This scope keys on the (hashed, normalized) submitted username
+        # instead, so attempts against a single account are capped no matter how
+        # many IPs participate. It is STACKED with "login" — both throttles apply
+        # to the login view. Env-tunable so an operator can tighten or loosen it.
+        # 5/min still leaves room for a human who fat-fingers a password a few
+        # times, while making cross-IP account targeting expensive.
+        "login_account": env("TRUEPPM_THROTTLE_LOGIN_ACCOUNT_RATE", default=_STRICTEST_RATE),
+        # Self-service password reset (#765, ADR-0209). Covers BOTH the request
+        # endpoint (which emails a reset link) and the confirm endpoint (which sets
+        # the new password). 5/min per IP bounds two abuses at once: email-bombing a
+        # victim by looping the request endpoint, and timing/enumeration probing of
+        # which addresses have accounts (the request endpoint returns an identical
+        # 200 either way, so the throttle is the primary enumeration defense — see
+        # ADR-0209). 5/min still leaves ample room for a human who mistypes, resends,
+        # and retries a confirm a couple of times.
+        "password_reset": _STRICTEST_RATE,
+        # JWT refresh (#814). 60/min is loose enough that any realistic
+        # web/mobile client (5-minute access-token TTL → ~12 refreshes/hour)
+        # never trips it, but tight enough that a stolen/leaked refresh token
+        # cannot be exchanged for access tokens at unbounded rate.
+        "refresh": _STANDARD_RATE,
+        # User typeahead for member invite (#815). Tight enough that a single
+        # account cannot bulk-scrape the workspace user list, loose enough that
+        # interactive typeahead (debounced, >=2 chars) never trips it.
+        "user_search": _STANDARD_RATE,
+        # ⌘K global Epic/Story omni-search (ADR-0508 D4, #2103). A debounced,
+        # >=2-char typeahead over the caller's own membership; the 60/min bound
+        # matches user_search — snug enough that a scripted loop cannot bulk-map
+        # every epic/story title the account can see, loose enough that live typing
+        # never trips it.
+        "omni_search": env("TRUEPPM_THROTTLE_OMNI_SEARCH_RATE", default=_STANDARD_RATE),
+        # Project/program key resolver + key suggestion (ADR-1237 §5-§6). One
+        # per-user bucket for both: the resolver runs once per cold key-URL load
+        # and the suggestion once per debounced keystroke on a create form, so
+        # 120/min never trips a person — and it bounds using either endpoint as a
+        # scan engine over the key namespace (the accepted existence oracle).
+        "resolve": env("TRUEPPM_THROTTLE_RESOLVE_RATE", default=_RELAXED_RATE),
+        # WebSocket connection tickets (#818, ADR-0141). One ticket is minted per
+        # socket open (and per reconnect, since tickets are single-use); 120/min
+        # covers aggressive reconnect storms without letting one account flood
+        # Redis with 30-second ticket keys.
+        "ws_ticket": _RELAXED_RATE,
+        # Invite-email resend (#969, ADR-0149). Each request re-issues a token and
+        # re-queues an email; 5/min per admin bounds email-bomb abuse while leaving
+        # ample room for a human clicking "Resend" on a handful of stuck invites.
+        # "Resend all" is one request → one bucket hit, so it cannot be looped past
+        # the cap.
+        "invite_resend": _STRICTEST_RATE,
+        # Workspace SMTP config (#712, ADR-0213). Writes re-open a candidate SMTP
+        # connection (validate-before-persist); "probe" covers the two outbound
+        # amplifiers — send-test (opens a real SMTP socket) and the deliverability
+        # health check (fires live DNS TXT lookups). Both are blind-SSRF / egress
+        # oracles if unbounded, so cap them tightly (security review H3). An admin
+        # configuring mail never trips these; a script probing hosts does.
+        "email_settings": "12/min",
+        "email_settings_probe": _STRICT_ABUSE_RATE,
+        # SSO domain discovery (ADR-0187). Unauthenticated; reveals only whether a
+        # *domain* uses SSO (never whether an account exists), but the rate still
+        # bounds bulk domain-probing. Loose enough for the interactive login page.
+        "oidc_discover": "30/min",
+        # SSO login start (ADR-0187). Each hit mints a single-use state/PKCE/nonce
+        # cache entry and 302s to the IdP; this also implicitly bounds the callback
+        # (every callback requires a state minted here). Snug but ample for humans.
+        "oidc_login": _MODERATE_RATE,
+        # SSO callback (ADR-0187). A token-issuing endpoint; the implicit bound via
+        # oidc_login already caps legitimate use, but an explicit cap blunts a flood
+        # of forged callbacks (each fails fast at the browser-state-cookie check).
+        "oidc_callback": "30/min",
+        # Admin "Test connection" probe (ADR-0517 §3.4). Each call triggers
+        # server-side egress (OIDC discovery + JWKS, or the GitHub API), so it needs
+        # an abuse bound so an admin cannot drive unbounded outbound requests.
+        # 20/min is ample for a human wiring up a provider.
+        "sso_test_connection": _MODERATE_RATE,
+        # SSO provider create/update/delete (#3552, ADR-1120). These views previously
+        # declared no throttle and fell back to the global "user" rate of 1000/min. Each
+        # accepted write now also appends an AuditEvent row, and the OSS audit table has
+        # no retention or pruning — so a scripted `enabled` toggle would append at the
+        # request ceiling, every row a *genuine* change that the no-op suppression cannot
+        # filter. Note who pays: in a self-hosted install the workspace Admin driving the
+        # loop and the operator whose disk fills are frequently different people. Applied
+        # to the mutating methods only (see ``_SsoProviderWriteThrottle``) — the
+        # collection GET backs the admin page and must not be capped at a write rate.
+        "sso_provider_write": _MODERATE_RATE,
+        # Integration-credential and Git webhook-secret endpoints (#1551). Covers the
+        # per-user credential store (connect/rotate/revoke/read) and the project-admin
+        # Git-automation config + secret-rotation views. Each of these mints, returns,
+        # or reveals the presence of a plaintext credential/secret, so they need the
+        # same brute-force/abuse bound the other credential-adjacent endpoints already
+        # carry. 10/min is snug for a human wiring up integrations yet far below any
+        # automated rotation-scraping rate.
+        "credential_rotate": _STRICT_RATE,
+        # Manual external-source pull trigger (POST /me/connections/{source}/sync/,
+        # ADR-0097 §4, #1419). The service-layer 60 s per-connection cooldown is the
+        # primary spacing control; this scope is the coarse abuse bound so a scripted
+        # loop cannot spam the outbox faster than a human ever would. 20/min sits
+        # above the cooldown's ~1/min steady state with headroom for multiple
+        # connected sources.
+        "external_sync": _MODERATE_RATE,
+        # Synchronous Monte Carlo simulation (#1552). run_monte_carlo executes an
+        # expensive (up to MC_SIMULATION_CAP iterations, caller-controlled
+        # n_simulations) simulation inline in the request/response cycle, gated only
+        # by project membership. Without a rate cap any single member can loop the
+        # endpoint to exhaust CPU. 10/min leaves ample headroom for a human tuning
+        # estimates and re-running the forecast a handful of times, while blunting a
+        # scripted resource-exhaustion flood.
+        "monte_carlo": _STRICT_RATE,
+        # Non-mutating Monte Carlo what-if (#993). The what-if endpoint runs *two*
+        # CPM passes and *two* Monte Carlo simulations per call (baseline vs the
+        # perturbed schedule, so the delta isolates the perturbation) — roughly
+        # double the CPU of a single run_monte_carlo — so it carries a tighter cap
+        # than the plain "monte_carlo" scope. 6/min still leaves ample room for a
+        # human (or an MCP agent) exploring a handful of "what if I slip this task"
+        # scenarios while blunting a scripted resource-exhaustion flood.
+        "monte_carlo_whatif": _STRICT_ABUSE_RATE,
+        # Burn chart / flow metrics reads (#3581). ProjectBurnView.get and
+        # FlowMetricsView.get both reconstruct their series from HistoricalTask
+        # snapshots — the floor cost scales with project history (#3579) even
+        # though #3566 bounds the window per request. Either endpoint is reachable
+        # by any project member (down to Viewer), and both were left on the
+        # general "user" default of 1000/min before this scope existed, which is
+        # meaningful amplification against a shared database. Shared bucket
+        # between the two views (same cost class, same table) rather than a
+        # scope each. 60/min is far above what the Reports page generates —
+        # useBurnChart has a 5-minute staleTime.
+        "burn": env("TRUEPPM_THROTTLE_BURN_RATE", default=_STANDARD_RATE),
+        # On-read CPM derivation (#2839). GET /projects/<pk>/schedule/derivation/ runs
+        # a full schedule() pass inside derive_value on every CPM-quantity call — the
+        # compute class #1808 bounded on its Monte Carlo siblings but missed here, so
+        # it fell through to the general 1000/min account default. One CPM pass is
+        # far cheaper than a simulation, so this sits at the general read tier rather
+        # than the 10/min monte_carlo tier: a person clicking through the "why" of a
+        # dozen values never trips it, a scripted loop is held to one pass a second.
+        "cpm_on_read": env("TRUEPPM_THROTTLE_CPM_ON_READ_RATE", default=_STANDARD_RATE),
+        # On-read merged program CPM (#2839), GET /programs/<pk>/schedule/. Same tier
+        # as cpm_on_read: a 5,000-task merged pass measured ~470 ms, MORE than the
+        # derivation's single-project pass, so it must not be laxer. 60/min holds a
+        # loop to ~0.5 core (vs ~7.8 at the 1000/min default). Per account, so tabs
+        # share it; one open tab can send up to 200/min (shared 300 ms debounce) in
+        # an edit storm, and on a 429 the page keeps its last chart. See
+        # ProgramScheduleThrottle.
+        "program_schedule": env("TRUEPPM_THROTTLE_PROGRAM_SCHEDULE_RATE", default=_STANDARD_RATE),
+        # Bundled-sample demo loader (#2402). POST /programs/load-sample/ is the
+        # most expensive single write in the API: it hard-deletes the caller's
+        # prior program with the same code (memberships -> projects -> cascade)
+        # and rebuilds the whole fixture — three projects, per-row saves with
+        # simple_history rows, the v2 replay timeline, and a forecast backfill —
+        # synchronously inside one transaction. The default sample measures ~3.4 s
+        # and ~3,700 sequential DB round-trips locally, several times that on
+        # modest hardware. Left on the general "user" default (1000/min) one
+        # authenticated member could drive a thousand full teardown-and-rebuilds a
+        # minute. 6/min matches monte_carlo_whatif — the same "one call is costly
+        # enough that even a modest loop is abusive" tier — and is ample for a
+        # human clicking "Load demo data" and trying a couple of samples.
+        "sample_load": env("TRUEPPM_THROTTLE_SAMPLE_LOAD_RATE", default=_STRICT_ABUSE_RATE),
+        # Caller-supplied seed import (#2402). POST /programs/import/ runs the
+        # *same* importer as load-sample on a payload the caller sizes, under the
+        # same IsAuthenticated-only gate, so it is the cheaper of the two
+        # exhaustion vectors and needs the same bound. A separate bucket from
+        # sample_load so loading a demo never spends a user's real import
+        # allowance — importing a handful of program bundles in a sitting is
+        # normal; sixty a minute is not.
+        "seed_import": env("TRUEPPM_THROTTLE_SEED_IMPORT_RATE", default=_STRICT_ABUSE_RATE),
+        # Seed dry run (#2418). POST /programs/import/validate/ parses and
+        # JSON-Schema-checks a caller-sized document but writes nothing, so it
+        # costs CPU proportional to the payload and none of the teardown-rebuild
+        # that makes seed_import expensive — a looser bound is right. It gets its
+        # own bucket rather than sharing seed_import's for a usability reason as
+        # much as a cost one: the whole point of a dry run is to iterate on a file
+        # until it passes, and spending the real import allowance to do that would
+        # lock an operator out of the import their fixed file just earned.
+        "seed_validate": env("TRUEPPM_THROTTLE_SEED_VALIDATE_RATE", default=_MODERATE_RATE),
+        # Bundled-fixture download (#2490). GET /programs/samples/{key}/download/
+        # streams a file off disk (<= ~78 KB) and touches no table, so it is orders
+        # of magnitude cheaper than sample_load and gets a correspondingly generous
+        # bound. It gets its own bucket rather than sharing sample_load's for an
+        # intent reason as much as a cost one: auditing all four fixtures before
+        # importing is the behavior this feature exists to encourage, and it must
+        # not spend the allowance a user needs to actually load a demo.
+        # Not unthrottled: it serves a file keyed by a client-supplied string, so
+        # even with the registry lookup closing traversal it would otherwise be a
+        # bandwidth amplifier and a free oracle for enumerating valid keys — and
+        # the scope becomes load-bearing the moment a deployment allowlists the
+        # route for anonymous access (ADR-0685).
+        "sample_download": env("TRUEPPM_THROTTLE_SAMPLE_DOWNLOAD_RATE", default=_STANDARD_RATE),
+        # MCP read surface per-token rate limits (#1808 finding F4). These bound
+        # token-authenticated reads on any McpReadableViewMixin view ONLY — human
+        # JWT/Session traffic on the same views is unaffected (the throttles'
+        # get_cache_key returns None for non-token callers, so DRF skips them; see
+        # apps/access/throttles.py). "mcp_read" is the baseline cap every
+        # MCP-readable view applies per token; "mcp_read_compute" is the tighter
+        # bucket the compute-heavy reads (whatif, monte-carlo/latest, forecast,
+        # sprint-forecast, schedule derivation #2839, and the program schedule
+        # action) STACK on top, since each triggers a CPM or Monte Carlo
+        # recompute per call and a read-only token loop must not burn arbitrary CPU.
+        # Env-tunable so an operator can widen the budget for a trusted agent fleet
+        # or tighten it under load. OSS ships basic per-token limits; per-agent
+        # budgets and anomaly auto-suspend are Phase 4 / Enterprise.
+        "mcp_read": env("TRUEPPM_THROTTLE_MCP_READ_RATE", default=_RELAXED_RATE),
+        "mcp_read_compute": env("TRUEPPM_THROTTLE_MCP_READ_COMPUTE_RATE", default="12/min"),
+        # Public board share-link endpoints (#283, ADR-0245). "share_mint" bounds
+        # how fast one Admin account can spray share links; "share_access" bounds
+        # scraping/abuse of the unauthenticated public board endpoint (the 256-bit
+        # token is already non-enumerable — this stops a leaked/viral link becoming
+        # an unthrottled load source on a self-hosted box, per Omar's VoC concern).
+        "share_mint": env("TRUEPPM_THROTTLE_SHARE_MINT_RATE", default=_MODERATE_RATE),
+        "share_access": env("TRUEPPM_THROTTLE_SHARE_ACCESS_RATE", default=_STANDARD_RATE),
+        # Telemetry test-export probe (#2110). An admin-only button that opens one
+        # outbound canary/reachability probe to the configured OTLP collector;
+        # scoped-throttled so it can't be used to hammer the collector.
+        "telemetry_test": env("TRUEPPM_THROTTLE_TELEMETRY_TEST_RATE", default=_STRICT_ABUSE_RATE),
+        # Inbound Git-event webhook receiver, per client IP (#2881,
+        # integrations.throttles.GitWebhookIpThrottle). The receiver's other
+        # throttle keys on the project UUID *from the URL*, so rotating that UUID
+        # minted a fresh bucket per request and the endpoint was effectively
+        # unbounded for an anonymous caller. Deliberately loose: a provider delivers
+        # from a small pool of shared egress addresses, so every repo on the install
+        # lands in ONE bucket and a tight limit would throttle honest traffic across
+        # unrelated projects. 600/min (10/s) sits far above any realistic aggregate
+        # PR/MR event rate while still bounding a single source. Env-tunable for an
+        # install with unusually heavy Git traffic.
+        "git_webhook_ip": env("TRUEPPM_THROTTLE_GIT_WEBHOOK_IP_RATE", default="600/min"),
+    },
+}
+
+# Global rate-limiting kill switch (ADR-0604): when an operator has disabled rate
+# limiting (with acknowledgment — see RATE_LIMIT_ENABLED above), neutralize every
+# DRF SimpleRateThrottle-family throttle in one place — drop the default throttle
+# classes and set every named scope's rate to None (DRF treats rate=None as "do not
+# throttle"). This covers all present and future scopes (anon, user, login,
+# monte_carlo, mcp_read, share_*, …) with no per-class edits. The custom Redis
+# BaseThrottle classes don't read these rates, so they bypass at request time via
+# the bypass_when_disabled decorator instead.
+if not RATE_LIMIT_ENABLED:
+    apply_rate_limit_disable(REST_FRAMEWORK)
+
+# MCP administration controls (#2021, ADR-0497).
+#
+# Instance-wide MCP kill switch. Default True preserves backward compatibility —
+# existing deployments keep agent (mcp:read token) access. Set False to deny every
+# MCP-token read at the McpReadableViewMixin chokepoint (403), even though the
+# token exists; human JWT/session auth on the same viewsets is unaffected. This is
+# the operator lever for "no agent access on this instance, period."
+TRUEPPM_MCP_ENABLED: bool = env.bool("TRUEPPM_MCP_ENABLED", default=True)
+
+# Whether a member project's ADR-0678 agent-read opt-out withholds a PROGRAM-LEVEL
+# BULK EXPORT from an agent (`mcp:read`) token — the sync JSON seed and the async
+# .tar.gz bundle both carry every member project's data verbatim (#3014).
+#
+#   "withhold" (default) — an agent token is refused (403) when ANY member project
+#       has opted out. The cascade's rule is that a team's "no" is final, and a
+#       bulk export is the widest possible read of the data it covers.
+#   "allow" — pre-0.4 behavior: the export is treated as a program-level artifact
+#       governed by the program's own `mcp_enabled` alone.
+#
+# OPERATOR-LEVEL ON PURPOSE, and the reason is the whole design (see
+# projects/mcp_settings.py, which refuses an `mcp_override_policy` field outright).
+# A workspace- or program-scoped toggle for this would be a *tenant* scope granting
+# over a team's denial — precisely the "consent that only an admin can grant or
+# revoke on the team's behalf is consent in name only" objection (#2415) the opt-out
+# exists to answer. An operator switch is the same kind of lever as
+# TRUEPPM_MCP_ENABLED above: the person running the server, not a scope above the
+# team inside it. Do not promote this to a model field.
+#
+# Humans are never affected by either value.
+TRUEPPM_MCP_PROGRAM_EXPORT_POLICY: str = env.str(
+    "TRUEPPM_MCP_PROGRAM_EXPORT_POLICY", default="withhold"
+)
+
+# Env-overridable safety caps for API tokens and inbound task-sync. Each keeps its
+# historical hardcoded default; surfacing them as settings lets an operator tune the
+# blast-radius/limits per deployment without a code change. Read at request time so
+# override_settings (and a live env change) takes effect.
+#
+# Max ACTIVE personal access tokens per user (ADR-0214). Bounds the blast radius of
+# a leaked account and keeps the /me/api-tokens/ list navigable.
+TRUEPPM_MAX_PERSONAL_ACCESS_TOKENS: int = env.int("TRUEPPM_MAX_PERSONAL_ACCESS_TOKENS", default=10)
+# Max pinned projects + programs per user (#2390, ADR-0627). A pin is a personal
+# wayfinding shortcut, so the cap exists to bound the row count and keep the rail
+# and /me/pinned/ navigable — not as a security control. Exceeding it is a 400
+# carrying `code: "pin_limit_reached"` so the client can say which limit was hit.
+TRUEPPM_MAX_USER_PINS: int = env.int("TRUEPPM_MAX_USER_PINS", default=100)
+# Token-issuance rate cap (req/min/user) on the mint endpoint (ADR-0068). Caps the
+# blast radius of a compromised admin session even when RBAC is satisfied.
+TRUEPPM_TOKEN_ISSUANCE_PER_MINUTE: int = env.int("TRUEPPM_TOKEN_ISSUANCE_PER_MINUTE", default=5)
+# Token-revocation rate cap (req/min/user) on the revoke endpoint (#2878). Set well
+# above the issuance cap deliberately: revocation is the containment action, and a
+# user cutting off a leak may legitimately revoke every token they hold in one burst.
+TRUEPPM_TOKEN_REVOCATION_PER_MINUTE: int = env.int(
+    "TRUEPPM_TOKEN_REVOCATION_PER_MINUTE", default=30
+)
+# Inbound task-sync per-project rate caps (ADR-0068). Steady-state limit applies
+# after the 60-minute backfill window; the higher backfill limit applies to a
+# freshly minted token so a large first import gets headroom.
+TRUEPPM_TASK_SYNC_STEADY_STATE_LIMIT: int = env.int(
+    "TRUEPPM_TASK_SYNC_STEADY_STATE_LIMIT", default=100
+)
+TRUEPPM_TASK_SYNC_BACKFILL_LIMIT: int = env.int("TRUEPPM_TASK_SYNC_BACKFILL_LIMIT", default=1000)
+
+# Public read-only sharing — board (#283, ADR-0245) and schedule (#1486, ADR-0265).
+# The instance kill switch governs BOTH share kinds: when False, minting new links
+# (403) and every public share endpoint (uniform 404, retroactively disabling
+# existing links) are turned off org-wide — the operator/PMO off lever for the
+# unauthenticated egress surface. One lever, one mental model: a deployment can
+# never leak schedules while "board sharing" reads off. Default True is safe because
+# no data is exposed until an Owner/Admin explicitly mints a link. The SHARE_*_MAX_*
+# caps bound each public snapshot payload (the projection flags "truncated" past the
+# cap rather than silently dropping content). The env var keeps its #283 name for
+# back-compat with deployments that already set it.
+TRUEPPM_PUBLIC_BOARD_SHARING_ENABLED = env.bool(
+    "TRUEPPM_PUBLIC_BOARD_SHARING_ENABLED", default=True
+)
+SHARE_BOARD_MAX_CARDS = env.int("TRUEPPM_SHARE_BOARD_MAX_CARDS", default=1000)
+SHARE_SCHEDULE_MAX_TASKS = env.int("TRUEPPM_SHARE_SCHEDULE_MAX_TASKS", default=1000)
+
+# ---------------------------------------------------------------------------
+# django-allauth
+# ---------------------------------------------------------------------------
+
+SITE_ID = 1
+# "none" is safe *because allauth's self-service account flows are never reached*
+# (#2248): we do NOT mount `allauth.urls`, so there is no allauth signup/login/
+# email-confirmation surface. Account creation flows only through (a) the invite
+# path — the email is fixed to the invite, not user-chosen — and (b) SSO, which
+# enforces its own `email_verified is True` + admin domain allow-list gate in
+# `apps.sso.services.resolve_user`. Do NOT mount `allauth.urls` (which would open
+# self-service registration) without first flipping this to a real verification
+# policy — otherwise unverified self-service signup would be silently enabled.
+ACCOUNT_EMAIL_VERIFICATION = "none"
+
+# ModelBackend FIRST so username/password login keeps working exactly as before
+# (ADR-0517 §1). The allauth backend is appended only so allauth's own account
+# machinery resolves; our SSO views never call allauth's login() — they mint the
+# simplejwt cookie session via the JWT bridge (apps/sso/views.py).
+AUTHENTICATION_BACKENDS = [
+    "django.contrib.auth.backends.ModelBackend",
+    "allauth.account.auth_backends.AuthenticationBackend",
+]
+
+# SOCIALACCOUNT_PROVIDERS is used purely as a per-provider CONFIG REGISTRY — it
+# pins the server-fixed OSS scopes and PKCE. Per-provider APPS are NOT hardcoded
+# here: each configured IdP lives as a DB `SocialApp` row (provider_id == our
+# registry slug) written through the admin API, so the APPS list stays empty
+# (ADR-0517 §1). We deliberately do NOT set LOGIN_REDIRECT_URL or
+# SOCIALACCOUNT_ADAPTER — our own views own the flow, allauth is a library.
+SOCIALACCOUNT_PROVIDERS = {
+    "openid_connect": {
+        "APPS": [],
+        "OAUTH_PKCE_ENABLED": True,
+        # Server-fixed in OSS — `groups`/custom claims are an Enterprise widening.
+        "SCOPE": ["openid", "email", "profile"],
+    },
+    "github": {
+        # OIDC-equivalent scopes: identity via GET /user + /user/emails.
+        "SCOPE": ["read:user", "user:email"],
+    },
+}
+
+# ---------------------------------------------------------------------------
+# Outbound email transport (#639 read-only status page, #764)
+# ---------------------------------------------------------------------------
+# Bind Django's standard EMAIL_* settings from the environment so operators
+# configure SMTP via container env vars / Helm values with no settings override.
+# The Beat-driven notification drain runs on the api, celery, and celery-beat
+# workloads, so all three must receive the same env. EMAIL_HOST_PASSWORD is read
+# from the environment but never exposed by the API or logged (#639).
+#
+# EMAIL_HOST defaults to "" (not Django's implicit "localhost") so an
+# unconfigured deployment reports "Not configured" on the read-only status page
+# and the drain skips sending, rather than silently attempting localhost:25.
+EMAIL_BACKEND = env("EMAIL_BACKEND", default="django.core.mail.backends.smtp.EmailBackend")
+EMAIL_HOST = env("EMAIL_HOST", default="")
+EMAIL_PORT = env.int("EMAIL_PORT", default=587)
+EMAIL_USE_TLS = env.bool("EMAIL_USE_TLS", default=True)
+EMAIL_USE_SSL = env.bool("EMAIL_USE_SSL", default=False)
+EMAIL_HOST_USER = env("EMAIL_HOST_USER", default="")
+EMAIL_HOST_PASSWORD = env("EMAIL_HOST_PASSWORD", default="")
+EMAIL_TIMEOUT = env.int("EMAIL_TIMEOUT", default=10)
+DEFAULT_FROM_EMAIL = env("DEFAULT_FROM_EMAIL", default="notifications@trueppm.local")
+
+# ---------------------------------------------------------------------------
+# drf-spectacular (OpenAPI)
+# ---------------------------------------------------------------------------
+
+# ---------------------------------------------------------------------------
+# Object change history (django-simple-history)
+# ---------------------------------------------------------------------------
+
+# Retention window in days. Records older than this are purged nightly by the
+# Celery beat task in trueppm_api.apps.history.tasks.
+# Set to None to disable automatic purging (enterprise unlimited retention).
+# Operator env var standardized on the TRUEPPM_ prefix pre-0.3 (#1325) so all
+# tunables share one namespace in ConfigMaps/Secrets; the legacy bare name is read
+# as a fallback so deploys that already set it keep working until they migrate.
+HISTORY_RETENTION_DAYS: int | None = env.int(
+    "TRUEPPM_HISTORY_RETENTION_DAYS", default=env.int("HISTORY_RETENTION_DAYS", default=90)
+)
+
+# ---------------------------------------------------------------------------
+# Signal-privacy ceiling-raise ratification (ADR-0104 Amendment A, #930)
+# ---------------------------------------------------------------------------
+
+# How long a team-ratification proposal to raise a signal's ceiling stays OPEN
+# before it lazily expires UNRATIFIED (the ceiling is left unchanged — silence is
+# never consent for widening a team signal's exposure). 72h is long enough for an
+# async team yet short enough not to stall a pending share. Evaluated lazily on
+# read/vote/propose; no Celery/Beat sweep is required.
+SIGNAL_CEILING_PROPOSAL_TTL_HOURS: int = env.int("SIGNAL_CEILING_PROPOSAL_TTL_HOURS", default=72)
+
+# ---------------------------------------------------------------------------
+# Task run retention (trueppm_api.apps.taskruns)
+# ---------------------------------------------------------------------------
+
+# Retention window in days for completed/failed/cancelled TaskRun records.
+# Set to None to disable automatic purging. Env var standardized on the TRUEPPM_
+# prefix pre-0.3 (#1325); legacy bare name read as a fallback.
+TASK_RUN_RETENTION_DAYS: int | None = env.int(
+    "TRUEPPM_TASK_RUN_RETENTION_DAYS", default=env.int("TASK_RUN_RETENTION_DAYS", default=30)
+)
+
+# ---------------------------------------------------------------------------
+# Time tracking (trueppm_api.apps.timetracking, ADR-0185)
+# ---------------------------------------------------------------------------
+
+# Stale-timer ceiling: a running timer that exceeds this many minutes is flagged
+# ``stale`` on GET /me/timer/, and ``stop`` caps the logged minutes at it rather
+# than the raw elapsed (so a timer left running over a weekend logs the ceiling,
+# not thousands of minutes). Default 600 = 10 h.
+TIMETRACKING_TIMER_MAX_MINUTES: int = env.int("TIMETRACKING_TIMER_MAX_MINUTES", default=600)
+
+# Manual-entry backdate window: a manual ``entry_date`` is rejected if it is in the
+# future or older than this many days, so a contributor can fill in last week but
+# not rewrite arbitrary history. Default 60 days.
+TIMETRACKING_BACKDATE_DAYS: int = env.int("TIMETRACKING_BACKDATE_DAYS", default=60)
+
+# ---------------------------------------------------------------------------
+# Dead-letter inspector bulk actions (ADR-0210)
+# ---------------------------------------------------------------------------
+
+# Upper bound on how many parked tasks one `requeue_all` / `drop_all` call may act
+# on, oldest-first; the response's `capped` flag tells the operator more remain
+# (ADR-0210 §4). Documented as tunable in docs → Administration → System Health, and
+# for its whole life it was not: `scheduling/views.py` read it with
+# `getattr(settings, "FAILED_TASK_BULK_ACTION_MAX", 500)` and no settings module
+# bound it, so the fallback always won and setting the env var did nothing (#2880 —
+# the same class as TRUEPPM_INTEGRATION_ALLOWED_HOSTS in #2860). The env var is
+# TRUEPPM_-prefixed per #1355; the setting name keeps its established spelling
+# because the view constant and its tests already reference it.
+FAILED_TASK_BULK_ACTION_MAX: int = env.int("TRUEPPM_FAILED_TASK_BULK_ACTION_MAX", default=500)
+
+# ---------------------------------------------------------------------------
+# Outbox retention + Beat liveness (ADR-0081)
+# ---------------------------------------------------------------------------
+
+# Retention window in days for terminal (SUCCESS/FAILED) WebhookDelivery rows.
+# Set to None to disable the nightly purge. New tunables are TRUEPPM_-prefixed
+# for env-var namespacing in shared ConfigMaps/Secrets (ADR-0081 §D).
+TRUEPPM_WEBHOOK_RETENTION_DAYS: int | None = env.int("TRUEPPM_WEBHOOK_RETENTION_DAYS", default=7)
+
+# Retention window in days for terminal (DONE/DEAD) ImportRequest rows. These
+# carry multi-MB file_content_b64 blobs. Set to None to disable the nightly purge.
+TRUEPPM_IMPORT_RETENTION_DAYS: int | None = env.int("TRUEPPM_IMPORT_RETENTION_DAYS", default=7)
+
+# Download-link validity (days) for a completed WorkspaceExportJob; past this the
+# nightly purge deletes the job row and its stored archive (ADR-0174). The full
+# archive can be large and contains every project's data, so it is not kept
+# indefinitely. Set to None to disable expiry/purge (links never lapse).
+TRUEPPM_EXPORT_RETENTION_DAYS: int | None = env.int("TRUEPPM_EXPORT_RETENTION_DAYS", default=7)
+
+# Retention window (days) for the ⌘Z undo ledger rows behind paste-many and
+# cascade classification (ADR-0810, #2756) — undone or not. 30 days comfortably
+# exceeds any plausible "wait, I meant to undo that" gap while staying inside
+# the 90-day HISTORY_RETENTION_DAYS these tables sit alongside. Set to None to
+# disable the purge (ledger rows kept indefinitely).
+TRUEPPM_BATCH_OPERATION_RETENTION_DAYS: int | None = env.int(
+    "TRUEPPM_BATCH_OPERATION_RETENTION_DAYS", default=30
+)
+
+# Window in seconds during which the same person repeating the change whose
+# config-change notice was the last one sent for a project is not re-notified
+# (ADR-1174 §D). A different change, a different person, or an intervening
+# different notice always sends. 0 disables the cooldown.
+TRUEPPM_CONFIG_NOTICE_COOLDOWN_SECONDS: int = env.int(
+    "TRUEPPM_CONFIG_NOTICE_COOLDOWN_SECONDS", default=600
+)
+
+# Age in seconds past which the Beat heartbeat is considered stale. Drives both
+# the GET /api/v1/health/beat/ stale flag and the beat.check_stale_heartbeat
+# WARNING log. Default 120 s = four missed 30 s beats.
+TRUEPPM_BEAT_STALE_SECONDS: int = env.int("TRUEPPM_BEAT_STALE_SECONDS", default=120)
+
+# Escape hatch for a *deliberate* image-only rollback (#2806). /api/v1/readyz
+# reports not-ready when the database records migrations this image does not ship
+# ("migration_state": "ahead"), because the probe cannot tell an additive upgrade
+# — whose schema the old code can usually still serve — from a destructive one it
+# certainly cannot. Fail-closed is the right default, but it also blocks the
+# additive-only rollback the upgrade runbook recommends, so an operator who has
+# read the release's migrations and knows they are additive can set this to true
+# to let the older image serve. It never suppresses the "behind" gate: a
+# mid-upgrade pod is still kept out of the Service.
+TRUEPPM_READYZ_ALLOW_DB_AHEAD: bool = env.bool("TRUEPPM_READYZ_ALLOW_DB_AHEAD", default=False)
+
+# Freshness/dedup window in hours for mobile sync upload batches (ADR-0082). A
+# duplicate upload with the same client_batch_id within this window replays the
+# stored response; past it, the id is allowed to re-run and the nightly
+# sync.purge_sync_batches task reaps the stale row.
+TRUEPPM_SYNC_BATCH_RETENTION_HOURS: int = env.int("TRUEPPM_SYNC_BATCH_RETENTION_HOURS", default=24)
+
+# Retention window in hours for the WebSocket event replay buffer (ADR-0236,
+# #321). BoardEvent rows older than this are reaped by the nightly
+# sync.purge_board_events task so the buffer stays bounded; a client reconnecting
+# with a ?since= older than the retained window gets a resync_required frame and
+# refetches. Kept deliberately short (a reconnect gap is minutes, not days).
+TRUEPPM_BOARD_EVENT_RETENTION_HOURS: int = env.int(
+    "TRUEPPM_BOARD_EVENT_RETENTION_HOURS", default=24
+)
+
+# Retention window in days for soft-deleted (trashed) projects. Once a project has
+# been soft-deleted for longer than this, the consolidated retention purge
+# (retention.run_purge, ADR-0173) HARD-deletes it and all its child data (tasks,
+# dependencies, sprints, baselines, …) via DB CASCADE. Set to None to disable the
+# purge (trashed projects are retained unbounded). A project soft-deleted before
+# this column existed has a NULL deleted_at and is never auto-purged.
+TRUEPPM_PROJECT_SOFT_DELETE_RETENTION_DAYS: int | None = env.int(
+    "TRUEPPM_PROJECT_SOFT_DELETE_RETENTION_DAYS", default=30
+)
+
+# How long a manual retention purge may be considered "in progress" before the
+# run endpoint stops treating a RUNNING PurgeRow as blocking (ADR-0173 §G). Bounds
+# the API-level single-flight guard to the coordinator's Redis lock window so a
+# worker that died mid-run can't block all future manual runs with a stale row.
+RETENTION_PURGE_INFLIGHT_SECONDS: int = env.int("RETENTION_PURGE_INFLIGHT_SECONDS", default=600)
+
+# Maximum rows (created + updated + deleted) in a single mobile sync upload
+# batch (ADR-0082). The batch applies in one transaction; this bounds how long
+# that transaction (and its per-task row locks) can be held by one request.
+TRUEPPM_SYNC_BATCH_MAX_ROWS: int = env.int("TRUEPPM_SYNC_BATCH_MAX_ROWS", default=500)
+
+# Batch-wide cap on inline ``owners`` entries across a sync upload batch (#3643):
+# summed over every created/updated task row's ``owners`` list, independent of
+# the row cap above (few rows can still carry many owners each).
+TRUEPPM_SYNC_BATCH_MAX_OWNERS: int = env.int("TRUEPPM_SYNC_BATCH_MAX_OWNERS", default=500)
+
+# Max simultaneously in-flight sync upload batches per user (#1756, defense in
+# depth over the SyncUploadThrottle rate cap). Each accepted batch is a heavy
+# transaction.atomic() (up to TRUEPPM_SYNC_BATCH_MAX_ROWS row locks + a CPM recalc
+# enqueue); under lock contention a burst of concurrent batches from one user can
+# tie up worker/DB resources *within* the per-minute rate cap. A per-user Redis
+# semaphore (INCR on entry / DECR in finally) bounds simultaneous heavy
+# transactions. Fails OPEN on a Redis error — parity with the rate throttle's
+# offline-client-retries reasoning would over-penalize here, and the rate cap
+# remains the hard bound. The counter carries a TTL so a worker that dies holding
+# a slot cannot leak it permanently.
+TRUEPPM_SYNC_MAX_CONCURRENT_BATCHES: int = env.int("TRUEPPM_SYNC_MAX_CONCURRENT_BATCHES", default=4)
+# TTL (seconds) on the per-user in-flight counter. A crashed worker's slot is
+# reclaimed once no further batch refreshes the key within this window; set
+# comfortably above the longest legitimate batch-apply time so an in-progress
+# slot is never reclaimed out from under a live request.
+TRUEPPM_SYNC_INFLIGHT_TTL_SECONDS: int = env.int("TRUEPPM_SYNC_INFLIGHT_TTL_SECONDS", default=120)
+
+# Cursor pagination for the offline delta PULL (#1013). A cold start (since=0)
+# on a large project would otherwise materialize every row into one unbounded
+# multi-MB response, past the "500-task delta < 3s" mobile target. The pull now
+# returns at most PAGE_SIZE rows (across all collections) per request and the
+# client loops on the cursor. PAGE_SIZE is the default; MAX_PAGE_SIZE clamps a
+# client-requested page_size so one request can never re-open the unbounded cliff.
+TRUEPPM_SYNC_PULL_PAGE_SIZE: int = env.int("TRUEPPM_SYNC_PULL_PAGE_SIZE", default=1000)
+TRUEPPM_SYNC_PULL_MAX_PAGE_SIZE: int = env.int("TRUEPPM_SYNC_PULL_MAX_PAGE_SIZE", default=5000)
+
+# Retention window in days for per-row soft-deleted tombstones in live projects
+# (is_deleted=True rows on Task, Risk, Sprint, Dependency). Rows older than this
+# are hard-deleted by the nightly sync.reap_domain_tombstones task. The 90-day
+# default aligns with the HistoricalTask history window so tombstones are never
+# retained longer than the audit trail that references them (#1321).
+TRUEPPM_TOMBSTONE_RETENTION_DAYS: int = env.int("TRUEPPM_TOMBSTONE_RETENTION_DAYS", default=90)
+
+# Look-ahead horizon (days) for lazy recurring-task occurrence generation (ADR-0090).
+# The hourly projects.generate_recurring_occurrences sweep materializes only
+# occurrences due within this window — a bounded look-ahead, never the full series.
+TRUEPPM_RECURRENCE_HORIZON_DAYS: int = env.int("TRUEPPM_RECURRENCE_HORIZON_DAYS", default=14)
+
+# ---------------------------------------------------------------------------
+# Workflow execution engine (ADR-0080)
+# ---------------------------------------------------------------------------
+
+# Dotted path to the WorkflowBackend implementation. The OSS default composes
+# the transactional outbox + Celery; enterprise editions register an alternate
+# (e.g. Temporal) by overriding this — the edition-routing pattern of ADR-0030.
+# Env vars standardized on the TRUEPPM_ prefix pre-0.3 (#1325); legacy bare names
+# read as a fallback so existing deploys keep working until they migrate.
+WORKFLOW_BACKEND = env.str(
+    "TRUEPPM_WORKFLOW_BACKEND",
+    default=env.str(
+        "WORKFLOW_BACKEND",
+        default="trueppm_api.workflows.backends.default.DefaultWorkflowBackend",
+    ),
+)
+
+# Retention window in days for WorkflowHistoryEvent rows (purged nightly by
+# workflows.purge_old_records). Set to None / 0 to disable history purging.
+WORKFLOW_HISTORY_RETENTION_DAYS: int | None = env.int(
+    "TRUEPPM_WORKFLOW_HISTORY_RETENTION_DAYS",
+    default=env.int("WORKFLOW_HISTORY_RETENTION_DAYS", default=30),
+)
+
+# Max rows the workflow outbox/timer drains process per tick. Bounds the work
+# per run so a large backlog (e.g. after a broker outage) can't exceed the task
+# time_limit — subsequent ticks drain the remainder.
+WORKFLOW_DRAIN_BATCH_SIZE = env.int(
+    "TRUEPPM_WORKFLOW_DRAIN_BATCH_SIZE", default=env.int("WORKFLOW_DRAIN_BATCH_SIZE", default=200)
+)
+
+# Rows deleted per statement by the nightly workflow retention purge. The purge
+# deletes in bounded chunks rather than one unbounded statement so the first run
+# on a mature install (e.g. after WORKFLOW_HISTORY_RETENTION_DAYS is first set)
+# cannot take a long lock over a large slice of the history/outbox tables.
+WORKFLOW_PURGE_BATCH_SIZE = env.int(
+    "TRUEPPM_WORKFLOW_PURGE_BATCH_SIZE", default=env.int("WORKFLOW_PURGE_BATCH_SIZE", default=500)
+)
+
+# ---------------------------------------------------------------------------
+# Idempotency-Key retention (trueppm_api.apps.idempotency, ADR-0170)
+# ---------------------------------------------------------------------------
+
+# Retention window in hours for stored Idempotency-Key responses. Purged hourly by
+# the Celery beat task in trueppm_api.apps.idempotency.tasks. After expiry, a retry
+# with the same key re-runs the mutation. Set to None to disable automatic purging.
+# Env vars standardized on the TRUEPPM_ prefix pre-0.3 (#1325); legacy bare names
+# read as a fallback so existing deploys keep working until they migrate.
+IDEMPOTENCY_RETENTION_HOURS: int | None = env.int(
+    "TRUEPPM_IDEMPOTENCY_RETENTION_HOURS",
+    default=env.int("IDEMPOTENCY_RETENTION_HOURS", default=24),
+)
+# Maximum stored response body size (bytes). Responses larger than this are not stored
+# (the claim row is dropped, so a retry re-runs). Mutation responses are single objects
+# and effectively never approach this.
+IDEMPOTENCY_MAX_BODY_BYTES: int = env.int(
+    "TRUEPPM_IDEMPOTENCY_MAX_BODY_BYTES",
+    default=env.int("IDEMPOTENCY_MAX_BODY_BYTES", default=1 * 1024 * 1024),
+)
+
+# ---------------------------------------------------------------------------
+# drf-spectacular (OpenAPI)
+# ---------------------------------------------------------------------------
+
+SPECTACULAR_SETTINGS = {
+    "TITLE": "TruePPM API",
+    "DESCRIPTION": "REST API for the TruePPM project scheduling platform.",
+    # Derived, never restated (#2605). This read "0.3.0" while the package was
+    # 0.4.0-beta.1, so every generated client and every published schema consumer
+    # was told the wrong version — and the literal sat ~900 lines below
+    # _package_version(), the anti-drift helper written to prevent exactly this.
+    # A version that has to be updated by hand at tag time is a version that will
+    # be wrong between tags.
+    "VERSION": TRUEPPM_VERSION,
+    "SERVE_INCLUDE_SCHEMA": False,
+    "COMPONENT_SPLIT_REQUEST": True,
+    # Meaningful top-level tag block (#1333). drf-spectacular defaults every
+    # /api/v1/ operation to the tag "v1", which collapses a generated client into a
+    # single API class. Defining tags here (plus the resource-tag assignment in the
+    # post-processing hook below) splits the SDK into ProjectsApi, SprintsApi,
+    # SchedulingApi, … the way an SDK consumer expects. Kept in lockstep with the
+    # tag-assignment map in trueppm_api.core.openapi (defined inline rather than
+    # imported: settings must not import DRF-dependent app code, which would force
+    # rest_framework's api_settings to cache before REST_FRAMEWORK is defined).
+    "TAGS": [
+        {
+            "name": "auth",
+            "description": "Authentication, login, token issuance and OIDC single sign-on.",
+        },
+        {
+            "name": "me",
+            "description": "The authenticated user's own account, credentials, timers and work.",
+        },
+        {
+            "name": "workspace",
+            "description": "Workspace-level settings, membership, invites and branding.",
+        },
+        {
+            "name": "projects",
+            "description": "Projects and their project-level views (overview, status, history).",
+        },
+        {
+            "name": "programs",
+            "description": "Programs — grouping of related projects managed by one PM.",
+        },
+        {
+            "name": "tasks",
+            "description": "Tasks, dependencies, milestones, acceptance criteria and task runs.",
+        },
+        {
+            "name": "task-relations",
+            "description": "Informational task-to-task relations (relates to, blocks, "
+            "duplicates) — cross-references with no scheduling effect.",
+        },
+        {
+            "name": "scheduling",
+            "description": "CPM scheduling, baselines, Monte Carlo forecasts and slip analysis.",
+        },
+        {
+            "name": "sprints",
+            "description": "Sprints, backlog, velocity, retrospectives and agile ceremonies.",
+        },
+        {
+            "name": "resources",
+            "description": "Resources, skills, allocation, utilization and assignments.",
+        },
+        {"name": "calendars", "description": "Working calendars, exceptions and recurrence rules."},
+        {"name": "teams", "description": "Teams and team membership."},
+        {"name": "members", "description": "Project and program membership management."},
+        {
+            "name": "integrations",
+            "description": "External task sources, Git automation and personal credentials.",
+        },
+        {
+            "name": "assets",
+            "description": "Workspace-scoped Assets feed: file/URL attachments and task links "
+            "aggregated across every project the caller can read.",
+        },
+        {
+            "name": "import-export",
+            "description": (
+                "File import and export: MS Project, Jira XML, CSV/Excel spreadsheets, "
+                "import templates, and data exports."
+            ),
+        },
+        {"name": "webhooks", "description": "Outbound webhook subscriptions."},
+        {
+            "name": "sync",
+            "description": "Offline delta-sync protocol and WebSocket connection tickets.",
+        },
+        {
+            "name": "share",
+            "description": "Public read-only board share links: mint, list, revoke, and the "
+            "public unauthenticated read endpoint.",
+        },
+        {
+            "name": "agent-actions",
+            "description": "Append-only, hash-chained audit trail of MCP/agent read actions "
+            "and refusals, scoped to project membership.",
+        },
+        {
+            "name": "meta",
+            "description": "Deployment metadata, health probes and administrative endpoints.",
+        },
+    ],
+    # Fill SDK-quality facets (operation summaries, resource tags, global + public
+    # security) that per-view annotations leave thin. Runs after the built-in enum
+    # post-processor, which must be preserved (drf-spectacular default).
+    "POSTPROCESSING_HOOKS": [
+        "drf_spectacular.hooks.postprocess_schema_enums",
+        "trueppm_api.core.openapi.postprocess_openapi",
+    ],
+    # Serve the Swagger UI / ReDoc assets from the bundled sidecar package (Django
+    # static, same origin) instead of the default jsdelivr CDN. Our strict CSP
+    # (script-src / style-src 'self', no CDN host) blocks the CDN-hosted bundles,
+    # leaving the docs pages blank. SIDECAR resolves every asset under 'self', so
+    # the pages work under CSP and offline/air-gapped. Paired with the split
+    # Swagger view in urls.py, which moves the bootstrap JS out of an inline
+    # <script> (also blocked by script-src 'self') to a same-origin request.
+    "SWAGGER_UI_DIST": "SIDECAR",
+    "SWAGGER_UI_FAVICON_HREF": "SIDECAR",
+    "REDOC_DIST": "SIDECAR",
+    # Self-hosted deployments serve the API from their own origin, so the schema
+    # advertises a single templated server (scheme + host variables) whose
+    # defaults are the local-dev address. Without a top-level `servers` array,
+    # openapi-typescript / Orval / openapi-generator emit base-URL-less clients
+    # or fail outright (#1329). Paths already carry the `/api/v1/` prefix, so the
+    # server URL is just the deployment origin.
+    "SERVERS": [
+        {
+            "url": "{scheme}://{host}",
+            "description": "Your TruePPM deployment",
+            "variables": {
+                "scheme": {"default": "https", "enum": ["https", "http"]},
+                "host": {
+                    "default": "localhost:8000",
+                    "description": "Host (and port) of your TruePPM API server.",
+                },
+            },
+        },
+    ],
+    # Pin state-enum names (ADR-0173). PurgeRun.state shares the field name "state"
+    # with the sprint lifecycle enum; introducing a second "state" choice set makes
+    # drf-spectacular disambiguate *both* by model prefix, renaming the sprint enum
+    # away from the stable `StateEnum` component (a schema regression). Pinning the
+    # sprint enum to `StateEnum` and ours to `PurgeRunStateEnum` keeps both stable.
+    # Likewise for "frequency": TaskRecurrenceRule.frequency (#736) introduces a
+    # second choice set sharing the field name with RetentionSchedule.frequency,
+    # so drf-spectacular would disambiguate both by model prefix and rename the
+    # stable `FrequencyEnum` component (a regression). Pin the retention enum back
+    # to `FrequencyEnum` and the recurrence enum to `RecurrenceFrequencyEnum`.
+    "ENUM_NAME_OVERRIDES": {
+        # #3037: the bulk refusal vocabulary. Pinned rather than left to
+        # drf-spectacular's derived naming because these two names are the handle a
+        # generated client's types carry — the whole point of publishing the enum is
+        # that an integrator can branch on it, and a component that renames itself
+        # when an unrelated field's choices change would break exactly that.
+        # `code` appears on three buckets of one response and must resolve to ONE
+        # component, not three postfixed variants.
+        "TaskBulkRefusalCodeEnum": "trueppm_api.apps.projects.refusal_codes.BulkRefusalCode",
+        "StructuralUndoBlockedReasonEnum": (
+            "trueppm_api.apps.projects.refusal_codes.StructuralUndoBlockedReason"
+        ),
+        # #3680: MonteCarloForecastDiagnosticSerializer.reason introduces a SECOND
+        # "reason" choice set alongside TaskGroupLeftAloneEntrySerializer.reason
+        # (an inline tuple, not an enum class — hence the raw-list value, same
+        # shape as OutcomeEnum below). Without a pin drf-spectacular disambiguates
+        # both by serializer prefix and renames the published `ReasonEnum` — the
+        # project_drf_enum_name_collision regression every pin in this block
+        # exists to prevent. Pin the incumbent to its stable name; the new
+        # Monte Carlo set is then free to take the prefixed form.
+        "ReasonEnum": ["ancestor_selected", "different_parent"],
+        "StateEnum": "trueppm_api.apps.projects.models.SprintState",
+        "PurgeRunStateEnum": "trueppm_api.apps.observability.models.PurgeRun.State",
+        "PurgeRunTriggerEnum": "trueppm_api.apps.observability.models.PurgeRun.Trigger",
+        "FrequencyEnum": "trueppm_api.apps.observability.models.RetentionSchedule.Frequency",
+        "RecurrenceFrequencyEnum": "trueppm_api.apps.projects.models.TaskRecurrenceFrequency",
+        # ADR-0102: SprintScopeChange.status (pending|accepted|rejected) introduces
+        # a new "status" choice set; without a pin drf-spectacular disambiguates
+        # every "status" field by model prefix and renames existing stable
+        # components (a schema-drift regression — project memory
+        # project_drf_enum_name_collision). Pin ours to a stable name.
+        "ScopeChangeStatusEnum": "trueppm_api.apps.projects.models.ScopeChangeStatus",
+        # ADR-0789 (#2729): ProjectTemplate.source_kind introduces a SECOND
+        # "source_kind" choice set alongside Task.source_kind (ADR-0786). Without
+        # a pin drf-spectacular disambiguates both by model prefix, which renames
+        # the already-published `SourceKindEnum` to `TaskSourceKindEnum` — a
+        # removed component, and exactly the schema-drift regression the two pins
+        # above exist to prevent. Pin Task's to its existing stable name; the
+        # template's own set is then free to take the model-prefixed name.
+        "SourceKindEnum": "trueppm_api.apps.projects.models.TaskSource",
+        # ADR-0880 (#2974): StructuralOperation.kind introduces a SECOND "kind"
+        # choice set alongside AssetItemSerializer.kind (file|link). Without a pin
+        # drf-spectacular disambiguates both by prefix, renaming the published
+        # `KindEnum` to `AssetItemKindEnum` — a removed component referenced by
+        # AgentAction, AssetItem, ShareLink, ShareLinkCreateRequest,
+        # ShareLinkCreateResponse and Task. Same regression class as every pin in
+        # this block. Keep the incumbent's name; the new set takes the prefixed one.
+        "KindEnum": "trueppm_api.apps.projects.asset_feed.KIND_CHOICES",
+        # #3525: health_band_source is declared on BOTH the single-project status
+        # summary and the my-projects health summary. Identical choices already
+        # resolve to one component, but the pin is proactive rather than
+        # incidental: the next endpoint that grows a "source" choice set would
+        # otherwise make drf-spectacular disambiguate every one of them by prefix
+        # and rename the published component — the project_drf_enum_name_collision
+        # regression every pin in this block exists to prevent. Pinned to the
+        # shared constant the two declarations reference, so the name cannot drift
+        # from the vocabulary.
+        "HealthBandSourceEnum": "trueppm_api.apps.projects.views.HEALTH_BAND_SOURCE_CHOICES",
+        "TemplateSourceEnum": "trueppm_api.apps.projects.models.TemplateSource",
+        # ADR-0116: Workspace.iteration_label_override_policy adds an
+        # INHERIT/SUGGEST/ENFORCE choice set. Pin it so drf-spectacular does not
+        # rename existing stable enums (the same schema-drift regression class as
+        # ScopeChangeStatus above — project_drf_enum_name_collision).
+        "TermOverridePolicyEnum": "trueppm_api.apps.workspace.models.TermOverridePolicy",
+        # #2723: TaskBulkAppliedEntry.outcome adds a SECOND "outcome" choice set,
+        # alongside the telemetry export result's. Without a pin drf-spectacular
+        # disambiguates both by serializer prefix and *renames* the existing stable
+        # OutcomeEnum to TelemetryTestExportResultOutcomeEnum — a published component
+        # disappearing, which breaks generated SDKs and trips schema-check. Pinning
+        # keeps the incumbent's name and lets the new one take the prefixed form.
+        # Same regression class as ScopeChangeStatus above (project_drf_enum_name_collision).
+        "OutcomeEnum": ["success", "reachable", "failure"],
+        # ADR-0107: Workspace gains a third use of Methodology (after Project +
+        # Program) and methodology_override_policy reuses TermOverridePolicy. Pin
+        # Methodology to its stable component name proactively so the third use does
+        # not trip the drf-spectacular enum-name-collision / schema-drift regression
+        # (project_drf_enum_name_collision), same class as the entries above.
+        "MethodologyEnum": "trueppm_api.apps.projects.models.Methodology",
+        # ADR-0105: Task gains task_type / readiness and Project gains
+        # backlog_scoring_model. Each is a new choice set on a *_type / status-adjacent
+        # field; pin to model-prefixed names so drf-spectacular does not rename the
+        # existing stable enums (same regression class as ScopeChangeStatus above).
+        "TaskTypeEnum": "trueppm_api.apps.projects.models.TaskType",
+        # ADR-0638 (#2333): the program label view adds a second serializer
+        # exposing Task.status, which was enough for drf-spectacular to stop
+        # resolving the stable `TaskStatusEnum` and emit a hashed
+        # `Status3ebEnum` in its place — renaming the component on every
+        # *existing* task endpoint, i.e. a breaking change to generated clients
+        # for a purely additive read view. Same regression class as the entries
+        # above (project_drf_enum_name_collision); pin it.
+        "TaskStatusEnum": "trueppm_api.apps.projects.models.TaskStatus",
+        "DorStateEnum": "trueppm_api.apps.projects.models.DorState",
+        "PrioritizationModelEnum": "trueppm_api.apps.projects.models.PrioritizationModel",
+        # ADR-0078 (#927): TeamMembership.role (member|admin) is a second "role"
+        # choice set sharing the field name with the access Role ordinal. Without
+        # a pin drf-spectacular disambiguates both by hash and renames the stable
+        # `RoleEnum` component (same regression class as ScopeChangeStatus above —
+        # project memory project_drf_enum_name_collision). Pin the access role back
+        # to `RoleEnum` and the team role to `TeamRoleEnum`. `RoleEnum` never reaches
+        # the published schema: the post-processing hook finds it by this pinned name
+        # and replaces it with the banded-integer `RoleOrdinal` (ADR-1291), so the
+        # pin is what keeps that hook from silently missing a renamed component.
+        "RoleEnum": "trueppm_api.apps.access.models.Role",
+        "TeamRoleEnum": "trueppm_api.apps.teams.models.TeamRole",
+        # ADR-0036 (#407): Task.governance_class / .delivery_mode add two new choice
+        # sets. Pin to stable model-prefixed names so a later delivery_mode on another
+        # model (e.g. Project, #410) cannot trigger a drf-spectacular rename of the
+        # existing component (same regression class as ScopeChangeStatus — project
+        # memory project_drf_enum_name_collision).
+        "GovernanceClassEnum": "trueppm_api.apps.projects.models.GovernanceClass",
+        "DeliveryModeEnum": "trueppm_api.apps.projects.models.DeliveryMode",
+        # ADR-0106 §5 (#860): ForecastSnapshot.basis / .confidence introduce two
+        # new choice sets on "basis" / "confidence" fields. Pin to model-prefixed
+        # names so drf-spectacular does not rename existing stable components
+        # (same regression class as ScopeChangeStatus — project memory
+        # project_drf_enum_name_collision).
+        "ForecastBasisEnum": "trueppm_api.apps.projects.models.ForecastBasis",
+        "ForecastConfidenceEnum": "trueppm_api.apps.projects.models.ForecastConfidence",
+        # ADR-0104 (#553): SignalAudience is a fresh ladder enum used in the
+        # signal-privacy serializer; pin it to a stable name so a future "audience"
+        # field cannot collide-and-rename it (project memory
+        # project_drf_enum_name_collision).
+        "SignalAudienceEnum": "trueppm_api.apps.projects.models.SignalAudience",
+        # #983: Sprint.goal_outcome (MET|PARTIAL|MISSED) is a new choice set; pin
+        # to a stable model-prefixed name so drf-spectacular does not rename
+        # existing components (same regression class as ScopeChangeStatus —
+        # project memory project_drf_enum_name_collision).
+        "SprintGoalOutcomeEnum": "trueppm_api.apps.projects.models.SprintGoalOutcome",
+        # #985: SprintTaskDisposition is exposed in the /outcome/ read serializer
+        # (DidntShipItemSerializer.disposition). Pin to a stable name so
+        # drf-spectacular does not hash-disambiguate it (project memory
+        # project_drf_enum_name_collision).
+        "SprintTaskDispositionEnum": "trueppm_api.apps.projects.models.SprintTaskDisposition",
+        # ADR-0124 (#1135): Task.blocker_type adds a new structured-blocker choice
+        # set. Pin to a stable model-prefixed name so drf-spectacular does not
+        # hash-disambiguate or rename existing components (same regression class as
+        # ScopeChangeStatus above — project memory project_drf_enum_name_collision).
+        "BlockerTypeEnum": "trueppm_api.apps.projects.models.BlockerType",
+        # #3416: annotating the four batch-undo actions adds a SECOND serializer
+        # exposing StructuralOperation.kind and TemplateApplication.status (the
+        # `*Undo` response wrappers subclass the ledger serializers). A second
+        # exposure of an already-resolved choice set is all it takes for
+        # drf-spectacular to stop deriving the stable name and emit a hashed
+        # `KindD4dEnum` / `StatusCf2Enum` instead — renaming the component on every
+        # *existing* endpoint that serves those rows, i.e. a Breaking change under
+        # `api/stability.md` for a purely additive response annotation. Exactly the
+        # TaskStatusEnum case above, and the same regression class as every pin in
+        # this block (project memory project_drf_enum_name_collision).
+        "StructuralOperationKindEnum": ("trueppm_api.apps.projects.models.StructuralOperationKind"),
+        "TemplateApplicationStatusEnum": (
+            "trueppm_api.apps.projects.models.TemplateApplicationStatus"
+        ),
+        # ADR-0219 (#1266): ProjectExportJob.status introduces a second export-job
+        # status choice set with the SAME members (pending|running|success|failed)
+        # as workspace.ExportJobStatus. drf-spectacular unifies identical value-sets
+        # into ONE component, and without a pin it hash-disambiguates and DROPS the
+        # existing WorkspaceExportJobStatusEnum (a schema-drift regression — project
+        # memory project_drf_enum_name_collision). Pin the shared value-set to the
+        # already-published WorkspaceExportJobStatusEnum name so no component is
+        # removed; the project export field simply reuses that stable component.
+        "WorkspaceExportJobStatusEnum": "trueppm_api.apps.workspace.models.ExportJobStatus",
+        # ADR-0112 RC1 (#1805): the AgentAction read serializer exposes verdict,
+        # refusal_reason, and actor_kind choice sets. "verdict"/"refusal_reason" are
+        # generic field names a future model could reuse; pin to stable model-prefixed
+        # names so drf-spectacular does not hash-disambiguate or rename them (same
+        # regression class as ScopeChangeStatus — project_drf_enum_name_collision).
+        "AgentActionVerdictEnum": "trueppm_api.apps.agents.models.AgentActionVerdict",
+        "AgentActionRefusalReasonEnum": "trueppm_api.apps.agents.models.AgentActionRefusalReason",
+        "AgentActorKindEnum": "trueppm_api.apps.agents.models.AgentActorKind",
+        # ADR-0421 (#1850): the refusal side-car exposes a "constraint" choice set;
+        # "constraint" is a generic field name, so pin it to a stable model-prefixed
+        # component name (same rationale as the verdict/refusal_reason enums above).
+        "RefusalConstraintEnum": "trueppm_api.apps.agents.models.RefusalConstraint",
+        # #3679: ProjectSprintHealthSignalSerializer.key ("orphan" |
+        # "phase_span" | "summary_in_sprint") introduces a second "key" choice
+        # set alongside RetentionPolicy.key, which is enough for drf-spectacular
+        # to stop resolving the stable `KeyEnum` and rename it to
+        # `RetentionPolicyWriteKeyEnum` — a removed component (same regression
+        # class as every pin in this block, project_drf_enum_name_collision).
+        # Pin the incumbent back to its stable name; the sprint-health set is
+        # then free to take the serializer-prefixed name it already resolves to.
+        "KeyEnum": "trueppm_api.apps.observability.retention.RETENTION_KEYS",
+        # #3684: giving the weekly time-entry rollup (`GET /me/time-entries/`) a
+        # real response schema exposes `TimeEntryWeeklySerializer.source`, a SECOND
+        # serializer surfacing `TimeEntry.source` alongside `TimeEntrySerializer`'s.
+        # A second exposure of an already-resolved choice set is exactly what makes
+        # drf-spectacular stop deriving the stable `TimeEntrySourceEnum` name and
+        # hash-disambiguate both instead — renaming the component on every
+        # *existing* time-entry endpoint for a purely additive response annotation
+        # (same regression class as ScopeChangeStatus above —
+        # project_drf_enum_name_collision). Pin it.
+        "TimeEntrySourceEnum": "trueppm_api.apps.timetracking.models.TimeEntrySource",
+    },
+}