# RC9 OpenAPI-Generated Kotlin and TypeScript Clients

**Governing issue:** #261  
**Claim base:** `main@030cd577e179863b70f24d99ab237e74660b4325`  
**RC9A merge:** `main@e43efc5050a792a902a1ca94113854541380b56e`  
**Runtime-adoption PR:** #497  
**State:** RC9 CLOSED — DETERMINISTIC GENERATED CLIENTS / BOUNDED RUNTIME ADOPTION

## Purpose

RC9 makes the canonical NestJS OpenAPI contract consumable by Android and TypeScript without weakening DIREKT-owned transport, authorization, privacy, retry, idempotency, offline or BFF policies.

Generated code is a contract implementation aid. It does not become a new authority boundary and does not authorize production, participant data, privileged direct access, payment-provider activation or real money.

## Canonical generated foundation

OpenAPI Generator `7.22.0` is locally and CI pinned to the official JAR SHA-256:

`3f1e6ce5c6ad4f15242c6170ab43aad4bad771622617eeece4a7d4f72ffaf329`

Generation rules:

- no online generator service;
- exact version and configuration committed;
- `hideGenerationTimestamp=true`;
- canonical checked OpenAPI input only;
- deterministic output paths and package names;
- byte-for-byte drift verification;
- no generated secrets, environment URLs or privileged credentials;
- generated output reviewed like source code and kept mechanically reproducible.

The current generated receipt records:

- canonical OpenAPI SHA-256: `1c13b69a34c30b84347b02ecddcf4f5b55c21e1958f036d4dc29c9106784e063`;
- Kotlin: `111` source files, tree SHA-256 `ba3e4b7ab4f2eeaf3fafd96bdf2bbbddfd2feb8ebbbe71f4f309c825eb7991cc`;
- TypeScript: `98` source files, tree SHA-256 `04cecfb32400eac04d5818ee1bb22e8394d822e2d350c8cfcc4f3a64eee982fe`;
- participant data: false;
- privileged client credentials: false;
- production authorization: false.

The immutable RC9A receipt deliberately retains `runtimeWired=false` for both output trees because it describes deterministic generation, not later application imports. The permanent RC9 verifiers separately enforce the two bounded runtime adoption points described below.

## RC9B — Android Kotlin auth/session slice

### Generator and dependency decision

- generator: `kotlin`;
- library: `jvm-retrofit2`;
- serialization: `kotlinx_serialization`;
- package root: `com.kudzimusar.direkt.generated.api`;
- migration slice: Firebase-to-DIREKT session exchange only.

Android now compiles the generated Kotlin tree and replaces only the former manual `HttpsURLConnection`/`JSONObject` exchange implementation with `GeneratedPilotSessionExchangeClient`, a DIREKT-owned wrapper around the generated `AuthenticationApi`.

The wrapper preserves:

- HTTPS-only origin validation;
- 10-second connect, read and write timeouts;
- redirects and SSL redirects disabled;
- automatic retries disabled;
- consent and notice-version propagation;
- generic user-facing rejection/failure semantics;
- Firebase sign-out after exchange;
- the existing Android Keystore-backed encrypted session store;
- existing push-token registration after successful DIREKT session creation;
- Android API 23 support through core-library desugaring.

Generated transport defaults do not decide authorization, trust, payment, retry, idempotency or offline success. DIREKT-owned code remains authoritative for those policies.

### Android Play/Data Safety reconciliation

The reviewed RC9 release runtime additions are inventoried in the permanent Phase 12B gate:

- Retrofit;
- Kotlin serialization converter;
- scalar converter;
- Kotlin serialization JSON;
- the generated client compile-time OkHttp logging dependency.

The generated default BODY logger is not activated: the Android wrapper supplies its own safe `OkHttpClient.Builder` and does not call the generated logger hook. The Phase 12B validator positively checks that HTTP body logging is inactive, HTTPS-only confinement remains present, redirects/retries remain disabled, and the transport targets only the private DIREKT API rather than a third-party, browser-direct, database or provider endpoint.

### Focused Android regression

`GeneratedPilotSessionExchangeClientTest` covers:

- rejection of non-HTTPS, user-info and query-bearing origins;
- normalization of an approved HTTPS origin;
- request mapping for the Firebase ID token, approved notice version, affirmative consent and bounded device label;
- preservation of the reviewed generic rejection message.

## RC9C — TypeScript server-only BFF contract adoption

Generated TypeScript request/response types are consumed only through `web/direkt-app/lib/server/generated-auth-contracts.ts`.

The existing DIREKT-owned BFF fetch wrapper remains responsible for:

- private Cloud Run origin confinement;
- Cloud Run infrastructure identity authentication;
- DIREKT session-token propagation;
- idempotency headers;
- timeout handling;
- `cache: "no-store"`;
- redirect rejection;
- safe problem-detail/error normalization.

A generated browser transport is not approved. Generated transport runtime modules do not enter client components, and the private API origin, infrastructure token, refresh token and privileged credentials remain server-only.

The BFF adapter now normalizes both generated `Date` values and raw JSON `date-time` strings before returning the existing DIREKT session contract. Focused verification rejects invalid date-time values and asserts that the adapter imports generated types only, not generated browser transport code.

## Permanent bounded-import contract

Generated imports remain prohibited throughout Android and web runtime source except for exactly these reviewed points:

1. Android `GeneratedPilotSessionExchangeClient.kt`;
2. server-only BFF `generated-auth-contracts.ts`.

The permanent verifier ignores compiler/build artifacts such as `.tsbuildinfo`, `.next`, `build`, `dist`, coverage and dependency directories, but scans authored source fail-closed.

## RC9D closure evidence

RC9 implementation PR #497 passed its complete exact-head matrix on `04ef57f31414ec5165e353abba74afb8dfdcc901` and squash-merged at `main@70de95c73128e921cd4d7c667de0e5a442a9e0c0`. The permanent RC9 contract and deterministic-generation workflows passed alongside Android CI/instrumentation, Android performance, backend/OpenAPI, web/PWA/W7, supply-chain, runtime audit, Phase 10–12 and RC5–RC7 preservation gates. The authoritative receipt is recorded in `RC9_CLOSURE_RECEIPT.md` and `LIVE_INTEGRATION_LEDGER.md`.

The repository lane is released after the RC9D closeout merge. RC10 is next but unclaimed; it must begin from current `main` through a new explicit claim.

## Stop conditions

Stop rather than merge if RC9 would:

- expose the private API origin or infrastructure identity token to browser code;
- put database, Supabase service-role, payment, OTP, WhatsApp, Maps backend or other provider secrets in generated output or clients;
- replace backend authorization/provider scope with client-selected values;
- treat generated DTO validation as payment, verification, trust, publication or dispute authority;
- break Android API 23 support, signing, Firebase, Maps, FCM, Crashlytics or secure session storage;
- weaken offline/failure semantics or claim a mutation succeeded without backend confirmation;
- accept generated drift or unpinned generator/tool dependencies;
- perform a broad client rewrite beyond the approved first slice.

## Production authorization

False. RC9 is deterministic contract tooling and bounded client migration only. It does not clear Phase 11 real evidence, 11J, legal/privacy gates, production credentials, participant traffic, real communications, real money or formal Phase 12 release.
