rampway 0.5.19 → 0.5.21

package/docs/config-reference.md

@@ -500,7 +500,7 @@ Rollbridge runtime adapter. Handles `deploy`, `validate`, `status`, `logs`, and
 | `socketPath` | string | no | Path to the Rollbridge Unix socket. |
 | `versionPath` | string | no | Path to a version file used for stale-daemon detection. |
 | `env` | object | no | String environment values passed to Rollbridge. Secret-like values are transported and redacted separately. |
-| `externalOwner` | object | no | Opt in to a persistent external foreground owner with `{type: "foreground"}`. Requires `config` and Rollbridge 0.1.20 or newer. |
+| `externalOwner` | object | no | Opt in to a persistent external foreground owner with `{type: "foreground"}`. Requires `config`, `socketPath`, and Rollbridge 0.1.21 or newer; upgrading a retained owner running an older Rollbridge fails closed (see below). |
 
 ```js
 runtime: {
@@ -521,17 +521,51 @@ runtime: {
 ```
 
 `externalOwner.handoffTimeoutMs` and `pollIntervalMs` are optional positive
-integer millisecond bounds (defaults: 30000 and 250). Every accepted deploy or
+integer millisecond bounds (defaults: 30000 and 250). `handoffTimeoutMs` is
+one deadline that bounds the authenticated `retire-owner` socket round trip
+and the subsequent replacement polling after initial owner identity
+verification; a stalled, truncated, malformed, or non-success
+retirement response fails the handoff deterministically without retrying
+retirement or taking over the owner. Every accepted deploy or
 rollback must establish the new boot digest, including first adoption and a
 same-contract release change. Rampway waits for health, `current` publication,
 and atomic boot-state persistence, then writes a request bound to the exact
 deploy lock and accepted boot digest. An owner already reporting the exact
 accepted release, runtime, and bootstrap attestation remains untouched.
-Otherwise Rampway stops only a daemon whose status first proves the accepted
-release and runtime identity, then waits for the external foreground owner with
-the exact boot attestation. Success removes the request; timeout preserves the
+Otherwise Rampway sends one authenticated `retire-owner` request only to a daemon
+whose status first proves the accepted release and runtime identity, then waits
+for the replacement foreground owner with the exact boot attestation. Retirement
+must release ownership and return without waiting for retained generations or
+connections to drain. Success removes the request; timeout preserves the
 accepted boot state and request for recovery.
 
+Deploy success and deploy-lock release follow healthy activation and replacement
+owner readiness. They must not wait for retired jobs generations, workers, jobs,
+HTTP/WebSocket connections, or other retained services to finish. Rollbridge
+durably supervises those drains after the command returns and reports every
+release directory still referenced by a retained process. Rampway owns the
+corresponding retention metadata and must exclude those pinned releases from
+cleanup until all references have ended. HTTP/WebSocket drain completion or
+timeout does not release a jobs-generation pin.
+Rampway atomically records the verified owner's referenced-release set before
+asynchronous retirement and replaces it from later owner status, so cleanup pins
+survive separate deploy invocations and end when Rollbridge drops the reference.
+
+Deploying over a retained external owner running Rollbridge older than 0.1.21
+fails closed before any shutdown or deploy: those versions have no
+authenticated `retire-owner` contract, so replacing them requires a full
+shutdown that interrupts service while long-running workers drain. Stage the
+migration through an intermediate 0.1.21+ release with `runtime.externalOwner`
+disabled in an explicitly planned maintenance restart, scheduled only after
+accepted long-running workers have drained, then re-enable it.
+
+Rolling back to a retained release whose runtime snapshot predates the
+`runtime.socketPath` requirement also fails closed, before any runtime
+activation: redeploy that release once with the current Rampway so its
+snapshot records the control socket path, then roll back. `runtime.socketPath`
+itself must be a non-empty string without NUL bytes and is validated at config
+load.
+
 Configure the service manager to run `rampway <stage> runtime-boot --config
 <absolute-path>` with `Restart=always` and a bounded restart delay. Early
 attempts may collide with the temporary daemon and exit; retries converge after
@@ -643,11 +677,16 @@ migration, publication, cleanup, or fallback selection. Rollbridge support
 requires an explicit `runtime.config` and Rollbridge 0.1.17 or newer; a
 successful deploy without stable config remains supported but cannot seed
 runtime boot state. The optional external-owner handoff requires Rollbridge
-0.1.20 or newer and passes the accepted boot-state digest as
+0.1.21 or newer and passes the accepted boot-state digest as
 `--boot-attestation` on an ordinary foreground daemon boot. A matching owner is
-a no-op; a stale or absent bootstrap on the exact accepted release/runtime is
-gracefully shut down once so a serial outer supervisor can start the
-replacement. Status/read identity mismatches fail closed without shutdown.
+a no-op; a stale or absent bootstrap on the exact accepted release/runtime
+receives one authenticated `retire-owner` control command through the
+configured `runtime.socketPath`, which quiesces the old owner and releases its
+proxy/control listeners promptly — without waiting for long-draining workers —
+so a serial outer supervisor can start the replacement. The retirement socket
+round trip and the replacement wait share one `handoffTimeoutMs` deadline; a
+stalled, truncated, malformed, or non-success response fails closed. Status/read identity
+mismatches fail closed without shutdown.
 
 ## Health checks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rampway",
-  "version": "0.5.19",
+  "version": "0.5.21",
   "description": "JS-native Capistrano-style release-directory deployments with Rollbridge integration.",
   "type": "module",
   "private": false,