trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/core/openapi.py

@@ -0,0 +1,1221 @@
+"""OpenAPI / drf-spectacular customizations for SDK-quality schema output (#1333).
+
+Generated clients (openapi-generator, Orval, openapi-typescript) key their method
+names, doc comments, and API-class grouping off three schema facets that
+drf-spectacular leaves thin by default:
+
+* ``summary`` — the human label a client renders as the method doc comment. Without
+  it, tools fall back to the raw ``operationId`` (``v1_calendars_exceptions_create``),
+  which produces unreadable SDK docs.
+* ``tags`` — the grouping key. drf-spectacular tags every ``/api/v1/`` operation
+  ``"v1"`` by default, so a generated client collapses the whole API into a single
+  ``V1Api`` class. Meaningful tags split it into ``ProjectsApi``, ``SprintsApi``,
+  ``SchedulingApi``, … the way an SDK consumer expects.
+* ``security`` — a global default plus explicit ``security: []`` on the public
+  endpoints, so a client knows which calls need a credential and which do not.
+
+Rather than hand-annotate ~300 view methods (error-prone, and every *new* endpoint
+would silently regress coverage), the mechanical facets are filled by a single
+post-processing hook that derives them from the request path — so coverage is
+complete today and stays complete as endpoints are added. A view can still override
+any facet with an explicit ``@extend_schema(...)``; the hook only fills what is
+missing (summary) or still default (the ``"v1"`` tag).
+
+The ``429`` documentation is injected by a custom :class:`AutoSchema` subclass
+because throttling is a *view* attribute (``throttle_classes``) that is not visible
+in the final schema dict — only the schema generator, which holds the view, can see
+it.
+
+The same subclass narrows ``security`` per-method on MCP-readable views (#2659):
+``McpReadableViewMixin`` adds ``projectApiTokenAuth`` at the view level, but the
+project/program-scoped credentials unique to that scheme are refused on the whole
+MCP surface, so the unsafe methods must not advertise it. A ``legacy:full``
+personal token *can* write there since #2877 and is described by
+``personalApiTokenAuth``, which those operations already carry.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, cast
+
+from drf_spectacular.openapi import AutoSchema
+from rest_framework.permissions import SAFE_METHODS
+
+from trueppm_api.core.demo_read_only import DEMO_READ_ONLY_CODE
+
+# ---------------------------------------------------------------------------
+# Tag definitions
+# ---------------------------------------------------------------------------
+
+# The top-level ``tags`` block (name + description for each tag below) is declared
+# in ``SPECTACULAR_SETTINGS["TAGS"]`` in settings/base.py — it is defined there
+# rather than imported from here because Django settings must not import
+# DRF-dependent app code. The two must stay in lockstep: every tag this module can
+# assign is described in that block.
+
+# Top-level path segment -> tag. Anything not listed falls through to the segment
+# itself (which will already be a sensible resource name).
+_TOP_TAG: dict[str, str] = {
+    "acceptance-criteria": "tasks",
+    "admin": "meta",
+    "auth": "auth",
+    "calendars": "calendars",
+    "cascade-classification-operations": "projects",
+    "dependencies": "tasks",
+    "edition": "meta",
+    "health": "meta",
+    "import-templates": "import-export",
+    "readyz": "meta",
+    "integrations": "integrations",
+    # ADR-1237: project/program key lookups, folded under `projects` rather than
+    # minting a top-level tag for two small read-only endpoints.
+    "keys": "projects",
+    "me": "me",
+    "paste-many-operations": "projects",
+    "poker": "sprints",
+    "programs": "programs",
+    "project-resources": "resources",
+    "project-templates": "projects",
+    "projects": "projects",
+    "recurrence-rules": "tasks",
+    "resource-skills": "resources",
+    "resolve": "projects",
+    "resources": "resources",
+    "retro-items": "sprints",
+    "scope-changes": "sprints",
+    "share": "share",
+    "skills": "resources",
+    "slip-conflicts": "scheduling",
+    "sprint-task-outcomes": "sprints",
+    "sprints": "sprints",
+    # ADR-0880 (#2974): the structural undo ledger, folded under `projects` with its
+    # ADR-0810 siblings (`paste-many-operations`, `cascade-classification-operations`)
+    # rather than minting a top-level tag for one read-only ledger.
+    "structural-operations": "projects",
+    "task-resources": "resources",
+    "task-runs": "tasks",
+    "task-skill-requirements": "resources",
+    "tasks": "tasks",
+    "teams": "teams",
+    "template-applications": "projects",
+    "users": "workspace",
+    "velocity-suggestions": "sprints",
+    "workspace": "workspace",
+    "ws": "sync",
+}
+
+# Second path segment under /projects/ or /programs/ -> tag, so nested resources
+# land in their own SDK class instead of the umbrella Projects/Programs class.
+_SUB_TAG: dict[str, str] = {
+    "tasks": "tasks",
+    "task": "tasks",
+    "milestones": "tasks",
+    "acceptance-results": "tasks",
+    "acceptance-criteria": "tasks",
+    "baseline": "scheduling",
+    "baselines": "scheduling",
+    "schedule": "scheduling",
+    "scheduler": "scheduling",
+    "monte-carlo": "scheduling",
+    "forecast": "scheduling",
+    "risk": "scheduling",
+    "risks": "scheduling",
+    "slip-conflicts": "scheduling",
+    "critical-path": "scheduling",
+    "sprints": "sprints",
+    "sprint": "sprints",
+    "sprint-health": "sprints",
+    "velocity": "sprints",
+    "retrospective": "sprints",
+    "standup": "sprints",
+    "burn": "sprints",
+    "board": "sprints",
+    "product-backlog": "sprints",
+    "queue": "sprints",
+    "ceremonies": "sprints",
+    "backlog": "sprints",
+    "resources": "resources",
+    "resource-allocation": "resources",
+    "resource-contention": "resources",
+    "utilization": "resources",
+    "members": "members",
+    "teams": "teams",
+    "webhooks": "webhooks",
+    "integrations": "integrations",
+    "integrations-summary": "integrations",
+    "import": "import-export",
+    "imports": "import-export",
+    "export": "import-export",
+    "share-links": "share",
+}
+
+# ---------------------------------------------------------------------------
+# Security
+# ---------------------------------------------------------------------------
+
+# The default requirement advertised at the document root: a caller authenticates
+# with either a bearer JWT or the session cookie. Operations that accept a project
+# API token additionally list ``projectApiTokenAuth`` on their own operation-level
+# ``security`` (emitted by drf-spectacular from the view's authentication classes).
+GLOBAL_SECURITY: list[dict[str, list[str]]] = [{"jwtAuth": []}, {"cookieAuth": []}]
+
+# Endpoints that require no credential at all. They must carry an explicit
+# ``security: []`` so a generated client does not attach a (non-existent) token.
+PUBLIC_PATHS: frozenset[str] = frozenset(
+    {
+        "/api/v1/auth/logout/",
+        "/api/v1/auth/oidc/callback/",
+        "/api/v1/auth/oidc/discover/",
+        "/api/v1/auth/oidc/login/",
+        "/api/v1/auth/token/",
+        "/api/v1/auth/token/refresh/",
+        "/api/v1/edition/",
+        "/api/v1/health/",
+        "/api/v1/readyz",
+        "/api/v1/integrations/projects/{project_pk}/git-webhook/",
+        "/api/v1/workspace/invites/accept/",
+    }
+)
+
+# Paths where only some methods are public. The workspace logo is served
+# anonymously (GET) but uploaded and cleared by an authenticated admin, so
+# marking the whole path public advertised the writes as unauthenticated.
+PUBLIC_METHODS_BY_PATH: dict[str, frozenset[str]] = {
+    "/api/v1/workspace/logo/": frozenset({"get"}),
+}
+
+_HTTP_METHODS = ("get", "post", "put", "patch", "delete", "head", "options", "trace")
+
+# Attribute stamped on a viewset ``@action`` handler to opt its list response out
+# of drf-spectacular's automatic pagination-envelope wrapping (see
+# :func:`suppress_list_pagination` and :meth:`TruePPMAutoSchema._get_paginator`).
+_SUPPRESS_PAGINATION_ATTR = "spectacular_suppress_pagination"
+_JSON_MEDIA_TYPE = "application/json"
+
+
+def suppress_list_pagination(view_func: Any) -> Any:
+    """Mark a viewset ``@action``'s list response as NON-paginated for the schema.
+
+    drf-spectacular auto-wraps any ``many=True`` response of a view whose
+    ``pagination_class`` is set in that paginator's envelope
+    (``Paginated…List``). Actions that deliberately return a **bare array** — a
+    small, capped, or fixed-size list the client consumes directly — must opt out
+    so the generated schema matches the real response body; otherwise the
+    committed schema claims a paginated object and every such response fails
+    ``response_schema_conformance`` (#2127). Pairs with
+    :meth:`TruePPMAutoSchema._get_paginator`.
+    """
+    setattr(view_func, _SUPPRESS_PAGINATION_ATTR, True)
+    return view_func
+
+
+_IRREGULAR_SINGULAR = {
+    "criteria": "criterion",
+    "analyses": "analysis",
+    "indices": "index",
+    "people": "person",
+}
+
+# Verbs used for standard CRUD-style detail operations, keyed by HTTP method.
+_DETAIL_VERB = {
+    "get": "Retrieve",
+    "put": "Update",
+    "patch": "Partially update",
+    "delete": "Delete",
+    "post": "Update",
+}
+
+
+def _humanize(segment: str) -> str:
+    """``acceptance-results`` -> ``acceptance results`` (lower, space-separated)."""
+    return segment.replace("-", " ").replace("_", " ").strip().lower()
+
+
+def _singularize(phrase: str) -> str:
+    """Singularize the last word of a humanized phrase (naive, with irregulars)."""
+    if not phrase:
+        return phrase
+    words = phrase.split()
+    last = words[-1]
+    if last in _IRREGULAR_SINGULAR:
+        singular = _IRREGULAR_SINGULAR[last]
+    elif last.endswith("ies") and len(last) > 3:
+        singular = last[:-3] + "y"
+    elif last.endswith(("ses", "xes", "ches", "shes")):
+        singular = last[:-2]
+    elif last.endswith("s") and not last.endswith("ss"):
+        singular = last[:-1]
+    else:
+        singular = last
+    words[-1] = singular
+    return " ".join(words)
+
+
+def _sentence_case(text: str) -> str:
+    return text[:1].upper() + text[1:] if text else text
+
+
+def _path_segments(path: str) -> list[str]:
+    """Path parts with the ``api``/``v1`` prefix stripped."""
+    return [p for p in path.split("/") if p and p not in ("api", "v1")]
+
+
+def _derive_tag(path: str) -> str:
+    segments = _path_segments(path)
+    literals = [p for p in segments if not (p.startswith("{") and p.endswith("}"))]
+    if not literals:
+        return "meta"
+    top = literals[0]
+    if top in ("projects", "programs") and len(literals) > 1:
+        return _SUB_TAG.get(literals[1], top)
+    return _TOP_TAG.get(top, top)
+
+
+def _derive_summary(path: str, method: str, collection_paths: frozenset[str]) -> str:
+    """Build a human ``summary`` from the request path and HTTP method.
+
+    The path structure disambiguates the three shapes an SDK cares about:
+    collection (``List``/``Create``), detail-by-id (``Retrieve``/``Update``/…) and
+    custom action (``Accept``/``Close``/…). A trailing literal is a *collection*
+    when a child ``.../{id}/`` path exists, otherwise it is treated as an action
+    (POST) or a singleton sub-resource (GET/PUT/PATCH/DELETE).
+    """
+    method = method.lower()
+    segments = _path_segments(path)
+    if not segments:
+        return _sentence_case(method)
+
+    last = segments[-1]
+
+    # Detail-by-id: the resource is the collection immediately above the id.
+    if last.startswith("{") and last.endswith("}"):
+        return _detail_summary(segments, method)
+
+    # Trailing literal that owns a ``.../{id}/`` route -> a collection.
+    normalized = path if path.endswith("/") else path + "/"
+    if normalized in collection_paths:
+        return _collection_summary(last, method)
+
+    # Trailing literal with no child id route: a custom action (POST) or a
+    # singleton sub-resource (safe/idempotent methods).
+    return _action_summary(segments, method)
+
+
+def _detail_summary(segments: list[str], method: str) -> str:
+    """Summary for a detail-by-id path: ``<verb> <singular resource>``."""
+    parent = segments[-2] if len(segments) > 1 else segments[-1]
+    resource = _singularize(_humanize(parent))
+    return f"{_DETAIL_VERB.get(method, 'Retrieve')} {resource}"
+
+
+def _collection_summary(last: str, method: str) -> str:
+    """Summary for a collection path: ``List``/``Create``/``<verb>`` the resource."""
+    human = _humanize(last)
+    if method == "get":
+        return f"List {human}"
+    if method == "post":
+        return f"Create {_singularize(human)}"
+    return f"{_DETAIL_VERB.get(method, 'Update')} {_singularize(human)}"
+
+
+def _action_summary(segments: list[str], method: str) -> str:
+    """Summary for a custom action (POST) or singleton sub-resource (safe methods)."""
+    last = segments[-1]
+    preceding_literals = [p for p in segments[:-1] if not (p.startswith("{") and p.endswith("}"))]
+    owner_segment = preceding_literals[-1] if preceding_literals else last
+    has_parent_id = any(p.startswith("{") and p.endswith("}") for p in segments[:-1])
+
+    if method == "post":
+        verb = _sentence_case(_humanize(last))
+        owner_human = _humanize(owner_segment)
+        owner = _singularize(owner_human) if has_parent_id else owner_human
+        if owner_segment == last:
+            return verb
+        return f"{verb} {owner}"
+
+    return f"{_DETAIL_VERB.get(method, 'Retrieve')} {_singularize(_humanize(last))}"
+
+
+def _collection_paths(paths: dict[str, Any]) -> frozenset[str]:
+    """Paths that own a child ``.../{param}/`` route (i.e. real collections)."""
+    collections: set[str] = set()
+    for path in paths:
+        segments = path.rstrip("/").split("/")
+        if not segments:
+            continue
+        tail = segments[-1]
+        if tail.startswith("{") and tail.endswith("}"):
+            parent = "/".join(segments[:-1]) + "/"
+            collections.add(parent)
+    return frozenset(collections)
+
+
+def postprocess_openapi(
+    result: dict[str, Any],
+    generator: Any,
+    request: Any,
+    public: bool,
+    **kwargs: Any,
+) -> dict[str, Any]:
+    """Fill SDK-quality facets the per-view annotations leave thin (#1333).
+
+    * add a derived ``summary`` to every operation that lacks one;
+    * replace the default ``"v1"`` tag with a meaningful resource tag;
+    * set a document-level ``security`` default and mark public paths ``security: []``.
+    * rewrite every bare ``format: "time"`` to a pattern (see ``_rewrite_time_format``).
+    * publish the role ordinal as a banded integer, not a closed enum
+      (see ``_publish_role_ordinal``, ADR-1291);
+    * mark every enum open or exhaustive (see ``_mark_enum_openness``, ADR-1291).
+
+    Explicit ``@extend_schema`` values are never overwritten — a non-default tag is
+    kept, and an existing summary is left untouched.
+    """
+    paths = result.get("paths", {})
+    collection_paths = _collection_paths(paths)
+
+    for path, operations in paths.items():
+        for method, operation in operations.items():
+            if method not in _HTTP_METHODS or not isinstance(operation, dict):
+                continue
+            is_public = path in PUBLIC_PATHS or method in PUBLIC_METHODS_BY_PATH.get(
+                path, frozenset()
+            )
+            _annotate_operation(operation, path, method, collection_paths, is_public)
+
+    _register_validation_error_detail(result)
+    _register_demo_read_only_error(result)
+    _rewrite_time_format(result)
+    # Order matters: the role ordinal stops being an enum before the openness pass
+    # runs, so it is never marked as one.
+    _publish_role_ordinal(result)
+    _mark_enum_openness(result)
+
+    # Document-level default so a client knows the baseline auth scheme.
+    result["security"] = list(GLOBAL_SECURITY)
+    return result
+
+
+# RFC 3339 `full-time` (what JSON Schema's `format: "time"` validates against)
+# requires a trailing offset (`09:30:00Z` / `09:30:00+00:00`). Every DRF
+# ``TimeField`` in this API represents a local wall-clock time-of-day (a daily
+# notification slot, a retention run time) rather than a UTC instant, and is
+# serialized as bare ``HH:MM:SS`` with no offset — so drf-spectacular's default
+# ``format: "time"`` mapping (``OpenApiTypes.TIME``) makes a claim the response
+# never satisfies. There is no accurate JSON Schema ``format`` for "local time,
+# no offset"; a pattern matching the real serialization is correct instead
+# (schemathesis job #16501510109 / #3811).
+_TIME_OF_DAY_PATTERN = r"^\d{2}:\d{2}:\d{2}(\.\d{1,6})?$"
+
+
+def _rewrite_time_format(node: Any) -> None:
+    """Replace every ``{"type": "string", "format": "time"}`` schema node in place.
+
+    Walks the whole document (not just ``components.schemas``) because the same
+    property can also appear inline in request/response bodies and parameters.
+    """
+    if isinstance(node, dict):
+        if node.get("type") == "string" and node.get("format") == "time":
+            del node["format"]
+            node["pattern"] = _TIME_OF_DAY_PATTERN
+        for value in node.values():
+            _rewrite_time_format(value)
+    elif isinstance(node, list):
+        for item in node:
+            _rewrite_time_format(item)
+
+
+# ---------------------------------------------------------------------------
+# Enum openness (ADR-1291, #4593)
+# ---------------------------------------------------------------------------
+
+#: Vendor extension carried by every ``enum`` node in the published document.
+#: Namespaced rather than reusing Zalando's ``x-extensible-enum`` on purpose: that
+#: convention takes an *array* of values and *replaces* ``enum``, so a tool that
+#: knows it would misread a string flag sitting beside ``enum``. See ADR-1291 for
+#: why ``enum`` is kept instead of replaced.
+ENUM_OPENNESS_KEY = "x-trueppm-enum"
+ENUM_OPEN = "open"
+ENUM_EXHAUSTIVE = "exhaustive"
+
+#: The enum components that are genuinely closed. Everything else is open: a
+#: later release may add a value, and a client must tolerate one it does not know
+#: (``stability.md`` § Change classes). Keep this short — every entry is a promise
+#: that adding a value is a Breaking change — and give each one a reason.
+EXHAUSTIVE_ENUMS: dict[str, str] = {
+    # drf-spectacular's structural devices for "blank" and "null" on a nullable /
+    # blankable choice field (`oneOf: [{X}, {BlankEnum}, {NullEnum}]`). They are not
+    # vocabularies; opening them would make every such `oneOf` accept any value.
+    "BlankEnum": "drf-spectacular's empty-string branch of a blankable choice field",
+    "NullEnum": "drf-spectacular's null branch of a nullable choice field",
+    # The four precedence-diagramming relationships are the whole set by
+    # definition, and both scheduling engines hard-code exactly four. A fifth would
+    # be a new engine contract, which is Breaking whatever the schema says.
+    "DepTypeEnum": "FS/SS/FF/SF is the complete set of CPM dependency types",
+    # Python's weekday() integers. There is no eighth day.
+    "DigestWeekdayEnum": "the seven weekdays, 0 (Monday) to 6 (Sunday)",
+    # Discriminator tags. Each names which `oneOf` variant a response is; a client
+    # dispatches on it, and a new chart type or engine pass arrives as a new variant
+    # with its own tag rather than as a new value of an existing variant's tag.
+    "ProjectBurnCombinedChartTypeEnum": "discriminator tag of the ProjectBurnResponse variant",
+    "ProjectBurnSeriesChartTypeEnum": "discriminator tag of the ProjectBurnResponse variant",
+    "ScheduleCpmDerivationPassEnum": "tags the CPM variant of ScheduleDerivationResponse",
+    "ScheduleMonteCarloDerivationPassEnum": (
+        "tags the Monte Carlo variant of ScheduleDerivationResponse"
+    ),
+}
+
+
+def _inline_enum_openness(node: dict[str, Any]) -> str:
+    """Openness of an enum declared inline (a parameter or an anonymous property).
+
+    A boolean or null constant (``sent: [false]``) has no room to grow, so it is
+    exhaustive; any other inline vocabulary follows the open default.
+    """
+    if node.get("type") == "boolean" or all(v is None for v in node.get("enum", [])):
+        return ENUM_EXHAUSTIVE
+    return ENUM_OPEN
+
+
+def _mark_inline_enums(node: Any) -> None:
+    if isinstance(node, dict):
+        if "enum" in node and ENUM_OPENNESS_KEY not in node:
+            node[ENUM_OPENNESS_KEY] = _inline_enum_openness(node)
+        for value in node.values():
+            _mark_inline_enums(value)
+    elif isinstance(node, list):
+        for item in node:
+            _mark_inline_enums(item)
+
+
+def _mark_enum_openness(result: dict[str, Any]) -> None:
+    """Mark every ``enum`` node in the document ``open`` or ``exhaustive`` (#4593).
+
+    Before this every one of the 143 enum components was published closed, while
+    ``stability.md`` called a new enum value an Additive change — so the schema
+    told strict generated clients (and the e2e schema guard) to reject exactly the
+    change the policy promised was safe. The default is now open; the closed ones
+    are named in :data:`EXHAUSTIVE_ENUMS` with a reason each.
+
+    ``enum`` itself is kept rather than replaced, so typed clients still get the
+    known values and the reference docs still list them. The marker is what a
+    client reads to decide whether an unrecognized value is a bug or a newer
+    server; ADR-1291 records the trade-off.
+    """
+    schemas = result.get("components", {}).get("schemas", {})
+    for name, schema in schemas.items():
+        if isinstance(schema, dict) and "enum" in schema:
+            schema[ENUM_OPENNESS_KEY] = ENUM_EXHAUSTIVE if name in EXHAUSTIVE_ENUMS else ENUM_OPEN
+    # Then everything still unmarked: inline property, parameter and response enums.
+    _mark_inline_enums(result)
+
+
+#: The component every role field is published as (ADR-0072 Amendment 2, ADR-1291).
+ROLE_ORDINAL = "RoleOrdinal"
+_ROLE_ENUM_REF = "#/components/schemas/RoleEnum"
+_ROLE_ORDINAL_REF = f"#/components/schemas/{ROLE_ORDINAL}"
+
+
+def _role_ordinal_schema() -> dict[str, Any]:
+    """The banded-integer schema for a role ordinal, derived from ``Role`` itself.
+
+    Derived rather than written out so the published OSS ordinals cannot drift
+    from the model's choices.
+    """
+    from trueppm_api.apps.access.models import Role  # app code: import at call time
+
+    tiers = ", ".join(f"`{member.value}` {member.name}" for member in Role)
+    return {
+        "type": "integer",
+        "minimum": int(min(Role)),
+        "maximum": int(max(Role)),
+        "description": (
+            "A role ordinal (ADR-0072). This is a banded integer, not a closed set. "
+            f"The five OSS roles are {tiers}; their display names depend on the "
+            "project or program vocabulary. The ordinals between them (2-99, "
+            "101-199, 201-299 and 301-399) are reserved for Enterprise custom "
+            "roles, and an Enterprise install may return one. A client must accept "
+            "any integer in range: compare with `>=` against the OSS ordinal that "
+            "opens a band to decide what a role may do, and render an unrecognized "
+            "ordinal by the band it falls in. `0` and anything above the owner "
+            "ordinal are never assigned. An OSS server accepts only the five OSS "
+            "ordinals on write."
+        ),
+    }
+
+
+def _rewrite_ref(node: Any, old: str, new: str) -> None:
+    if isinstance(node, dict):
+        if node.get("$ref") == old:
+            node["$ref"] = new
+        for value in node.values():
+            _rewrite_ref(value, old, new)
+    elif isinstance(node, list):
+        for item in node:
+            _rewrite_ref(item, old, new)
+
+
+def _publish_role_ordinal(result: dict[str, Any]) -> None:
+    """Publish ``role`` / ``default_member_role`` / ``my_role`` as a banded integer.
+
+    drf-spectacular derives a closed ``RoleEnum = [1, 100, 200, 300, 400]`` from
+    the ``Role`` choices. That enum is closed over the very ordinals ADR-0072
+    reserves for Enterprise custom roles, so an Enterprise install returning a
+    role at 250 would violate the published OSS contract by design (#4593). The
+    component is replaced by :data:`ROLE_ORDINAL` and every reference repointed.
+
+    Some fields carry a project ``Role`` ordinal as a plain ``integer`` with no
+    reference to the role at all: a ``SerializerMethodField`` (``my_role``,
+    ``max_project_role``) or a bare ``IntegerField`` whose choices are enforced in
+    ``validate`` rather than declared. They are pointed at the same component so
+    their bands are documented in the one place every role field reads them from.
+    ``my_role`` is matched on every component that declares it; the others are
+    named in :data:`_BARE_ROLE_FIELDS`.
+    """
+    schemas = result.get("components", {}).get("schemas")
+    if not schemas or "RoleEnum" not in schemas:
+        return
+    del schemas["RoleEnum"]
+    schemas[ROLE_ORDINAL] = _role_ordinal_schema()
+    _rewrite_ref(result, _ROLE_ENUM_REF, _ROLE_ORDINAL_REF)
+    for name, schema in schemas.items():
+        properties = schema.get("properties", {}) if isinstance(schema, dict) else {}
+        for field in ("my_role", *_BARE_ROLE_FIELDS.get(name, ())):
+            _point_at_role_ordinal(properties.get(field))
+    result["components"]["schemas"] = dict(sorted(schemas.items()))
+
+
+#: Component -> properties that carry a project ``Role`` ordinal as a bare
+#: ``integer``. Workspace-role fields (``workspace_role``, ``role_value``, the
+#: workspace member/invite ``role``, SSO ``default_role``) are deliberately absent:
+#: they are ``WorkspaceRole`` ordinals, a different scale this component does not
+#: describe.
+_BARE_ROLE_FIELDS: dict[str, tuple[str, ...]] = {
+    "ProjectMembershipWriteRequest": ("role",),
+    "PatchedProjectMembershipUpdateRequest": ("role",),
+    "GroupProjectLink": ("role",),
+    "GroupProjectWriteRequest": ("role",),
+    "Me": ("max_project_role",),
+}
+
+
+def _point_at_role_ordinal(prop: Any) -> None:
+    """Turn ``{type: integer, ...}`` into ``{allOf: [RoleOrdinal], ...}`` in place."""
+    if not isinstance(prop, dict) or prop.get("type") != "integer":
+        return
+    del prop["type"]
+    rest = dict(prop)
+    prop.clear()
+    prop["allOf"] = [{"$ref": _ROLE_ORDINAL_REF}]
+    prop.update(rest)
+
+
+def _register_validation_error_detail(result: dict[str, Any]) -> None:
+    """Register the recursive ``ValidationErrorDetail`` component (#3324).
+
+    It is defined here rather than through drf-spectacular's component registry
+    because nothing in the API is serialized by it — it describes DRF's *error*
+    output, which has no serializer to introspect. The ``$ref`` that points at it
+    is injected per-operation by :class:`TruePPMAutoSchema`, so registering it in
+    the finished document is what makes that ``$ref`` resolve.
+
+    Re-sorted afterwards because drf-spectacular emits ``components.schemas``
+    alphabetically; appending to the end would make the committed
+    ``docs/api/openapi.json`` diff against a fresh regenerate on ordering alone.
+    """
+    schemas = result.setdefault("components", {}).setdefault("schemas", {})
+    schemas[VALIDATION_ERROR_DETAIL] = deepcopy(_VALIDATION_ERROR_DETAIL_SCHEMA)
+    result["components"]["schemas"] = dict(sorted(schemas.items()))
+
+
+DEMO_READ_ONLY_ERROR = "DemoReadOnlyError"
+
+
+def _register_demo_read_only_error(result: dict[str, Any]) -> None:
+    """Register the ``403`` body demo read-only mode returns for every refused write.
+
+    The demo read-only middleware answers before routing, so no operation has a view to
+    attach this response to, and stamping a ``403`` onto every write operation would
+    describe a response the vast majority of deployments can never return. A single
+    named component, which ``api/errors.md`` and the API description point at, is the
+    honest shape: any unsafe request may return it, but only when the deployment sets
+    ``TRUEPPM_DEMO_READ_ONLY``.
+
+    Re-sorted for the same reason as :func:`_register_validation_error_detail`: the
+    committed ``docs/api/openapi.json`` must not diff against a fresh regenerate on
+    ordering alone.
+    """
+    schemas = result.setdefault("components", {}).setdefault("schemas", {})
+    schemas[DEMO_READ_ONLY_ERROR] = {
+        "type": "object",
+        "description": (
+            "Returned with HTTP 403 for every `POST`, `PUT`, `PATCH` or `DELETE` under "
+            "`/api/` when the deployment runs in demo read-only mode "
+            "(`TRUEPPM_DEMO_READ_ONLY=true`), except sign-in, token refresh and sign-out. "
+            "Independent of role, permission class and authentication: an Owner and an "
+            "anonymous caller are refused identically, and retrying with more permission "
+            "never helps. A normal installation never returns it."
+        ),
+        "properties": {
+            "detail": {
+                "type": "string",
+                "description": "Human-readable explanation. May be reworded; do not match on it.",
+            },
+            "code": {
+                "type": "string",
+                "enum": [DEMO_READ_ONLY_CODE],
+                "description": "Stable machine-readable refusal code. Branch on this.",
+            },
+        },
+        "required": ["detail", "code"],
+        "additionalProperties": False,
+    }
+    result["components"]["schemas"] = dict(sorted(schemas.items()))
+
+
+def _annotate_operation(
+    operation: dict[str, Any],
+    path: str,
+    method: str,
+    collection_paths: frozenset[str],
+    is_public: bool,
+) -> None:
+    """Fill a single operation's ``summary``/``tags``/``security`` in place.
+
+    Explicit ``@extend_schema`` values are preserved: an existing summary and a
+    non-default tag are left untouched.
+    """
+    if not operation.get("summary"):
+        operation["summary"] = _derive_summary(path, method, collection_paths)
+
+    tags = operation.get("tags")
+    if not tags or tags == ["v1"]:
+        operation["tags"] = [_derive_tag(path)]
+
+    if is_public:
+        operation["security"] = []
+
+
+# ---------------------------------------------------------------------------
+# 429 documentation via a custom AutoSchema
+# ---------------------------------------------------------------------------
+
+# The 403 an API-token caller receives on the credential-management surface (#2878) and
+# on SSO provider configuration (#3551). Declared on every operation whose view carries
+# ``IsNotTokenAuthenticated``, so an integrator scripting against a token learns from the
+# contract that this refusal is by design rather than discovering it as an apparent
+# permissions bug. Worded for the whole surface rather than the token routes alone: it is
+# emitted verbatim on SSO operations too, where a token-management-specific sentence
+# would be a confidently wrong diagnosis.
+_TOKEN_REFUSED_RESPONSE = {
+    "description": (
+        "Refused because the caller authenticated with an API token. Managing "
+        "credentials or sign-in configuration requires a session or JWT — a token can "
+        "neither mint, list or revoke tokens, nor read or reconfigure SSO providers — "
+        "so that revoking a leaked credential is actual containment. The ``refusal`` "
+        "envelope carries ``reason: policy`` and ``constraint: capability_scope``. A "
+        "token that is revoked, expired, or carries the wrong scope for this surface is "
+        "rejected earlier, by the authenticator, and receives ``401`` with "
+        "``reason: identity`` instead. This status is also returned to a *session* "
+        "caller who lacks the required role; that refusal carries ``detail`` alone, "
+        "with no ``refusal`` envelope."
+    ),
+    "content": {
+        _JSON_MEDIA_TYPE: {
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "type": "string",
+                        "example": (
+                            "API tokens cannot manage credentials or sign-in "
+                            "configuration. Sign in to perform this action."
+                        ),
+                    },
+                    "refusal": {
+                        "type": "object",
+                        "properties": {
+                            "verdict": {"type": "string", "example": "refused"},
+                            "reason": {"type": "string", "example": "policy"},
+                            "constraint": {"type": "string", "example": "capability_scope"},
+                        },
+                    },
+                },
+            }
+        }
+    },
+}
+
+#: Component name for the recursive validation-error value (#3324).
+VALIDATION_ERROR_DETAIL = "ValidationErrorDetail"
+_VALIDATION_ERROR_DETAIL_REF = {"$ref": f"#/components/schemas/{VALIDATION_ERROR_DETAIL}"}
+
+#: What one field key in a 400 body can hold (#3324).
+#:
+#: #3286 declared this as ``array<string>`` and the first nightly ``api:fuzz`` run
+#: after it merged failed three operations on ``response_schema_conformance``:
+#: ``POST /projects/``, ``POST /programs/`` and ``PATCH /auth/me/profile/`` all
+#: returned ``{"0": [...], "1": [...]}`` under a field key, which is not an array.
+#: That is not a defect in the response — ``ListField.to_internal_value``
+#: accumulates per-item errors into a dict keyed by ITEM INDEX and raises
+#: ``ValidationError`` on it, and the index is the part a client needs to point at
+#: the offending element. The contract was the thing that was too narrow.
+#:
+#: Four shapes reach a field key, and only the first was declared:
+#:
+#:   ``["msg", ...]``                     flat field
+#:   ``{"0": ["msg"]}``                   ``ListField`` — keyed by item index
+#:   ``{"sub": ["msg"]}``                 nested serializer — keyed by subfield
+#:   ``[{}, {"sub": ["msg"]}]``           ``many=True`` — one entry per submitted item
+#:   ``{"non_field_errors": ["msg"]}``    a constraint on the list as a whole (#3596)
+#:
+#: The last one keys on neither an index nor a subfield: a length cap, or a value that
+#: is not a list at all, has no failing *item* to point at, so ``ListSerializer`` puts
+#: it under ``non_field_errors``. Declaring only "index or subfield name" sent an
+#: integrator looking for a ``"0"`` key that is never there.
+#:
+#: Recursive rather than an enumeration of those four, because nesting composes: a
+#: ``ListField`` inside a ``many=True`` serializer nests one level deeper than any
+#: of them and would need a fifth branch, then a sixth. The invariant that holds at
+#: every depth is the one declared here — **strings at the leaves**. The three
+#: branches are disjoint by ``type``, so ``oneOf`` is exact rather than merely
+#: permissive: no value matches two of them.
+_VALIDATION_ERROR_DETAIL_SCHEMA = {
+    "description": (
+        "One field's validation errors. A flat field yields a list of messages. A "
+        "list field or nested serializer nests one level further, as an object keyed "
+        "by item index or by subfield name; a ``many=True`` serializer yields one "
+        "entry per submitted item, ``{}`` where that item validated. A constraint on "
+        "the list as a whole — its length, or a value that is not a list — has no "
+        "failing item to point at and keys on ``non_field_errors`` instead. Nesting is "
+        "arbitrarily deep and the leaves are always message strings."
+    ),
+    "oneOf": [
+        {"type": "string"},
+        {"type": "array", "items": _VALIDATION_ERROR_DETAIL_REF},
+        {"type": "object", "additionalProperties": _VALIDATION_ERROR_DETAIL_REF},
+    ],
+}
+
+#: The 400 every operation that accepts a request body can return (#3286).
+#:
+#: Modelled on what the API actually emits rather than on one tidy shape, because
+#: ``docs/api/errors.md`` documents two and DRF contributes a third:
+#:
+#:   ``{"detail": "..."}``                       Shape 1 — a bare refusal
+#:   ``{"code": "...", "detail": "..."}``        Shape 2 — ``code`` is the contract
+#:   ``{"name": ["This field is required."]}``   DRF's field-keyed serializer errors
+#:
+#: ``additionalProperties`` carries the third, via the recursive component above so
+#: that its nested forms are described too. Declaring only ``detail`` would be the
+#: more comfortable lie: a generated client would type the uncommon case and
+#: mis-type field validation, which is the majority of real 400s.
+#:
+#: ``detail`` and ``code`` reference that same component rather than declaring
+#: ``string`` (#3347). In JSON Schema ``additionalProperties`` applies only to keys
+#: **not** matched by ``properties``, so the widening #3324 made to the field-keyed
+#: map never reached the two keys named in the envelope — they stayed pinned to
+#: ``string``. That is only sound while each name means one thing, and ``code``
+#: means two: the refusal envelope's stable machine code, and the validation errors
+#: of the serializer field literally *named* ``code`` — ``Program.code`` and
+#: ``Project.code``, reachable on 21 operations. DRF keys the latter by field name
+#: and yields a list, so the 2026-09-04 nightly ``api:fuzz`` failed
+#: ``POST /programs/`` and ``POST /projects/`` on
+#: ``["Ensure this field has no more than 40 characters."] is not of type "string"``.
+#: The response was right and the declaration was narrow, exactly as in #3324.
+#:
+#: ``detail`` is widened with it. No serializer has a writable ``detail`` field
+#: today, so that half is latent — but it is the *same* declaration bug, and the
+#: one-instance fix is what left this open after #3324.
+#:
+#: The reference is exact, not merely permissive: ``ValidationErrorDetail``'s first
+#: ``oneOf`` branch is ``{"type": "string"}``, so the envelope form still validates
+#: against precisely one branch. What a client loses is the guarantee that ``code``
+#: is a string — which it never had. It gains the discriminator: a **string**
+#: ``code`` is a refusal code from the vocabulary in ``docs/api/errors.md``; a list
+#: or object under ``code`` is field validation of the field of that name.
+#:
+#: ``allOf`` wraps the ``$ref`` because this is OpenAPI 3.0.3, where sibling keys
+#: alongside a ``$ref`` are discarded — without it the description and example are
+#: silently dropped from the published schema.
+_VALIDATION_RESPONSE = {
+    "description": (
+        "The request was rejected. Either a field failed validation — in which case "
+        "the body is keyed by field name with a list of messages — or the request was "
+        "refused as a whole, in which case it carries ``detail`` and, when the failure "
+        "is one a client is expected to handle rather than merely report, a stable "
+        "``code``. Branch on ``code`` **when it is a string**; a list or object under "
+        "``code`` or ``detail`` is field validation of the field of that name, not the "
+        "envelope. ``detail`` is prose and may be reworded at any time. See the error "
+        "reference for the code vocabulary."
+    ),
+    "content": {
+        _JSON_MEDIA_TYPE: {
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "allOf": [_VALIDATION_ERROR_DETAIL_REF],
+                        "description": (
+                            "The refusal's human-readable explanation when the request "
+                            "was refused as a whole. A list or object here is instead "
+                            "the validation errors of a serializer field named "
+                            "``detail``."
+                        ),
+                        "example": "Request body must be a JSON object.",
+                    },
+                    "code": {
+                        "allOf": [_VALIDATION_ERROR_DETAIL_REF],
+                        "description": (
+                            "The refusal's stable machine code when the request was "
+                            "refused as a whole — a string, drawn from the vocabulary "
+                            "in the error reference. A list or object here is instead "
+                            "the validation errors of the serializer field named "
+                            "``code`` (``Program.code``, ``Project.code``)."
+                        ),
+                        "example": "invalid_body",
+                    },
+                },
+                "additionalProperties": _VALIDATION_ERROR_DETAIL_REF,
+            }
+        }
+    },
+}
+
+
+def validation_envelope_400(description: str) -> Any:
+    """Declare a 400 with a site-specific description and the shared error envelope.
+
+    The #3286 injection uses ``setdefault``, so an operation that declares its own 400
+    with a description only *replaces* the envelope body rather than refining it,
+    silently dropping the ``application/json`` schema every other 400 carries. Use this
+    where an endpoint wants its own wording but the standard ``detail``/``code``/
+    field-keyed body.
+    """
+    from drf_spectacular.utils import OpenApiResponse
+
+    return OpenApiResponse(
+        response=deepcopy(
+            cast("dict[str, Any]", _VALIDATION_RESPONSE["content"])[_JSON_MEDIA_TYPE]["schema"]
+        ),
+        description=description,
+    )
+
+
+# ---------------------------------------------------------------------------
+# #3319 — the 400 a BODYLESS write returns when it refuses on state
+# ---------------------------------------------------------------------------
+
+#: The three wire shapes a bodyless write's refusal actually takes.
+#:
+#: Which one an endpoint emits is decided by *how* it raises, not by intent, and
+#: the three are not interchangeable — a client that types the wrong one mis-reads
+#: every refusal that endpoint produces:
+#:
+#:   ``detail``    ``Response({"detail": ...}, status=400)`` or
+#:                 ``ValidationError({"detail": ...})`` — a JSON **object**.
+#:   ``messages``  ``ValidationError("a bare string")`` — DRF wraps a string detail
+#:                 in a list, so the body is a top-level JSON **array**, not an
+#:                 object. Easy to declare wrongly; verified per site.
+#:   ``fields``    ``ValidationError({"field": "..."})`` — DRF's field-keyed object,
+#:                 described by the recursive ``ValidationErrorDetail`` component.
+_STATE_REFUSAL_SHAPES: dict[str, dict[str, Any]] = {
+    "detail": {
+        "type": "object",
+        "properties": {"detail": {"type": "string"}},
+    },
+    "messages": {"type": "array", "items": {"type": "string"}},
+    "fields": {
+        "type": "object",
+        "additionalProperties": _VALIDATION_ERROR_DETAIL_REF,
+    },
+}
+
+
+def state_refusal_400(
+    description: str,
+    *,
+    shape: str = "detail",
+    codes: tuple[str, ...] = (),
+) -> Any:
+    """Declare the 400 a **bodyless** write returns when it refuses on state (#3319).
+
+    #3286 injects a 400 wherever an operation has a ``requestBody``, because
+    ``requestBody`` present is precisely the condition under which DRF can raise
+    ``ValidationError`` — a real equivalence the generator already computed. A
+    write that takes no body has no equivalent signal, and blanket-declaring a 400
+    across all of them would advertise a refusal most cannot produce: the same
+    defect as omitting one, pointing the other way. So every site opts in by hand,
+    having been checked against what the handler actually returns.
+
+    Args:
+        description: The state that makes *this* endpoint refuse. Site-specific by
+            design — a generic string would make the declaration decoration rather
+            than contract, which is the thing this issue exists to avoid.
+        shape: Which of :data:`_STATE_REFUSAL_SHAPES` reaches the wire. Read it off
+            the ``raise``/``Response`` in the handler, not off the neighbours.
+        codes: Stable ``code`` values the refusal really puts in the response
+            **body**. Pass one only where the handler writes it into a literal
+            response dict — a ``ValidationError(..., code=...)`` keyword never
+            reaches the client (#2550), so declaring that would invert this fix.
+
+    Returns:
+        The ``OpenApiResponse`` to hang off ``responses={400: ...}``.
+    """
+    from drf_spectacular.utils import OpenApiResponse
+
+    schema = deepcopy(_STATE_REFUSAL_SHAPES[shape])
+    if codes:
+        # Only reachable on the object shapes; a list body has nowhere to carry it.
+        schema["properties"]["code"] = {
+            "type": "string",
+            "enum": list(codes),
+            "description": "Stable refusal code — branch on this, not on ``detail``.",
+        }
+    return OpenApiResponse(response=schema, description=description)
+
+
+def ownership_refusal_403(description: str, *, codes: tuple[str, ...] = ()) -> Any:
+    """Declare the 403 an object-ownership guard returns (#3365).
+
+    Six guards used to refuse with ``ValidationError`` and so answered ``400`` for
+    what is an authorization decision — "you are not the author / uploader / a
+    role above the target", not "the thing you sent is malformed". A client
+    branching on status could not tell the two apart, and retrying with a
+    corrected body could never succeed because the body was never the problem.
+    They now raise ``PermissionDenied``, and this declares what reaches the wire
+    so a generated client has a typed branch for it.
+
+    Args:
+        description: Who is refused and why, for *this* endpoint. Site-specific
+            for the same reason :func:`state_refusal_400` insists on it — a
+            generic string is decoration, not contract.
+        codes: Stable ``code`` values the refusal really puts in the response
+            body. A guard emits one only by raising ``PermissionDenied`` with a
+            **dict** detail (``{"detail": ..., "code": ...}``) — DRF serializes a
+            dict detail key-for-key, whereas a ``code=`` keyword never leaves the
+            ``ErrorDetail`` object (#2550). Declare only what the handler writes.
+
+    Returns:
+        The ``OpenApiResponse`` to hang off ``responses={403: ...}``.
+    """
+    from drf_spectacular.utils import OpenApiResponse
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {"detail": {"type": "string"}},
+        "required": ["detail"],
+    }
+    if codes:
+        schema["properties"]["code"] = {
+            "type": "string",
+            "enum": list(codes),
+            "description": "Stable refusal code — branch on this, not on ``detail``.",
+        }
+        schema["required"].append("code")
+    return OpenApiResponse(response=schema, description=description)
+
+
+_THROTTLE_RESPONSE = {
+    "description": (
+        "Rate limit exceeded. The client is issuing requests faster than the "
+        "endpoint's throttle allows; retry after the interval in the "
+        "``Retry-After`` response header."
+    ),
+    "content": {
+        _JSON_MEDIA_TYPE: {
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "type": "string",
+                        "example": "Request was throttled. Expected available in 42 seconds.",
+                    }
+                },
+            }
+        }
+    },
+}
+
+
+class TruePPMAutoSchema(AutoSchema):
+    """AutoSchema that documents a ``429`` response on rate-limited operations, and
+    keeps the ``projectApiTokenAuth`` security scheme honest on MCP-readable views.
+
+    Throttling is a view attribute (``throttle_classes``) invisible to the final
+    schema dict, so 429 documentation has to happen here — where the generated
+    operation and its view are both in hand — rather than in a post-processing hook.
+    Only statically-declared ``throttle_classes`` are considered; that covers every
+    scoped/dedicated throttle in the codebase (login, refresh, ws-ticket,
+    user-search, credential rotation, Monte Carlo what-if, invite accept/resend,
+    resource catalog, Git webhook, inbound task-sync and acceptance-result reporting).
+    """
+
+    def get_auth(self) -> list[dict[str, Any]]:
+        """Drop ``projectApiTokenAuth`` from unsafe operations on MCP-readable views (#2659).
+
+        ``McpReadableViewMixin.get_authenticators`` prepends
+        ``ProjectApiTokenAuthentication`` at the *view* level (so a token is
+        recognized on every action), but drf-spectacular's default ``get_auth()``
+        reads ``view.get_authenticators()`` with no awareness of *which* method is
+        being documented — so it attached ``projectApiTokenAuth`` to every method on
+        the view, including the unsafe ones no credential unique to that scheme can
+        reach. That made the schema advertise 82 write operations
+        (POST/PUT/PATCH/DELETE) as project/program-token-writable when they are not.
+
+        The rule the filter describes changed shape in #2877 but not in outcome.
+        Before: ``TokenReadOnlyMethods`` refused *every* token an unsafe method on
+        these views. Now a ``legacy:full`` personal access token may write here — but
+        that credential is described by the **``personalApiTokenAuth``** scheme,
+        which these operations already advertise through the default authentication
+        stack. The credentials unique to ``projectApiTokenAuth`` are the project- and
+        program-scoped tokens, and those are still refused on this whole surface by
+        ``TokenIsOwnerScoped`` (401), so the scheme remains unreachable for an unsafe
+        method and must not be advertised. Both schemes are ``http bearer`` with the
+        same ``tppm_<64-hex>`` format, so a client reading the schema is told exactly
+        the header it needs.
+
+        This method and its view are the one place drf-spectacular hands both to the
+        same call, so the filter belongs here rather than in the mixin (which has no
+        reason to know about schema generation) or in a blanket post-processing hook
+        (which would also strip the scheme from ``TaskSyncView`` /
+        ``AcceptanceResultIngestView`` — two views that reference
+        ``ProjectApiTokenAuthentication`` directly to *accept* a token write, and
+        must keep advertising it).
+        """
+        auth = super().get_auth()
+        if self._mcp_scoped_token_write_unreachable():
+            auth = [entry for entry in auth if "projectApiTokenAuth" not in entry]
+        if self._token_callers_refused():
+            auth = [
+                entry
+                for entry in auth
+                if "projectApiTokenAuth" not in entry and "personalApiTokenAuth" not in entry
+            ]
+        return auth
+
+    def _token_callers_refused(self) -> bool:
+        """Whether this view refuses every API token outright (``IsNotTokenAuthenticated``).
+
+        The credential-management surface is session/JWT only since #2878, and SSO
+        provider configuration since #3551, so neither token scheme is reachable on any
+        of their operations and the schema must not advertise them — an integrator
+        reading it would otherwise write a script that cannot possibly work, against the
+        surfaces where the failure looks like a permissions bug rather than a deliberate
+        refusal.
+
+        Read off ``permission_classes`` rather than ``get_permissions()`` because schema
+        generation has no request to resolve per-action permissions against; every view
+        carrying the guard declares it statically, which is also what makes the
+        route-table tripwire in ``tests/apps/access/test_route_table_invariants.py``
+        sound.
+        """
+        from trueppm_api.apps.access.permissions import IsNotTokenAuthenticated
+
+        classes = getattr(self.view, "permission_classes", []) or []
+        return any(cls is IsNotTokenAuthenticated for cls in classes)
+
+    def _mcp_scoped_token_write_unreachable(self) -> bool:
+        """Whether this operation is an unsafe method on an ``McpReadableViewMixin`` view.
+
+        On such an operation the project/program-scoped credentials that
+        ``projectApiTokenAuth`` uniquely describes are refused by
+        ``TokenIsOwnerScoped``, which applies to every ``ApiToken`` on the MCP
+        surface regardless of scope and regardless of method — so the predicate
+        stays a plain "unsafe method on the mixin" and does not need to restate the
+        scope logic (#2877).
+        """
+        from trueppm_api.apps.access.permissions import McpReadableViewMixin
+
+        return isinstance(self.view, McpReadableViewMixin) and self.method not in SAFE_METHODS
+
+    def get_operation(
+        self,
+        path: str,
+        path_regex: str,
+        path_prefix: str,
+        method: str,
+        registry: Any,
+    ) -> dict[str, Any] | None:
+        operation = super().get_operation(path, path_regex, path_prefix, method, registry)
+        if operation is None:
+            return operation
+
+        throttle_classes = getattr(self.view, "throttle_classes", None)
+        if throttle_classes:
+            responses = operation.setdefault("responses", {})
+            responses.setdefault("429", dict(_THROTTLE_RESPONSE))
+        # A 400 is declarable exactly where there is a body to reject (#3286). The
+        # predicate is READ OFF the operation drf-spectacular just built rather than
+        # guessed from the view: `requestBody` is present precisely when the
+        # generator resolved a serializer or a raw-body declaration for this method,
+        # which is the same condition under which DRF can raise ValidationError. An
+        # unsafe method with no body — a POST action that works from the URL alone —
+        # gets nothing, because advertising a refusal an endpoint cannot produce is
+        # the same defect as omitting one it can, pointing the other way.
+        #
+        # `setdefault`, so an operation declaring its own richer 400 (the
+        # refusal-code enums in `refusal_codes.py`, say) keeps it.
+        if method not in SAFE_METHODS and "requestBody" in operation:
+            responses = operation.setdefault("responses", {})
+            responses.setdefault("400", dict(_VALIDATION_RESPONSE))
+        if self._token_callers_refused():
+            # Declared here rather than by decorating each view for the same reason as
+            # the 429 above: the fact lives in a view attribute the schema dict cannot
+            # see, and one injection point cannot drift from the permission class the
+            # way fifteen hand-written `@extend_schema` blocks would (#2878).
+            responses = operation.setdefault("responses", {})
+            responses.setdefault("403", dict(_TOKEN_REFUSED_RESPONSE))
+        return operation
+
+    def _get_paginator(self) -> Any:
+        """Return ``None`` for actions marked with :func:`suppress_list_pagination`.
+
+        drf-spectacular paginates a ``many=True`` response whenever the view has a
+        ``pagination_class``. An ``@action`` that returns a bare array opts out via
+        the marker so its schema is a plain array, not a pagination envelope
+        (#2127). Every other action falls through to the default behaviour.
+        """
+        action = getattr(self.view, "action", None)
+        if action:
+            handler = getattr(self.view, action, None)
+            if handler is not None and getattr(handler, _SUPPRESS_PAGINATION_ATTR, False):
+                return None
+        # drf-spectacular's AutoSchema is untyped; the base return is a paginator or None.
+        return super()._get_paginator()  # type: ignore[no-untyped-call]
+
+
+def undo_summary_schema(description: str, **counts: str) -> dict[str, Any]:
+    """Raw OpenAPI schema for the ``undo`` key a batch-undo action adds to its 200 (#3416).
+
+    All four undo actions build their body as ``data = serializer.data`` followed by
+    ``data["undo"] = summary``. Declaring the bare serializer as the ``200`` therefore
+    publishes a document missing the one value the endpoint exists to report — a
+    generated SDK has no ``undo`` field at all, so a typed client cannot read the
+    outcome of the call it just made. That is the #3399 trap pointed at a different
+    surface: the declaration is self-consistent, ``api:schema-drift`` passes on it,
+    and it is still false.
+
+    The counts differ per action (``deleted``/``kept`` for the two that remove rows,
+    ``reverted``/``kept`` for the cascade, five keys for the structural undo), so each
+    site passes its own. They are spelled out rather than left as an open
+    ``additionalProperties: {type: integer}`` map because the key set is closed and a
+    client branches on the individual names.
+
+    Args:
+        description: What this action's summary counts, in its own vocabulary.
+        **counts: ``field_name="what it counts"`` for every key the summary carries.
+
+    Returns:
+        A schema dict to hang off ``@extend_schema_field`` on the wrapper's field.
+    """
+    return {
+        "type": "object",
+        "description": description,
+        "properties": {
+            name: {"type": "integer", "minimum": 0, "description": text}
+            for name, text in counts.items()
+        },
+        "required": list(counts),
+        "additionalProperties": False,
+    }