feat: support custom server deployment drafts

2026-07-24 16:56:28 +08:00
parent 292b380f3c
commit 220ef91a8e
36 changed files with 1520 additions and 85 deletions
@@ -0,0 +1,42 @@
+# 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.
+
+## 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.
+
+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`, `install`,
+`configure`, `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.