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

ADDED Requirements

Requirement: SCUM plugin owns SCUM operation semantics

The game.scum plugin SHALL declare SCUM-specific commands, snapshot schemas, log event schemas, database query templates, permissions, approval levels, page contracts, and policy labels.

Scenario: Platform loads SCUM bridge declarations

• WHEN the Platform registers the SCUM plugin manifest
• THEN it validates the declared SCUM operation catalog and stores safe declarations without adding SCUM business logic to independent Run

Scenario: Unknown SCUM command is rejected

• WHEN a plugin page or operator attempts to queue a SCUM command that is not declared by the active SCUM plugin catalog
• THEN the Platform rejects the command before it reaches a companion client

Requirement: SCUM companion client uses Platform identity and bridge APIs

The SCUM companion client SHALL register and heartbeat through the Platform Client Manager component-session flow and SHALL use Game Client Bridge command and snapshot APIs for game-window interaction.

Scenario: Generated client package starts with platform config

• WHEN a SCUM Client Manager package is generated and deployed
• THEN its runtime configuration aligns with the actual companion client bootstrap and includes only the material required to register with Platform through the current component-key generation

Scenario: Legacy shared-token endpoint is not used

• WHEN a SCUM companion client exchanges commands or snapshots with Platform
• THEN it does not use legacy shared-token /api/v1/scum-clients/hello, /heartbeat, /commands, /results, or /snapshots endpoints

Scenario: Insecure TLS skip is not allowed

• WHEN the SCUM companion client connects to Platform
• THEN it must not disable certificate verification through an unconditional insecure TLS setting

Requirement: SCUM snapshots cover core operational state

The SCUM plugin SHALL define typed snapshot schemas for at least online sessions, players, squads, vehicles, flags or territories, and companion health diagnostics.

Scenario: Player snapshot is ingested

• WHEN the SCUM companion client uploads a declared player or online-session snapshot
• THEN Platform stores a versioned safe projection that plugin pages can query by server instance and observed time

Scenario: Vehicle and flag snapshots are ingested

• WHEN the SCUM companion client uploads declared vehicle, squad, flag, or territory snapshots
• THEN Platform validates the schema version and sequence before updating the current projection

Requirement: SCUM command catalog is bounded and permissioned

The SCUM plugin SHALL expose only declared, typed, permission-scoped game commands such as announcements, player lookup, reward delivery, event actions, maintenance preparation, and safe companion diagnostics.

Scenario: Operator queues announcement

• WHEN an authorized operator queues a declared SCUM announcement command
• THEN Platform records the requester, approval state, command payload, idempotency key, and audit event before the companion client can claim it

Scenario: Risky command requires approval

• WHEN a SCUM command is marked as risky, destructive, economy-affecting, or punitive
• THEN Platform requires the declared approval level before making the command claimable

Requirement: SCUM moderation begins as evidence and review

The SCUM plugin SHALL model suspicious duplicate IP, unlock, mine, trade, kill, admin, and economy signals as evidence, alerts, and operator-reviewed recommendations by default.

Scenario: Suspicious event is parsed

• WHEN SCUM semantic log parsing detects a suspicious event pattern
• THEN Platform records a typed evidence event or alert without automatically banning, punishing, or modifying the player

Scenario: Operator approves punitive action

• WHEN an operator chooses a punitive SCUM action from a recommendation
• THEN Platform applies the command catalog permission and approval rules before dispatching any companion command

Requirement: SCUM logs are parsed into typed events

The SCUM plugin SHALL define typed semantic log events for chat, login, logout, kill, trade, mine, unlock, admin, and performance records.

Scenario: Chat log event is parsed

• WHEN SCUM chat log lines are ingested
• THEN Platform stores typed chat events that plugin pages can filter by player, time range, and server instance

Scenario: Performance log event updates metrics

• WHEN SCUM performance log lines are ingested
• THEN Platform maps FPS and entity counts into bounded metric projections and alert inputs

Requirement: SCUM database access uses read-only templates

The SCUM plugin SHALL declare read-only SCUM.db query templates with typed parameters, bounded result schemas, and permission scopes instead of exposing arbitrary SQL.

Scenario: Operator runs player lookup template

• WHEN an authorized operator runs a declared player lookup query template
• THEN Platform dispatches a bounded read-only request and returns only the declared result columns

Scenario: Arbitrary SQL is requested

• WHEN a plugin page submits SQL text that is not backed by a declared query template
• THEN Platform rejects the request and does not dispatch it to Run or the companion client

Requirement: SCUM backup and restart policy remains plugin-declared

The SCUM plugin SHALL declare backup scopes, retention policy, restart schedules, warning announcements, and update-check policy as SCUM operational policy while Platform and Run execute only generic jobs.

Scenario: Scheduled restart is prepared

• WHEN a SCUM restart schedule reaches its warning window
• THEN Platform queues declared SCUM announcement commands and generic lifecycle actions according to plugin policy and operator approvals

Scenario: Backup is requested

• WHEN an authorized operator requests a SCUM backup
• THEN Platform records the logical SCUM backup scope and dispatches generic archive/artifact operations without exposing raw host paths or storage credentials to the plugin page

Requirement: SCUM operation pages use safe Platform projections

The SCUM plugin pages SHALL render bridge state, snapshots, commands, logs, backup/restart policy, and review flows using Platform-mediated DTOs only.

Scenario: SCUM operations page loads

• WHEN a user opens the SCUM operations page for a server instance
• THEN the page can display safe bridge status, companion health, current snapshots, command availability, and recent results without receiving raw secrets, host paths, DSNs, direct Run sockets, or component session material