browser/openspec/changes/implement-server-management-workflows/specs/server-management-workflows/spec.md

ADDED Requirements

Requirement: Server create workflow dispatches install job

The platform SHALL provide a server create workflow that validates an installed game plugin, a compatible run endpoint, and a non-empty idempotency key before creating a server instance and dispatching a queued install job through the job channel.

Scenario: Create workflow accepted

• WHEN an operator submits a create workflow with an installed plugin, an online compatible run endpoint, a server name, and an idempotency key
• THEN the platform MUST create a server instance in installing state and create a queued process.install job bound to that instance and run endpoint

Scenario: Create workflow rejects invalid dependencies

• WHEN an operator submits a create workflow with a missing plugin, disabled plugin, offline run endpoint, or run endpoint missing required capabilities
• THEN the platform MUST reject the workflow and MUST NOT dispatch a lifecycle job

Requirement: Server start workflow dispatches start job

The platform SHALL provide a start workflow for an existing server instance that validates the instance state, config version, plugin lifecycle action, run endpoint status, run endpoint capability, and idempotency key before dispatching a queued start job.

Scenario: Start workflow accepted

• WHEN an operator starts a ready or stopped server instance with the current config version and an idempotency key
• THEN the platform MUST create a queued process.start job for the instance and return both the instance and job metadata

Scenario: Start workflow rejects stale config

• WHEN an operator starts a server instance with an expected config version that does not match the instance config version
• THEN the platform MUST reject the workflow and MUST NOT dispatch a lifecycle job

Requirement: Server stop workflow dispatches stop job

The platform SHALL provide a stop workflow for an existing running server instance that validates the instance state, config version, plugin lifecycle action, run endpoint status, run endpoint capability, and idempotency key before dispatching a queued stop job.

Scenario: Stop workflow accepted

• WHEN an operator stops a running server instance with the current config version and an idempotency key
• THEN the platform MUST create a queued process.stop job for the instance and return both the instance and job metadata

Scenario: Stop workflow rejects non-running instance

• WHEN an operator stops a server instance that is not running
• THEN the platform MUST reject the workflow and MUST NOT dispatch a lifecycle job

Requirement: Lifecycle job results update server instance state

The platform SHALL project terminal lifecycle job results onto the associated server instance after accepting a run job result.

Scenario: Install result marks ready

• WHEN run completes a process.install lifecycle job successfully
• THEN the platform MUST mark the associated server instance ready

Scenario: Start result marks running

• WHEN run completes a process.start lifecycle job successfully
• THEN the platform MUST mark the associated server instance running

Scenario: Stop result marks stopped

• WHEN run completes a process.stop lifecycle job successfully
• THEN the platform MUST mark the associated server instance stopped

Scenario: Failed lifecycle result marks failed

• WHEN run completes an install, start, or stop lifecycle job as failed or cancelled
• THEN the platform MUST mark the associated server instance failed

Requirement: Run lifecycle executor is bounded

The run executor SHALL support only declared lifecycle capabilities for install, start, and stop jobs and MUST return bounded metadata-only results without raw host paths, raw credentials, or direct socket details.

Scenario: Supported lifecycle job handled

• WHEN run receives a job assignment for process.install, process.start, or process.stop
• THEN the lifecycle executor MUST produce a successful bounded result suitable for the job result channel

Scenario: Unsupported lifecycle job rejected

• WHEN run receives a job assignment for an unsupported lifecycle capability
• THEN the lifecycle executor MUST return a failed bounded result without executing local commands

Requirement: Server management UI supports create start and stop

The frontend SHALL expose server management controls that use platform workflow APIs to create, start, stop, and refresh server instances without receiving run credentials, raw host paths, raw AI keys, or direct sockets.

Scenario: UI creates server workflow

• WHEN an operator submits the server management create form
• THEN the frontend MUST call the platform create workflow API and render the returned instance and lifecycle job status

Scenario: UI starts and stops server

• WHEN an operator clicks start or stop for an eligible server instance
• THEN the frontend MUST call the matching platform workflow API with the current config version and render the returned lifecycle job status

Scenario: UI refreshes workflow status

• WHEN the server management page refreshes data
• THEN the frontend MUST read server instances, jobs, plugins, and run endpoints through platform APIs and MUST NOT display raw secrets, host paths, run credentials, or direct sockets