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.
This commit is contained in:
Marc-André Bombeck committed 2026-08-23 14:06:52 +02:00
1 parent 87929eb3b8
commit f4c0eb0ab9
9 files changed
+521 -11

No files matched your search

+9
View File
@@ -47,6 +47,7 @@ import {
} from "@/lib/fhir/rest";
import { SHARE_LINK_MAX_DAYS } from "@/lib/validations/clinician-share-link";
import { ALL_LEAF_IDS, SHARE_GROUPS } from "@/lib/report-selection/catalogue";
import { RETIRED_ROUTES } from "@/lib/http/retired-routes";
export const dynamic = "force-dynamic";
@@ -140,5 +141,13 @@ export const GET = apiHandler(async () => {
groups: SHARE_GROUPS,
leaves: ALL_LEAF_IDS,
},
// Paths this server used to serve and no longer does. A capability that
// disappears from the lists above is a signal a client can act on without
// comparing versions; this is the same signal for the routes themselves,
// and it arrives on the launch read rather than on the failing call. The
// list is the same constant the proxy answers 410 from and the contract
// publishes as gone, so a retirement cannot be announced here and not
// honoured, or honoured and not announced.
retiredRoutes: RETIRED_ROUTES,
});
});