feat(gateway): add client-carried model affinity

[Menci]

Summary

• add per-API-key encrypted affinity carriers for Chat Completions, Messages, Gemini, and Responses
• wrap every natural opaque blob independently and ensure the first logical assistant element carries a target anchor
• derive prefer and force only at ingress from current protocol structure; routing strength is not serialized
• make Responses persistence independent from affinity and retain complete client-wire items for 30 days
• add a general hidden serverSecret to each API key and derive an affinity-specific encryption key from it

Wire behavior

The version 1 AES-256-GCM trailer has no magic or delimiter, preserves canonical Base64/Base64URL bytes without nested encoding, and authenticates the original bytes plus protocol/slot domain. Values that cannot be authenticated by the current key remain byte-for-byte foreign for cascaded Floway deployments.

Affinity identity contains upstream ID, canonical model ID, and exact alias-rule presence/value. Protocol restore data may include upstream item identity or a whole-element synthetic marker. It contains neither an upstream configuration revision nor routing strength.

Egress has two responsibilities:

1. wrap each natural upstream blob with target and restoration data;
2. augment the first logical assistant element, or insert a protocol-native prefix element, when it has no blob.

Ingress decrypts the target first, restores or removes owned state per candidate, and derives request-local routing evidence. Ordinary assistant state prefers a target. Responses compaction and program state force the associated target.

Protocol placement

• Chat Completions treats each choice message as one logical element. It emits one last-write-wins wrapped or originless reasoning_opaque immediately before finish_reason.
• Messages uses a first thinking/redacted block directly. A first thinking block without a natural signature receives an originless signature at block close; text/tool-first messages receive a redacted prefix and every original block index is shifted by one.
• Gemini uses a sliding one-event lookahead. Same-element continuations release the older event unsigned and keep only the newer event buffered; a later natural signature moves onto that content-bearing Part, while a definite boundary or finish synthesizes only when none arrived.
• Responses augments a carrier-capable first output item at output_item.done. Other first item types are shifted behind a synthetic reasoning added/done prefix; all later output_index and sequence_number values plus terminal output are rewritten consistently.

Responses state and migration

Native Responses input expands previous_response_id and hydrates complete stored items before affinity routing. Output applies affinity before public ID rewriting and persistence. HTTP store: false performs no writes; WebSocket store: false keeps state only for that socket session.

Migration 0057_responses_full_state.sql rebuilds the schema while copying every key-scoped row that still has a complete payload. It preserves payload descriptors, hashes, IDs, item types, creation timestamps, and every fully backed snapshot. Legacy database affinity (upstream_id / upstream_item_id) is intentionally not migrated because the old rows lack canonical model and alias data. Preserved pre-0057 history resumes through normal routing and may be rejected by an upstream as a known breaking transition. Metadata-only and unscoped rows are omitted. Retention is uniformly creation-based at 30 days.

Compatibility

Client payloads containing Floway-owned carriers are a Floway wire contract and are expected to continue through Floway. Replaying a modified payload directly to an upstream is not guaranteed.

Research against current official OpenAI, Anthropic, and Google SDKs plus Agents, Vercel AI SDK, ADKs, LangChain, LlamaIndex, Continue, and Cline informed placement. Responses and official Messages structured clients retain prefix items/blocks. Chat reasoning_opaque remains opportunistic in high-level clients that discard unknown Chat fields. Gemini sliding lookahead avoids repeated signatures even when the natural value arrives after multiple same-element continuation events; only the newest event is ever buffered.

Normal API-key CRUD and dashboard DTOs never expose serverSecret. Admin data transfer format version 10 includes it so restored deployments retain gateway-private per-key state.

Test plan

• pnpm run test — 361 files, 4295 tests
• pnpm run typecheck
• pnpm run lint