A3 · OpenAPI pipeline: springdoc → contracts/openapi.json (drift-checked) → generated typed client in apps/web

Architecture epic, foundation step 3 of 5. Depends on A2. Commandments 3, 4 and 8.

Do

Backend

• Add org.springdoc:springdoc-openapi-starter-webmvc-api, the version compatible with Boot 3.5. Expose /api/public/openapi.json (keep it under /api/public/** so routing doesn't change). Disable Swagger UI in production.
• Annotate the existing controllers minimally: operation ids, tags per domain, response schemas for records. Don't redesign the endpoints.
• Add a Gradle task generateOpenApi that boots the app context in test mode and writes the spec to ../../contracts/openapi.json (the springdoc Gradle plugin, or a test that writes the file).
• Drift check: add a CI step in backend.yml that regenerates the spec and fails if git diff --exit-code contracts/openapi.json shows a change.

Web

• Add openapi-typescript (dev) and openapi-fetch. Add a script "gen:api": "openapi-typescript ../../contracts/openapi.json -o lib/api/schema.d.ts". Commit the generated file, and fail CI if it's stale.
• Add lib/api/client.ts:
  • Server: createServerClient() forwards the user's Keycloak access token from the Auth.js session (rule 7). No service accounts.
  • Client: a browser client for client hooks.
  • Guest: both clients fall back to anonymous for guest reads.
• Add domains/README.md describing the domains/<x>/{data,components} structure and the data pattern: data/server.ts (server functions for RSC) plus data/hooks.ts (client hooks, used by PAR-401's cache once it lands).

Acceptance

• contracts/openapi.json is committed and valid (OpenAPI 3.1).
• Changing a controller without regenerating the spec fails CI.
• lib/api/schema.d.ts is generated, and a typed call compiles in a sample server function. Remove the sample before merging, or keep it as the README example.
• Lint, typecheck, tests and ./gradlew test all pass.