browser/platform/protocol/server-lifecycle.md

Server Plugin and Instance Lifecycle Contract

Installed Server Plugin

An installed game management plugin is reusable. It defines a server type, but it is not a server instance.

The plugin marketplace API is a platform-facing projection over this installed registry metadata. It is not a package store, billing system, provider marketplace, or cloud host sales surface.

States

• installed: plugin manifest and schemas are valid.
• disabled: plugin cannot create new servers but existing instances remain inspectable.
• invalid: plugin failed validation and cannot create or manage instances.
• updating: plugin version is being changed.

Server Instance

A server instance is created from one installed game management plugin and bound to one run endpoint.

States

• draft: instance record exists but the first bootstrap job has not completed.
• installing: the first plugin-owned bootstrap job is active.
• ready: install/bootstrap succeeded without starting a supervised process, and the server can start.
• running: server process is running.
• stopped: server process is stopped.
• failed: last lifecycle operation failed.
• deleted: instance is no longer active.

Invariants

• One GamePlugin installation may own many ServerInstance records.
• A ServerInstance must keep its own config version, artifacts, jobs, log streams, and permissions.
• Updating a plugin must not silently mutate existing server instances without a recorded reconcile job.
• Deleting a plugin must be blocked or explicitly require handling existing server instances first.

Lifecycle Actions

• create: validate plugin, create instance record, dispatch the plugin-owned bootstrap job.
• start: dispatch process start job through the bound run endpoint.
• stop: dispatch process stop job through the bound run endpoint.
• restart: dispatch stop/start or plugin-defined restart job.
• update: dispatch server update job and record version/result.
• delete: stop server when needed, preserve or remove artifacts according to policy, mark deleted.

Implemented Workflow Routes

• GET /api/v1/plugin-marketplace/plugins lists plugin marketplace summaries from registry metadata with status, server type, capability, and keyword filters.
• GET /api/v1/plugin-marketplace/plugins/{id} returns one registry-backed marketplace detail.
• POST /api/v1/plugin-marketplace/plugins/{id}/state applies metadata-only install, enable, or disable state changes.
• POST /api/v1/server-instances/workflows/create validates an installed plugin, a compatible run endpoint, a non-empty idempotency key, and required lifecycle action references. It creates the instance in installing state and queues either process.install or, for guided deployments whose selected lifecycle profile supports supervised start, process.start so the plugin start script can install-if-missing and stream process logs.
• POST /api/v1/server-instances/{id}/start validates the instance is ready or stopped, checks the expected config version, verifies the plugin start action and run endpoint process.start capability, and queues a start job.
• POST /api/v1/server-instances/{id}/stop validates the instance is running, checks the expected config version, verifies the plugin stop action and run endpoint process.stop capability, and queues a stop job.
• GET /api/v1/server-instances/{id}/config returns logical read-only config content for an authorized server instance with config version, format, key, source, and update timestamp metadata.
• POST /api/v1/server-instances/{id}/config/diff validates an authorized proposed config write against the current config version and returns a bounded platform diff without queuing work.
• POST /api/v1/server-instances/{id}/config/approve revalidates an explicitly reviewed config diff and queues a scoped config.write job using a logical config key and input ref.
• POST /api/v1/file-operations/dispatch queues scoped files.read or files.write jobs for logical server/plugin file keys after role and permission checks.
• GET /api/v1/metrics/server-instances returns bounded per-server metrics for instances visible to the authenticated user.

Workflow route responses include the accepted action, bounded server instance metadata, and bounded job metadata. They do not expose run session tokens, host paths, raw credentials, direct sockets, AI provider keys, or plugin action file contents.

Config read and server metrics responses are also bounded and platform-mediated. They do not expose host filesystem paths, run sockets, raw credentials, direct storage backends, or AI provider keys.

Config write approval and file dispatch are platform-mediated. They carry logical keys such as server.properties or logs/latest.log, scoped refs such as input://... or artifact://..., and bounded job metadata only. They do not mutate local files in the platform process and do not expose raw host paths, run credentials, direct sockets, AI provider keys, or inline large payloads.

Marketplace state actions update only registry install state. They do not download packages, dispatch run jobs, execute plugin bridge code, write server files, expose package bytes, or contact external services. Package acquisition and runtime execution remain deferred to explicit future changes.

Lifecycle Job Projection

Terminal run job results update the associated server instance when the job capability is a lifecycle capability:

• process.install + succeeded marks the instance ready.
• process.start + succeeded marks the instance running.
• process.stop + succeeded marks the instance stopped.
• process.install, process.start, or process.stop + failed or cancelled marks the instance failed.

Active start and stop jobs do not introduce separate starting or stopping states in this change. Operators can inspect pending job state through the job list while the instance remains in its last terminal server state.