Merge branch 'main' into docs/pinokio-browser-performance

docs/APPLICATION.md

@@ -158,7 +158,7 @@ routing and regional caches. Request parameters cannot override these endpoints.
 Voice controls accept an action runner and a controller factory through
 `createVoiceCommands` (`./voice/commands`). The default Realtime controller owns
 microphone tracks, playback, push-to-talk, tool cancellation and radio handoff.
-Its backend supplies `requestToken({ tier, signal })` and
+Its backend supplies `requestToken({ tier, authMode, signal })` and
 `negotiate({ offerSdp, credential, signal })`. The Realtime-compatible adapter
 (`./voice/realtime-backend`) accepts separate token and connection transports
 and endpoints. Only the short-lived client secret reaches the SDP endpoint.

docs/VOICE-OWNERSHIP.md

@@ -8,6 +8,7 @@ The session adapter, action runner and backend interfaces remain unchanged.
 | Owner | State and responsibility |
 | --- | --- |
 | `realtimeConnection.js` | Start generation, request cancellation, peer/data channel, acquired microphone stream and playback element |
+| `realtimeBackend.js` | Token and SDP requests, their separate transports, the abort/timeout scope around both, and client-secret expiry |
 | `realtimeTurns.js` | Active and superseded responses, pending confirmations, deduplicated calls and action cancellation |
 | `realtimeRadio.js` | Speaker ducking, prepared playback, stronger-action reservations and playback observers |
 | `realtimeInput.js` | Physical Space gesture, microphone mute, input/output meters and their frame/listener lifetime |
@@ -21,6 +22,15 @@ The session adapter, action runner and backend interfaces remain unchanged.
 | `resultDisplay.js` | What the voice card shows for a result and which items it numbers (read by the card and `referents.js`) |
 | `gevActions.js` runner | Analyst follow-up memory (session: `resetConversation()` on stop, `dispose()` on removal) |
 
+The backend is replaceable per deployment: `realtimeController.js` accepts it as a
+`backend` option and falls back to `createRealtimeBackend()`. Its two method
+signatures live with [application construction](APPLICATION.md); what belongs here
+is the ownership. The connection is the backend's only consumer in the application.
+The connection reads credential metadata for diagnostics and cost accounting,
+then passes the complete credential unchanged to `negotiate`. Client-secret expiry is refused inside the backend, not by the connection.
+`realtimeOwners.test.mjs` drives whole sessions through a substitute that
+implements only those two methods.
+
 Pure input policy, preferences and protocol-response policy have separate modules.
 Owners receive named readers, operations or focused collaborators. Cross-owner
 cancellation uses operations; response handling does not own Radio's reservations