# OpenNOW shell/core protocol The Qt shell and Rust application core communicate over newline-delimited UTF-8 JSON on inherited standard input/output. Standard error is reserved for redacted diagnostics. A line is limited to 1 MiB. Unknown, malformed or oversized protocol messages terminate the core connection instead of leaving the shell in an ambiguous state. ## Handshake The first shell request is always: ```json {"type":"request","id":"1","method":"core.hello","params":{"protocolVersion":5,"shell":"qt","shellVersion":"0.5.4"}} ``` Protocol 5 requires an exact selected catalog variant and account scope for fresh session allocation. It retains the bounded library-page contract introduced in protocol 4. Older shells are rejected with `incompatible_protocol` during `core.hello`, and protocol-5 shells reject older cores. The native streamer protocol remains 7. The core must return the same protocol version and its capabilities. The shell does not send product requests before this succeeds. Version mismatches, a five-second handshake deadline, process exit and invalid data all transition the transport to `failed` with a credential-free diagnostic. The desktop queue selector requires the `queue.servers.v1` capability in this handshake. The Qt client and relocated package probes reject cores that omit it, including older protocol-5 binaries, before sending any product requests. This additive capability leaves the JSON envelope and native streaming ABI unchanged. ## Saved accounts (`auth.accountPicker.v1`) The "Who's playing?" picker requires the `auth.accountPicker.v1` capability. The Qt client rejects cores that omit it during `core.hello`, before any product request. The capability is additive: the protocol version, the envelope and the native streaming ABI are unchanged. `auth.accounts.list` returns `{accounts, activeUserId, generation}`. Each account contains only public identity fields; tokens never cross the boundary: | Field | Type | Meaning | |---|---|---| | `userId`, `displayName` | string | Saved identity. | | `email`, `avatarUrl` | string or null | From the last sign-in or token refresh. | | `membershipTier` | string | `FREE`, `PERFORMANCE` or `ULTIMATE` today. Shells must render other values without failing. | | `providerCode` | string | Login provider code. `NVIDIA` is NVIDIA; any other code is an alliance partner. | | `providerName` | string | Display name for the provider. The core owns the code-to-name mapping (`gfn::provider_display_name`): the name saved at sign-in, then the discovered provider name for that code, then the code itself. `BPC` is always `bro.game`. | | `providerIdpId` | string, optional | Provider IdP for "Sign in again". Absent for accounts saved before this field existed until their next sign-in or refresh. | | `alliance` | bool | `providerCode != "NVIDIA"`. | | `hasPin` | bool | A local profile PIN guards `auth.accounts.switch`. | | `needsSignIn` | bool | The last restore or switch for this account ended with refresh outcome `expired` after the provider answered (not after a network failure). Cleared when the account signs in or refreshes again. | `auth.accounts.switch` never ends a running cloud session; the seat keeps its original owner. The Qt shell ends the session through its end-session confirmation and waits for `session.stop` before it sends the switch. The `startAsLastUsedAccount` setting (bool, default `false`) skips the launch picker when two or more accounts are saved. Loading settings migrates the retired `consoleProfilePickerOnLaunch: false` to `startAsLastUsedAccount: true`. ## Cloud library actions and launch decisions `catalog.launch.inspect({appId, variantId})` always resolves the exact parent and store variant. Its response contains `appId`, `variantId`, `game`, `scope`, `catalogRevision`, `fetchedAt`, `freshness`, and `decision: {status, message}`. Statuses are `ready`, `ownership_required`, `selection_required`, `link_required`, `subscription_required`, `patching`, `maintenance`, `unavailable`, and `metadata_unconfirmed`. Only the selected variant's `MANUAL` or `PLATFORM_SYNC` library status records ownership. App-wide library flags, Home pins, favorites, free-game labels, store subscriptions, and ownership of another variant do not. Store-link requirements use the store definitions and fresh account state. Recorded store-subscription IDs must match the account's active subscriptions. App playability, variant readiness, patch metadata, and membership restrictions remain independent checks. Unknown metadata is not a positive authorization. `catalog.launch.store.inspect({store?})` resolves the platform-client apps for the current streaming region with a `PLATFORM_CLIENT` type filter and returns `{store, appId, variantId, game, scope, decision, catalogRevision, fetchedAt, freshness}`. The resolved `appId`, `variantId`, and `game` are the values the platform-client query returned for this account. `store` defaults to `STEAM`, the only supported store-client launch, and any other value is `invalid_params`. The eligible target is the first game exposing a variant whose exact `appStore` value matches the store and whose `id` is a bounded identifier; extra variants and extra platform-client apps are searched, not rejected. The store-launch decision reuses the shared decision vocabulary. It requires the exact parent identity and variant identity, the exact store on the resolved variant, a present `gfn.status` of `AVAILABLE`, and any patching or maintenance metadata the server returns. It then requires the persistent-storage entitlement: the subscription `addons` entry whose `type` is `STORAGE` and whose `subType` is `PERMANENT_STORAGE` and whose `status` is `OK`, which the core publishes as `subscription.storageAddon`. An ephemeral storage add-on, including `EPHEMERAL_STORAGE`, does not authorize a store launch. Store-account linking requirements, recorded store subscriptions, membership tier, and `isGamePlayAllowed` apply from the same account metadata the ordinary launch path uses. Cloud DLSS overrides follow the official client. The `dlssOverrides` setting stores the exact `requestedStreamingFeatures.dlssOverrides` wire object (`srMode`, `srModel`, `srScale`, `rrModel`, `fgMode`, `fgModel`, `fgMultiplier`), where `0` leaves a feature to the game. The core clamps unknown enum values to `0`, leaves a mode to the game when its model is, fixes `srScale` for every SR mode except Custom (33–100), and sends `fgMultiplier` only for Dynamic frame generation. Every create request carries the object. `subscription.dlssOverrides` reports `entitled` and `upsell` for `superResolution`, `frameGeneration`, and `rayReconstruction` from the MES `SUPPORTED_DLSS_OVERRIDE_*` features and `SUPPORT_DLSS_OVERRIDE_*` upsells, plus the entitled `frameGenerationMultipliers` from `SUPPORTED_DLSS_FG_MULTIPLIERS`. A platform client that the ordinary catalog resolution also returns is judged by that resolution's metadata, so catalog `playabilityState` and patch state are enforced there. When the ordinary resolution does not return the app, the store query's own `gfn.status` is the readiness field, because that query selects no catalog playability. When the ordinary resolution returns the app but not the discovered variant, the two sources disagree and the decision is `metadata_unconfirmed` rather than a guess. `catalog.launch.inspect` and `session.create` accept `storeLaunch: true`, a boolean that selects the platform-client resolution source and the persistent-storage requirement. The flag grants nothing: the same mutation admission, scope, catalog revision, active-seat, and exact-variant checks run, and a store intent that names a target the platform-client resolution does not return is not ready. Missing, non-boolean, or mismatched values do not fall back to another target. All five mutation RPCs require a bounded nonempty parent `appId` and the current `scope: {generation, userId, providerIdpId}`. Ownership mutations also require the exact `variantId`. `catalog.ownership.add` requires `confirmedExistingLicense: true`, the user's assertion that they already own the selected store license. This operation neither buys nor grants a license. `catalog.ownership.select` accepts only an owned variant and does not add ownership. Favorites map to the GraphQL `AddFavoriteApp` and `RemoveFavoriteApp` operations with `appId` and `locale` variables. Ownership maps to `AddOwnedVariant`, `RemoveOwnedVariant`, and `SelectOwnedVariant`, with `cmsId` and `locale` variables. `cmsId` supplies the `variantId` argument. Every mutation selects `app { id }` and checks the returned parent identity. Mutations share catalog scheduling and serialize conflicting actions for the same account and parent app. Fresh allocation holds that same app admission while checking and creating. Mutation results distinguish `outcome: acknowledged|unconfirmed` from `reconciliation: confirmed|unconfirmed`. A fresh exact read confirms the desired current state; acknowledgement alone does not. Results include captured target IDs, `operation`, `scope`, `catalogRevision`, nullable refreshed `game`, a visible `message`, and sanitized `error.code`, `error.httpStatus`, and `error.graphql` code/path details. `reconciliationCode` and `invalidationCode` distinguish read or cache-invalidation failures from the mutation outcome. Neither ambiguous failures nor HTTP 401 cause mutation replay. Catalog pages are invalidated before sending and again after the attempt. Cancellation may prevent delivery of the outcome without preventing an already-sent upstream mutation. The shell marks that outcome unconfirmed and refreshes metadata without resending. `catalog.favorites.list` reads the `FAVORITES` panel using `GetGameSection` with `panelNames`, `vpcId`, and `locale`; it has no cursor. It preserves all parsed game items up to the 1,000-game and 768-KiB response bounds, rather than the Store panel's 24-item display limit. The response contains `games`, section identity and `seeMoreInfo`, `scope`, `catalogRevision`, and `fetchedAt`. `coverage` is `unknown` and `complete` is false because the panel does not establish global completeness. No pagination or see-more request is invented. A failed read keeps the shell's last usable list, and a specific favorite is reconciled through the exact app's `library.favorited` value. Existing `favoriteGameIds` remain local Home pins; pinning, collections, hiding, and reordering do not upload favorites. ## Messages ### Authentication boundary Protocol 5 auth responses and `auth.session.changed` events use the same envelope. `session` is either null or an allowlisted object containing `user` and `provider`. Credentials and issuing-client details remain private to the core. The envelope includes the core-process account `generation`, `persistence`, `refresh`, `warnings`, and `deviceIdentity`. Consumers reject older generations and reset their generation when a new core process completes its handshake. A token refresh does not change account generation. `auth.device.start` returns `attemptId`, `userCode`, verification URLs, `qrRows`, `expiresAt`, and `intervalSeconds`. Poll, complete, and cancel use `attemptId` only. The core retains the device grant and enforces the deadline, one in-flight poll, and cumulative five-second `slow_down` increments. Pending poll replies include `retryAfterMs`; the shell schedules one subsequent poll from that reply. Cancellation before the completion commit fence prevents persistence and publication. Once the fence is entered, completion is committed under auth ownership; cancelling its response does not undo that login. The shell reconciles such cancellation with `auth.session.get`. Logout or account replacement invalidates pending login/link work. Persistence intent is independent of outcome. Persistent sessions prefer the OS credential store on every desktop platform, including Windows. `secure-store` means the session was written to and verified in that store and its nonsecret index committed. `local-file` means session tokens are saved in unencrypted JSON because the OS store is unavailable. The per-account file is under `data_dir/fallback-sessions/.json`, with private file access permissions. Those permissions do not encrypt the tokens. The shell warns that anyone who can read the file can access the account. Fallback reads take priority over stale OS-store entries. The next successful secure save verifies the OS-store entry before removing the JSON fallback. If the account-index commit fails after JSON is written, persistence remains `local-file` and warnings report that account restoration may fail. Interrupted JSON temporary files are removed on startup and during account cleanup. `memory-only` never writes a plaintext credential fallback. `migration-pending` means a recoverable legacy source remains because migration could not finish. `unavailable` means restoration failed. Warnings identify deferred cleanup without containing credentials, and the auth envelope never includes tokens. An explicitly temporary login suppresses automatic restoration of older saved grants for that identity. Legacy sources are removed only after verified persistence and metadata commit, or explicit account removal. This is file cleanup, not guaranteed secure erasure of backups or snapshots. Logout always ends local auth ownership and reports `remoteRevoke` separately from `localCleanup`. Revocation is best-effort DELETE of the selected client grant with an access bearer; all-account revocation has a five-second total network budget. Failed local deletion remains suppressed in the nonsecret account index and is retried on startup. Logout removes the JSON fallback even if the OS store remains inaccessible; deferred OS-store cleanup keeps the existing suppression semantics. A metadata write failure reports pending cleanup and cannot guarantee that suppression survives restart. Logout selects the next saved account only when it does not require a profile PIN. Automatic restoration, including a new core process, never activates a PIN-protected profile. Its credentials remain saved for an explicit PIN-verified switch. An already unlocked session remains active within the current core process. Qt loads saved profiles independently of signed-in account services. After a signed-out startup completes, saved profiles open in the existing account picker. An active stream does not trigger automatic navigation. Its user can open saved accounts explicitly from sign-in and unlock a profile without replacing the native video item. Logout-all also scans local fallback files independently of the account index. Missing or corrupt metadata cannot prevent best-effort plaintext cleanup. Recoverable identities are suppressed and removed from the OS store too. Unreadable identities or failed cleanup remain `pending`; corrupt metadata is not silently overwritten. The core persists one versioned 64-hex device identity. Upgrades freeze the previously derived identity using the current environment; if that environment changed before the first upgraded launch, the former hash cannot be recovered. Corrupt or unwritable identity storage is not replaced, new login is blocked, and restoration reports unavailable device identity rather than claiming durable compatibility. ```json {"type":"request","id":"42","method":"settings.get","params":{}} {"type":"response","id":"42","ok":true,"result":{"settings":{}}} {"type":"response","id":"42","ok":false,"error":{"code":"invalid_setting","message":"…"}} {"type":"event","name":"settings.changed","payload":{"key":"fps","value":120}} {"type":"cancel","id":"42"} ``` Request IDs are unique within a core process. Every request has a bounded deadline (100 ms to five minutes). The shell sends cancellation after a timeout or explicit cancellation. Events are delivered in batches through a queue of at most 512 items; overflow drops the oldest event and emits a diagnostic counter. The core admits at most eight RPC workers, with at most four background workers (`catalog.*`, `artwork.*`, and `network.regions.ping`). The remaining capacity is reserved for other methods, including session/control operations. Excess requests receive `busy`; duplicate active IDs are also rejected. Cancellation only tracks active IDs and never frees a worker slot before that worker exits. The Qt client keeps requests rejected with `busy` pending and retries the same ID and payload after 100 ms, doubling the delay up to one second. Retries do not extend the original deadline. Cancellation, shutdown, and process failure discard pending retries. Other errors are delivered to the caller without retrying. Cancelled requests suppress their response. Store page retries/cache traversal and region measurement loops stop at cooperative checkpoints. An already-running blocking HTTP, DNS, or TCP operation is not forcibly interrupted; its existing timeout still applies. Other mutating operations already dispatched are not rolled back. Protocol 5 retains the requirement for the Qt client to acknowledge an accepted successful `session.create` response with `{"type":"ack","id":"42"}` before delivering that response to QML. Cancelled or timed-out requests do not acknowledge late responses. The create worker retains its admission slot for at most ten seconds awaiting acceptance, then the CloudMatch owner deletes an unaccepted fresh allocation with an eight-second HTTP deadline. Fresh creation sends a CloudMatch POST without a follow-up PUT; cancellation after POST uses the same cleanup. PUT RESUME applies only to claims of existing sessions. The receipt does not apply to claims of existing sessions. A create response is not also broadcast as `session.changed`, preventing a late event from reviving a cancelled launch. Cleanup failure retains the seat and its scoped discovery route for explicit retry, blocks another fresh allocation, and reports `session_cleanup_pending`. The failed-cleanup record persists only the seat identity, app/status, trusted control route, original provider/account identity, and error code in `pending-session-cleanup.json`; it contains no tokens or signaling secrets. Discovery surfaces it only to that account. Explicit successful DELETE or not-found clears that exact record, never a different seat. HTTP-success DELETE responses containing an explicit vendor rejection retain ownership. The CloudMatch owner reserves fresh-create admission before endpoint resolution or POST. Concurrent creation, pending handoff, and in-progress cleanup lock contention fail promptly with `session_update_busy`, not the automatically retried `busy` response. Admission is released on every pre-ID error; after allocation the exact seat remains reserved until handoff or compensation completes. Cleanup records are read through a 16-KiB limit plus one overflow-detection byte before parsing, including for corrupt or oversized files. The `session.terminalCleanup.v1` capability adds `session.ended`. The Qt client requires this capability during the handshake so an older packaged core cannot silently retain an ended seat. The JSON protocol version remains 5. After an authoritative, non-resumable `nvst-server` termination, the shell sends `session.ended` with `{sessionId, ownerScope: {userId, providerIdpId}}` from the ended session. This local acknowledgement makes no network request and requires no valid authentication token. It releases only the exact accepted seat whose account and provider match. An extra `ownerScope.generation` is ignored: control reconciliation can change the core generation before the shell consumes its response, but it does not change the remote seat's identity. Pending allocation handoffs and cleanup records are not released. A matching pending handoff returns `session_update_busy` so the shell retries after handoff. The response is `{sessionId, cleared}`; duplicate or stale notifications return `cleared: false` without changing another seat. No `session.changed` event is emitted, so a late acknowledgement cannot clear a replacement session in the shell. The shell blocks another launch until the acknowledgement arrives and retries after transient RPC failure or core restart. Late session snapshots cannot revive the natively terminated seat. Transport EOF and other failures with unknown resumability do not send this request. Raw CloudMatch status 7 is `phase: "finished"`, with a `termination` object containing `source: "cloudmatch-session-status"`, `status: 7`, and `resumable: false`. This proves the seat is terminal, not whether the game exited successfully; no vendor reason is invented. A targeted GET returning HTTP 404 yields `session: null` and a top-level termination with `source: "cloudmatch-http"`, `httpStatus: 404`, `sessionId`, and `resumable: false`. Authentication, invalid payloads, other HTTP failures, empty lists, and native transport closure are not terminal evidence. Recovery first polls the exact seat before claiming it. `session.poll` with `recoveryMode: true` does not broadcast a session change while the recovery owner is deciding whether to claim. Negotiated profiles retain normalized `bitDepth` (8 or 10), CloudMatch `chromaFormat` (0 or 1), and per-component `*Source` fields. `request`, `finalized`, `server`, and `unreported` distinguish present values from omissions. Same-seat partial updates retain previously known components; explicit finalized invalid values are not replaced with saved preferences. Incomplete or unsupported accepted color is rejected before native attachment. Transport terminal events add `termination: {source: "nvst-transport", code, resumable: null}`, preserving unknown cloud-session disposition rather than assigning a normal-exit reason to EOF. Native ABI 13 adds `session-timer` events through the existing JSON event callback, with `startId`, `timerType`, `secondsLeft` and `active`. Idle-warning type 4 shows stream chrome without stopping media; type 5 or successfully delivered gameplay input clears it. Server termination events preserve `wireCode` separately from optional application `reason` and `extendedCode` in `termination`, use source `nvst-server`, and carry a boolean `resumable` only for verified classifications. Nonresumable server termination prevents automatic restart and resume. Unknown classification remains null and is reconciled against CloudMatch. The JSON protocol version is unchanged; the native library and Qt shell must be rebuilt together. Expected, authoritative server endings do not create stream-error incidents or session-error telemetry. Resumable, unknown, and local transport/decode failures retain their existing reporting. Deferred input also preserves the ordering of one bounded, cancellation-aware paste batch. Accepted prefixes are not replayed, later discrete input waits behind text, and cancellation removes only unsent text. Rejected paste admission emits `text-input-error` with `startId` and a fixed `reason`, through the existing ABI 13 JSON callback. It is a nonterminal retry notice, not a stream failure; Qt discards stale generations and shows feedback over the current video item. After a decoder-stall recovery attempt, the native engine allows one further video-timeout interval for decoded output to resume. Output progress or a decoder-epoch change clears that deadline. Otherwise the engine emits `nvst-recovery-exhausted` and a stopped status once, allowing Qt to recover the session instead of leaving silent media connected forever. This does not classify the remote cloud session as ended. ## Implemented core methods ### Game artwork GraphQL-backed game objects expose nullable artwork URL strings: `imageUrl` prefers `GAME_BOX_ART`, `heroImageUrl` prefers hero/banner imagery, and `keyArtUrl` prefers NVIDIA `KEY_ART` with `KEY_IMAGE` as a fallback. Console Home uses `keyArtUrl` for square tiles while retaining hero imagery for wide tiles. If key art is absent, the shell falls back to `imageUrl`, then `heroImageUrl`. Older cached objects and public-catalog games may omit `keyArtUrl`; it is an optional, additive field in protocol 1 and does not change the handshake or existing artwork fields. ### Store pagination (`catalog.storePages.v1`) The protocol-1 envelope and 1 MiB limit are unchanged. This additive capability advertises cursor pagination and separate storefront presentation. The existing `catalog.store.list` method now caps `limit` at 100 (default 100), returning one complete upstream page instead of aggregating thousands of games. Fresh upstream pages request up to 100 games. Existing cached pages may contain fewer games; always follow the returned cursor rather than assuming a full page has the requested count. Request: `{ "limit":100, "cursor":"", "searchQuery":"" }`. Cursor is an opaque string (at most 4096 UTF-8 bytes); search is at most 512 UTF-8 bytes. Response: `{ "games":[], "count":0, "totalCount":0, "hasNextPage":false, "nextCursor":"", "source":"store-browse", "fetchedAt":0 }`. Pass `nextCursor` unchanged to the next call with the same search. A final page has `hasNextPage:false`; empty non-final pages may advance only when the upstream supplies an advancing cursor. Invalid mapped identities are errors. Missing, repeated or oversized continuation cursors are errors, not completion. Each result is limited to 768 KiB after JSON encoding, leaving room for the envelope. Oversized pages are refetched with a smaller count at the same cursor; they are never truncated while advancing the cursor. A single oversized game returns `catalog_response_too_large` without disrupting the core connection. `catalog.store.presentation` accepts `{ "section":"marquee" }` (also `panels` or `filters`) and returns `{ "section":"marquee", "items":[] }`, independently bounded to 768 KiB. Failed/oversized optional sections do not fail game pages. Store pages and presentation results include `cacheHit` (boolean). Successful responses are persisted under the core data directory in `store-cache-v1`, with hashed account/provider/membership/proxy/locale and request keys. Credentials are not stored. Reads remain bounded to 768 KiB; the cache is limited to 64 MiB and 512 entries. Missing or corrupt entries refetch normally. There is no timed catalog invalidation: an optional `refresh:true` on a first-page request clears that account/context's pages and presentation before fetching. Continuations must omit it or send false. Other accounts' entries are unaffected. Concurrent misses for the same cache key and refresh epoch share one successful fetch. Store network requests (including server metadata, presentation fallbacks, and oversized-page retries) are serialized with at least 50 ms between them. HTTP 429 starts a core-wide Store cooldown using `Retry-After` (seconds or HTTP date), or 60 seconds when it is absent or invalid. Uncached requests during the cooldown return `rate_limited` without network traffic; cached responses remain available. The core does not automatically retry a rate-limited request. Server metadata lookups share one bounded, in-memory cache across Store, library, and subscription requests. A successful lookup is reused for five minutes, scoped by provider endpoint, account, and token fingerprint; concurrent callers share the lookup. Ordinary failures use the same context's last known value (or `GFN-PC` when none exists) for 30 seconds before retrying. Rate-limit and cancellation errors propagate instead of becoming cached fallback values. The shell serializes game requests, merges by stable game identity, and retains loaded games and the failed cursor on error. Retries resume that page. Search/account changes cancel requests before clearing state; late responses are ignored. ### Local Store browsing (`catalog.storeLocal.v1`) `catalog.store.local` pages and searches the saved catalog, without replaying every cached page into Qt. It accepts `limit` (capped at 60), `cursor`, `searchQuery`, and optional `genre`, `store`, and `categoryId` strings (at most 256 UTF-8 bytes each). A cursor belongs to its search/filter context and must be returned unchanged. The existing 768 KiB result budget still applies. The result includes `games`, `count`, `totalCount` (matching games), `catalogTotalCount`, `hasNextPage`, `nextCursor`, `source:"store-local"`, `cacheHit:true`, and `cacheComplete`. First pages also include `facets` with all indexed genres, stores, and official categories (`id`, `label`, `count`), not just those present on the visible page. Subsequent pages omit facet data by returning `facets:null`. `categoryId:"all"` selects the entire catalog. The core builds one bounded, account-scoped metadata index from saved pages; full records remain on disk and only selected results are materialized. Search ranks exact titles, acronyms, prefixes, reordered words and single typing errors, with owned games preferred on close matches. Store requests 40 results per page; Ctrl+K uses the same algorithm with a six-result limit and debounced, cancellable requests. There is no automatic catalog crawl. Scroll/navigation demand or Load more requests the next page. A missing/partial cache fetches bounded upstream pages on demand; `cacheComplete:false` distinguishes this from a complete index. On this method, `refresh:true` rebuilds the local index without deleting saved pages. The upstream `catalog.store.list` refresh behavior remains unchanged. `catalog.store.presentation` also accepts `metadataOnly:true`. For `panels`, each section returns its title and `totalCount` with an empty `games` array; the complete panel remains cached in the core. Qt materializes shelf games and artwork only near the viewport, using the section's local category ID (`shelf::
`). See all opens that category in Store. ### Method list - `core.hello` - `app.status` - `settings.get` - `settings.choices.get` - `settings.set` - `settings.shortcuts.update` - `settings.reset` - `auth.providers.list` - `auth.session.get` - `auth.device.start` - `auth.device.poll` - `auth.device.complete` - `auth.device.cancel` - `auth.logout` - `auth.accounts.logoutAll` - `auth.accounts.list` - `auth.accounts.switch` - `auth.accounts.remove` - `auth.pin.status`, `auth.pin.set`, `auth.pin.clear`, `auth.pin.verify` - `catalog.public.list` - `catalog.library.list` returns one bounded upstream page, not an aggregate library. - `catalog.game.get`, `catalog.definitions.get`, `catalog.languages.get` - `catalog.launch.inspect`, `catalog.favorites.list` - `catalog.launch.store.inspect` resolves the eligible Steam store-client launch target. - `catalog.favorites.add`, `catalog.favorites.remove` - `catalog.ownership.add`, `catalog.ownership.remove`, `catalog.ownership.select` - `catalog.store.list`, `catalog.store.local`, `catalog.store.presentation` - `network.regions.list` - `network.regions.ping` - `queue.servers.list` - `account.subscription.get` - `account.connections.list`, `account.connections.sync`, `account.connections.unlink` - `account.connections.sync.status`, `account.connections.sync.cancel` - `account.connections.link.start`, `account.connections.link.poll` - `account.storage.locations`, `account.storage.reset` - `session.create` - `session.poll` - `session.stop` - `session.ended` - `session.active.get` - `session.remote.list`, `session.claim`, `session.ad.report` - `streamer.detect` - `streamer.prepare` - `streamer.start` - `streamer.status.get` - `streamer.stop` - `streamer.input.pause`, `streamer.control`, `streamer.surface.update` - `streamer.recording.start`, `streamer.recording.stop` - `diagnostics.snapshot`, `diagnostics.export`, `acceptance.export` - `media.root.get`, `media.recording.target`, `media.list`, `media.delete` - `cache.delete` - `queue.status.get`, `queue.serverMapping.get` - `thanks.data.get`, `communityProxy.provision` - `updater.state.get`, `updater.check`, `updater.download`, `updater.install`, `updater.startup.ack` - `updater.highlights.get`, `updater.highlights.ack` - `social.capabilities.get` - `discord.activity.sync`, `discord.activity.clear` - `feedback.submit`, `bug_report.submit`, `bug_report.incident`, `analytics.track` ### Usage & bug reports (`automaticBugReports.v2`) `automaticBugReports.v2` replaces `automaticBugReports.v1` and removes `telemetry.sync` and the `optInTelemetry` capability. The core owns every network call: reports go to `POST {base}/v1/reports` and usage events to `POST {base}/v1/events`, where `base` is `https://opennow-reports-production.up.railway.app` unless the `OPENNOW_REPORTS_API` environment variable names another `http(s)` origin when the core starts. One setting, `automaticBugReports` (`unset`, `enabled`, `disabled`), labelled "Usage & bug reports", gates automatic reports and usage events. `unset` means the notice has not been answered and is treated as enabled while OpenNOW is experimental. Loading settings migrates the legacy `errorReportingConsent`: `denied` together with `unset` becomes `disabled`; the legacy key is otherwise inert. `settings.set` for `automaticBugReports` accepts an optional `source` (`signin_notice`, `first_run_sheet`, or `settings`, default `settings`). Every `enabled` or `disabled` write queues one anonymous `consent_changed` event (`account` is `null`) even when the new value is `disabled`. A `disabled` write first deletes the queued events, the event spool, and pending reports; the core does the same at startup when the setting is already `disabled`. #### Reports Every report is multipart form data with a `report` part (JSON, at most 64 KB) and an optional `log` file part (`application/gzip`, at most 5 MB compressed) holding the redacted diagnostics export: ```json {"schemaVersion":1, "automatic":true, "installId":"32 hex", "account":{"userId":"…", "providerIdpId":"…", "providerCode":"NVIDIA", "providerName":"NVIDIA", "alliancePartner":false, "reporter":"Zortos", "reporterBasis":"username", "membershipTier":"ULTIMATE"}, "trigger":{"kind":"frame_drops", "code":"sustained_frame_drops", "message":"…", "metrics":{"droppedFrames":412, "windowSeconds":60}}, "activity":{"currentGame":{"title":"Cyberpunk 2077", "appId":"100"}, "recentGames":[{"title":"…", "appId":"…"}]}, "app":{"version":"1.0.3", "os":"windows", "arch":"x86_64", "gpu":"NVIDIA RTX 4070", "decoderBackend":"d3d11", "channel":"stable"}} ``` Automatic reports carry `trigger`; manual reports set `automatic:false` and carry `manual:{title, description}` instead. `account` is `null` when no account is signed in. `reporterBasis` is `username`, `email`, or `none`. `gpu` and `decoderBackend` come from the latest runtime capabilities the shell sent and may be `null`. The core triggers an automatic report when `session.create`, `session.poll`, `session.claim`, `streamer.prepare`, `streamer.start`, or `catalog.library.list` fails with a code that is not a user action or account state (for example `cancelled`, `stale_account`, or `session_conflict` are ignored). `session.create` also records the launched title in the diagnostics log and the recent-games list attached to every report. The Qt shell reports in-process media problems with `bug_report.incident`: `kind` is `stream_error` or `frame_drops`, `code` is a lowercase identifier, `message` is redacted and bounded, and `metrics` copies only the numeric fields `droppedFrames`, `windowSeconds`, `framesPerSecond`, `packetLossPercent`, `pingMs`, and `decodeTimeMs`. The result is `{accepted:true}` or `{accepted:false, reason}` (`disabled`, `signed_out`, `already_reported`). Each kind and code pair is reported once per core run, at most five reports per run, at least 30 seconds apart. Only a signed-in account triggers automatic reports. Accepted automatic reports upload in the background and publish `bug_report.changed` events with `state` `sending`, then `sent` (with `reportId` and `issueStatus`, for example `investigating`) or `failed` (with `message` and `queued`), plus `kind`, `code`, and the current `game` title. `bug_report.submit` takes `{title (8–120 characters), description (40–12,000), includeDiagnostics}` and returns `{submitted:true, reportId, issueStatus}`. `feedback.submit` takes `{category: bug|idea|other, message (8–4,000), includeSystemInfo}` and sends a manual report titled `Feedback: ` without an account; without `includeSystemInfo` it omits the game activity, GPU, and decoder backend. Both return `{submitted:false, queued:true}` when the upload was queued for retry. A network failure, or an error response whose `error.retryable` is true (or a 408, 429, or 5xx without that field), writes the report and its compressed log to `/reports/pending/`. The core keeps at most five pending reports, no older than seven days, and retries them oldest first after the first sign-in of the next run, stopping at the first retryable failure. A non-retryable error drops the report. #### Usage events `analytics.track` takes `{event, props, uiSurface?}`. `uiSurface` is `desktop` or `console`; the core remembers it for events it emits itself. The shell may send these events, and the core keeps only the listed properties that pass validation (unknown events are `invalid_params`; invalid properties are dropped): | Event | Properties | | --- | --- | | `session_started` | `game_id`, `game_title`, `codec` (`h264`/`h265`/`av1`), `resolution` (`x`), `fps_target`, `hdr`, `decoder_backend`, `first_frame_ms`, `queue_wait_s` | | `session_ended` | `game_id`, `game_title`, `duration_s`, `outcome`, `error_code`, `recoveries`, `video_drop_count`, `avg_fps`, `avg_ping_ms`, `avg_packet_loss_pct`, `decoder_errors` | | `session_error` | `stage` (`create`, `poll`, `claim`, `prepare`, `start`, `stream`, `presentation`), `code`, `game_id` | | `frame_drops_detected` | `dropped`, `window_s`, `game_id`, `decoder_backend` | `outcome` is `clean` when the user ends a session that presented video, `user_stopped` when the user ends it before the first frame, `remote_ended` when the cloud session ends, and `error` when the stream had failed. Codes are `[a-z0-9_]{1,64}`; identifiers are `[A-Za-z0-9_.:-]{1,64}`; numbers are finite and non-negative. `{event:"app_opened", runtimeCapabilities}` is the one exception: the shell sends it once the native runtime handshake finishes, and the core sends `app_opened` once per run with `gpu_vendor` and `package_kind` derived from those capabilities and the installation. The core also emits `signed_in` (`auth.device.complete` with `restored:false`; a restored or switched account with `restored:true`), `game_launch_requested` (`session.create`, from its `appId`, `title`, `store`, and `zone`), `session_error` and `library_load_failed` for the failures that trigger automatic reports, `bug_report_sent` after a report is accepted, and `consent_changed`. Each event gets `app_version`, `os`, `arch`, `ui_surface`, and `channel`. The result is `{accepted:true}` or `{accepted:false, reason}`. Events are queued in memory (at most 1,000; overflow drops the oldest and is logged in diagnostics) and sent as `{installId, account:{userId, providerIdpId}|null, events:[{event, ts, props}]}` batches of at most 100 events every 30 seconds, at 50 queued events, and at shutdown within one second. Failed batches are appended to `/analytics/spool.jsonl` (at most 1 MB, oldest batches dropped first) and resent after the next successful send or at the next start. `diagnostics.export` optionally accepts `embeddedStream.drops` and `lastSessionReport.drops` from the Qt session owner. Each contains the cumulative `videoDropCount` (frames), `audioDiscardedMs` (decoded audio duration), `audioPacketDropCount` (audio packets/PCM blocks with unknown duration), `callbackDropCount` (Qt callbacks), and `otherQueueDropCount` (unclassified items). The core copies only bounded, non-negative numeric counters into the export's `shell` section; it does not export arbitrary caller-provided fields. These counters survive embedded-runtime stop and remain separate from the core's process-streamer snapshot and its legacy mixed-unit `queueDropCount`. `diagnostics.export` also optionally accepts `runtimeCapabilities` from the in-process Qt streamer. The export's separate `nativeRuntime` section preserves allowlisted backend and codec availability, HDR support, and bounded, redacted failure reasons, even before a stream starts. It does not copy arbitrary runtime fields or treat an empty process-streamer snapshot as the embedded capabilities. ### Session resume and reconnect `session.active.get` without hints remains a local-only lookup. After a core restart, Qt can reconcile an existing native stream by supplying `{sessionId, ownerScope: {userId, providerIdpId}}` after authentication is restored. Both hints are required together. The session ID must contain 1–256 ASCII letters, digits, hyphens, or underscores; each owner identity must contain 1–1024 bytes and match the authenticated selected account. An optional old `ownerScope.generation` is ignored because generations are process-local. Caller-supplied endpoints are ignored. Hinted reconciliation discovers the exact seat through authenticated, core-owned provider routes and reads its current state with GET. It restores local control context and ownership without RESUME/PUT, allocation, or native transport changes. An already-owned matching seat returns its current local state. Another seat or owner fails with `session_owner_mismatch`. Successful results use the existing `{session, scope}` shape and publish the current generation in `scope` and `session.ownerScope`, preserving the remote phase without adding `resumePending`. A missing discovery match fails with `session_discovery_failed`; authentication, network, cancellation, and stale-account failures remain errors. Local absence is not termination. Only an exact-seat GET reporting status 7 or HTTP 404 confirms termination. Status 7 includes `session.termination`; HTTP 404 returns `{session: null, termination: {source: "cloudmatch-http", httpStatus: 404, sessionId, resumable: false}, scope}`. Qt keeps the native stream alive while retrying reconciliation errors and resumes ordinary session polling after local ownership is restored. Scope-checked discovery also authorizes exact-seat cleanup if reconciliation is cancelled before active ownership is adopted. A later account generation cannot reuse that discovery to stop a seat. `session.remote.list` checks the selected endpoint and the regions advertised by CloudMatch instead of treating the first empty regional response as authoritative. Discovery deduplicates session IDs and uses at most four concurrent requests, a three-second per-request timeout, a 12-second total budget (including region discovery), and at most 32 regional endpoints. If no sessions were found but a region failed, returned invalid data, or could not be checked within these bounds, the request fails with `session_discovery_failed` rather than returning an empty list. HTTP 401 remains `http_unauthorized` after at most one safe-read renewal; HTTP 403 remains `authentication_required`. A found session can be returned even when another region fails; an empty successful list means all discovered regions were checked successfully. Callers must not create a new session after a discovery failure. ### Provider routing and account scope `auth.providers.list` returns `providers`, `defaultProviderIdpId`, `generation`, and `discovery: {state, message, retryAfterMs}`. Successful discovery is fresh for 15 minutes. A failed refresh retains the last known providers and reports `state: "degraded"`. Without a discovered list, the response includes the restored provider, when present, and an explicit NVIDIA fallback. This fallback is not authoritative discovery. Retries wait at least 30 seconds; HTTP 429 `Retry-After` can extend the wait up to one hour. Qt performs at most three automatic retries. An explicit unknown `providerIdpId` fails with `provider_unavailable` rather than selecting another provider. Endpoint updates reconcile by exact IDP identity. Authenticated catalog and account reads include `scope: {generation, providerIdpId, userId}`. Core reads capture private ServiceId credentials and reject obsolete account/provider generations before publishing. HTTP 401 permits one renewal and one replay of a safe read for the same owner. HTTP 403 does not trigger renewal. Create, claim, account sync/unlink, and storage reset do not replay mutations after an ambiguous response. Authenticated VPC lookup requires a successful server-info response with a nonempty `requestStatus.serverId`. Missing or rejected metadata is an error, not a successful `GFN-PC` library. VPC cache entries are scoped by provider route, account, credential, generation, and proxy, with coalescing within each scope. Library and VPC requests use the same selected proxy. The core does not silently retry a selected proxy directly. Authenticated HTTP clients do not follow redirects. LCARS retains its configured shared endpoint; an Alliance provider ID does not select `GFNPartnerJWT` or invent a GraphQL hostname. GFN service transport failures, including server-info lookup, keep the `network_error` code. When the HTTP client identifies the failed stage, the message ends with `(dns)`, `(connect)`, `(tls)`, or `(timeout)`; the message never includes the request URL or host. When an Alliance (non-NVIDIA) provider's server-info lookup for VPC or region discovery fails at the `dns` stage, the `network_error` message instead says that the provider display name can only be reached from inside its home country and network, asks the user to turn off any VPN, proxy or custom DNS, and keeps the original failure after `Details:`. Library, favorites, store, launch inspection, subscription and region reads share this message; the shell displays it as received. `settings.set` for `region` also requires the current `providerIdpId`. The core atomically updates `region`, `regionProviderIdpId`, and the `providerRegions` map. The metadata fields cannot be written separately. Existing unscoped preferences remain eligible only for NVIDIA. Region overrides must occur in the current provider's server-info list. An unavailable or incompatible override falls back once to that provider's base without deleting the saved preference. Provider and region bases must be HTTPS NVIDIA-grid names without userinfo or nonstandard ports. Arbitrary partner domains require a separate evidenced trust policy. ### Free-tier queue locations `queue.servers.list({})` returns `{locations, recommendedZoneId}`. Each location contains `zoneId`, `title`, `region`, `queuePosition` (nonnegative integer), `etaMs` (milliseconds or null), `lastUpdated` (Unix seconds), `pingMs` (milliseconds or null), `streamingBaseUrl`, and `alternateCount` (the number of other fresh zones folded into this location). Missing mapping entries retain their raw zone ID as the title and a friendly continent name as the region. Mapping failure does not prevent use of valid queue data. Mapping entries marked `nuked: true`, malformed rows, non-NVIDIA zones, timestamps over 15 minutes old, and timestamps more than 60 seconds in the future are excluded. No usable fresh rows, invalid queue payloads, and HTTP failures return `queue_servers_failed`; cancellation returns `cancelled`. The core requests PrintedWaste's public queue and mapping endpoints without credentials, account identifiers, cookies, proxies, or redirects. Each fetch has a five-second deadline and a 256 KiB streamed body limit, with at most 256 input entries and 128 usable zones. Only strict `NP-<3–8 uppercase alphanumeric location beginning with a letter>-<2 digits>` identifiers generate a probe or launch URL: `https://.cloudmatchbeta.nvidiagrid.net/`. Neither provider payload can supply an arbitrary host. Latency uses a TCP warm-up and two TCP connection samples, each bounded to 750 ms across all resolved addresses, with 50 ms between samples. Probes run in batches of at most 32 and check cancellation between samples and batches. DNS resolution has a 750 ms caller deadline, uses at most 32 resolver workers and 32 queued jobs, and returns at most eight addresses per host. Stalled system DNS calls cannot block the caller or spawn additional workers; expired/cancelled jobs are skipped before resolution. `pingMs` is the rounded-up mean of successful TCP samples, excluding DNS, TLS, and server processing. All-failed probes produce null latency, not fabricated ping values. Zones sharing a title and region are grouped. Each primary and the final recommendation prefer measured zones when available, then minimize a normalized 75% latency / 25% queue score. A score winner above 100 ms is replaced by the lowest-latency candidate. Without measurements the shortest queue wins. Ties are deterministic. `recommendedZoneId` always names a returned location primary; that row sorts first, with remaining rows ordered by region and title. The desktop shell presents this selector only for an explicitly known `FREE` NVIDIA membership, not for unknown membership or alliance accounts. `hideQueueSelector` is a persisted boolean preference, default `false`, exposed through the standard settings API and boolean normalization. It does not change the separate region-selector preference. The public queue RPC is unauthenticated and does not itself authorize gameplay or infer membership. For a fresh NVIDIA launch, the shell may pass a selected location's exact `zone` and `streamingBaseUrl` to `session.create`. The core accepts a strict zone and its exact derived URL for the NVIDIA IDP and NVIDIA provider code even when that zone is absent from server-info discovery. This exception does not apply to alliance providers, does not alter persisted region preferences, and does not bypass account scope, catalog eligibility, or subscription checks. All other region overrides retain the provider-discovery rules above. `session.create` requires `catalogAppId` as the parent LCARS identifier, `variantId` as the selected positive GraphQL Int identifier encoded as a string, and `appId` equal to that exact variant ID. `scope` must contain the current `generation`, `userId`, and `providerIdpId`. The core resolves fresh catalog and account metadata and applies the same decision as `catalog.launch.inspect` immediately before allocation. Only `ready` admits a fresh allocation. A decision from an earlier inspection is not a transferable permission. Missing, foreign, or mismatched identifiers do not fall back to another variant or a title. Existing validated seat claims remain separate and never write ownership. `session.create` acquires a single typed CloudMatch admission guard before provider discovery, authentication, or route locks. A concurrent create returns `session_update_busy` immediately instead of waiting to allocate after the first request fails or is cancelled. Pre-allocation failure releases the guard; after an allocation exists, the existing receipt and exact-seat cleanup state continue to prevent another allocation. CloudMatch requests serialize with account changes. An active seat belongs to its exact session ID, user ID, and provider IDP, independently of the account generation. Returning from account A to B to A, clearing caches, or signing in again as A does not revoke A's ownership. New owned-seat operations publish the current generation and retain the core-captured control and media endpoints. An active seat retains its original account for polling and exact-seat cleanup after a switch or logout. If that retained credential expires, `session_owner_authentication_required` asks the user to return to the original account without restarting media. New-account credentials never authorize requests to the retained seat. When the selected account matches that owner, explicit cleanup renews expired ServiceId credentials before issuing DELETE. A rejected DELETE is not automatically replayed. Session results include `ownerScope` inside `session`; Qt distinguishes updates for its existing native session from unrelated old-account responses. Ordinary asynchronous results, discovered seats, and catalog results remain generation fenced. A new allocation's receipt retains its original generation even when the active seat is republished under a newer generation; an obsolete receipt still triggers exact-seat compensation. Qt accepts authoritative terminal status 7 or HTTP 404 for the exact displayed session and its user/provider identity even when the result's generation is old. This exception applies before ordinary response and `session.changed` scope filters. It does not admit stale nonterminal updates, another account/provider, another session ID, or a resumable or non-authoritative termination. Duplicate terminal delivery cannot end a replacement seat. `streamer.prepare` uses the caller's session ID to resolve the current core-owned active seat. Caller-supplied connection endpoints are ignored. The response also returns the owned `session` with its current `ownerScope`, which Qt retains for later session events. Foreign ownership or an unknown seat fails with `session_owner_mismatch`, a non-ready seat with `session_not_ready`, and missing RTSPS endpoints with `session_endpoint_missing`. The existing negotiated profile checks still run. Preparation does not expose OAuth tokens to Qt or alter the native `/rtsp` websocket session-ID authentication. These fields are additive to protocol 5; allocation receipts and exact-seat compensation remain unchanged. `session.create` reports an existing-session limit as `session_conflict`, including CloudMatch status `11`, `SESSION_LIMIT` descriptions, and unified error `4AF1201E`, including structured session-limit responses with HTTP 403. An unrecognized HTTP 403 remains `authentication_required`; HTTP 401 is `http_unauthorized`. Session creation is never automatically replayed. The rejected request never becomes an active local session. The shell should call `session.remote.list` once and offer to resume or end the existing session instead of displaying the raw vendor error or retrying creation. When the create response supplies usable `otherUserSessions` or `session` details, the core normalizes them to the ordinary discovery descriptors and hands them to the next list request without another network lookup. This handoff is account-scoped, consumed once, and expires after 30 seconds; it is not a persistent discovery fallback. The code/message error envelope and protocol version are unchanged. `session.claim` first queries the trusted seat host returned by discovery, including conflict-response handoffs whose create region may not own the existing session. If that host fails for a reason other than authentication, it falls back to the regional endpoint. The shell refreshes the chosen session's descriptor before retrying a failed claim, without substituting another game or silently creating a new session. `session.claim` discovers the session's actual control server, sends the minimal `action: 2, data: "RESUME"` request for a ready, streaming, or paused seat, and returns a session with `resumePending: true` and `phase: "resuming"`. It preserves the stable device identity and existing launch mode; it does not renegotiate codec, resolution, FPS, or bitrate. An initializing (`1`) or resuming (`6`) seat is polled without repeating the mutation. Discovery includes paused (`4`/`5`) and resuming seats so they remain available to resume and reconnect. Finished or unknown states reject the claim. The PUT acknowledgement is not stream readiness. Call `session.poll` until a fresh GET has a successful CloudMatch request status (`statusCode: 1`), session status `2` or `3`, and nonempty native RTSPS endpoints. Only then does the core clear `resumePending` and expose the ready/streaming phase. Transient status `6` continues to report `resuming`; finished or unknown poll states clear `resumePending` and report `failed`. A RESUME response of `SESSION_NOT_PAUSED` (`statusCode: 34`) also proceeds to polling, including on an HTTP error response. Authentication failures and other transport/API failures remain typed RPC errors. Qt polls every 1.5 seconds with only one request outstanding, bounded by 60 polls and a 90-second deadline checked between requests. Native connection recovery first stops the old media transport, discovers the same session ID through `session.remote.list`, then claims/polls it and calls `streamer.prepare` for fresh connection context. It never creates a replacement cloud game or claims a different session. During recovery, `session.remote.list` accepts the active `sessionId` so the core can use its remembered regional service rather than the native server IP. Failed recovery attempts back off up to eight seconds and stop after eight attempts; only a presented first frame resets this budget. Ending the session cancels recovery. A native stop stalled for 30 seconds reports an error without launching another transport over the still-owned resources. An exhausted video SETUP negotiation (`missing-video-peer`) or an explicitly unsupported legacy transport (`nvst-legacy-transport-unsupported`) stops automatic recovery and preserves the original error and owned seat for an explicit retry or stop. These compatibility failures do not trigger another claim of the same seat. For the embedded Qt client, `session.create` also accepts an optional numeric `maxEntitledFps`: the highest frame rate the signed-in membership entitles at the requested resolution, or `0` or absent when that is not confirmed. Qt derives it from the normalized `entitledResolutions` entries it already displays; the core never invents it. The requested frame rate is bounded by the documented resolution ceiling (1920x1080 and 1920x1200 top out at 360 FPS, every other resolution at 240 FPS) and, above 240 FPS, by both a hardware decoder for the selected codec confirmed in `runtimeCapabilities` and an entitlement limit that covers the requested rate. An absent or software-only capability probe and an absent or lower entitlement limit both bound the request to the unconditional 240 FPS ceiling, so the saved preference cannot request the conditional tier without affirmative evidence. This is a necessary condition, not a throughput qualification: the client does not measure decoder throughput, and CloudMatch remains the authority on the finalized profile. Rates snap to 30, 60, 90, 120, 144, 165, 240, or 360 FPS before allocation. Embedded codec limits below can reduce the request further. For the embedded Qt client, `session.create` and `streamer.prepare` accept an optional `runtimeCapabilities` object copied from the in-process streamer's protocol-7 `hello` response. The core filters its available `videoBackends` by the persisted `nativeVideoBackend` preference and resolves codec `auto` to AV1, HEVC, then H.264 for both SDR and HDR (subject to requested color mode) before CloudMatch allocation. This resolution is session-local: the saved preference stays `auto`. Each codec entry may include `colorQualities`, an authoritative array of supported settings values such as `8bit_420` and `10bit_420`. An empty array means no supported color modes. The embedded Linux runtime publishes this field for every codec: Vulkan values come from the attached device's actual decode profiles, while non-Vulkan Linux paths report only 8-bit 4:2:0. The core filters codecs by the requested color mode before both Auto and manual selection, so an HEVC decoder supporting Main but not Main10 cannot allocate a 10-bit session, and the shared Vulkan path cannot allocate 4:4:4. Missing or malformed advanced-color profile information on Linux/Vulkan fails closed; other platforms retain their existing behavior when this optional field is absent. The selected codec and color remain session-local and never downgrade the user's requested color mode. Manual unavailable codecs/backends return `streamer_codec_unavailable` or `streamer_backend_unavailable`, respectively. `streamer.prepare` also validates the negotiated codec on resume; it never changes the codec of an already allocated stream. Older callers without this optional object retain the external-streamer probe path. The additive fields do not change the JSON protocol version or native FFI ABI. ### Windows graphics preference `settings.get`, `settings.set`, and `settings.reset` expose `windowsGpuDeviceId`. The default empty string selects Automatic. Explicit values are opaque device identities, limited to 1024 UTF-8 bytes with no NUL characters. Invalid persisted values normalize to Automatic; invalid writes are rejected without changing the saved preference. Before creating the Qt graphics device, the shell may run: ```text opennow-core --graphics-preferences ``` This mode emits one JSON line, then exits without initializing account, network, catalog, telemetry, or streaming services: ```json {"version":1,"windowsGpuDeviceId":""} ``` It uses the normal data-directory resolution, including `--data-dir`, `OPENNOW_DATA_DIR`, and legacy-directory discovery. The read is limited to 1 MiB and never saves migrations, creates directories, or renames corrupt settings. Missing, corrupt, or oversized input selects Automatic. Qt bounds the subprocess and its output and also uses Automatic if bootstrap fails. Qt resolves the saved identity to a current-boot Windows adapter LUID. The same LUID selects Qt's D3D11 adapter and the native runtime's capability probes; LUIDs are not persisted. A missing saved GPU falls back for that launch without erasing the preference. The settings selector appears only with at least two detected hardware adapters, excluding software adapters. It is on the Stream settings page. Saving a different GPU affects the next application launch, not the active graphics device or session. Adapters are enumerated high-performance first. Before that launch, each adapter is indexed for H.264, HEVC, and AV1 hardware decode profiles at 1920×1080 or 1280×720. Automatic uses the first adapter in that order that exposes one of those profiles. A hybrid laptop whose discrete GPU has no decoder, such as a GeForce MX110 beside Intel HD Graphics 620, therefore uses the integrated GPU instead of failing the session. An explicit saved GPU is still used even when its index is empty. Each settings choice lists the codecs that index found. The embedded streamer's protocol-7 `hello` may include `graphicsAdapters`. The field is omitted when no adapters were indexed. Each entry has `name`, `active`, `codecs` (`h264`, `h265`, `av1`), `h265Main10`, and an optional `reason`. It does not include the adapter LUID. `active` marks the adapter selected for that process. When no hardware backend is available and another indexed adapter can decode, the session error names that GPU and points to Settings → Stream → Graphics processor. Diagnostics copy the same allowlisted fields. ### Recording and replay capture The Qt/native recorder and replay exporter preserve the negotiated source video and Opus game audio in Matroska without decoding or re-encoding. Recording resolution, frame rate and bitrate follow the stream; the retained legacy `recordingResolution`, `recordingFps` and `recordingBitrateMbps` preferences do not configure native capture. `settings.get` / `settings.set` expose `replayBufferEnabled` (default `false`), `replayBufferSeconds` (default 30, clamped to 15–120), `replayBufferMemoryMiB` (default 256, clamped to 64–512), and `shortcutSaveClip` (default `Ctrl+F12`). `streamer.prepare` includes these settings in the session context and maps `shortcutSaveClip` to `shortcuts.saveClip`. Enabling replay and changing its limits apply to the next native session. Disabling it sends `replay-stop` immediately, clears buffered media and cancels an in-progress clip export. These commands use the embedded streamer's protocol-7 JSON payload without changing the C ABI: - Manual `recording-start` uses its command `id` as the recording identity. A `recording-state` terminal event carries that identity as `requestId` and a `state` of `saved` or `failed`. A saved result includes `path`, `videoPackets`, `audioPackets`, and `completion`. Normal completion is `{"kind":"complete"}`. A preserved valid prefix is `{"kind":"cut","reason":"discontinuity"}`, `{"kind":"cut","reason":"queue-overflow"}`, or `{"kind":"cut","reason":"interrupted"}`. A cut stops manual recording and produces a visible early-save notice; it does not start another file or change replay capture. - `recording-stopped` repeats the terminal result and its originating `requestId`; its `id` still identifies the stop command. Qt applies a correlated terminal result once, whether the event or stop response arrives first. A repeated stop returns `recording-not-active` without replacing an earlier cut or failure. Packet-write, trailer, publication, and no-valid-keyframe failures remain failures, not saved prefixes. - Completion metadata and event correlation are additive protocol-7 fields. Qt ignores uncorrelated terminal events and stale recording identities. A missing completion field means ordinary saved output only on an authoritative, correlated stop response. Historical producers without correlated terminal events do not provide the new unsolicited-completion behavior. These fields do not guarantee callback delivery or preservation after a process crash. - The `start` response includes `replayEnabled` for the actual session. - `clip-save` accepts `id` and an absolute `.mkv` `outputPath` allocated by `media.recording.target`. It returns `clip-saving` promptly or a typed error if replay is disabled, not yet decodable, or another export is still running. - A `clip-state` event reports `state` (`saved` or `failed`), `requestId`, `path` and `message`. The shell correlates `requestId` with the outstanding export and ignores completion from a previous session. Cancelled exports do not publish a completed file or a stale success event. - `replay-stop` returns `replay-stopped`. A new session is required to enable buffering again. Replay retains encoded packets with bounded memory, frame count and duration. Clips start on a retained video keyframe, so their length may be shorter than the requested duration. Export transfers the retained buffer to a single worker; buffering rebuilds from a subsequent keyframe within the remaining memory budget. There is no assumed periodic-keyframe guarantee: when a whole GOP exceeds the configured limit, replay returns `replay-not-ready` until a new source keyframe. Capture does not issue periodic keyframe requests that would change stream traffic. Discontinuity or producer contention clears replay history rather than blocking playback or publishing a clip with missing references. There is no additional video encoder or GPU readback. Packet bookkeeping, container muxing and disk I/O still consume CPU and bandwidth; zero CPU usage or zero performance impact is not a supported guarantee. ### HDR session contract `settings.enableHdr` is a persisted boolean with default `false`; HDR requires explicit user opt-in. Qt adds `nativeHdrSupported: boolean` to `params.runtimeCapabilities` on each `session.create` and `streamer.prepare` request. It must describe the actual stream window's current HDR output, including the active monitor, compositor/OS HDR state, and presentation surface support, not merely a GPU or decoder capability. Missing, false, or malformed values deny HDR. This value is transient: `settings.set` rejects `nativeHdrSupported`, the settings loader discards legacy copies, and the core never saves runtime capability results. With HDR enabled, an HDR session needs an available hardware HEVC or AV1 decoder whose `colorQualities` explicitly includes the requested ten-bit profile. The optional per-codec `hdrSupported: true` permits `10bit_420` when `colorQualities` is absent, but does not establish 4:4:4 support. The optional per-codec `hdrColorQualities` array lists verified HDR profiles. When present, it must contain the requested profile; empty or malformed values deny HDR. HDR 4:4:4 requires an explicit `10bit_444` entry in both color-quality arrays. Missing `hdrColorQualities` retains the existing HDR 4:2:0 checks only. Windows reports explicit SDR color-quality lists and HDR support from actual decoded profile fixtures and GPU conversion; it no longer infers advanced formats from an eight-bit codec probe. macOS HEVC HDR and ten-bit 4:4:4 similarly require hardware-required fixture decode and Metal conversion. Linux uses exact attached-device profiles for Vulkan Video. An explicit false or malformed `hdrSupported` denies HDR even if 10-bit profiles exist. A true value never overrides an explicit empty or incompatible `colorQualities` array. Neither setting changes SDR capability filtering. HDR constrains the session-local color quality to ten bits while preserving the selected chroma format and saved SDR color preference. HEVC supports `10bit_420` and `10bit_444`; AV1 remains limited to `10bit_420`. Unsupported color and HDR requests degrade before a seat is allocated instead of failing. The core resolves them in this order and returns the effective `codec`, `colorQuality`, `enableHdr`, `resolution`, and `fps` that CloudMatch and the streamer use: 1. Missing HDR output (`nativeHdrSupported` not `true`) clears HDR. 2. Software decoding resolves to 8-bit 4:2:0 SDR. 3. A 4:4:4 request selects HEVC, replacing Auto or any explicit codec, when the selected backend decodes HEVC at that 4:4:4 profile (or HEVC HDR 10-bit 4:4:4 with HDR). Otherwise the chroma becomes 4:2:0 and the bit depth is kept. 4. HDR that the selected codec cannot decode is cleared. Explicit H.264 is SDR-only. Auto prefers AV1, then HEVC, then H.264 for both SDR and HDR, independent of bitrate and platform. When neither AV1 nor HEVC decodes HDR, Auto continues as SDR. 5. Ten-bit SDR that the selected codec, or every Auto candidate, cannot decode falls back to 8-bit 4:2:0 BT.709. 6. H.264 caps the frame rate at 120 FPS and the image area below 4,953,600 pixels, including explicit requests and Auto with only H.264 decode. Resolution reduction selects the closest aspect ratio among supported settings modes that fit the limits, then the largest image at that ratio. For example, 3440x1440 becomes 2560x1080. 7. AV1 remains eligible for Auto at up to 120 FPS and 5120x2880 pixels. No runtime probe currently confirms higher AV1 frame rates, so explicit AV1 above 120 FPS also caps at 120. 8. Each codec may report `maxDecodeDimensions:{width,height}` in `runtimeCapabilities`. Both values are positive uint32 dimensions. Windows reports the decoder's enforced 4096x2304 envelope; the attached Linux Vulkan device reports the conservative intersection of its advertised color-profile limits; the opt-in MediaCodec bridge reports 2560x1440. Other producers omit unknown limits rather than estimating them. Core reduces oversized modes before allocation using the same closest-aspect rule. It rejects malformed limits or a request with no supported mode within the limits. `session.create` records each applied fallback as a `streamer`/`stream_profile_fallback` diagnostics event. An explicitly selected codec that the selected backend cannot decode at all, an unavailable backend, or a backend that cannot decode 8-bit 4:2:0 with any candidate still fails with `streamer_codec_unavailable` or `streamer_backend_unavailable`. The core never substitutes another codec for an unavailable explicit codec except for the HEVC 4:4:4 rule above. `streamer.prepare` repeats the same resolution against the accepted session; when the accepted codec, color quality, or HDR mode differs from what the current decoder can present, it fails with `streamer_color_unavailable` instead of attaching a mismatched decoder. Accepted native resolution and FPS override current saved preferences on attachment. An accepted mode requiring resolution or FPS normalization fails with `streamer_mode_unavailable`; preflight never changes an already allocated stream's mode. Without HDR, the saved color preference is used, subject to exact hardware profiles and the GFN codec restrictions below. Callers without embedded runtime capabilities cannot request HDR through the external-streamer probe path. CloudMatch receives `sessionRequestData.sdrHdrMode=1` and monitor `sdrHdrMode=1` only for this validated HDR request. `requestedStreamingFeatures.trueHdr=false` remains separate because TrueHDR is the server's AI SDR-to-HDR filter, not native HDR. CloudMatch uses bit-depth/chroma enums `1/0` for 10-bit 4:2:0 and `1/1` for 10-bit 4:4:4. For HDR, monitor `displayData` carries validated output luminance when the current output reports it. `desiredContentMaxLuminance` is the peak in nits; `desiredContentMinLuminance` is the minimum in 0.0001-nit units, rounded after multiplication by 10000. Wayland color-management supplies only this luminance pair. `desiredContentMaxFrameAverageLuminance` is omitted for a pair-only snapshot because Wayland exposes no comparable sustained full-frame value. When the runtime supplies a complete validated optional group, the core also writes its full-frame nits into that field and writes the red, green, blue, and white chromaticities as rounded `xy * 50000` integers in `displayPrimaryX0/Y0`, `displayPrimaryX1/Y1`, `displayPrimaryX2/Y2`, and `displayWhitePointX/Y`, respectively. The official PC client's Bifrost serializer confirms the field order and scales; the mapping from the display's maximum full-frame luminance to the frame-average field is inferred from native struct offsets, not an observed HDR session. Without a validated output snapshot, HDR requests keep the fixed requested-content defaults of maximum luminance 1000 nits, minimum luminance 0, and maximum frame-average luminance 400 nits, matching the Mac native session payload. Those defaults are requested content characteristics rather than measurements of the physical display and are not presented as calibration. SDR sends `displayData:null`. HDR does not invent display primaries or a white point; those fields require validated chromaticities from the current runtime output. The validated snapshot travels from Qt in `runtimeCapabilities.nativeHdrDisplay` as `minimumNits` and `maximumNits` in cd/m², omitting either value the output does not report. Optionally it also carries `maximumFullFrameNits` and normalized floating-point `redX/redY`, `greenX/greenY`, `blueX/blueY`, and `whiteX/whiteY`. The core validates the pair again and drops it when the bounds are not finite, negative, above 10000 cd/m², or not strictly increasing. It accepts the optional group only when every coordinate is finite, within [0, 1], has a valid xy sum and positive y, the primaries form a nondegenerate triangle, and `minimumNits < maximumFullFrameNits <= maximumNits`. Missing or invalid optional fields discard the entire group but retain a valid pair. The snapshot is transient: `settings.set` rejects it, the settings loader discards persisted copies, and the core never saves runtime capability results. Stale snapshots are discarded rather than reused. Qt injects the snapshot only while the current output reports a validated range and removes any caller-supplied or previously injected value when it does not; the core strips any earlier snapshot from the resolved settings before carrying the current capability, so a display change that invalidates the output falls back to the requested-content defaults instead of replaying the previous display's luminance. Claim and resume requests do not carry monitor settings at all, so they cannot replay one either. The normalized server response carries `negotiatedStreamProfile.enableHdr: boolean`. It comes from the returned session's `sdrHdrMode`, then the returned monitor's mode, then the returned session-request mode; missing or unsupported modes mean SDR. An explicit server SDR response wins over saved HDR intent. `trueHdr` is not used to infer accepted dynamic range. Resume preserves that returned mode rather than renegotiating from current settings. The claim request intentionally omits monitor settings and requested streaming features, so its only copied dynamic-range field is the accepted session `sdrHdrMode`. Fresh creation sends the full request in its POST, with the requested session mode, monitor mode, requested-content luminance, and `trueHdr`; only an existing-session claim uses PUT RESUME. Attachment revalidates the session's HDR codec/color profile and current window output, so moving to an SDR display cannot silently resume an HDR stream as SDR. Fresh creation also applies the launched store version's catalog HDR support. When `enableHdr` is on, the window output reports native HDR, and the exact variant that `catalog.launch.inspect` validated for this launch has a `features` array without `hdr`, the core requests that one session as SDR before resolving the embedded profile: the request's `enableHdr` is false, so `sdrHdrMode` is `0`, `displayData` is null, and `trueHdr` stays false. Codec and color selection then run as for any SDR request. The saved `enableHdr` preference is not changed. A variant whose `features` is null (the catalog returned no feature list), a Steam store launch, and every case where HDR was not effectively requested keep the request unchanged; missing metadata never downgrades HDR. The normalized session carries `hdrDowngrade`: `"game-unsupported"` when this core downgraded the request, otherwise null. Polls, resume, and reconnects preserve it only for the same session ID; sessions this core did not create report null. Shells use it to explain the SDR stream and must not repeat the catalog lookup. The session also carries `catalogAppId`, the parent catalog game ID of the launch (`appId` stays the launched store version's CloudMatch ID), with the same same-session preservation; it is null for sessions this core did not create. Shells key once-per-game state on it, so every store version of a game shares one identity. The normalized session also carries `keyboardLayout` when this core created or resumed the session. It records the exact layout sent in the CloudMatch request, not the current saved preference. Polls and ad updates preserve it only for the same session ID; a successful resume replaces it with the newly requested layout. Qt uses this value for physical key mapping, so changing settings during a stream does not change input before the remote layout changes. An unclaimed session whose layout is unknown omits this field. Color negotiation overlays each returned `finalizedStreamingFeatures` field on the server's returned `sessionRequestData.requestedStreamingFeatures`. An empty or partial finalized object must not erase the echoed codec, bit depth, or chroma. Explicit finalized values, including invalid values, take precedence; missing values never come from current saved preferences. CloudMatch chroma enums are `0` for 4:2:0 and `1` for 4:4:4; NVST chroma-format IDs `2` and `3` are not accepted as CloudMatch 4:4:4 values. When present, `session.negotiatedStreamProfile.codec` takes precedence over the numeric feature-map codec. H.264/AVC and H.265/HEVC names normalize to `H264` and `H265`; `AV1` remains unchanged. An explicit null or unsupported codec stays unknown rather than falling back to a requested codec. The request itself names no codec: like the official client, codec selection stays client-side and reaches the seat in the RTSP ANNOUNCE (`x-nv-vqos` bit-stream format), so a negotiated codec is only ever server-reported (echo, finalized features, or a direct profile). When the server omits every codec field, downstream stages resolve the codec from current saved preferences instead. Polling, direct-server responses, claims, and ad updates preserve that evidence only for the same session ID. `codecSource` distinguishes `request`, `server`, and `unreported`; a reported codec supersedes the request and remains authoritative in later partial responses. Unknown discovered sessions never borrow a codec from current saved preferences. Preparation failures log bounded codec/color evidence and a redacted reason, never the full session or credentials. Embedded session preflight rejects H.264 with advanced color and AV1 with 4:4:4 before allocation, even if a decoder capability lists those formats. These combinations are not requested by the supported GFN wire policy. Auto selects HEVC for 4:4:4 rather than silently reducing chroma; an explicit incompatible codec remains an error. The native context preserves the resolved profile and codec provenance. Its accepted `enableHdr` initializes the native HDR mode (missing means false). Invalid accepted HDR profiles are rejected before stream startup. NVST ANNOUNCE states color explicitly on every session using literal bit depth `8` or `10` with `chroma_format_idc` (`chromaFormat=1` for 4:2:0, `3` for 4:4:4); `dynamicRangeMode=1` is sent for HDR only, and SDR omits the line. This matches the vendor capture of a `10bit_420` session (`bitDepth:10 chromaFormat:1`) and the working third-party reference clients: a lone `bitDepth` line is never sent, because seats cannot initialize an encoder from an incomplete color spec. The internal 0/1 chroma value from the client's app-to-NVST conversion is mapped back to idc at SDP emission and never reaches the wire. CloudMatch keeps its own bit-depth enum (`0` or `1`) with chroma `0`/`1`. The ANNOUNCE also carries the encoder identity the seat reads before initializing (`maxCodecProfile`/`maxCodecLevel` and the `maxH264` pair, profile 3 / level 61, as captured). One resolved configuration feeds the wire values, the media runtime, and the decoder, so a server color choice cannot leave the decoder expecting a different format. The stored CloudMatch profile and user preferences are not rewritten. Full SDP must not be logged because it contains ICE credentials and encryption material. After an update check, `updater.highlights.get` returns the latest published release notes for the selected channel, even when that release is equal to or older than the installed app. Its `version` and `title` identify that published release, independently of `updater.state.get.availableVersion`. Historical notes do not emit `updater.highlights.show` or enable downloading a downgrade. Missing release bodies and empty channels return an explanatory note instead of the pre-check placeholder. Updater preferences are independent. `autoCheckForUpdates` defaults to `true`; `autoDownloadUpdates` defaults to `false` and requires an explicit opt-in. Neither preference authorizes installation or application shutdown. New profiles use the nightly update channel when the embedded application version has a `nightly` prerelease identifier; existing persisted channel choices are preserved. `updater.install` requires the boolean parameter `confirmed: true`. The core serializes update preparation against session creation, claiming, polling, and streamer startup. It rejects installation while a CloudMatch session exists or the streamer is starting, negotiating, streaming, or recovering. The shell must also check its local native-runtime state before requesting installation. `updater.state.get` is authoritative after an error or request timeout. The core emits `updater.changed` after update operations even if the original request was cancelled, because cancellation does not undo an installation already prepared by the native helper. While `updater.download` runs, the updater state carries the additive field `downloadProgress: {"receivedBytes": n, "totalBytes": n}`, where `totalBytes` is the signed asset size. It is `null` in every other state. The core emits `updater.changed` when the download starts and each time the received bytes cross another whole percent of the signed size, so a download produces at most about 101 progress events before its response. Progress is advisory: hash and size verification still decide whether the download succeeds. Clients must not synthesize `canDownload`, `canInstall`, or `canCheck` from an error message. A failed check or a later release check does not discard an already verified download. Inside Flatpak, the updater reports `status: "unsupported"` and `updateSource: "flatpak"`. `canCheck`, `canDownload`, `canInstall`, and `exitRequired` are false. `updater.check` returns that state without contacting GitHub. Download and install requests fail with the package-manager instruction in `message`. The core does not recover native update transactions inside the sandbox, and the native update helper rejects execution there. Flatpak owns package replacement and updates. The additive updater state fields `exitRequired` and `installVersion` describe the prepared installation, separately from `availableVersion` and `downloadedVersion`. The shell may quit for an update only after a confirmed install request in that same shell process, with authoritative `status: "awaiting-exit"` and `exitRequired: true`, and while the local session remains inactive. `preparing`, `applying`, and `restarting` are not permission to quit. Terminal outcomes are `succeeded`, `rolled-back`, and `failed`; `managed-pending` and `reboot-required` require native package-manager or operating system completion. Spawning an installer or the replacement application never counts as success. On a later launch, the core reconciles these managed outcomes against the native package registration and its running version. A known live installer keeps `managed-pending` active. A completed installer resolves to `succeeded` or `failed`, and the core clears the persisted active transaction. Terminal helper outcomes (`succeeded`, `rolled-back`, `failed`) are likewise reported for that launch only; the core clears the persisted transaction after the first reconciliation so the same failure dialog does not reappear on every restart. An MSI reboot warning remains until Windows' per-boot sequence number changes. Sessions remain available, but another update must wait for the required reboot so it cannot overlap pending Windows file replacements. Reopening the app before reboot does not count as successful installation. If an installer process cannot be identified, the core keeps the transaction pending until a recorded boot change proves that the previous installer has stopped. Legacy transactions without a boot marker establish a baseline and may require one additional restart rather than guessing that installation finished. Windows portable replacement requires a volume with persistent ACL support; FAT/exFAT installations are refused before shutdown because private staging cannot be enforced there. Preserved portable profile data retains its ownership and effective access permissions. Preparation also fails before shutdown if the replacement overlaps user data or exceeds the bounded copy limits. MSI packages use Windows Installer registration and preserve the registered installation root; they are not treated as portable directories. `updater.startup.ack` accepts no parameters and returns `{ "acknowledged": true }` only for a valid helper-launched update attempt. A normal launch returns `acknowledged: false`. The shell calls it after its UI and core connection are ready. The core validates the prepared version, per-attempt nonce, and running Qt application identity before acknowledging startup to the waiting helper. These changes are additive within protocol version 1; they do not change the native streamer ABI. `updater.highlights.show` announces unread release notes, not a navigation command. The shell keeps the current stream and its video item alive, defers the announcement during sessions, and acknowledges the notes only when the user opens them. Setting `themePack` applies its default appearance (`light` for Bone/Cobalt, `dark` for the other built-in packs) and clears `themeAccentOverride` in the same save. Setting `appAccentColor` enables `themeAccentOverride` in the same save. The `settings.set` response and `settings.changed` event include these coupled values in `changes`; clients can still override appearance or restore the pack accent by setting `appTheme` or `themeAccentOverride` independently. `settings.shortcuts.update` writes stream shortcut bindings as one transaction: `{"bindings":{"shortcutToggleStats":"Ctrl+F11","shortcutScreenshot":""}}`. Only the existing `shortcut*` setting keys are accepted, each value is a string of at most 80 bytes (empty means unbound), and `Ctrl+G` and `Shift+F3` stay reserved. After the change is merged, no two non-empty bindings may share a chord (case and modifier order are ignored). Any rejection leaves every binding unchanged. The core persists the whole map in one save and rolls it back in memory if the save fails. The response is `{"bindings":{...applied}}`; the `settings.changed` event names the first applied key and carries the full map in `changes`. Qt uses this for moving a chord from one command to another, clearing, resetting one binding, and resetting all bindings. Each successful settings write publishes `settings.changed` before its own response. A client that starts its next per-key write from that response has already consumed the previous event. Other response/event pairs, including `settings.reset`, retain their existing response-first order. Qt delivers `settings.changed` before the corresponding response rather than deferring it through the general event queue. The settings owner serializes writes per key, keeps ordinary controls optimistic, and retains a confirmed snapshot for failure rollback. Later edits use the latest intended value; a failed queued tail restores the last confirmed value and its coupled changes. Confirmation-sensitive settings and collection callbacks retain their existing behavior. Settings writes use a temporary file plus recoverable backup and normalize compatibility-sensitive values. `audioOutputDevice` is an opaque native output identifier (at most 1024 UTF-8 bytes, without NUL characters); an empty string follows the system default. It is persisted and passed unchanged in the prepared stream context for the next session. A missing fixed output fails playback startup instead of falling back to another device. Setting `launchInConsoleMode=false` atomically sets `switchToConsoleOnPad=false` too, so a manual desktop choice survives restart. That response and `settings.changed` event additionally contain `"changes":{"switchToConsoleOnPad":false}`; consumers apply these coupled values before the primary key. Automatic console switching defaults off. Existing pre-opt-in settings receive a one-time reset of automatic switching only; explicit subsequent opt-ins and the independent startup preference are preserved. Existing microphone device selections are cleared only when explicitly selecting Open microphone; that write likewise reports `"changes":{"microphoneDeviceId":""}` so the shell follows the system-default capture selection. Setting `colorQuality` repairs an explicitly saved `codec` (or `fallbackCodec`) the new color mode cannot use toward `auto` in the same save — H.264 is 8-bit 4:2:0 only, AV1 is 4:2:0 only — and reports the repair in `changes`. Explicit `codec`/`fallbackCodec` selections the saved color cannot use are rejected as `invalid_setting` instead; unknown spellings still clamp to Auto. `onboardingCompleted` is a persisted boolean, defaulting to `false` for a new profile or an unreadable or malformed settings file. A valid existing settings JSON object without the key migrates to `true` and is saved during loading, so upgrades do not trigger first-run setup. Explicit `false` and `true` values survive reloads and unrelated writes, including startup preferences and window geometry. Non-boolean values normalize to `false` under the standard settings type rules. `settings.reset` preserves the current completion value while resetting preferences; it does not replay onboarding for an existing user. Failed saves leave the previous in-memory value and persisted settings unchanged. `gameCollections` defaults to `[]`. `settings.set` replaces the complete ordered array with at most 100 objects of the form `{"id":"collection-id","name":"Collection name","gameIds":["game-id"]}`. Collection IDs are caller-owned stable strings, unique across the array, and must not be regenerated when renaming a collection. IDs are preserved verbatim, must contain a non-whitespace character, and are limited to 128 Unicode characters. Names are trimmed and must contain 1–80 Unicode characters after trimming; names need not be unique. Each `gameIds` array contains at most 10,000 unique strings with the same nonempty/128-character ID constraints. Game IDs may appear in multiple collections, and empty collections are allowed. Array order is preserved. Malformed types, missing or extra fields, duplicate IDs, or exceeded limits return an error without modifying the in-memory settings or persisted file. Save failures also restore the previous in-memory settings, including when resetting settings. Reloads trim valid persisted names and preserve collections across unrelated writes; invalid persisted collections cause an `InvalidData` load error before any write, rather than silently dropping collections or truncating identifiers. A successful `settings.reset` clears collections along with other preferences. `controllerLeftStickDeadzone`, `controllerRightStickDeadzone` (integers 0–50, default 5) and `controllerVibrationIntensity` (integer 0–100, default 100) stay the global controller tuning and the default for every pad. `controllerProfiles` defaults to `{}` and holds per-pad overrides keyed by pad identity. Qt builds the key as `serial:::` (four-digit lowercase hex vendor and product IDs) when SDL reports a serial number, and as `guid:` otherwise. Two identical pads without a serial therefore share one key and one profile. Each value has the form `{"name":"DualSense","leftStickDeadzone":8,"rightStickDeadzone":5,"vibrationIntensity":70,"lastSeen":1760440000000}`. Every tuning field is optional; a missing field means the global setting applies. `settings.set` replaces the whole map and normalizes it rather than rejecting it: keys are trimmed and must hold 1–160 characters; tuning fields that are not integers are dropped and integers are clamped to the global ranges; `name` is trimmed to at most 80 characters and dropped when empty; `lastSeen` (Unix milliseconds) defaults to 0. Entries that are not objects or keep no tuning field are dropped, so deleting a pad's fields resets it to the globals. At most 32 profiles are kept, preferring the highest `lastSeen`. Non-object values normalize to `{}`. Settings saved before this key existed load with `{}`, and `settings.reset` clears it. These values apply live in Qt before input reaches the streamer; they never require a new session. Provider discovery falls back to NVIDIA's default service when discovery is unavailable. Device-login tokens are stored through the OS credential store (DPAPI/Credential Manager, Keychain or Secret Service), with an explicit memory-only fallback when that facility is unavailable; the shell never receives a password. Public catalog results are cached in the core process and bounded per response. CloudMatch session methods preserve one client/device identity through create, poll and stop, retain pending queue responses before signaling is available, and return the complete ordered connection, ICE and negotiated-feature payload needed by the native streamer. `streamer.prepare` returns the normalized session context used by the native runtime linked into the Qt shell. The in-process runtime owns secure NVIDIA signaling, ICE/DTLS/SCTP, RTSPS, Mjolnir, RTCP and native gameplay input, while Qt owns the graphics device, scene graph, video item and all top-level windows. Legacy streamer lifecycle methods remain protocol compatibility routes and are not used by the Qt shell. `webrtcCompatibilityMode` selects `auto`, `on`, or `off` for new allocations. The default `auto` uses WebRTC for a detected, authenticated alliance provider and NVST for NVIDIA. `on` explicitly selects WebRTC for either provider; `off` selects NVST. Provider selection is resolved in the core before codec validation and allocation, not inferred by Qt or changed after allocation. The UI calls it **WebRTC compatibility mode** and warns about lower performance than NVST. An older `allianceWebrtcCompatibility: true` preference migrates to `on`; the old default `false` migrates to `auto`. The historical boolean remains a compatibility alias for explicit on/off writes. Session ownership and authentication remain required. Legacy persisted `transportMode` values still normalize to `nvst`; only the core-owned session's transport selects the embedded WebRTC path. An explicit H.265 selection preserves the requested resolution and frame rate, subject to the normal allocation and decoder checks, and supports 8-bit or 10-bit 4:2:0 SDR. Both WebRTC and NVST CloudMatch requests use `requestedStreamingFeatures.bitDepth: 1` for 10-bit and `0` for 8-bit, rather than the literal media bit depth. The owned session profile carries the selected codec through polling, restart, and attachment; changed preferences cannot reinterpret an existing stream. H.264, Auto, and AV1 selections retain the H.264 compatibility profile, at most 1920×1080 at 60 FPS with 8-bit 4:2:0. Both WebRTC codecs use SDR, stereo, and no microphone. WebRTC startup rejects profiles outside the native runtime's dimensions or frame rate bounds rather than substituting a different viewport in its SDP answer. WebRTC signaling endpoints remain separate from RTSPS endpoints, including their server-provided paths and ports. The native runtime owns the WebSocket offer, answer, NVIDIA quality SDP, and ICE exchange. It delivers compressed media to the existing decoder and GPU presentation path. The setting does not authorize a live NVST seat to be converted, deleted, or replaced. For an owned WebRTC allocation that supplies only legacy RTSP descriptors, the core derives `wss:///nvst/` on port 443, matching Android's WebRTC signaling contract. It does not reuse the RTSP port as a WebSocket or UDP media port. Explicit WebSocket descriptors take priority and keep their paths and ports. `prepare_endpoints` diagnostics record bounded descriptor types and numeric protocol/port fields, never hosts, URLs, session IDs, or credentials. WebRTC offers may contain additional microphone or inactive media sections. Negotiation keeps their order and MIDs, disables RTP upload, and accepts one incoming video track matching the selected H.264, H.265 Main, or H.265 Main10 profile and at most one incoming Opus audio track. Unsupported microphone codecs are rejected in place with valid SDP format identifiers rather than rejecting the whole session. Offers remain bounded to eight media sections. The `webrtc-offer` diagnostic records section kinds and directions without SDP credentials. Keyframe feedback uses the transport's negotiated video MID. For an `actpass` offer, the native client takes the active DTLS role and sends ClientHello, matching browser behavior against NVIDIA's ICE-lite endpoint. Explicit active or passive remote roles retain their complementary local role. Connection diagnostics distinguish ICE completion from DTLS establishment and record redacted candidate classes, ports, and packet-family counters without addresses, credentials, or payloads. The Qt video item remains visible while the native backend is connecting, including reconnect attempts, so it can create the graphics context before the first frame. Gameplay focus/input still waits for streaming; startup overlays may cover the same video item without preventing presentation initialization. `acceptance.export` is available only through the Qt shell's Diagnostics screen. It rejects headless window systems and writes an atomic, redacted `opennow.live-acceptance` JSON file. The file records machine-observed ten-minute streaming, first-frame, guide/input ownership, surface, microphone, recording, hashed media, bounded recovery and terminal-error checks. It contains no account identifiers, session identifiers, URLs, process identifiers, executable paths or local media paths. A false check is retained as evidence of an incomplete run; it is never promoted to a pass by the release verifier. Network work runs outside the protocol reader with a fixed concurrency ceiling, connect/request deadlines, one serialized output writer and best-effort response suppression after cancellation. The full Electron API inventory remains tracked in [the machine-readable parity manifest](../native/opennow-core/contracts/legacy-open-now-api.json), validated against its [JSON schema](../native/opennow-core/contracts/legacy-open-now-api.schema.json) and executable golden-fixture tests. A method is not considered ported until its owner, wire shape, fixtures and replacement disposition are recorded there. ### Push invalidation capability Protocol 5 advertises `account.pushInvalidation.v1` when the core ships the native push subscriber. The capability only describes the accelerator below; the shell must keep working when it is absent. The core may open a native FCM/PNS subscription for the signed-in account. The subscription is provider-scoped and bounded: it exists only while an account is signed in, and it is torn down or paused on sign-out, account switch, or shutdown. `push.json` in the data directory is an optional override, never required. When it is genuinely absent, the core uses a bundled default built from the vendor's public client identifiers (see provenance below). When it is present, it always wins: the core never falls back to the bundled default for an existing override. The override is either a single object or an array of objects, each with `providerIdpId`, `projectId`, `apiKey`, `senderId`, `appId`, `firebaseAppId`, optional `vapidKey`, `pnsServer`, optional `pnsVersion`, and `pnsClientId`, plus an optional `enabled` boolean. The entry whose `providerIdpId` matches the signed-in provider is the only one used. A present override suppresses the default when it disables push (`"enabled": false`, whole-file or per entry), is unreadable, malformed, or larger than 64 KiB, or carries no complete entry for the signed-in provider. The override file is read-only deployment input: the core never writes it, never logs it, never returns it from `settings.get`, and never stores it in the user settings schema. The bundled default contains only public client identifiers: a Firebase web API key, app, project, and sender identifiers, the VAPID public key, and the PNS client id and server. It carries no credentials and the core never writes it to the data directory. Per-account and per-device secrets — the ECE key pair, the auth secret, and the GCM/FCM tokens — are generated locally and stay in the OS credential store, and the PNS bearer token is the user's own sign-in token. The default is bound to the authenticated provider and generation snapshot by the same owner guards as an override, so it is re-evaluated on account and provider changes. Whether the PNS backend accepts registrations for providers other than the vendor's own is unverified; the bundled default mirrors the vendor client's authenticated-account gate and does not claim guaranteed acceptance. The bundled default derives from the vendor's public client configuration asset (`shared/assets/config/config.json` inside the official package, SHA256 8e7db09026e5b48b0eabb364395c726543fcab9778b3561529fcb6a96208db65; official package archive SHA256 47ddbe0425b9ab560f64fa42a0052794c9de335ded0fd59637f082dd7a161ad4), mapping `firebase.pns` to the Firebase identity and `pnsServerConfig` to the PNS endpoint. A subscription delivers invalidation hints only. Each hint is emitted as an ordinary event envelope: ```json {"type":"event","name":"account.push.changed","payload":{"generation":7,"kind":"library","changedIds":["app-id"]}} ``` `kind` is one of `library`, `favorites`, `subscription`, `linked-account`, or `platform-sync`. `generation` is the GFN state generation the hint belongs to; a shell drops hints whose generation does not match its current account generation. `changedIds` is bounded and advisory. Hints never assert a result. `platform-sync` carries the store's reported `platformCode`, `syncState`, `syncDate`, and `syncGameCount` and only makes the shell observe the existing sync earlier; completion still requires a fresh `syncDate` with `syncState` `SYNC_SUCCESS` from `account.connections.sync.status`. A hint that arrives while its account is no longer current is discarded, and a subscription never serves another account's registration. Push registration state is per account and stored in the OS credential store. No token, key, or message body is written to settings, diagnostics, or logs. The subscriber uses only deadline-bounded network operations, and a configuration change, sign-out, or account switch retires the current subscription before another one starts. Every registration stage is guarded between requests, so a retired scope or shutdown stops the remaining stages after at most one in-flight request deadline. A refused MCS login (a non-zero `LoginResponse.error.code`) is a session failure, not a credential verdict: it triggers one bounded registration refresh that keeps the stored device identity and replaces only the registration keys and tokens. A `LoginResponse` that carries a zero error code is accepted as a successful login. The device identity is replaced only when the check-in authority rejects it with HTTP 400 or 401. Every received frame counts toward the `last_stream_id_received` the session advertises. The session acknowledges incoming heartbeat pings, answers an immediate-ack data message or every ten unacknowledged persistent messages with an IQ stream acknowledgement (`extension id` 13), and honours the heartbeat interval the server negotiates through `LoginResponse.heartbeat_config` within bounded limits. A heartbeat that stays unanswered past the acknowledgement deadline, or a login request without a response within its deadline, ends the session so the owner reconnects with the stored registration rather than holding a half-open connection. Encrypted bodies are selected the way the maintained client selects them: a declared `content-encoding` of `aes128gcm` uses the RFC 8291 body header (salt, record size, key id), `aesgcm` uses the legacy `Crypto-Key`/`Encryption` headers, any other declared value is rejected, and an absent declaration falls back to the legacy headers when both are present and to the RFC 8291 body otherwise. This follows Chromium's `components/gcm_driver/crypto/gcm_encryption_provider.cc`, where `content-encoding` is the `kContentEncodingProperty` discriminator and the legacy path is keyed on the presence of both `Encryption` and `Crypto-Key`. No ciphertext shape is guessed: an unsupported declaration is an error, not a heuristic. Live delivery remains unverified. The subscriber ships complete in code with the bundled default and is covered by fixtures, but no live Google check-in, c2dm, FIS, FCM, PNS, or end-to-end encrypted delivery has been exercised, and hardware and account-backed validation are out of scope for the fixture path. ### Catalog page and metadata capabilities Protocol 4 requires `catalog.libraryPages.v1`, `catalog.metadata.v1`, `account.syncObservation.v1`, and `catalog.languages.v1` in the core handshake. The Qt client and both relocated package probes check these capabilities. The JSON envelope and native streaming ABI do not change. `catalog.library.list` accepts `limit` from 1 to 100, an opaque `cursor` up to 4,096 bytes, and a `traversalId` up to 256 bytes. Continuations must carry the `catalogRevision` and opaque `catalogContext` returned by the first page. The context binds the cursor to the provider, account, generation, endpoint, resolved VPC, proxy route and locale. Results contain `games`, `count`, nullable `totalCount`, `hasNextPage`, `nextCursor`, `fetchedAt`, `freshness`, `traversalId`, `catalogRevision`, `catalogContext`, and the authenticated `scope`. One result is at most 768 KiB. Oversized pages are retried at the same cursor with a smaller count; a record that cannot fit is an error. Invalid identities or missing pagination state are errors, not an empty complete library. CatalogState stages these pages and detects cursor cycles. A complete library means the traversal reached a validated end; it does not imply a transactional snapshot of concurrently changing vendor data. Refresh preserves the previous complete snapshot until the new traversal ends. The foreground slice is 30 seconds, with an explicit Continue action. The hard aggregate bounds are 20,000 games and 32 MiB of conservative serialized-size accounting. Partial/error results retain usable data, the failed cursor where safe, and the error text. `catalogLastCompleteAt` changes only when the aggregate traversal completes. `catalog.game.get` accepts exactly one `appId` or `variantId`. The former is a parent LCARS string; the latter must fit a positive GraphQL `Int`. The request selects library-aware metadata and verifies the returned identity. It always revalidates rather than authorizing from cached browse cards. The result has `game`, `catalogRevision`, `scope`, `fetchedAt`, and `freshness`. Game variants retain nullable `librarySelected`, `libraryStatus`, `playStatus`, `installed`, `subscription`, `gfnStatus`, `stateDetails`, `paymentModels`, `subscriptions`, and `supportedLanguages`. Patch details distinguish automatic patches, manual patches, maintenance, and unknown types. Games retain app-level `favorited`, `catalogSkuStrings`, `campaignIds`, and fallback `paymentModels`. App availability, favorites, payment models, and GFN membership do not establish ownership of another variant. Visible detail metadata refreshes every 30 seconds; patch duration history is an estimate, not a promised completion time. Every game variant also carries `features`, an array of lowercase strings parsed from the variant's `gfn.features` key/value list: `rtx` from `RTX_ENABLED`, `hdr` from `HDR_ENABLED` or a non-empty `SUPPORTED_HDR_VERSION`, and `reflex` from `REFLEX_ENABLED`. Disabled, null, and unknown keys produce nothing, so the array is empty when the catalog does not declare a feature. `features` is null when the catalog response carried no feature list for that variant, so consumers can tell unknown from none. The catalog has no per-game DLSS key, so the core, and only the core, derives a game-level `dlss` field from NVIDIA's published DLSS games list (the JSON behind NVIDIA's RTX games page) by title. Shells still must not infer features from titles or genres themselves, and a `"dlss"` string in a variant's `features` means nothing. While the list is loaded, every game in every `catalog.*` result carries `dlss`, including `catalog.public.list`, `catalog.library.list`, `catalog.game.get`, `catalog.launch.inspect`, `catalog.launch.store.inspect`, `catalog.favorites.list`, the favorites and ownership mutation results, `catalog.store.local`, `catalog.store.list`, and `catalog.store.presentation`. The value is either null (not on NVIDIA's list) or: ```json {"superResolution":"native","frameGeneration":"override", "multiFrameGeneration":{"maxMultiplier":4},"rayReconstruction":null, "dlaa":"override","source":"nvidia-rtx-games-list"} ``` `superResolution`, `frameGeneration`, `rayReconstruction`, and `dlaa` are `native` when the game supports the technology itself, `override` when a DLSS override acts on it (the list's "NV, …" cells: an upgraded SR/RR/DLAA or frame generation model, or DLAA enabled through the SR mode override), and null when the list does not show it. `multiFrameGeneration` is null or the highest multiplier an override enables. `dlss` is null when the title has no match and when the matched row lists no DLSS technology. When the list is unavailable, games have no `dlss` key at all: an absent key means DLSS support is unknown, and shells must not present it as "not on NVIDIA's list". Matching removes ™, ®, ©, and zero-width characters, folds the title to ASCII with NFKD, lowercases it, spells `&` as "and", and collapses every other non-alphanumeric run to one space. An exact match wins; otherwise a loose match also drops the words "the" and "tm" and trailing edition words (game of the year, goty, definitive, enhanced, complete, deluxe, standard, ultimate, director's cut, anniversary, edition, pc). "Remastered" is never dropped, because remasters are listed separately. Only rows of type "Game" count. The core keeps the list in the store cache for 24 hours (stale copies are used when a refresh fails), rejects documents over 4 MiB or 5,000 rows, and applies it when a catalog response is sent, so cached catalog pages are unaffected and the scope stays `catalog-v3`. Fetching never fails or holds a catalog response: only one request waits for the core's first attempt, for at most 1.5 seconds; a failed attempt retries on a catalog request at least 60 seconds later. The field is additive within protocol version 5. Every game also carries `requiresPaidMembership`, true when the catalog's `minimumMembershipTierLabel` names a tier other than Free (the catalog reports `Premium` today). It is the rule the core applies before a launch, so shells compare it with the account's `membershipTier` instead of parsing the label. Both fields are additive within protocol version 5; store-catalog cache scopes moved from `catalog-v2` to `catalog-v3` so cached cards are refetched with it. `catalog.definitions.get` returns independently fetched `stores`, `genres`, and `subscriptions` sections. Each section has `items`, `source`, `status`, `freshness`, `fetchedAt`, `expiresAt`, and nullable `error`. Static definitions expire after 24 hours. Store definitions retain the feature union and per-variant linking metadata. They drive account rows and allowed actions. Unknown stores are display-only; unavailable definitions use labelled, action-disabled fallback rows. A current server `supported:false` overrides older capability data. Store subscription IDs are separate from MES/GFN membership. `catalog.store.presentation` retains parsed filter expressions and `sortOrders`. `catalog.store.list` can receive a `filterId` or `sortId`; the core resolves these to the returned server expressions rather than sending an ID as a filter object. `revalidate:true` invalidates only the addressed page key; use it for an explicit search submission rather than `refresh:true`, which resets a browse chain. Local Store facets remain local. `catalog.store.local` returns `localHasNextPage`, `cacheComplete`, `upstreamCoverage`, and `facetsSource` alongside its existing demand-driven cursor. Local exhaustion does not prove upstream coverage. Browse disk pages expire after 15 minutes, and explicit local refresh first revalidates the upstream first page before rebuilding the index. Confirmed account changes persist an increasing catalog revision, so old pages cannot join a new traversal or reappear after a core restart. Failure to persist the revision is an explicit cache-invalidation error, not completion. Cache identities include provider/account, generation, endpoint, resolved VPC, proxy route, locale and schema revision. ### Store synchronization observation `account.connections.sync` sends one ALS POST and accepts only HTTP 202. It returns `operationId`, `provider`, and a local `phase`. Repeated starts for the same active provider return the existing operation instead of repeating POST. There are at most eight account-scoped operations. Mutating requests are never automatically replayed after a 401, timeout, cancellation, or ambiguous send. `account.connections.sync.status` accepts `operationId`. Each poll reads fresh `userAccount` at most once. Calls are spaced at two seconds initially and five seconds after 20 seconds, with a 120-second observation deadline. The operation records the baseline date and state. Only a changed valid RFC3339 `syncDate` with `SYNC_SUCCESS` enters `refreshing_library`; unchanged old success, an unchanged old failure, and changed counts alone do not prove completion. New failure, disconnection, and expiry enter `failed`. Missing completion evidence ends as `timed_out`, meaning completion is unconfirmed. After `refreshing_library`, Qt starts the final library traversal. Only a complete traversal displays completion and acknowledges it with `sync.status({operationId, libraryRefreshed:true})`. Partial refresh retains a separate incomplete notice. `account.connections.sync.cancel` stops observation, not accepted remote work. Account/provider generation changes clear pending work; late results cannot complete another account's operation. Polls do not sleep across their observation lifetime or hold authentication or scheduler locks across HTTP. Link callbacks and unlink acknowledgements require a fresh account read before claiming the connection changed. ### Overall supported game languages `catalog.languages.get({refresh:false})` works without sign-in. Its anonymous HTTP document is exactly `{ overallGfnSupportedLanguages { language } }`. There are no variables and no Authorization header. It returns exact wire IDs in `languages`, `status` (`success`, `stale`, or `error`), `source`, cache timing, nullable `error`, and `scopeGeneration`. The bounded cache is shared with the existing disk-cache owner, keyed separately by public endpoint, provider context, and proxy route. Its TTL is 14 days. At most 512 safe IDs of 64 bytes are accepted; duplicate IDs are removed without normalization. Invalid or empty metadata does not replace a previous good list. Failure with a previous list is explicitly stale; failure without one has an empty list and error status. This reference data does not select the interface locale, keyboard map, or a game's preferences. ### Independent language preferences and settings choices `appLanguage` defaults to `system` and selects a bundled Qt interface locale. `gameLanguage` defaults to `en_US`; `keyboardLayout` defaults to `en-US`. Changing one does not change either of the others. Game language identifiers retain exact case, separators, script, and numeric-region subtags. They have an ASCII alphabetic first subtag of 2–8 bytes, subsequent alphanumeric subtags of 1–8 bytes separated by `_` or `-`, and a total limit of 64 bytes. `auto` and `system` are rejected, case-insensitively. Safe future IDs need not appear in current metadata to remain saved. `settings.get` returns `keyboardLayouts` beside `settings`, never inside the persisted values. Each descriptor has `value`, `label`, and `aliases`. The table in `language.rs` is the authority for the supported Windows-rig keyboard subset on all Qt platforms. Historical `ja-JP` and `Japanese106` request `ja-106`; historical `es-ES` requests `es-ES_tradnl`. Valid saved aliases retain their original spelling on disk. This does not select proprietary Mac keyboard IDs. New unrecognized keyboard values and malformed game IDs return `invalid_setting`. Restored strings remain visible, but a shared request resolver replaces corrupt game or keyboard values with the existing respective defaults before create, immediate resume, or claim requests. The interface locale never enters these query parameters. `settings.choices.get({runtimeCapabilities})` also returns `frameRates` for the documented frame-rate tiers, using the same `value`, `disabled`, and nullable `reason` descriptor shape. The conditional top tier reports a reason for each unconfirmed condition: a resolution outside full HD, an unreported capability probe, or a reported probe without a hardware decoder for the selected codec. Missing or unreported capabilities never imply support, and only rates at or below 240 FPS are unconditional. The entitlement limit stays a Qt-side decision because the core holds no subscription data. `settings.choices.get({runtimeCapabilities})` returns `colorQualities` for the current persisted settings and embedded streamer capability snapshot. Each of the four descriptors contains `value`, `disabled`, and nullable `reason`. The operation calls the same profile resolver as final launch. A color quality is disabled when resolution fails or when the launch would fall back to a lower bit depth or a different chroma format; the reason names the delivered profile. Codec descriptors are disabled only when the codec itself cannot decode 8-bit 4:2:0 SDR on the selected backend. Missing or incompatible capabilities do not imply support. This read does not persist or coerce any setting. Protocol 5 and native streamer protocol 7 are unchanged. CoreClient injects the current native window's `nativeHdrSupported` into `runtimeCapabilities`, overriding any caller-supplied flag, just as it does for `session.create` and `streamer.prepare`. It injects `nativeHdrDisplay` alongside it only when the output reported a validated luminance range, so an unavailable snapshot is omitted rather than sent as zero. SettingsState observes `HdrOutput.supported` only to cancel and refetch choices when the display changes; it does not author the wire capability or expose platform handles. Qt `SettingsState` owns shared desktop/console choices and the single lazy language request. Settings entry loads idle or expired metadata. Explicit retry sets `refresh:true`; there is no retry loop. Requests have a 15-second deadline. Readiness, account/provider generation, or proxy changes clear request ownership before cancellation and discard old metadata, but preserve saved preferences. Only a response for the current request and generation is accepted. `cacheHit`, stale/error status, saved IDs absent from metadata, and local fallback choices remain distinguishable. Language and profile edits serialize per key and become selected only after persistence succeeds; older failures cannot roll back a newer successful edit. These local settings operations do not restart media.