state-hub/api/routers/suggestions.py

"""Retired: the suggestion backlog.

Slice E1 of the State Hub retirement (`STATE-WP-0079-T05`). The capability was
superseded by the **intake** work-record entity; mutations were retired
2026-07-21 under `CUST-WP-0061-T06`, and the reads were kept live only so the
historical record stayed reachable.

That history is now archived at
`the-custodian/docs/archived-suggestion-backlog.md` — all 10 suggestions, 10
notes and 5 relevance bumps, every one closed as `declined` during the intake
migration and none promoted. With a durable record outside this repo, the read
surface has no remaining job, so the whole router answers 410.

The `suggestions`, `suggestion_notes` and `suggestion_relevance_bumps` tables
are deliberately left in place: they are `retire`/`archive` in `SHR-INV-0001`
and are captured by the final dump at `STATE-WP-0079-T06`. Dropping them here
would remove data ahead of the dump for no gain.
"""

from fastapi import APIRouter, HTTPException

router = APIRouter(prefix="/suggestions", tags=["suggestions"])

_DETAIL = (
    "suggestions are retired (STATE-WP-0079-T05, slice E1). "
    "Use POST /intakes/ for new discovery work. The historical backlog is "
    "archived at the-custodian/docs/archived-suggestion-backlog.md — see also "
    "the-custodian/intake-legacy-suggestions-migration.md and "
    "canon/standards/work-record-types_v0.1.md."
)


def _retired() -> HTTPException:
    return HTTPException(status_code=410, detail=_DETAIL)


@router.api_route(
    "/{path:path}",
    methods=["GET", "POST", "PATCH", "PUT", "DELETE"],
    include_in_schema=False,
)
@router.api_route("/", methods=["GET", "POST", "PATCH", "PUT", "DELETE"])
async def suggestions_retired(path: str = "") -> None:
    """Every suggestion route is retired; see module docstring."""
    raise _retired()