feat(ci): gate shipped code against the frozen OpenAPI contract

[github-actions]

What

gate-openapi-conformance measures the shipped code against each service's frozen OpenAPI spec, in both directions. It never regenerates the spec from code. A spec derived from its implementation agrees with that implementation by construction, so it cannot detect that the implementation drifted — that pipeline silently converts a contract into documentation.

Nothing else in this repo closes this seam. Type-check, lint, unit tests and helm template | kubeconform are each individually happy with a service that implements an endpoint the contract never declared, or that quietly stopped implementing one a consumer generated a client for. gate-route-ownership checks which service serves a path; this checks whether the path was ever agreed.

Failure classes

Class	Meaning
MISSING	Declared in the contract, not implemented. A consumer generated a client from the spec and got a 404.
UNDOCUMENTED	Implemented, absent from the contract. Surface nobody agreed to and nobody reviewed — the shape most likely to be missing authz, because it was never designed.
NO CONTRACT	A service serving routes with no openapi.yaml at all.
UNRESOLVED	A mount the extractor could not statically resolve.

UNRESOLVED fails. Skipping what cannot be parsed is how a gate becomes vacuous: the routes hardest to parse are the likeliest to be undocumented, so skipping them biases the gate toward passing on exactly the cases it exists to catch. Zero routes extracted is likewise a failure, never a pass — a parser that finds nothing would otherwise report "no undocumented endpoints", which is technically true, worthless, and indistinguishable in CI from a genuinely conformant service.

NO CONTRACT closes the same hole one level up. An earlier cut of discover() returned only services that had a spec, so a service with no contract at all — the maximally undocumented case — wasn't a finding, it was invisible.

Two design points worth reviewing

Mounts resolve through imports, per file. The obvious first cut mapped every exported name to a file and looked mounts up in that one table. It resolved zero routes in four of six services here, because the dominant idiom is import listsRouter from './routes/lists' against an export default router — a default export has no name to key on. It was also unsound: two files exporting the same identifier silently aliased.

servers[].url is honoured. OpenAPI paths are relative to the server URL. Ignoring it reported every billing- and payment-service endpoint as both missing and undocumented — 26 findings that were one prefix, and the precise shape that teaches a team to ignore a gate. Both live mounting styles are conformant with the same contract: billing-service mounts its own public base (API_BASE = '/api/v1/billing'), config-service mounts bare paths behind an ingress rewrite. The base is stripped from the code side only when every route carries it, so a partial mismatch stays visible as findings.

The escape hatch is a file, not a flag

governance/openapi-conformance-allowlist.txt carries two entry forms, each with the reason it is not drift:

• METHOD /path — an endpoint deliberately outside contract surface (kubelet probes, self-served Swagger UI).
• middleware NAME — an identifier mounted with .use() that is middleware, not a router.

The second exists because app.use(API_BASE, graphCreate({ aggregate: … })) imports from @izzywdev/fuzefront-identity, which no static reader can walk into and which is indistinguishable from a router it simply cannot see. Guessing "probably middleware" is how a gate stops catching the thing it is for, so the operator asserts it in a file that shows up in the diff.

Verification

Non-vacuity is proven by mutation against the real tree, not by passing on it. Each of these produces a failure; the unmutated tree is green:

Mutation	Result
baseline	exit=0
rename a spec path	exit=1 — 1 MISSING, 1 UNDOCUMENTED
add a stray code route	exit=1 — 1 UNDOCUMENTED
withdraw the middleware declaration	exit=1 — 1 UNRESOLVED
delete a service's contract	exit=1 — 3 NO CONTRACT
blind the parser on one mount	exit=1 — 1 MISSING, 1 UNRESOLVED
restored	exit=0

17 self-tests, weighted toward asserting the gate fails on a violation, and the workflow runs them before the real check — if they are red, the run below them proves nothing.

Final state across all nine services with sources:

billing-service:        spec=16 code=15 (rebased off server base /api/v1/billing) -> OK
chat-service:           spec=6  code=5  -> OK
config-service:         spec=7  code=7  -> OK
notification-service:   spec=11 code=11 -> OK
payment-service:        spec=7  code=6  (rebased off server base /api/v1/payments) -> OK
selection-list-service: spec=24 code=24 -> OK
sms-service:            spec=2  code=2  -> OK
email-service:          NO CONTRACT, 1 route(s) -> OK (all allowlisted)
provisioning-service:   NO CONTRACT, 1 route(s) -> OK (all allowlisted)

Two real findings, fixed here rather than reported

• billing-service serves GET /subscriptions — an actor-scoped endpoint the UI consumes, returning 200 { subscription: null } for "no plan" — and it was absent from the contract. Documented, including the null-not-404 semantics a caller must branch on.
• sms-service served POST /sms/send and POST /sms/verify with no contract whatsoever. Contract written from the handlers and their zod schemas. The inverted authoring order is recorded in the file rather than hidden, along with the fail-closed behaviour of its shared-secret guard.

The two remaining spec-less services (email-service, provisioning-service) serve only an allowlisted GET /health, so they stay quiet — and the first real endpoint added to either without a contract reds CI, which is the point at which a contract is cheap to write.

Follow-up, not in this PR

This gate is FuzeFront-local. It was built here because this is where the services are and where it could be validated against real drift. Promoting it to a canonical workflow-templates/ entry in FuzeSDLC — the same path gate_ds_conformance.py took — is a separate change, and one that should not be folded into the PR that first proves the gate works.

[izzywdev]

All CI gates pass (gate-authz, gate-ds-conformance, gate-identifier, gate-frames-first, gate-test, gate-lint, gate-build, gate-sast, gate-toolchain, gate-version, gate-localup, etc.). Approving per governance policy.