rampway 0.2.6 → 0.3.1

package/build/src/velocious/sanitize.js

@@ -0,0 +1,154 @@
+// @ts-check
+const MAX_STRING_LENGTH = 4000;
+const MAX_DEPTH = 20;
+const MAX_COLLECTION_ENTRIES = 100;
+const MAX_VISITED_VALUES = 1000;
+const MAX_SERIALIZED_BYTES = 64 * 1024;
+const MAX_PREVIEW_LENGTH = 8000;
+const REDACTED = "[redacted]";
+const TRUNCATION_MARKER = "[truncated]";
+const TRUNCATED_VALUE = Symbol("truncated");
+/** @typedef {{visited: number}} SanitizerState */
+/**
+ * @param {string} value - Value to redact.
+ * @param {string[]} secrets - Exact configured secrets.
+ * @returns {string} Redacted and bounded value.
+ */
+function redactString(value, secrets) {
+    let result = value;
+    for (const secret of secrets) {
+        if (secret.length > 0)
+            result = result.split(secret).join(REDACTED);
+    }
+    return result.length > MAX_STRING_LENGTH ? `${result.slice(0, MAX_STRING_LENGTH)}…` : result;
+}
+/**
+ * Converts an integration value to bounded JSON data while redacting secrets
+ * in values and keys. Colliding redacted keys are retained with stable suffixes.
+ *
+ * @param {unknown} value - Integration value.
+ * @param {string[]} secrets - Secrets to remove.
+ * @param {number} [depth] - Current depth.
+ * @returns {any} JSON-safe value or undefined.
+ */
+export function sanitizeAdapterValue(value, secrets, depth = 0) {
+    const sanitized = sanitizeValue(value, secrets, depth, { visited: 0 });
+    if (sanitized === undefined)
+        return undefined;
+    if (sanitized === TRUNCATED_VALUE)
+        return { reason: "Sanitized output exceeded traversal limits", truncated: true };
+    const serialized = JSON.stringify(sanitized);
+    if (Buffer.byteLength(serialized) <= MAX_SERIALIZED_BYTES)
+        return sanitized;
+    return {
+        preview: serialized.slice(0, MAX_PREVIEW_LENGTH),
+        reason: `Sanitized output exceeded ${MAX_SERIALIZED_BYTES} bytes`,
+        truncated: true
+    };
+}
+/**
+ * @param {unknown} value - Integration value.
+ * @param {string[]} secrets - Secrets to remove.
+ * @param {number} depth - Current depth.
+ * @param {SanitizerState} state - Shared traversal budget.
+ * @returns {any} JSON-safe value, undefined, or the truncation sentinel.
+ */
+function sanitizeValue(value, secrets, depth, state) {
+    if (state.visited >= MAX_VISITED_VALUES || depth > MAX_DEPTH)
+        return TRUNCATED_VALUE;
+    state.visited++;
+    if (value === null)
+        return null;
+    if (typeof value === "string")
+        return redactString(value, secrets);
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "boolean")
+        return value;
+    if (Array.isArray(value)) {
+        const result = [];
+        let truncated = value.length > MAX_COLLECTION_ENTRIES;
+        const contentLimit = truncated ? MAX_COLLECTION_ENTRIES - 1 : value.length;
+        for (let index = 0; index < contentLimit; index++) {
+            const sanitized = sanitizeValue(value[index], secrets, depth + 1, state);
+            if (sanitized === TRUNCATED_VALUE) {
+                truncated = true;
+                break;
+            }
+            if (sanitized !== undefined)
+                result.push(sanitized);
+        }
+        if (truncated)
+            result.push(TRUNCATION_MARKER);
+        return result;
+    }
+    if (typeof value !== "object")
+        return undefined;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return undefined;
+    /** @type {Record<string, any>} */
+    const result = {};
+    const keys = [];
+    let truncated = false;
+    for (const key in value) {
+        if (!Object.hasOwn(value, key))
+            continue;
+        keys.push(key);
+        if (keys.length > MAX_COLLECTION_ENTRIES) {
+            truncated = true;
+            keys.length = MAX_COLLECTION_ENTRIES - 1;
+            break;
+        }
+    }
+    for (const key of keys) {
+        const sanitized = sanitizeValue(/** @type {Record<string, unknown>} */ (value)[key], secrets, depth + 1, state);
+        if (sanitized === TRUNCATED_VALUE) {
+            truncated = true;
+            break;
+        }
+        if (sanitized === undefined)
+            continue;
+        defineAvailableProperty(result, redactString(key, secrets), sanitized);
+    }
+    if (truncated)
+        defineAvailableProperty(result, TRUNCATION_MARKER, true);
+    return result;
+}
+/**
+ * Defines a property without dropping a colliding diagnostic key.
+ *
+ * @param {Record<string, any>} target - Sanitized object.
+ * @param {string} key - Desired key.
+ * @param {unknown} value - Sanitized value.
+ * @returns {void}
+ */
+function defineAvailableProperty(target, key, value) {
+    let availableKey = key;
+    let collision = 2;
+    while (Object.hasOwn(target, availableKey)) {
+        availableKey = `${key}#${collision}`;
+        collision++;
+    }
+    Object.defineProperty(target, availableKey, {
+        configurable: true,
+        enumerable: true,
+        value,
+        writable: true
+    });
+}
+/**
+ * @param {unknown} error - Deployment failure.
+ * @param {string[]} secrets - Secrets to remove.
+ * @returns {{message: string, recovery: any}} Safe failure payload.
+ */
+export function sanitizeErrorPayload(error, secrets) {
+    const message = error instanceof Error ? error.message : String(error);
+    const recovery = error instanceof Error ? /** @type {Error & {recovery?: unknown}} */ (error).recovery : undefined;
+    const payload = sanitizeAdapterValue({ message, recovery }, secrets);
+    if (payload && typeof payload === "object" && typeof payload.message === "string") {
+        return { message: payload.message, recovery: payload.recovery };
+    }
+    return { message: "Deployment failure diagnostics were truncated", recovery: payload };
+}
+//# sourceMappingURL=sanitize.js.map

package/build/src/velocious/sanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../../../src/velocious/sanitize.js"],"names":[],"mappings":"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"}

package/docs/config-reference.md

@@ -38,6 +38,7 @@ Each stage under `stages` supports:
 | `linkedFiles` | array | no | `[]` | Files symlinked from `shared/` into each release. See Linked files below. |
 | `linkedDirs` | array | no | `[]` | Directories symlinked from `shared/` into each release. |
 | `tasks` | object | no | `{}` | Named task groups executed in order during deploy. See Tasks below. |
+| `operationalTasks` | object | no | `{}` | Explicit standalone tasks that run against the active release. See Operational tasks below. |
 | `hooks` | object | no | `{}` | Lifecycle-phase hooks executed at specific points in the deploy pipeline. See Hooks below. |
 | `runtime` | object | no | `{type: "none"}` | Runtime adapter config. See Runtime below. |
 | `healthChecks` | array | no | `[]` | Checks run after tasks and before publish. See Health checks below. |
@@ -198,6 +199,47 @@ rampway production tasks --json
 
 Each entry shows its command plus any `cwd`, `env`, `optional`, and `onlyIfChanged` metadata. Secret-like env values and `KEY=value` assignments in commands are redacted in both the human and `--json` output.
 
+## Operational tasks
+
+`operationalTasks` is a strict namespace for reusable standalone operations. It is separate from deploy lifecycle `tasks`: an operational task runs only when its exact configured name is invoked.
+
+```js
+operationalTasks: {
+  "cache:warm": [
+    {
+      command: "npm run cache:warm",
+      cwd: "backend",
+      env: {NODE_ENV: "production"},
+      forwardEnv: ["CACHE_WARM_CREDENTIAL"]
+    }
+  ]
+}
+```
+
+Each value is a command string, one entry object, or a non-empty ordered array of strings and entry objects. Entry objects accept only:
+
+- `command` — required non-empty shell command from trusted configuration.
+- `cwd` — optional non-empty release-relative directory; absolute and escaping paths are rejected.
+- `env` — optional string-valued environment literals with safe shell names. Secret-like keys are rejected; use `forwardEnv`.
+- `forwardEnv` — optional unique allowlist of safe environment names. Every named value must exist in Rampway's invocation environment and is always treated as sensitive.
+
+Task names are 1–128 characters and match `^[A-Za-z0-9][A-Za-z0-9:_-]*$`. Selection is an exact name lookup; command text and arbitrary trailing arguments cannot come from the CLI.
+
+```bash
+CACHE_WARM_CREDENTIAL=... rampway production task cache:warm
+CACHE_WARM_CREDENTIAL=... rampway production task cache:warm --json
+```
+
+Rampway resolves all forwarded values before transport work, acquires the same exclusive lock used by deploy and rollback, then strictly resolves `current` to one existing direct child of `releases/`. Every entry is required and runs in order against that immutable release path. Missing configuration, forwarded values, lock ownership, active release, command failures, and transport failures all fail closed. There is no task `--force`.
+
+For SSH, forwarded values are sent to a fixed remote shell through stdin rather than SSH argv. Known values are redacted from streamed output, returned output, and errors even when echoed without their variable name or split across chunks. Human output identifies the application, stage, task, and release. JSON mode emits only:
+
+```json
+{"application":"demo","stage":"production","task":"cache:warm","releaseId":"20260728120000","status":"passed"}
+```
+
+Standalone task runs are not appended to the deployment report. The plural `rampway <stage> tasks` command remains a read-only inventory of deploy task groups.
+
 ## Hooks
 
 Hooks are lifecycle-phase callbacks that run commands at specific points during the deploy pipeline, outside the fixed task-group slot. Each hook phase accepts an array of task entries (strings or objects, same format as tasks).

package/docs/docker-development-environment.md

@@ -0,0 +1,103 @@
+# Docker development environment
+
+Rampway has one canonical root development image and one persistent Compose service. The image is digest-pinned Ubuntu 26.04 LTS with exact NodeSource Node 24, a checksummed signing key, the universal coding/debugging baseline, and the current OpenCode, Codex, Claude Code, and official Kimi Code CLIs. The build is source-independent: `.dockerignore` closes the build context to the Dockerfile metadata, the image copies no repository content, and project dependencies are installed only inside the running service.
+
+## First use
+
+Prerequisites are Docker with Compose v2 and a dedicated UID/GID-1000 development home containing this checkout at `$DEV_HOME_PATH/rampway`.
+
+Copy the portable template and confirm its required read-only credential sources:
+
+```bash
+cp .env.example .env
+test -d "${GH_CONFIG_SOURCE_PATH:-$HOME/.config/gh}"
+test -f "${CODEX_AUTH_SOURCE_PATH:-$HOME/.codex/auth.json}"
+```
+
+Set `DEV_HOME_PATH` in `.env` to a dedicated home path containing this checkout at `$DEV_HOME_PATH/rampway`. Do not use an unrelated general host home or recursively change its ownership in the container. The environment template defaults to `/home/dev`; adjust it for any non-default host layout.
+
+Run the preparation helper to create the required mount-target parent directories with correct permissions, then start the persistent service and install locked dependencies:
+
+```bash
+scripts/prepare-dev-home.sh
+docker compose up --build --detach dev
+scripts/docker-run.sh npm ci
+```
+
+`scripts/docker-run.sh` uses `docker compose exec -T dev` and preserves every command argument exactly. The service must already be running. Dependencies, caches, the checkout, and ordinary tool state persist naturally under the complete `/home/dev` bind.
+
+## Isolation and mounts
+
+Compose declares the default project name `rampway`. Override it with `COMPOSE_PROJECT_NAME` (or `-p`) and use a distinct `DEV_HOME_PATH` for each concurrent instance. Run `scripts/prepare-dev-home.sh` to create required mount-target parent directories before the first start:
+
+```bash
+COMPOSE_PROJECT_NAME=rampway-review DEV_HOME_PATH=/srv/rampway-dev-homes/review \
+  scripts/prepare-dev-home.sh
+COMPOSE_PROJECT_NAME=rampway-review DEV_HOME_PATH=/srv/rampway-dev-homes/review \
+  docker compose up --build --detach dev
+```
+
+The `dev` service has exactly these mounts:
+
+- `${DEV_HOME_PATH:?Set DEV_HOME_PATH in .env}` at `/home/dev`;
+- `${GH_CONFIG_SOURCE_PATH:?Set GH_CONFIG_SOURCE_PATH in .env}` at `/home/dev/.config/gh`, read-only;
+- `${CODEX_AUTH_SOURCE_PATH:?Set CODEX_AUTH_SOURCE_PATH in .env}` at `/home/dev/.codex/auth.json`, read-only.
+
+The GitHub config directory is selected through `GH_CONFIG_DIR`. Only the narrow Codex auth file is authorized; SSH keys, Docker sockets, broad host auth mounts, and separate Claude/Kimi/OpenCode secret paths are not. The tracked topology also forbids source split mounts, named source/session volumes, fixed names/ports, privileged mode, sidecars, and container-side ownership fixups.
+
+Provider CLI installation is not provider authorization. Threadwire remains parent-owned and is resolved outside this service through bare unversioned `npx threadwire`; Rampway installs no global or project Threadwire package and tracks no provider workspace profile.
+
+## Static validation
+
+The dependency-free verifier checks the image pin, NodeSource verification, provider specs, complete apt baseline, non-root identity, exact mounts, fail-closed interpolation, closed build context, forbidden topology, ignored `.env`, and helper contract. Its focused tests also inject representative regressions:
+
+```bash
+npm run verify:docker-dev-environment
+npm run test:docker-dev-environment
+```
+
+## Docker-capable coordinator validation
+
+The bootstrap service has no Docker access. A coordinator must render Compose and build the image cleanly:
+
+```bash
+export COMPOSE_PROJECT_NAME=rampway-canonical-validation
+docker compose config --quiet
+docker compose config
+docker compose build --pull --no-cache dev
+docker compose up --detach dev
+docker compose exec -T dev sh -lc 'test "$HOME" = /home/dev && test "$PWD" = /home/dev/rampway && test "$(id -u)" = 1000 && test "$(id -g)" = 1000'
+docker compose exec -T dev npm ci
+docker compose exec -T dev npm run verify:docker-dev-environment
+```
+
+To prove two-instance isolation, prepare two UID/GID-1000 development homes with Rampway at `<home>/rampway`, start both, and compare their container IDs:
+
+```bash
+COMPOSE_PROJECT_NAME=rampway-isolation-a DEV_HOME_PATH=/srv/rampway-dev-homes/isolation-a docker compose up --build --detach dev
+COMPOSE_PROJECT_NAME=rampway-isolation-b DEV_HOME_PATH=/srv/rampway-dev-homes/isolation-b docker compose up --build --detach dev
+test "$(COMPOSE_PROJECT_NAME=rampway-isolation-a docker compose ps -q dev)" != "$(COMPOSE_PROJECT_NAME=rampway-isolation-b docker compose ps -q dev)"
+```
+
+For fresh cutover, provision a new dedicated home with Rampway already checked out at `<home>/rampway`, then perform a clean image build and dependency install:
+
+```bash
+export RAMPWAY_COMPOSE_PROJECT=rampway-cutover-fresh
+export RAMPWAY_DEV_HOME=/srv/rampway-dev-homes/cutover-fresh
+test -d "$RAMPWAY_DEV_HOME/rampway/.git"
+COMPOSE_PROJECT_NAME="$RAMPWAY_COMPOSE_PROJECT" DEV_HOME_PATH="$RAMPWAY_DEV_HOME" docker compose build --pull --no-cache dev
+COMPOSE_PROJECT_NAME="$RAMPWAY_COMPOSE_PROJECT" DEV_HOME_PATH="$RAMPWAY_DEV_HOME" docker compose up --build --detach dev
+COMPOSE_PROJECT_NAME="$RAMPWAY_COMPOSE_PROJECT" DEV_HOME_PATH="$RAMPWAY_DEV_HOME" docker compose exec -T dev npm ci
+```
+
+For exact resume, reuse the retained home and project name without reinstalling or relocating state, then prove the same checkout revision is visible:
+
+```bash
+test -n "$RAMPWAY_COMPOSE_PROJECT"
+test -d "$RAMPWAY_DEV_HOME/rampway/.git"
+export RAMPWAY_EXPECTED_HEAD="$(git -C "$RAMPWAY_DEV_HOME/rampway" rev-parse HEAD)"
+COMPOSE_PROJECT_NAME="$RAMPWAY_COMPOSE_PROJECT" DEV_HOME_PATH="$RAMPWAY_DEV_HOME" docker compose up --build --detach dev
+COMPOSE_PROJECT_NAME="$RAMPWAY_COMPOSE_PROJECT" DEV_HOME_PATH="$RAMPWAY_DEV_HOME" docker compose exec -T -e RAMPWAY_EXPECTED_HEAD="$RAMPWAY_EXPECTED_HEAD" dev sh -lc 'test "$PWD" = /home/dev/rampway && test "$(git rev-parse HEAD)" = "$RAMPWAY_EXPECTED_HEAD"'
+```
+
+The obsolete `/workspace` and named-volume state is not imported. Verify the new service before stopping the old project; removal of old named volumes is a separate destructive coordinator decision.

package/docs/migration-from-capistrano.md

@@ -17,6 +17,7 @@ Rampway is a JS-native alternative to Capistrano for Node projects. This guide m
 | `SSHKit` | `transport: {type: "ssh"}` |
 | `after/before` hooks | `tasks` run in config order, or use lifecycle `hooks` for phase-specific callbacks |
 | `deploy:starting` … `deploy:finished` | task groups + runtime deploy |
+| Explicit custom task against `current` | `operationalTasks` + `rampway production task <exact-name>` |
 | `cap production deploy` | `rampway production deploy` |
 | `cap -T` / `cap production -T` | `rampway production tasks` |
 | `cap production deploy:rollback` | `rampway production rollback` |
@@ -106,7 +107,27 @@ tasks: {
 }
 ```
 
-### 5. Convert process management
+### 5. Convert standalone operational tasks
+
+Keep operations that were invoked explicitly in Capistrano out of deploy task groups. Declare each one under the strict `operationalTasks` namespace and invoke its exact configured name:
+
+```js
+operationalTasks: {
+  "cache:warm": {
+    command: "npm run cache:warm",
+    cwd: "backend",
+    forwardEnv: ["CACHE_WARM_CREDENTIAL"]
+  }
+}
+```
+
+```bash
+CACHE_WARM_CREDENTIAL=... rampway production task cache:warm
+```
+
+Rampway owns the configured transport, shared deploy lock, active-release resolution, and secret-value redaction. Replace the former caller's direct SSH with the Rampway invocation; do not retain an SSH fallback. Operational tasks are explicit and never run as part of every deploy.
+
+### 6. Convert process management
 
 Capistrano relies on SSH-based process management (puma, sidekiq, etc.) or custom tasks:
 
@@ -136,7 +157,7 @@ Rollbridge handles zero-downtime restarts, health checks, and log access. Rampwa
 
 For simple setups without a process manager, use `runtime: {type: "none"}` and handle process restarts yourself via task commands.
 
-### 6. Run the first deploy
+### 7. Run the first deploy
 
 ```bash
 # Validate
@@ -149,7 +170,7 @@ rampway production plan
 rampway production deploy
 ```
 
-### 7. Verify and cleanup
+### 8. Verify and cleanup
 
 ```bash
 rampway production status
@@ -162,6 +183,7 @@ After verifying the first deploy works, remove your old Capistrano config files.
 
 - **No Ruby dependency.** Rampway runs on Node.js, matching your JS/TS stack.
 - **Task groups replace hooks.** Order task groups instead of registering `after`/`before` callbacks. For Capistrano-style lifecycle callbacks, use `hooks` with named phases like `before_publish` and `after_cleanup`.
+- **Operational tasks replace explicitly invoked remote tasks.** Configure an exact name under `operationalTasks`; Rampway executes it against the locked active release and securely forwards allowlisted caller environment values.
 - **Runtime adapters replace process management tasks.** Rollbridge or a custom adapter handles zero-downtime handoff.
 - **ESM config.** `rampway.config.mjs` uses ES module syntax, not Ruby DSL.
 - **Health checks are built in.** Add `healthChecks` to verify deploy readiness before publishing.

package/docs/velocious-deployment-api.md

@@ -0,0 +1,189 @@
+# Velocious callable deployment API
+
+`rampway/velocious` is Rampway's authenticated deployment control plane for a
+Velocious application. Rampway owns every deployment-specific decision and
+calls its normal deploy lifecycle; Velocious supplies only route mounting,
+request/connection scopes, database persistence, background execution, and
+framework error events.
+
+The API accepts no command, path, repository, branch, environment value, log
+request, or arbitrary Git ref. A caller can select only a configured
+project/stage pair, an immutable lowercase 40-character commit SHA reachable
+from that target's approved release branch, and an idempotency key.
+The idempotency key must be a non-secret client-generated value of at most 255
+characters and must not contain any configured bearer token; matching is
+case-sensitive, and such requests are rejected with `422` before run lookup or
+persistence.
+
+## Install and mount
+
+Install Velocious in the application that mounts this optional integration.
+Rampway declares it as an optional peer so applications that only use the CLI
+do not acquire a web-framework dependency.
+
+```sh
+npm install rampway velocious
+```
+
+In the application's Velocious routes file:
+
+```js
+import Routes from "velocious/build/src/routes/index.js"
+import RampwayDeploymentApi from "rampway/velocious"
+import deploymentSecrets from "../config/secrets/deployments.js"
+
+const routes = new Routes()
+
+routes.draw((route) => {
+  route.mount(RampwayDeploymentApi, {
+    at: "/rampway/deployments",
+    accessTokens: deploymentSecrets.rampwayAccessTokens,
+    projects: {
+      "my-app": {
+        stages: {
+          production: {
+            configPath: "/srv/my-app/control/rampway.config.mjs",
+            releaseBranch: "main"
+          }
+        }
+      }
+    }
+  })
+})
+
+export default {routes}
+```
+
+`accessTokens` and every `configPath` are explicit backend configuration.
+Provision the secrets module outside source control using the application's
+normal secret mechanism. There is deliberately no environment-variable
+fallback. `configPath` must be absolute, and its selected Rampway stage must
+use `remote-git`; the deployment target must have Git access to the stage's
+configured repository. Every `releaseBranch` is checked against Git heads-ref
+rules during mounting, so invalid names such as a trailing dot or `.lock`
+component fail at startup rather than during deployment.
+
+Mount options:
+
+| Option | Required | Meaning |
+| --- | --- | --- |
+| `at` | yes | HTTP mount prefix. |
+| `accessTokens` | yes | One or more non-empty backend-held bearer tokens. |
+| `projects` | yes | Explicit project/stage allowlist with absolute Rampway config paths and approved release branches. |
+| `databaseIdentifier` | no | Velocious database used for runs/audits; default `default`. |
+| `staleRunTimeoutMs` | no | Ownership lease; default `60000`, minimum `4`. |
+
+## Client calls
+
+Create a run from a client whose token is also loaded from explicit backend
+secrets (not an environment fallback or command argument):
+
+```js
+import deploymentClientSecrets from "./config/secrets/deployment-client.js"
+
+const baseUrl = "https://app.example/rampway/deployments"
+const headers = {
+  Authorization: `Bearer ${deploymentClientSecrets.rampwayAccessToken}`,
+  "Content-Type": "application/json"
+}
+const createResponse = await fetch(`${baseUrl}/runs`, {
+  method: "POST",
+  headers,
+  body: JSON.stringify({
+    project: "my-app",
+    stage: "production",
+    revision: "0123456789abcdef0123456789abcdef01234567",
+    idempotencyKey: "release-2026-08-03-1"
+  })
+})
+const created = await createResponse.json()
+```
+
+Read the durable result:
+
+```js
+const runResponse = await fetch(`${baseUrl}/runs/${encodeURIComponent(created.run.id)}`, {headers})
+const {run, current} = await runResponse.json()
+```
+
+Authentication is accepted only from the `Authorization` header. Never place
+the token in a URL or command argument that is logged; clients should obtain it
+from their own secret store and configure the HTTP library's header directly.
+Rampway never includes tokens in response data, run state, audit payloads, Git
+commands, deploy commands, or deployment reports. Adapter values and object
+keys are JSON-normalized and recursively redacted before persistence. Sanitized
+structures are limited to 100 entries per array/object, 1,000 visited values,
+20 levels, 4,000 characters per string, and 64 KiB total serialized output;
+explicit truncation markers and a bounded redacted preview retain diagnostic
+context.
+
+Create responses are bounded:
+
+- `202`: created; execution continues in a fresh Velocious connection context.
+- `200`: matching idempotent replay; the original run is returned.
+- `401`: missing or invalid bearer token.
+- `404`: project/stage is not allowlisted.
+- `409`: key conflict, an active deployment, or operator reconciliation is required.
+- `422`: invalid request parameters.
+
+Run status is one of `pending`, `running`, `succeeded`, `failed`, `interrupted`,
+or `reconciliation_required`. Failed runs include sanitized recovery state.
+An immutable revision that is not reachable from the approved branch is
+recorded as a sanitized failed run rather than discarded before admission.
+Readback also reports the current/previous Rampway release and active revision.
+If live status cannot be read, the response still returns the durable run with
+`live_status: null` and a sanitized `live_status_error` annotation; the outage
+is also sent to Velocious framework error reporting.
+
+## Execution and recovery guarantees
+
+Rampway serializes durable admission before validating reachability on the
+deployment target, so an idempotent retry storm performs the Git fetch only for
+the created run. It then invokes the same `deploy()` used by the CLI: deploy
+lock, immutable remote-Git release, linked state, build/migration tasks, runtime
+handoff, health checks, `current` link, cleanup, and report persistence. It does
+not implement an alternate deployment engine or arbitrary command bridge. If
+failure occurs after the requested revision becomes active, the executor calls
+Rampway's existing rollback lifecycle with the captured prior current release
+as its explicit target and records whether that previous live state was
+restored.
+
+Runs and audits are stored in `rampway_deployment_runs` and
+`rampway_deployment_api_audit_events`, scoped by a stable hash of the mount.
+Target and idempotency advisory locks prevent duplicate concurrent admission,
+including one key racing across targets. Pending/running/terminal transitions
+are fenced by mount, run, owner, status, and (for stale reconciliation) the
+observed heartbeat. A renewed live owner therefore cannot be reclaimed, and an
+expired owner cannot overwrite a reconciled run.
+
+Pending work whose lease expires becomes `interrupted` and no longer blocks a
+new run. A stale running run, or a known successful activation whose success
+record could not be persisted, becomes `reconciliation_required` and continues
+to block duplicates until an operator verifies live state. Audit persistence
+failure is reported through both Velocious `framework-error` and `all-error`
+events and never strands deployment execution.
+Keyed retries and run-status polling evaluate the lease before returning, so a
+dead owner's stale `pending` or `running` state is reconciled without requiring
+a different-key deployment attempt.
+
+## Token rotation and revocation
+
+Use overlapping tokens for zero-downtime rotation:
+
+1. Add a new random token to the backend secrets list and restart/deploy every
+   web worker.
+2. Move every authorized client to the new token.
+3. Remove the old token from backend secrets and restart/deploy every worker
+   again.
+4. Confirm the old token receives `401` on every instance.
+
+For emergency revocation, remove the compromised token and restart all workers
+immediately. Revocation affects new HTTP requests; an already authenticated,
+durably admitted run continues under its owner lease. Inspect the run and audit
+records, reconcile any ambiguous running result, and rotate any repository or
+host credentials independently if they may also be compromised.
+
+Do not print tokens while diagnosing authentication. Record only token version
+or fingerprint metadata in an external secret inventory, never the token
+itself. Rampway framework-error payloads deliberately omit the HTTP request so
+listeners cannot accidentally serialize its Authorization header.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rampway",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "JS-native Capistrano-style release-directory deployments with Rollbridge integration.",
   "type": "module",
   "private": false,
@@ -54,6 +54,14 @@
       "types": "./build/src/test-helpers.d.ts",
       "default": "./build/src/test-helpers.js"
     },
+    "./velocious": {
+      "types": "./build/src/velocious/index.d.ts",
+      "default": "./build/src/velocious/index.js"
+    },
+    "./velocious.js": {
+      "types": "./build/src/velocious/index.d.ts",
+      "default": "./build/src/velocious/index.js"
+    },
     "./package.json": "./package.json"
   },
   "imports": {
@@ -64,8 +72,10 @@
   },
   "scripts": {
     "test": "npm run build && node --test tests/**/*.test.js",
-    "lint": "eslint src/ tests/",
+    "lint": "eslint src/ tests/ scripts/",
     "typecheck": "tsc --noEmit",
+    "verify:docker-dev-environment": "node scripts/verify-docker-dev-environment.js",
+    "test:docker-dev-environment": "node --test tests/docker-dev-environment.test.js",
     "clean": "node scripts/clean.js",
     "compile": "tsc -b",
     "postcompile": "node scripts/ensure-cli-executable.js",
@@ -84,7 +94,16 @@
   "devDependencies": {
     "eslint": "^9.39.2",
     "eslint-plugin-jsdoc": "^61.5.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "velocious": "^1.0.574"
+  },
+  "peerDependencies": {
+    "velocious": "^1.0.574"
+  },
+  "peerDependenciesMeta": {
+    "velocious": {
+      "optional": true
+    }
   },
   "files": [
     "build",