browser/openspec/changes/implement-game-client-bridge-and-scum-operations/specs/game-client-bridge/spec.md

ADDED Requirements

Requirement: Component sessions authenticate bridge access

The Platform SHALL require every Game Client Bridge request from a companion client to use a valid component session issued through the Client Manager registration flow.

Scenario: Valid component session uses bridge capability

• WHEN a deployed companion client registers with the current component key generation, deployment generation, and game-client.bridge capability
• THEN the Platform accepts bridge requests for the bound server instance, plugin, profile key, artifact, and session expiry window

Scenario: Stale component session is rejected

• WHEN a companion client uses a session from a revoked key generation, expired session, old deployment generation, or undeclared bridge capability
• THEN the Platform rejects the bridge request without returning raw key material or internal secret locations

Requirement: Commands are durable and fenced

The Platform SHALL persist Game Client Bridge commands with lifecycle state, idempotency key, expiry, priority, declared command type, payload reference or inline bounded payload, target server instance, plugin, requester, approval state, claim lease, fencing token, and audit metadata.

Scenario: Operator queues declared bridge command

• WHEN an authorized operator queues a command declared by the active plugin bridge catalog
• THEN the Platform stores the command as pending, records an audit event, and exposes only safe command status to plugin pages

Scenario: Duplicate idempotency key is reused

• WHEN the same requester submits the same command type with the same idempotency key for the same server instance
• THEN the Platform returns the existing command instead of creating a duplicate command

Scenario: Expired command is not claimed

• WHEN a pending command has passed its expiry time before a companion client claims it
• THEN the Platform marks the command expired and prevents later claim or execution

Requirement: Companion clients claim and complete commands

The Platform SHALL let authenticated companion clients claim pending bridge commands in bounded batches and complete them only with the active claim lease and fencing token.

Scenario: Client claims pending command batch

• WHEN an online companion client polls for bridge commands for its bound server instance and profile key
• THEN the Platform returns only eligible pending commands, marks them claimed, assigns leases, and includes fencing tokens

Scenario: Stale claim cannot complete command

• WHEN a companion client submits an ack or result with an expired lease, stale fencing token, or mismatched component session
• THEN the Platform rejects the update and leaves the current command state protected from stale completion

Scenario: Command result is recorded

• WHEN the active claimant completes a command with a success or failure result
• THEN the Platform stores sanitized result metadata, updates command status, records completion time, and emits an audit event

Requirement: Operators can cancel pending or claimed commands

The Platform SHALL allow authorized operators to cancel bridge commands that are not already terminal and SHALL prevent cancelled commands from being executed or completed as successful.

Scenario: Pending command is cancelled

• WHEN an authorized operator cancels a pending command
• THEN the Platform marks the command cancelled and excludes it from future claim batches

Scenario: Claimed command is cancelled before completion

• WHEN an authorized operator cancels a claimed command
• THEN the Platform records the cancellation and rejects later success results from the old claim

Requirement: Snapshots are versioned and typed

The Platform SHALL ingest Game Client Bridge snapshots only when their type, schema version, sequence, source component, payload shape, and retention policy match active plugin declarations.

Scenario: Client uploads declared snapshot

• WHEN a companion client uploads a snapshot that matches a declared snapshot type and schema version
• THEN the Platform stores it with server instance, plugin, profile key, source session, sequence, observed time, and retention metadata

Scenario: Snapshot sequence is stale

• WHEN a companion client uploads a snapshot with a sequence older than or equal to the latest accepted sequence for the same stream
• THEN the Platform rejects or quarantines the stale snapshot according to validation policy and does not replace the current projection

Scenario: Plugin page queries snapshots

• WHEN an authorized plugin page requests snapshots for an owned server instance
• THEN the Platform returns bounded safe projections without raw component secrets, host paths, direct sockets, or unbounded raw dumps

Requirement: Bridge traffic is isolated from Run channels

The Platform SHALL keep Game Client Bridge command and snapshot traffic separate from Run control heartbeat, job acknowledgement, log ingest, and artifact transfer channels.

Scenario: Large snapshot ingestion does not block control

• WHEN a companion client uploads a large but allowed snapshot payload
• THEN Run control heartbeat, job acknowledgement, and log upload remain independently serviceable through their own channels

Scenario: Bridge unavailable does not disable server lifecycle

• WHEN the Game Client Bridge service is unavailable or no companion client is online
• THEN existing Run lifecycle actions, log ingest, artifact transfer, and Client Manager lifecycle projections continue to operate

Requirement: Browser-visible bridge DTOs are safe projections

The Platform SHALL expose only safe bridge declarations, command statuses, results, snapshots, availability reasons, and audit references to plugin pages.

Scenario: Plugin page loads bridge state

• WHEN a plugin page loads bridge state for a server instance
• THEN the response excludes raw credentials, component keys, sessions, DSNs, host paths, direct Run endpoints, sockets, and storage provider credentials

Requirement: Bridge records are retained and audited

The Platform SHALL apply bounded retention to bridge commands, results, snapshots, and audit references while preserving enough metadata for operator review and troubleshooting.

Scenario: Retention job expires old bridge records

• WHEN bridge records exceed configured retention limits
• THEN the Platform expires or compacts old records without exposing deleted payloads through plugin page APIs