# 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`.

The first-party Windows SCUM template declares `steamcmd`, Visual C++ 2012,
2013, and 2015-2022 (x86 and x64), plus DirectX runtime prerequisites. Run
checks their Windows markers before installation and uses only its fixed
Microsoft installer catalog with silent arguments when one is absent. The
template builds SteamCMD as separate arguments: `+force_install_dir`, the
protected root, anonymous login, App `3792580`, `validate`, and `+quit`. The
original root and constructed command are eligible only for opt-in local Run
diagnostics; they never enter progress or result payloads.

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.