3.5 KiB
Server deployment plan v1
deployment.plan.v1 is the capability gate for Run implementations that can
execute a protected server deployment plan. Platform only sends the plan in a
leased RunJobAssignmentResponse.executionInput.deployment; it never appears
in public server, job, audit, log, or plugin-bridge responses.
SCUM controlled deployments additionally require deployment.scum.v1. The
leased assignment includes executionInput.serverDeploymentPlan with
schemaVersion: "1", an operation of install or adopt, the frozen template
key/version, Steam app id, logical executable/config references, explicit field
mappings, discovery markers, and required verification checks. The plan is
secret-free and contains logical keys only; the protected deployment body still
holds the operator's paths/commands and is resolved only by Run.
Capability and policy
Run advertises deployment.plan.v1 along with its normal lifecycle
capabilities. A Run that supports shell commands additionally advertises its
local policy for posix-sh, powershell, or cmd out of band with its
operator configuration. Platform must not infer shell support from command
text. Empty shell means argv-oriented execution.
Required local preflight
Before a write, install, or process action, Run validates the selected plan:
- absolute server root and working directory are allowed anywhere permitted by the local Run policy; they are not required to be adjacent to the Run binary;
- the effective directory, executable, permissions, timeout, plugin version, and requested ports are locally valid;
- selected shell kind and custom-command policy are enabled;
- no raw command, path, secret, socket address, or credential is emitted in a result, diagnostic, log batch, or artifact name.
For an SCUM install, Run performs SteamCMD app installation followed by
configuration materialization and health checks. For adopt, Run performs a
scan first and must not reinstall or overwrite existing configuration. A
controlled SCUM install or adoption requires an explicit protected server root;
the root is never exposed in browser projections. Adoption does not require
new-install create inputs because its mapping phase is read-only unless a
separate approved write is dispatched. A
terminal SCUM result must include bounded serverDeploymentEvidence with
preflight, discovery, mapping, and verification states. Required mapping
results are applied or unchanged; required verification results are
passed (adoption may report mapping as skipped). Failed results include a stable failureCode and never include the
resolved path or command text. Successful result kinds are
scum.install.completed and scum.adopt.completed; failed result kinds are
scum.install.failed and scum.adopt.failed.
An existing-server plan may omit installation. A custom-command plan
requires a start command. Guided templates remain plugin recommendations;
Run owns their local resolution and execution.
Safe progress reports
Run reports bounded progress with percent, phase, and a safe message. The
allowed phase vocabulary is queued, claimed, preflight, scan, install,
configure, mapping, start, and health. On failure it reports a stable safe error
code and summary such as working-directory-unavailable, never the supplied
path or command text.
Platform treats preflight as authoritative. It does not open a direct shell, SSH connection, raw socket, or host filesystem to compensate for a failed preflight.