"""Generate and post-process the omnigent OpenAPI 3.2 document.

The omnigent server runs on FastAPI 0.135.x, which emits OpenAPI
3.1. OpenAPI 3.2 (released September 2025) introduced first-class
support for sequential media types — specifically, the
``itemSchema`` keyword for describing each item in a streaming
response on a ``text/event-stream`` content entry. We need 3.2's
``itemSchema`` so the SSE routes describe their per-event shape
correctly to consuming SDK / docs tooling.

This script:

1. Imports :func:`omnigent.server.app.create_app` and instantiates
   it against in-memory store stubs (no DB needed).
2. Calls ``app.openapi()`` to get the FastAPI-generated 3.1 dict.
3. Bumps the top-level ``openapi`` field to ``"3.2.0"``.
4. Materializes the :data:`ServerStreamEvent` discriminated union as
   a top-level entry under ``components.schemas`` so SSE responses
   can ``$ref`` it.
5. Rewrites the ``text/event-stream`` content entries on the SSE
   routes to use the OAS 3.2 ``itemSchema`` keyword in place of
   FastAPI's 3.1 ``schema`` keyword.
6. Writes the result to ``openapi.json`` at the repo root.

Run with no arguments to (re)generate the file. Pass ``--check``
in CI to verify the on-disk file is up to date — non-zero exit
means a developer changed the spec without regenerating.

Usage::

    python scripts/dump_openapi.py             # write openapi.json
    python scripts/dump_openapi.py --check     # exit 1 if drifted
"""

from __future__ import annotations

import argparse
import hashlib
import json
import re
import sys
from pathlib import Path
from typing import Any

# DBOS's ``compute_app_version`` calls ``hashlib.md5()`` without
# ``usedforsecurity=False`` for a non-security content hash, which
# raises ``ValueError`` on FIPS-enabled hosts. Patch md5 here BEFORE
# any DBOS import so both this script and the drift test
# (``tests/server/test_openapi_drift.py``, which imports
# ``generate_spec`` from this module) work on FIPS hosts. The flag is
# the standard Python 3.9+ way to opt non-security md5 calls out of
# the FIPS gate; on non-FIPS hosts it's a harmless no-op.
_orig_md5 = hashlib.md5


def _fips_safe_md5(*args: Any, **kwargs: Any) -> Any:
    kwargs.setdefault("usedforsecurity", False)
    return _orig_md5(*args, **kwargs)


hashlib.md5 = _fips_safe_md5

from pydantic import TypeAdapter  # noqa: E402 — must follow md5 patch

# ── Module-level constants (rule 34) ──────────────────────────────

# Output path. The spec lives at the repo root so external tooling
# (Stoplight, openapi-generator, redocly, …) can pick it up via a
# stable URL relative to the project. Pinned absolute via
# ``Path(__file__).resolve().parent.parent`` so the script works
# regardless of CWD.
_REPO_ROOT: Path = Path(__file__).resolve().parent.parent
_OPENAPI_OUT: Path = _REPO_ROOT / "openapi.json"
if str(_REPO_ROOT) not in sys.path:
    sys.path.insert(0, str(_REPO_ROOT))

# OpenAPI 3.2.0 release: 2025-09-23. We pin the patch version so
# the post-processed doc declares its target spec unambiguously.
_OPENAPI_VERSION: str = "3.2.0"

# Routes that emit Server-Sent Events. Each tuple is
# ``(path, method)`` keyed exactly as the OpenAPI ``paths`` map
# stores them. If the route inventory grows (e.g. a new SSE
# endpoint), add the entry here so post-processing rewrites it.
_SSE_ROUTES: list[tuple[str, str]] = [
    ("/v1/responses", "post"),
    ("/v1/sessions/{session_id}/stream", "get"),
]

# ── Document-level enrichment ─────────────────────────────────────
#
# FastAPI emits accurate per-operation schemas but none of the
# document-level metadata an integrator needs: no ``servers``, no auth
# description, no ``info.description``, and only bare snake_case tags.
# We inject that connective tissue here so the published reference
# (rendered by Scalar on the omnigent website) is usable for building
# an integration. Keeping it in this script — rather than scattering it
# across the route decorators — confines presentation concerns to the
# spec-generation layer, and the drift test
# (``tests/server/test_openapi_drift.py``) guards the result.

# Self-hosted base URL. ``omnigent server`` binds 127.0.0.1:6767 by
# default (see ``_DEFAULT_LOCAL_PORT`` in
# ``omnigent/host/local_server.py``).
_SERVERS: list[dict[str, str]] = [
    {
        "url": "http://127.0.0.1:6767",
        "description": "Self-hosted Omnigent server (default local port).",
    },
]

# Markdown prose shown at the top of the rendered reference. Covers
# what the API is, the self-hosted base URL, and the deployment-driven
# auth model (there is no bearer/API-key scheme — see
# ``omnigent/server/auth.py``).
_INFO_DESCRIPTION: str = """\
Omnigent is an open-source meta-harness for building and running AI \
agents. This is the REST API exposed by the Omnigent server: use it to \
create and drive **sessions**, manage **agents**, **hosts**, and \
**runners**, attach **contextual policies**, post **comments**, and work \
with session **resources** — files, terminals, and sandboxed \
environments.

## Base URL

Omnigent is self-hosted. The server binds `http://127.0.0.1:6767` by \
default (`omnigent server`); point the base URL at your own deployment.

## Authentication

There is no API-key or bearer-token scheme. Identity is supplied by the \
deployment's configured auth provider (`OMNIGENT_AUTH_PROVIDER`):

- **Trusted proxy header** (default) — an upstream proxy injects an \
identity header (`X-Forwarded-Email`, configurable). Single-user local \
runtimes fall back to a reserved `local` user.
- **Session cookie** — a signed session cookie minted after an \
interactive OIDC or accounts login. It is named `ap_session` over HTTP \
(the advertised local default) and `__Host-ap_session` under HTTPS, where \
the `__Host-` prefix guards against subdomain cookie-tossing.

Auth is configured server-side; clients send the cookie or proxy header \
according to your deployment.

## Streaming

`GET /v1/sessions/{session_id}/stream` streams Server-Sent Events \
(`text/event-stream`). Each event conforms to the `ServerStreamEvent` \
schema documented below.
"""

# Auth representations. Omnigent has no bearer/API-key scheme — identity
# arrives via a trusted-proxy header or a signed session cookie,
# selected by ``OMNIGENT_AUTH_PROVIDER``. We model both as OpenAPI
# ``apiKey`` schemes so SDK generators and the reference can surface
# them. We deliberately do NOT assert a top-level ``security``
# requirement: the active scheme is deployment-specific, and public
# endpoints (``/health``, ``/api/version``) require none — the prose in
# :data:`_INFO_DESCRIPTION` carries the human-facing explanation.
_SECURITY_SCHEMES: dict[str, dict[str, str]] = {
    "proxyHeaderAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Forwarded-Email",
        "description": (
            "Trusted-proxy identity header (header-auth mode, the "
            "default). The header name is configurable via "
            "``OMNIGENT_AUTH_HEADER``."
        ),
    },
    "sessionCookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        # Named to match the advertised HTTP server. The ``__Host-``
        # prefix requires HTTPS (browsers drop it on plain HTTP), so the
        # cookie is ``ap_session`` for the default local deployment and
        # ``__Host-ap_session`` only under HTTPS — see ``secure_cookies``
        # in ``accounts_config.py`` / ``oidc.py``.
        "name": "ap_session",
        "description": (
            "Signed session cookie minted after an interactive OIDC or "
            "accounts login (oidc / accounts auth modes). Named "
            "``ap_session`` over HTTP (the advertised local default); "
            "under HTTPS the secure ``__Host-ap_session`` prefixed form "
            "is used instead."
        ),
    },
}

# Tag display metadata: human descriptions + sidebar order. Each
# ``name`` MUST match the tag FastAPI puts on operations (the route
# decorators use these snake_case values). ``x-displayName`` gives docs
# tooling a readable label in place of the raw tag. Order here is the
# order tags render in the reference sidebar.
#
# This intentionally covers only the stub-build surface that
# ``generate_spec()`` emits: the ``terminals`` router is WebSocket-only
# (no HTTP operations in the spec) and the ``auth`` router is mounted
# only when an auth provider with a ``login_url`` is configured (absent
# in the stub build). If either ever surfaces HTTP operations here, add
# its tag below so the operation doesn't render without a description.
_TAGS: list[dict[str, str]] = [
    {
        "name": "sessions",
        "x-displayName": "Sessions",
        "description": (
            "Create, inspect, fork, and drive agent sessions — the core "
            "unit of work. Covers session items and events, agent "
            "binding, permissions, labels, and child sessions. The "
            "files, terminals, and sandboxed environments attached to a "
            "session live under Session Resources."
        ),
    },
    {
        "name": "session_resources",
        "x-displayName": "Session Resources",
        "description": (
            "Files, terminals, and sandboxed environments attached to a "
            "session: upload and read files, create and manage "
            "terminals, and read, write, edit, and search the "
            "environment filesystem."
        ),
    },
    {
        "name": "session_mcp_servers",
        "x-displayName": "Session MCP Servers",
        "description": (
            "Manage the MCP server declarations on a session's bound "
            "agent: list the configured servers and create, update, and "
            "remove them on session-scoped agents."
        ),
    },
    {
        "name": "agents",
        "x-displayName": "Agents",
        "description": "Discover the built-in agents available to bind to a session.",
    },
    {
        "name": "hosts",
        "x-displayName": "Hosts",
        "description": (
            "Hosts that can launch runners. Browse the host filesystem and create directories."
        ),
    },
    {
        "name": "runners",
        "x-displayName": "Runners",
        "description": "Launch runners on a host and check their status.",
    },
    {
        "name": "session_policies",
        "x-displayName": "Session Policies",
        "description": (
            "Contextual policies scoped to a single session — list, create, update, and remove."
        ),
    },
    {
        "name": "default_policies",
        "x-displayName": "Default Policies",
        "description": "Server-level default policies applied to new sessions.",
    },
    {
        "name": "policy_registry",
        "x-displayName": "Policy Registry",
        "description": "The catalog of policy types available to instantiate.",
    },
    {
        "name": "comments",
        "x-displayName": "Comments",
        "description": (
            "Threaded comments on a session, including sending a comment to the agent."
        ),
    },
    {
        "name": "system",
        "x-displayName": "System",
        "description": "Health, version, and identity endpoints for the running server.",
    },
]

# Utility endpoints FastAPI leaves untagged. We assign them a synthetic
# ``system`` tag so they group cleanly in the reference instead of
# floating in an unlabeled "default" bucket. Keyed ``(path, method)``
# like :data:`_SSE_ROUTES`; keep accurate if the route inventory grows.
_SYSTEM_ROUTES: list[tuple[str, str]] = [
    ("/health", "get"),
    ("/api/version", "get"),
    ("/v1/info", "get"),
    ("/v1/me", "get"),
]

# HTTP methods that denote an operation object inside a path item
# (everything else under a path — ``parameters``, ``servers``, … — is
# not an operation and must be skipped when retagging).
_HTTP_METHODS: frozenset[str] = frozenset(
    {"get", "put", "post", "delete", "patch", "options", "head", "trace"},
)

# Path prefix whose operations form the dedicated "Session Resources"
# group. The sessions router is mounted with ``tags=["sessions"]`` in
# app.py, so every session route — including the resource subtree —
# inherits that single tag. We split this subtree (files, terminals,
# sandboxed environments) into its own section in the published
# reference rather than fracturing the router.
_SESSION_RESOURCES_PREFIX: str = "/v1/sessions/{session_id}/resources"


def _build_app_with_stub_stores() -> Any:
    """
    Build a FastAPI app with stub stores sufficient for OpenAPI generation.

    ``app.openapi()`` walks the route table and Pydantic models — it
    does not call any store methods. We use the SQLite-backed
    implementations against an on-disk temporary database. The temp
    file is best-effort cleaned up by the caller's filesystem.

    :returns: A configured :class:`fastapi.FastAPI` app.
    """
    import tempfile

    from omnigent.runtime.agent_cache import AgentCache
    from omnigent.server.app import create_app
    from omnigent.stores.agent_store.sqlalchemy_store import SqlAlchemyAgentStore
    from omnigent.stores.artifact_store.local import LocalArtifactStore
    from omnigent.stores.comment_store.sqlalchemy_store import SqlAlchemyCommentStore
    from omnigent.stores.conversation_store.sqlalchemy_store import (
        SqlAlchemyConversationStore,
    )
    from omnigent.stores.file_store.sqlalchemy_store import SqlAlchemyFileStore
    from omnigent.stores.host_store import HostStore
    from omnigent.stores.policy_store.sqlalchemy_store import SqlAlchemyPolicyStore

    # On-disk SQLite (mkdtemp ensures uniqueness so concurrent
    # invocations don't collide).
    workdir = Path(tempfile.mkdtemp(prefix="oa-openapi-"))
    db_path = workdir / "spec.sqlite"
    db_uri = f"sqlite:///{db_path}"
    artifact_store = LocalArtifactStore(str(workdir / "artifacts"))
    return create_app(
        agent_store=SqlAlchemyAgentStore(db_uri),
        file_store=SqlAlchemyFileStore(db_uri),
        conversation_store=SqlAlchemyConversationStore(db_uri),
        comment_store=SqlAlchemyCommentStore(db_uri),
        artifact_store=artifact_store,
        agent_cache=AgentCache(
            artifact_store=artifact_store,
            cache_dir=workdir / "cache",
        ),
        # Pass stores so conditionally-mounted routes stay in the spec.
        host_store=HostStore(db_uri),
        policy_store=SqlAlchemyPolicyStore(db_uri),
    )


def _server_stream_event_schema() -> dict[str, Any]:
    """
    Return the JSON-Schema dict for the ``ServerStreamEvent`` union.

    Pydantic's ``TypeAdapter.json_schema(ref_template=...)`` emits a
    schema with internal ``$ref`` pointers in OpenAPI's expected
    ``#/components/schemas/<name>`` form. We then split out the
    union-root schema and inline the variant definitions into the
    components map so each per-event class appears as a top-level
    component schema.

    :returns: A dict with two keys:

        * ``"root"`` — the discriminated-union schema (the value
          assigned to ``components.schemas.ServerStreamEvent``).
        * ``"definitions"`` — the per-variant component schemas
          (merged into ``components.schemas``).
    """
    from omnigent.server.schemas import ServerStreamEvent

    adapter: TypeAdapter[ServerStreamEvent] = TypeAdapter(ServerStreamEvent)
    schema = adapter.json_schema(ref_template="#/components/schemas/{model}")
    # Pydantic returns ``{"oneOf": [...], "discriminator": {...},
    # "$defs": {...}}``. We hoist ``$defs`` to top-level component
    # schemas and keep the rest as the union root.
    definitions = schema.pop("$defs", {})
    return {"root": schema, "definitions": definitions}


def _rewrite_sse_route(
    paths: dict[str, Any],
    path: str,
    method: str,
) -> None:
    """
    Rewrite one SSE route's ``text/event-stream`` content for OAS 3.2.

    FastAPI emits ``content: {text/event-stream: {schema: <ref>}}``;
    OAS 3.2 uses ``itemSchema`` for sequential media types so each
    event in the stream is described as one item. We rename the key.

    No-op if the route doesn't exist (e.g. a renamed endpoint that
    fell off the inventory) — the caller's job is to keep
    :data:`_SSE_ROUTES` accurate.

    :param paths: The OpenAPI ``paths`` map; mutated in place.
    :param path: Route path, e.g. ``"/v1/responses"``.
    :param method: HTTP method (lowercase), e.g. ``"post"``.
    """
    op = paths.get(path, {}).get(method)
    if op is None:
        return
    ok_response = op.get("responses", {}).get("200", {})
    content = ok_response.get("content", {})
    sse_entry = content.get("text/event-stream")
    if sse_entry is None:
        return
    # Rename ``schema`` → ``itemSchema``. The value (a ``$ref``) is
    # untouched because the union schema applies to each event
    # equally — itemSchema is "validate this against every item
    # in the stream" per the 3.2 spec.
    if "schema" in sse_entry:
        sse_entry["itemSchema"] = sse_entry.pop("schema")


def _tag_system_routes(paths: dict[str, Any]) -> None:
    """
    Assign the synthetic ``system`` tag to untagged utility routes.

    FastAPI leaves ``/health``, ``/api/version``, ``/v1/info``, and
    ``/v1/me`` untagged. Without a tag they render in an unlabeled
    "default" bucket in the reference; tagging them groups the lot
    under "System". Only fills in a tag where none exists — never
    overrides one FastAPI already set.

    No-op for any ``(path, method)`` not present, so
    :data:`_SYSTEM_ROUTES` stays resilient to inventory changes.

    :param paths: The OpenAPI ``paths`` map; mutated in place.
    """
    for path, method in _SYSTEM_ROUTES:
        op = paths.get(path, {}).get(method)
        if op is None:
            continue
        if not op.get("tags"):
            op["tags"] = ["system"]


def _retag_session_resources(paths: dict[str, Any]) -> None:
    """
    Move the session-resource subtree into its own ``session_resources`` tag.

    Every operation whose path starts with
    :data:`_SESSION_RESOURCES_PREFIX` has its tag list *replaced* (not
    appended) with ``["session_resources"]`` so it renders as a
    dedicated section instead of inheriting the broad ``sessions`` tag.
    Prefix-based so newly added resource endpoints group automatically.

    :param paths: The OpenAPI ``paths`` map; mutated in place.
    """
    for path, methods in paths.items():
        if not path.startswith(_SESSION_RESOURCES_PREFIX):
            continue
        for method, op in methods.items():
            if method in _HTTP_METHODS and isinstance(op, dict):
                op["tags"] = ["session_resources"]


# ── reStructuredText docstring → Markdown ─────────────────────────
#
# FastAPI uses each route handler's docstring verbatim as the OpenAPI
# operation ``description``. Our docstrings are Sphinx/reST: ``:param
# name:`` / ``:returns:`` / ``:raises Exc:`` field lists and inline
# ``:class:`Foo``` cross-reference roles. Docs renderers (Scalar) treat
# the description as Markdown, so reST field lists collapse into one
# unreadable run of literal text. We convert that markup to Markdown:
#
#   * each ``:param name:`` whose name matches a real query/path
#     parameter is moved onto that parameter's ``description`` (so it
#     renders inline in the parameter table, not in the prose blob);
#   * request-body / form ``:param`` entries that have no matching
#     parameter become a Markdown ``**Parameters**`` bullet list;
#   * ``:returns:`` becomes a ``**Returns:**`` line, ``:raises:`` a
#     ``**Raises**`` bullet list;
#   * framework-internal params (``request``/``response``/…) are dropped;
#   * inline ``:role:`X``` roles collapse to `` `X` `` and reST double
#     backticks (`` ``X`` ``) normalize to Markdown single backticks.

# Field-list line markers (matched at column 0; continuation lines are
# indented and accumulate onto the field opened above them).
_RST_PARAM = re.compile(r"^:(?:param|parameter|arg|argument|keyword|kwarg)\s+(\S+)\s*:\s*(.*)$")
_RST_RETURNS = re.compile(r"^:returns?\s*:\s*(.*)$")
_RST_RAISES = re.compile(r"^:raises?\s+([^:]+?)\s*:\s*(.*)$")
# Any other reST field marker (``:rtype:``, ``:type x:``, …) — dropped.
_RST_OTHER_FIELD = re.compile(r"^:[a-zA-Z][\w ]*:")
# Inline cross-reference role, e.g. ``:class:`Foo``` → `` `Foo` ``.
_RST_ROLE = re.compile(r":[a-zA-Z]+:`([^`]+)`")
# reST inline literal (double backtick) → Markdown code span (single).
# Non-greedy + DOTALL so a literal may span lines and contain nested
# single backticks (e.g. a role left inside it); the replacement flattens
# those so the resulting code span is valid.
_RST_DOUBLE_BACKTICK = re.compile(r"``(.+?)``", re.DOTALL)

# Handler parameters that are FastAPI plumbing, not API inputs.
_INTERNAL_PARAMS = frozenset(
    {"request", "response", "websocket", "ws", "background_tasks", "bg", "_", "args", "kwargs"},
)


def _rst_double_backtick_to_code(match: re.Match[str]) -> str:
    """Flatten a reST ``literal`` into a single-line Markdown code span."""
    inner = re.sub(r"\s+", " ", match.group(1).replace("`", "")).strip()
    return f"`{inner}`"


def _rst_inline_to_md(text: str) -> str:
    """Convert inline reST roles / literals in *text* to Markdown."""
    text = _RST_ROLE.sub(r"`\1`", text)
    return _RST_DOUBLE_BACKTICK.sub(_rst_double_backtick_to_code, text)


def _rst_field_text(lines: list[str]) -> str:
    """Join a field's (possibly multi-line) body into one Markdown string."""
    joined = re.sub(r"\s+", " ", " ".join(lines)).strip()
    return _rst_inline_to_md(joined)


def _parse_rst_doc(desc: str) -> tuple[str, list[tuple[str, str | None, str]]]:
    """
    Split a reST docstring into Markdown prose and parsed fields.

    Lines before the first reST field marker are prose; ``:param:`` /
    ``:returns:`` / ``:raises:`` open a field that subsequent indented
    continuation lines accumulate onto. Unknown field markers (e.g.
    ``:rtype:``) are discarded.

    :param desc: The raw (reST) description text.
    :returns: ``(prose_markdown, fields)`` where ``fields`` is a list of
        ``(kind, name, text)`` triples (``kind`` in ``param`` /
        ``returns`` / ``raises``) with ``text`` already Markdown.
    """
    prose: list[str] = []
    fields: list[tuple[str, str | None, list[str]]] = []
    cur: tuple[str, str | None, list[str]] | None = None
    in_fields = False
    for line in desc.split("\n"):
        param_m = _RST_PARAM.match(line)
        if param_m:
            in_fields = True
            cur = ("param", param_m.group(1).strip().lstrip("*"), [param_m.group(2)])
            fields.append(cur)
            continue
        returns_m = _RST_RETURNS.match(line)
        if returns_m:
            in_fields = True
            cur = ("returns", None, [returns_m.group(1)])
            fields.append(cur)
            continue
        raises_m = _RST_RAISES.match(line)
        if raises_m:
            in_fields = True
            cur = ("raises", raises_m.group(1).strip(), [raises_m.group(2)])
            fields.append(cur)
            continue
        if in_fields and _RST_OTHER_FIELD.match(line):
            cur = ("drop", None, [])  # unknown field (e.g. :rtype:) — discard
            fields.append(cur)
            continue
        if in_fields:
            if cur is not None:
                cur[2].append(line)
        else:
            prose.append(line)

    prose_md = _rst_inline_to_md("\n".join(prose).strip())
    parsed = [(kind, name, _rst_field_text(body)) for kind, name, body in fields if kind != "drop"]
    return prose_md, parsed


def _reformat_doc(
    desc: str | None,
    targets: dict[str, Any],
    internal: frozenset[str] | None = None,
) -> str | None:
    """
    Convert one reST ``description`` to Markdown.

    Each ``:param name:`` whose ``name`` is a key in *targets* (a
    parameter or property object) is moved onto that object's own
    ``description``; entries with no matching target become a Markdown
    ``**Parameters**`` list. ``:returns:`` / ``:raises:`` become
    ``**Returns:**`` / ``**Raises**`` sections. Names in *internal*
    (FastAPI plumbing) are dropped.

    :param desc: The raw description, or ``None``.
    :param targets: Map of name -> object that may receive a moved
        ``description`` (empty when there are no field targets).
    :param internal: Parameter names to drop entirely (``None`` = drop
        none, used for schema fields).
    :returns: The rebuilt Markdown description, or the original falsy
        value when *desc* is empty.
    """
    if not desc:
        return desc
    skip = internal or frozenset()
    prose_md, fields = _parse_rst_doc(desc)
    body_params: list[tuple[str, str]] = []
    raises: list[tuple[str, str]] = []
    returns: str | None = None
    for kind, name, text in fields:
        if kind == "param":
            if not text or name in skip:
                continue
            target = targets.get(name) if name else None
            if isinstance(target, dict):
                # Move onto the matching field; don't clobber an explicit
                # Field/Query description if one already exists.
                if not target.get("description"):
                    target["description"] = text
            else:
                body_params.append((name or "", text))
        elif kind == "raises" and text:
            raises.append((name or "", text))
        elif kind == "returns" and text:
            returns = text

    sections: list[str] = []
    if prose_md:
        sections.append(prose_md)
    if body_params:
        sections.append("**Parameters**\n\n" + "\n".join(f"- `{n}` — {t}" for n, t in body_params))
    if returns:
        sections.append(f"**Returns:** {returns}")
    if raises:
        sections.append("**Raises**\n\n" + "\n".join(f"- `{e}` — {t}" for e, t in raises))
    return "\n\n".join(sections)


def _reformat_operation_doc(op: dict[str, Any]) -> None:
    """
    Rewrite an operation's (and its responses') reST docs as Markdown.

    Matched ``:param:`` entries move onto ``op['parameters']``; response
    descriptions are reformatted with no field targets.

    :param op: An OpenAPI operation object; mutated in place.
    """
    if op.get("description"):
        targets = {p.get("name"): p for p in op.get("parameters", []) if isinstance(p, dict)}
        op["description"] = _reformat_doc(op["description"], targets, _INTERNAL_PARAMS)
    for resp in (op.get("responses") or {}).values():
        if isinstance(resp, dict) and resp.get("description"):
            resp["description"] = _reformat_doc(resp["description"], {})


def _reformat_schema_node(node: Any) -> None:
    """
    Rewrite a JSON-Schema node's reST ``description`` as Markdown.

    A model's docstring becomes its schema ``description`` with
    ``:param name:`` entries describing its fields; each moves onto the
    matching ``properties[name]`` description. Recurses into nested
    schema positions so inline sub-objects are handled too.

    :param node: A JSON-Schema object (non-dicts are ignored); mutated
        in place.
    """
    if not isinstance(node, dict):
        return
    if node.get("description"):
        props = node.get("properties")
        node["description"] = _reformat_doc(
            node["description"],
            props if isinstance(props, dict) else {},
        )
    properties = node.get("properties")
    if isinstance(properties, dict):
        for sub in properties.values():
            _reformat_schema_node(sub)
    for defs_key in ("$defs", "definitions"):
        defs = node.get(defs_key)
        if isinstance(defs, dict):
            for sub in defs.values():
                _reformat_schema_node(sub)
    for child_key in ("items", "additionalProperties"):
        _reformat_schema_node(node.get(child_key))
    for combinator in ("allOf", "anyOf", "oneOf", "prefixItems"):
        members = node.get(combinator)
        if isinstance(members, list):
            for sub in members:
                _reformat_schema_node(sub)


def _reformat_descriptions(paths: dict[str, Any]) -> None:
    """Convert every operation's reST description to Markdown in place."""
    for methods in paths.values():
        for method, op in methods.items():
            if method in _HTTP_METHODS and isinstance(op, dict):
                _reformat_operation_doc(op)


def _reformat_component_schemas(components: dict[str, Any]) -> None:
    """Convert every component schema's reST description to Markdown."""
    schemas = components.get("schemas")
    if isinstance(schemas, dict):
        for schema in schemas.values():
            _reformat_schema_node(schema)


def _normalize_inline_descriptions(node: Any) -> None:
    """
    Final safety net: normalize inline reST in any remaining description.

    Walks the whole document and converts inline ``:role:`X``` roles and
    reST double-backtick literals to Markdown `` `X` `` in every
    ``description`` string — covering responses, ``info``, tags and
    security schemes that the structured passes don't rewrite.

    :param node: Any spec fragment; mutated in place.
    """
    if isinstance(node, dict):
        for key, value in node.items():
            if key == "description" and isinstance(value, str):
                node[key] = _rst_inline_to_md(value)
            else:
                _normalize_inline_descriptions(value)
    elif isinstance(node, list):
        for value in node:
            _normalize_inline_descriptions(value)


def _enrich_spec(spec: dict[str, Any]) -> None:
    """
    Inject document-level metadata for docs / SDK tooling.

    Adds ``info.description``, ``servers``, top-level ``tags`` with
    human-readable descriptions, and ``components.securitySchemes`` —
    none of which FastAPI emits — tags the untagged utility routes, and
    rewrites reST docstrings (operations, parameters, and component
    schemas) as Markdown.
    Mutates ``spec`` in place. See the module-level enrichment
    constants for the rationale behind each value.

    :param spec: The generated OpenAPI dict; mutated in place.
    """
    info = spec.setdefault("info", {})
    info["description"] = _INFO_DESCRIPTION
    spec["servers"] = _SERVERS
    spec["tags"] = _TAGS

    components = spec.setdefault("components", {})
    components["securitySchemes"] = _SECURITY_SCHEMES

    paths = spec.setdefault("paths", {})
    _tag_system_routes(paths)
    _retag_session_resources(paths)
    _reformat_descriptions(paths)
    _reformat_component_schemas(components)
    _normalize_inline_descriptions(spec)


def generate_spec() -> dict[str, Any]:
    """
    Build, generate, and post-process the OpenAPI 3.2 spec.

    Encapsulates every step (app construction, generation, version
    bump, schema injection, SSE rewrite) so callers can compare the
    generated dict against ``openapi.json`` without writing to disk.

    :returns: The post-processed OpenAPI dict, ready to serialize.
    """
    app = _build_app_with_stub_stores()
    spec = app.openapi()
    # Bump the OpenAPI version literal — we don't change any
    # 3.1-only constructs because FastAPI's emitted shape is also
    # valid 3.2.x (3.2 is JSON-Schema-aligned and largely additive
    # over 3.1).
    spec["openapi"] = _OPENAPI_VERSION

    # Inject the ServerStreamEvent union + per-variant defs into
    # ``components.schemas`` so the SSE routes' $ref points resolve.
    components = spec.setdefault("components", {})
    schemas = components.setdefault("schemas", {})
    union = _server_stream_event_schema()
    schemas["ServerStreamEvent"] = union["root"]
    for name, definition in union["definitions"].items():
        # Don't clobber a same-named schema FastAPI already
        # synthesized — the union's per-variant defs include
        # ``ResponseObject`` (referenced from terminal events), and
        # FastAPI also emits one. Keep FastAPI's version; the
        # serialized shape is identical for our models.
        schemas.setdefault(name, definition)

    # Rewrite SSE routes' content entries to use ``itemSchema``.
    paths = spec.get("paths", {})
    for path, method in _SSE_ROUTES:
        _rewrite_sse_route(paths, path, method)

    # Inject document-level metadata (servers, auth, tags, prose) that
    # FastAPI doesn't emit but docs / SDK tooling needs.
    _enrich_spec(spec)

    return spec  # type: ignore[no-any-return]


def main() -> int:
    """
    CLI entry point.

    With no arguments, regenerates ``openapi.json``. With
    ``--check``, compares the generated spec to the on-disk file
    and exits 1 if they differ.

    :returns: 0 on success / no drift, 1 on drift in ``--check``
        mode.
    """
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--check",
        action="store_true",
        help=(
            "CI mode — exit 1 if the on-disk openapi.json differs from "
            "the generated spec. Use to fail PRs that change the spec "
            "without regenerating."
        ),
    )
    args = parser.parse_args()

    spec = generate_spec()
    serialized = json.dumps(spec, indent=2, sort_keys=True) + "\n"

    if args.check:
        if not _OPENAPI_OUT.exists():
            sys.stderr.write(
                f"openapi.json not found at {_OPENAPI_OUT}; "
                "run `python scripts/dump_openapi.py` to generate it.\n",
            )
            return 1
        existing = _OPENAPI_OUT.read_text()
        if existing != serialized:
            sys.stderr.write(
                "openapi.json is out of sync with the generated spec.\n"
                "Run `python scripts/dump_openapi.py` to regenerate.\n",
            )
            return 1
        sys.stdout.write("openapi.json is up to date.\n")
        return 0

    _OPENAPI_OUT.write_text(serialized)
    sys.stdout.write(f"Wrote {_OPENAPI_OUT}\n")
    return 0


if __name__ == "__main__":
    sys.exit(main())