[Task] Define a language-neutral client registration OpenAPI and lifecycle contract #8038

Goal

Specify a language-neutral HTTP registration contract so Java, Go, Python, Node.js and other business-service clients can interoperate with Admin without depending on Java implementation classes.

Build on the main-owned registration protocol v1 and its fixtures from #7605. This is protocol standardization, not a request to expose unrestricted Admin selector/rule management APIs or mechanically export current Java DTOs as the final public contract.

Scope

• Inventory current registration/authentication endpoints and document their actual v1 request/response shapes in a versioned OpenAPI document.
• Define namespace/service/instance identity, endpoint registration, retries/idempotency, duplicate/concurrent requests, heartbeat, offline and capability/version negotiation.
• Distinguish request acceptance, persistence and gateway-observed configuration readiness. Specify how clients observe each state without implying that a successful acknowledgement means routing is ready.
• Specify authentication, credential expiry/renewal and authorization boundaries for service/namespace-scoped registration. Do not let a business client change arbitrary gateway policies.
• Pair OpenAPI schemas with lifecycle semantics and shared serialized compatibility fixtures; document wire types rather than relying on common Java classes.
• Preserve headerless v1 behavior and existing response contracts. Any breaking redesign needs an explicit new version, coexistence window and rollback path.
• Validate with the existing Java producer and at least one non-Java reference client through register -> actual gateway request -> heartbeat -> offline.

Acceptance criteria

A client implementer can build registration using only the HTTP contract and examples. Contract tests cover success, invalid input, retries, expiry, unsupported versions and namespace isolation. The reference demonstration records pinned server/client revisions and actual gateway responses. No generated-SDK or release compatibility claim is made without corresponding verification.

Related: #7602 (client migration), #7605 (main protocol), #6366 (interoperability), #8036 (documentation alignment). This work can proceed independently of moving source; protocol changes require coordination across repositories.

Follow-up tasks

• [Task] Define server-issued registration leases and heartbeat expiry semantics for business instances #8039 — Define server-issued registration leases and heartbeat expiry semantics for business instances
• [Task] Fence stale business-instance heartbeat and offline requests with boot-session identity #8040 — Fence stale business-instance heartbeat and offline requests with boot-session identity
• [Task] Define business-upstream health probe capabilities and separate probe results from heartbeat liveness #8041 — Define business-upstream health probe capabilities and separate probe results from heartbeat liveness
• [Task] Define business-instance readiness and draining admission semantics independently of liveness #8042 — Define business-instance readiness and draining admission semantics independently of liveness