feat(api): publish retirement in the contract, the capability read, and the coverage guard

Three surfaces, one source. The registry the proxy answers 410 from now
also emits the tombstones into `docs/api/openapi.yaml` and rides on
`GET /api/meta/capabilities`, so a retirement cannot be honoured at
runtime and invisible everywhere a client could have read it first.

The contract publishes each retired path with 410 as its only response,
the removing version, and the replacement. `deprecated: true` is
imprecise — the word means "still works, stop using it", and these do not
work — but it is what makes a generator warn at the call site, and the
description carries the exact truth the flag approximates. `security: []`
because the answer is produced before any handler and reads no
credential; publishing it as authenticated would tell a client to sign in
to be told a path is gone.

The capability read carries the same list. That surface is the one a
client already polls on launch, so a retirement can reach it before the
failing call rather than through it.

The coverage guard gains a third state. Published and exempted both
describe a route that exists, so removing one used to leave exactly one
legal move — erase it from the contract as well — and that move is
invisible to every client already calling it. A registered path is now
required to be absent from `src/app` AND present in the contract, which
is the one combination the phantom-path case rejected outright. Both ways
out are named in the failure message.

Its docblock says what the state cannot do, because the first draft
overclaimed: a check over one commit's state cannot see a deletion, so it
cannot insist that a removal should have been registered. Proving that
needs the previous release tag, and the job running this suite checks out
at depth one with no tags, which would make the check one that silently
cannot fail. What is held instead is the registration's integrity, in
three directions and with the mutation for each written down.

The sharing-denial guard learns the same state: a retired path resolves
no record fence because it reaches no handler.

docs/api/openapi.yaml

@@ -46,6 +46,10 @@ tags:
   - name: Records
   - name: Admin
   - name: Meta
+  - name: Retired
+    description: Paths that were published and have been removed. They answer 410 Gone with `meta.errorCode` =
+      `route.retired`, the removing version, and the replacement path where there is one. Listed so a client generated
+      from this contract learns the path is gone from the contract rather than from a 404 in production.
 security:
   - bearerAuth: []
   - cookieAuth: []
@@ -19347,6 +19351,221 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorEnvelope"
+  /api/bugreport:
+    post:
+      security: []
+      deprecated: true
+      tags:
+        - Retired
+      summary: POST /api/bugreport — removed in v1.23.0
+      description: >-
+        Removed in v1.23.0. Every request to this path answers 410 Gone, whatever the method and whatever credential it
+        carries. There is no replacement; the capability is gone rather than moved.
+
+
+        The in-app bug reporter forwarded a description to a GitHub issue on the operator's behalf. It was removed with
+        its tables; report through the project's issue tracker instead.
+
+
+        Retiring a path is deliberate, so the answer says so rather than leaving a client to read a 404 as a broken
+        deployment and retry forever. Treat 410 as terminal: drop the call, degrade the surface that depended on it, and
+        do not offer a retry.
+      responses:
+        "410":
+          description: The path was removed in v1.23.0 and will not answer again. `meta.errorCode` = `route.retired`,
+            `meta.removedIn` carries the version, and `meta.replacedBy` carries the replacement path or null.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
+  /api/bugreport/status:
+    get:
+      security: []
+      deprecated: true
+      tags:
+        - Retired
+      summary: GET /api/bugreport/status — removed in v1.23.0
+      description: >-
+        Removed in v1.23.0. Every request to this path answers 410 Gone, whatever the method and whatever credential it
+        carries. There is no replacement; the capability is gone rather than moved.
+
+
+        Told a client whether the in-app bug reporter was configured. Removed with the reporter itself.
+
+
+        Retiring a path is deliberate, so the answer says so rather than leaving a client to read a 404 as a broken
+        deployment and retry forever. Treat 410 as terminal: drop the call, degrade the surface that depended on it, and
+        do not offer a retry.
+      responses:
+        "410":
+          description: The path was removed in v1.23.0 and will not answer again. `meta.errorCode` = `route.retired`,
+            `meta.removedIn` carries the version, and `meta.replacedBy` carries the replacement path or null.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
+  /api/auth/me/doctor-report-prefs:
+    get:
+      security: []
+      deprecated: true
+      tags:
+        - Retired
+      summary: GET /api/auth/me/doctor-report-prefs — removed in v1.32.39
+      description: >-
+        Removed in v1.32.39. Every request to this path answers 410 Gone, whatever the method and whatever credential it
+        carries. Use `/api/auth/me/report-selection` instead.
+
+
+        The doctor report grew a per-leaf selection, and the old preference blob could not express it. The replacement
+        stores the same intent against the current leaf catalogue.
+
+
+        Retiring a path is deliberate, so the answer says so rather than leaving a client to read a 404 as a broken
+        deployment and retry forever. Treat 410 as terminal: drop the call, degrade the surface that depended on it, and
+        do not offer a retry.
+      responses:
+        "410":
+          description: The path was removed in v1.32.39 and will not answer again. `meta.errorCode` = `route.retired`,
+            `meta.removedIn` carries the version, and `meta.replacedBy` carries the replacement path or null.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
+    put:
+      security: []
+      deprecated: true
+      tags:
+        - Retired
+      summary: PUT /api/auth/me/doctor-report-prefs — removed in v1.32.39
+      description: >-
+        Removed in v1.32.39. Every request to this path answers 410 Gone, whatever the method and whatever credential it
+        carries. Use `/api/auth/me/report-selection` instead.
+
+
+        The doctor report grew a per-leaf selection, and the old preference blob could not express it. The replacement
+        stores the same intent against the current leaf catalogue.
+
+
+        Retiring a path is deliberate, so the answer says so rather than leaving a client to read a 404 as a broken
+        deployment and retry forever. Treat 410 as terminal: drop the call, degrade the surface that depended on it, and
+        do not offer a retry.
+      responses:
+        "410":
+          description: The path was removed in v1.32.39 and will not answer again. `meta.errorCode` = `route.retired`,
+            `meta.removedIn` carries the version, and `meta.replacedBy` carries the replacement path or null.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
+  /api/fhir/$everything:
+    get:
+      security: []
+      deprecated: true
+      tags:
+        - Retired
+      summary: GET /api/fhir/$everything — removed in v1.32.39
+      description: >-
+        Removed in v1.32.39. Every request to this path answers 410 Gone, whatever the method and whatever credential it
+        carries. Use `/api/fhir/Patient/$everything` instead.
+
+
+        The whole-record operation moved under the resource type it operates on, which is where FHIR R4 defines it and
+        where the capability statement points.
+
+
+        Retiring a path is deliberate, so the answer says so rather than leaving a client to read a 404 as a broken
+        deployment and retry forever. Treat 410 as terminal: drop the call, degrade the surface that depended on it, and
+        do not offer a retry.
+      responses:
+        "410":
+          description: The path was removed in v1.32.39 and will not answer again. `meta.errorCode` = `route.retired`,
+            `meta.removedIn` carries the version, and `meta.replacedBy` carries the replacement path or null.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
+  /api/auth/me/research-mode:
+    get:
+      security: []
+      deprecated: true
+      tags:
+        - Retired
+      summary: GET /api/auth/me/research-mode — removed in v1.37.2
+      description: >-
+        Removed in v1.37.2. Every request to this path answers 410 Gone, whatever the method and whatever credential it
+        carries. There is no replacement; the capability is gone rather than moved.
+
+
+        Research Mode was an opt-in for the estimated drug-level curve. The chart had stopped consulting the flag
+        several releases earlier and painted for every account regardless, so the switch governed nothing. The curve is
+        simply part of the medication page now and needs no preference read.
+
+
+        Retiring a path is deliberate, so the answer says so rather than leaving a client to read a 404 as a broken
+        deployment and retry forever. Treat 410 as terminal: drop the call, degrade the surface that depended on it, and
+        do not offer a retry.
+      responses:
+        "410":
+          description: The path was removed in v1.37.2 and will not answer again. `meta.errorCode` = `route.retired`,
+            `meta.removedIn` carries the version, and `meta.replacedBy` carries the replacement path or null.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
+    post:
+      security: []
+      deprecated: true
+      tags:
+        - Retired
+      summary: POST /api/auth/me/research-mode — removed in v1.37.2
+      description: >-
+        Removed in v1.37.2. Every request to this path answers 410 Gone, whatever the method and whatever credential it
+        carries. There is no replacement; the capability is gone rather than moved.
+
+
+        Research Mode was an opt-in for the estimated drug-level curve. The chart had stopped consulting the flag
+        several releases earlier and painted for every account regardless, so the switch governed nothing. The curve is
+        simply part of the medication page now and needs no preference read.
+
+
+        Retiring a path is deliberate, so the answer says so rather than leaving a client to read a 404 as a broken
+        deployment and retry forever. Treat 410 as terminal: drop the call, degrade the surface that depended on it, and
+        do not offer a retry.
+      responses:
+        "410":
+          description: The path was removed in v1.37.2 and will not answer again. `meta.errorCode` = `route.retired`,
+            `meta.removedIn` carries the version, and `meta.replacedBy` carries the replacement path or null.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
+    delete:
+      security: []
+      deprecated: true
+      tags:
+        - Retired
+      summary: DELETE /api/auth/me/research-mode — removed in v1.37.2
+      description: >-
+        Removed in v1.37.2. Every request to this path answers 410 Gone, whatever the method and whatever credential it
+        carries. There is no replacement; the capability is gone rather than moved.
+
+
+        Research Mode was an opt-in for the estimated drug-level curve. The chart had stopped consulting the flag
+        several releases earlier and painted for every account regardless, so the switch governed nothing. The curve is
+        simply part of the medication page now and needs no preference read.
+
+
+        Retiring a path is deliberate, so the answer says so rather than leaving a client to read a 404 as a broken
+        deployment and retry forever. Treat 410 as terminal: drop the call, degrade the surface that depended on it, and
+        do not offer a retry.
+      responses:
+        "410":
+          description: The path was removed in v1.37.2 and will not answer again. `meta.errorCode` = `route.retired`,
+            `meta.removedIn` carries the version, and `meta.replacedBy` carries the replacement path or null.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
 components:
   schemas:
     CreateCycleCustomSymptomRequest:
@@ -29850,6 +30069,41 @@ components:
             - leaves
           additionalProperties: false
           description: Clinician share-link surface descriptor.
+        retiredRoutes:
+          type: array
+          items:
+            type: object
+            properties:
+              path:
+                type: string
+                description: The path, as it was published.
+              removedIn:
+                type: string
+                description: Release the removal shipped in, without the `v`.
+              replacedBy:
+                anyOf:
+                  - type: string
+                  - type: "null"
+                description: Where the capability went, or null when it went nowhere.
+              reason:
+                type: string
+                description: Why it was removed, in one sentence, in English.
+              methods:
+                type: array
+                items:
+                  type: string
+                description: The verbs the route exported before it was removed. Every verb answers 410 regardless — the path was
+                  retired, not a selection of methods on it.
+            required:
+              - path
+              - removedIn
+              - replacedBy
+              - reason
+              - methods
+            additionalProperties: false
+          description: Paths this server used to serve and no longer does. Each answers 410 Gone with `meta.errorCode` =
+            `route.retired`. Read on launch so a client can drop the surface that depended on one before it makes the
+            call, rather than learning from the failure.
       required:
         - apiContractVersion
         - derivedMetricIds
@@ -29859,6 +30113,7 @@ components:
         - ingest
         - fhir
         - share
+        - retiredRoutes
       additionalProperties: false
       description: Live id vocabularies + contract version. Every list is derived server-side from the canonical registry it
         documents, so it cannot drift from the values the routes actually accept/emit.