first commit

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

@@ -0,0 +1,79 @@
+## 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