browser/openspec/changes/complete-scum-deployment-lifecycle/specs/scum-deployment-lifecycle/spec.md

ADDED Requirements

Requirement: SCUM deployments use a versioned game template

The Platform SHALL register a versioned SCUM server deployment template that declares the Steam app id, compatible target, executable marker, install root logical key, config file logical key, supported field mappings, discovery markers, and required verification checks. A leased install or adoption job MUST freeze the template version used for that job.

Scenario: Guided SCUM install template

• WHEN an operator creates a SCUM server with guided installation on a compatible Windows Run node
• THEN Platform dispatches an install job with the frozen SCUM template, Steam app 3792580, and mappings for the declared SCUM fields
• AND the assignment contains no raw browser credential or direct socket

Scenario: Unsupported Run is rejected

• WHEN the selected Run node does not advertise deployment.scum.v1
• THEN Platform rejects the deployment before changing the instance to installing
• AND the response identifies the missing capability without exposing host details

Requirement: New install and existing-server adoption are distinct

The Platform SHALL dispatch guided installation and existing-server adoption as different operations. Installation SHALL perform preflight, SteamCMD install, configuration materialization, and health verification. Adoption SHALL perform preflight and discovery first, and SHALL NOT reinstall or overwrite existing configuration without an explicit approved mapping request.

Scenario: Adoption discovers an existing server

• WHEN an operator chooses existing-server adoption
• THEN Run scans the selected logical server root and returns bounded executable, version, port, config-marker, and log-marker facts
• AND Platform persists those facts as a safe deployment projection

Scenario: Adoption scan fails

• WHEN the scan cannot identify a compatible SCUM executable or required marker
• THEN the instance remains failed or draft with a stable failure code
• AND Platform does not silently switch to install

Requirement: SCUM configuration mappings are explicit and reviewable

The SCUM template SHALL map only declared create fields to known logical configuration keys. Run SHALL report each mapping as applied, unchanged, skipped, or failed with a bounded reason code. Platform SHALL require successful required mappings before reporting an install as ready.

Scenario: Materialize SCUM settings

• WHEN a new SCUM install completes SteamCMD setup with valid inputs
• THEN Run applies serverName, gamePort, queryPort, and maxPlayers through the frozen mappings
• AND the evidence reports the mapping outcomes without returning the absolute config path

Scenario: Unsupported field is submitted

• WHEN a create request includes a field not present in the template mapping
• THEN Platform rejects the request before dispatch

Requirement: Installation completion requires verification evidence

The Platform SHALL accept SCUM installation as ready only when Run returns successful required checks for executable presence/version, configured ports, config readability, and process health. A terminal success without required evidence SHALL be rejected as an invalid result.

Scenario: Health verification succeeds

• WHEN Run reports all required SCUM checks as passed
• THEN Platform projects the instance to ready after install, or running after start
• AND the deployment projection records the verification timestamp and template version

Scenario: Verification fails

• WHEN any required check fails
• THEN Platform projects the job as failed with a stable error code and keeps the raw diagnostic local to Run

Requirement: Deployment evidence is safe for browser projection

Public server, job, marketplace, and plugin bridge responses SHALL expose only bounded logical facts and configured/reviewable state. They MUST NOT expose raw host paths, command text, credentials, process ids, or direct sockets.

Scenario: Operator reads deployment status

• WHEN an operator opens a SCUM deployment status view
• THEN the response includes operation, template version, discovery/mapping/verification states, and safe failure code
• AND it omits the supplied server root, working directory, install/start/stop commands, and any secret material