browser/openspec/changes/add-run-distribution-and-client-managers/specs/run-distribution-and-client-managers/spec.md

ADDED Requirements

Requirement: Platform generates server-scoped run packages

The platform SHALL let an authorized operator generate a run package for a selected server instance and target platform using the server's single current run key stored encrypted in the platform database.

Scenario: Operator generates run from server actions

• WHEN an authorized operator selects generate executor for a server instance and chooses a supported OS/architecture
• THEN platform MUST create or reuse the server's current encrypted run key, write that key into the generated package config, create a distribution record with key generation, build/download artifact, checksum metadata, and audit event, and MUST NOT return the raw key in the API response

Scenario: Operator downloads generated run package

• WHEN an authorized operator downloads a generated run artifact
• THEN platform MUST authorize access by server scope and return the secret-bearing package through artifact/download APIs without exposing raw host paths, direct sockets, or database credentials in package metadata

Requirement: Run and client-manager keys are isolated singletons

Run executors and plugin-declared client managers SHALL use different authentication secrets, and each server/component SHALL have exactly one current active key stored encrypted in the platform database.

Scenario: Client manager is generated after run

• WHEN a plugin-declared client-manager package is generated for a server that already has a run package
• THEN platform MUST create or reuse the server's current encrypted client-manager key and MUST NOT reuse, reveal through API metadata, or derive it from the run key

Scenario: Component key reset is requested

• WHEN an operator resets a server's run key or client-manager key
• THEN platform MUST replace the encrypted database key for that component, increment the key generation, revoke all packages generated with prior generations, and record an audit event identifying the component kind without logging raw key material

Scenario: Old package authenticates after reset

• WHEN a run or client-manager package generated before the latest key reset attempts to authenticate
• THEN platform MUST reject the old key and require the operator to regenerate and redeploy the corresponding run or client-manager package

Requirement: Plugins declare runtime profiles

Game plugins SHALL declare runtime profiles that describe how run or external transports can discover, control, observe, and connect to the game server using logical keys instead of raw credentials or host paths.

Scenario: Plugin declares server discovery and transports

• WHEN a plugin manifest declares runtime profiles with discovery probes, lifecycle actions, dependency probes, log sources, FTP/rsync, SQL, RCON, or client-manager bindings
• THEN plugin validation MUST accept only known profile fields and platform MUST preserve the declarations for server setup and action gating

Scenario: Plugin manifest includes unsafe runtime details

• WHEN a plugin manifest embeds raw run keys, client-manager keys, FTP passwords, database DSNs, RCON passwords, absolute host paths, direct sockets, or arbitrary shell scripts in runtime profiles
• THEN plugin validation and platform registration MUST reject the manifest before it becomes installable

Requirement: Server runtime bindings resolve plugin profiles

Server instances SHALL bind plugin-declared logical runtime keys to operator-provided local or remote settings before run-dependent actions are enabled.

Scenario: Run discovers an existing server

• WHEN run registers for a server instance with complete runtime bindings and the plugin declares discovery probes
• THEN run MUST evaluate the probes locally, report logical discovery status, version, and health, and MUST NOT return raw host paths or secret values to platform_web or plugin pages

Scenario: Required binding is missing

• WHEN an operator opens server actions for a runtime profile that requires unbound install root, service name, FTP profile, SQL profile, RCON profile, or client-manager profile
• THEN platform MUST mark dependent actions unavailable and explain the missing logical binding without exposing internal storage details

Requirement: Plugins control third-party startup behavior

Third-party game program startup and shutdown SHALL be driven by plugin-declared lifecycle profiles and server runtime bindings, not hardcoded platform game logic.

Scenario: Local process server starts through run

• WHEN a plugin declares a local process lifecycle profile and the server runtime binding is complete
• THEN run MUST start or stop the third-party program through the declared bounded action template and stream stdout/stderr through the log channel

Scenario: Hosted server has no local lifecycle control

• WHEN a plugin declares an FTP-only, FTP+RCON, or custom-client runtime profile without local process lifecycle
• THEN platform MUST hide or deny local start/stop actions and expose only the declared remote or client-manager actions

Requirement: Dependency checks and installs are typed

Run SHALL check dependencies through plugin-declared probes and SHALL install missing dependencies only through approved, typed, reviewable install plans.

Scenario: Dependency check reports missing runtime

• WHEN run evaluates plugin-declared dependency probes and a required runtime, service, package, toolchain, Steam app, Java runtime, Docker runtime, or OS package is missing
• THEN platform MUST show dependency status and a reviewable install plan if the plugin declares one for the target platform

Scenario: Dependency install is approved

• WHEN an authorized operator approves a dependency install plan
• THEN platform MUST queue a bounded run job using typed package/download steps, checksum or source metadata where provided, and must reject arbitrary shell snippets

Requirement: Client-manager packages are plugin-declared builds

The platform SHALL support plugin-declared client-manager build profiles for companion executables that require source checkout, configuration injection, and compilation before download.

Scenario: SCUM-style client manager is generated

• WHEN a plugin declares a client-manager build profile with repository, revision policy, supported target platform, build system, config template, and output artifact paths
• THEN platform MUST create a build job that checks out the approved source, injects redacted configuration from secret refs, produces a downloadable artifact, and redacts secrets from build logs

Scenario: Unsupported client-manager target is requested

• WHEN an operator requests a client-manager build for an OS/architecture not declared by the plugin profile
• THEN platform MUST reject the request before cloning source or creating a credential

Requirement: Online run endpoints self-update through platform jobs

The platform SHALL update online run endpoints by queuing a bounded self-update job that references an approved artifact and checksum instead of sending raw shell commands.

Scenario: Online run accepts update

• WHEN an assigned run endpoint is online and supports self-update
• THEN platform MUST queue an update job, and run MUST download the artifact, verify checksum or signature metadata, stage the replacement, report progress, and restart or swap only after verification succeeds

Scenario: Update verification fails

• WHEN run cannot verify or stage the update artifact
• THEN run MUST keep the current executable, report a bounded failure result, and preserve heartbeat or last-known status without leaking local paths or credentials

Requirement: Run exposes multi-channel transport capabilities

Run SHALL provide declared server operations through separate control, job, log, artifact/file, FTP/rsync, SQL, and RCON channels or adapters while preserving priority and bounded payload rules.

Scenario: Long file transfer is active

• WHEN run is transferring a large file, FTP payload, rsync payload, or artifact chunk
• THEN heartbeat, job ack/result, cancellation polling, and log ingest MUST continue independently without waiting for transfer completion

Scenario: Undeclared transport operation is requested

• WHEN a plugin page or platform caller requests FTP, SQL, RCON, file, or process work not declared by the plugin runtime profile and run capabilities
• THEN platform MUST deny the request before creating a job and MUST return only a safe error

Requirement: Live and historical logs are platform-mediated

Platform_web SHALL show live and historical server logs through platform APIs backed by run log ingest, log checkpoints, and plugin-declared log sources.

Scenario: Live log tail is opened

• WHEN an operator opens live logs for a server with an online run endpoint
• THEN platform_web MUST read from platform log APIs and display sequenced log entries from run without direct run sockets or raw file paths

Scenario: Historical log backfill is requested

• WHEN an operator requests older logs for a declared process, file, FTP, SQL, or plugin-specific log source
• THEN platform MUST queue or serve a backfill using per-source checkpoints, cursors, or file fingerprints and MUST avoid embedding large log bodies in job result payloads

Requirement: Server action menu reflects declared availability

The server list and server detail action menu SHALL show generate run, download run, push run update, generate client manager, dependency check, install dependency, live logs, and historical logs only when the current user and plugin/runtime state permit them.

Scenario: Actions are available

• WHEN a server has a plugin with runtime profiles, complete bindings, and the current user has the required permissions
• THEN platform_web MUST render the applicable actions using the existing game-operations console style and call platform APIs rather than plugin-owned direct endpoints

Scenario: Actions are unavailable

• WHEN a server lacks a required plugin declaration, binding, online run status, build profile, or user permission
• THEN platform_web MUST hide or disable the action with a safe reason and MUST NOT render raw credentials, host paths, direct sockets, or secret refs beyond redacted identifiers

Requirement: Distribution and control events are audited

The platform SHALL audit run generation, run download, credential reset, run update, dependency install, client-manager build, client-manager download, and transport operation requests.

Scenario: Sensitive operation completes

• WHEN a sensitive distribution or control operation succeeds, fails, or is denied
• THEN platform MUST record actor, server instance, plugin ID, component kind, operation, result, artifact ID or job ID where applicable, and redacted reason without raw secret material