run402 4.0.2 → 4.1.0

package/README.md

@@ -74,6 +74,8 @@ run402 projects schema <id>                              # introspect tables + R
 ```bash
 run402 sites deploy-dir ./dist                # incremental upload (plan/commit transport)
 run402 deploy apply --manifest app.json       # one-call full stack deploy
+run402 apply --manifest app.json --rehearse --json
+run402 deploy verify op_... --project prj_... --wait
 run402 deploy release active                  # inspect current-live release inventory
 run402 deploy release diff --from empty --to active
 run402 deploy diagnose --project prj_123 https://example.com/events --method GET
@@ -82,7 +84,9 @@ run402 subdomains claim my-app                # → my-app.run402.com (auto-reas
 ```
 
 `deploy-dir` hashes each file client-side and only uploads bytes the gateway doesn't already have. Re-deploying an unchanged tree returns immediately with `bytes_uploaded: 0`. Progress events stream to stderr.
-Release inspection commands print `{ release: ... }` or `{ diff: ... }` (raw payload, no envelope — see the "Output Contract" section in [llms-cli.txt](llms-cli.txt)); use them after deploys to compare release inventory without starting another mutation. Inventories include `release_generation`, `static_manifest_sha256`, and nullable `static_manifest_metadata`; diffs include `static_assets` counters such as unchanged/changed/added/removed and CAS byte reuse. `deploy diagnose` / `deploy resolve --url` print URL-first diagnostics with `would_serve`, `diagnostic_status`, `match`, warnings, `edge_propagation`, and next steps; host misses are successful diagnostic calls with `would_serve: false`. Stable-host resolve fields can include `authorization_result`, `cas_object`, `response_variant`, `allow`, `route_pattern`, `target_type`, `target_name`, `target_file`, and `edge_propagation` (`settled`, `propagating`, or `sync_pending`).
+Release inspection commands print `{ release: ... }` or `{ diff: ... }` (raw payload, no envelope — see the "Output Contract" section in [llms-cli.txt](llms-cli.txt)); use them after deploys to compare release inventory without starting another mutation. `deploy verify` prints the canonical edge-coherence report and exits 2 when the report is valid but not yet coherent. Inventories include `release_generation`, `static_manifest_sha256`, and nullable `static_manifest_metadata`; diffs include `static_assets` counters such as unchanged/changed/added/removed and CAS byte reuse. `deploy diagnose` / `deploy resolve --url` print URL-first diagnostics with `would_serve`, `diagnostic_status`, `match`, warnings, `edge_propagation`, and next steps; host misses are successful diagnostic calls with `would_serve: false`. Stable-host resolve fields can include `authorization_result`, `cas_object`, `response_variant`, `allow`, `route_pattern`, `target_type`, `target_name`, `target_file`, and `edge_propagation` (`settled`, `propagating`, or `sync_pending`).
+
+For database-bearing changes, use `run402 apply --manifest app.json --rehearse --json` before commit. It creates a contained branch, applies the candidate plan there, runs checks, and exits nonzero on a failed rehearsal. Manual restore points live under `run402 snapshots create|list|get|restore|delete`; temporary data branches live under `run402 branches create|list|renew|delete`.
 
 ### GitHub Actions OIDC deploys
 
@@ -150,7 +154,7 @@ import { db, adminDb, auth, email, ai } from "@run402/functions";
 
 ### Same-origin web routes
 
-`run402 deploy apply` accepts `site.public_paths` for clean static browser URLs and `routes.replace` for function ingress or exact method-aware static aliases. Release asset paths such as `events.html` are distinct from public paths such as `/events`: prefer `{ "site": { "replace": { "events.html": { "data": "<h1>Events</h1>" } }, "public_paths": { "mode": "explicit", "replace": { "/events": { "asset": "events.html" } } } } }` for ordinary clean static URLs. In explicit mode `/events.html` is not public unless separately declared; `mode: "implicit"` restores filename-derived reachability and can widen access. `routes.replace` is an array of route entries, not a path-keyed map. Use exact `/admin` plus final-wildcard `/admin/*` for a routed section root, narrow `/api/*` methods such as `["GET","POST","OPTIONS"]`, POST-only `/login` function routes, and exact static route targets like `{ "pattern": "/events", "methods": ["GET","HEAD"], "target": { "type": "static", "file": "events.html" } }` only for route-table alias behavior. Static route `file` is a release asset path, not a public path, URL, CAS hash, rewrite, or redirect. Routed functions use Node 22 Fetch Request -> Response; `req.url` is the full public URL on managed subdomains, deployment hosts, and verified custom domains. Direct `/functions/v1/:name` remains API-key protected. Known resolve literals include `host_missing`, `manifest_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `none`, `static_exact`, `static_index`, `spa_fallback`, `spa_fallback_missing`, `route_function`, `route_static_alias`, and `route_method_miss`; known `authorization_result` values include `authorized`, `not_public`, `not_applicable`, `manifest_missing`, `target_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `missing_cas_object`, `unfinalized_or_deleting_cas_object`, `size_mismatch`, and `unauthorized_cas_object`. Known `fallback_state` values include `active_release_missing`, `unsupported_manifest_version`, and `negative_cache_hit`; preserve unknown future strings. Release inventories may include `static_public_paths` with `public_path`, `asset_path`, `reachability_authority`, and `direct`; resolve may return the same reachability fields plus `authorization_result`, `cas_object`, `response_variant`, and route/static fields like `allow`, `route_pattern`, `target_type`, `target_name`, and `target_file`. Static route target warnings include `STATIC_ALIAS_SHADOWS_STATIC_PATH`, `STATIC_ALIAS_RELATIVE_ASSET_RISK`, `STATIC_ALIAS_DUPLICATE_CANONICAL_URL`, `STATIC_ALIAS_EXTENSIONLESS_NON_HTML`, and `STATIC_ALIAS_TABLE_NEAR_LIMIT`; inspect active routes, `static_public_paths`, and the backing `asset_path`. Runtime route failure codes to branch on: `ROUTE_MANIFEST_LOAD_FAILED`, `ROUTED_INVOKE_WORKER_SECRET_MISSING`, `ROUTED_INVOKE_AUTH_FAILED`, `ROUTED_ROUTE_STALE`, `ROUTE_METHOD_NOT_ALLOWED`, and `ROUTED_RESPONSE_TOO_LARGE`.
+`run402 deploy apply` accepts `site.public_paths` for clean static browser URLs and `routes.replace` for function ingress or exact method-aware static aliases. Release asset paths such as `events.html` are distinct from public paths such as `/events`: prefer `{ "site": { "replace": { "events.html": { "data": "<h1>Events</h1>" } }, "public_paths": { "mode": "explicit", "replace": { "/events": { "asset": "events.html" } } } } }` for ordinary clean static URLs. In explicit mode `/events.html` is not public unless separately declared; `mode: "implicit"` restores filename-derived reachability and can widen access. `routes.replace` is an array of route entries, not a path-keyed map. Use exact `/admin` plus final-wildcard `/admin/*` for a routed section root, narrow `/api/*` methods such as `["GET","POST","OPTIONS"]`, POST-only `/login` function routes, and exact static route targets like `{ "pattern": "/events", "methods": ["GET","HEAD"], "target": { "type": "static", "file": "events.html" } }` only for route-table alias behavior. Static route `file` is a release asset path, not a public path, URL, CAS hash, rewrite, or redirect. Recipe — static home page + SPA shell: a root alias `{ "pattern": "/", "target": { "type": "static", "file": "home.html" } }` (with `home.html` at the site root) serves real static bytes at `GET /` (`route_static_alias`) while unmatched app routes keep the `index.html` shell (`spa_fallback`); expect non-blocking `STATIC_ALIAS_SHADOWS_STATIC_PATH` (warn) / `STATIC_ALIAS_DUPLICATE_CANONICAL_URL` (info) plan lints and verify with `run402 deploy resolve --url https://<your-site>/ --method GET`. Routed functions use Node 22 Fetch Request -> Response; `req.url` is the full public URL on managed subdomains, deployment hosts, and verified custom domains. Direct `/functions/v1/:name` remains API-key protected. Known resolve literals include `host_missing`, `manifest_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `none`, `static_exact`, `static_index`, `spa_fallback`, `spa_fallback_missing`, `route_function`, `route_static_alias`, and `route_method_miss`; known `authorization_result` values include `authorized`, `not_public`, `not_applicable`, `manifest_missing`, `target_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `missing_cas_object`, `unfinalized_or_deleting_cas_object`, `size_mismatch`, and `unauthorized_cas_object`. Known `fallback_state` values include `active_release_missing`, `unsupported_manifest_version`, and `negative_cache_hit`; preserve unknown future strings. Release inventories may include `static_public_paths` with `public_path`, `asset_path`, `reachability_authority`, and `direct`; resolve may return the same reachability fields plus `authorization_result`, `cas_object`, `response_variant`, and route/static fields like `allow`, `route_pattern`, `target_type`, `target_name`, and `target_file`. Static route target warnings include `STATIC_ALIAS_SHADOWS_STATIC_PATH`, `STATIC_ALIAS_RELATIVE_ASSET_RISK`, `STATIC_ALIAS_DUPLICATE_CANONICAL_URL`, `STATIC_ALIAS_EXTENSIONLESS_NON_HTML`, and `STATIC_ALIAS_TABLE_NEAR_LIMIT`; inspect active routes, `static_public_paths`, and the backing `asset_path`. Runtime route failure codes to branch on: `ROUTE_MANIFEST_LOAD_FAILED`, `ROUTED_INVOKE_WORKER_SECRET_MISSING`, `ROUTED_INVOKE_AUTH_FAILED`, `ROUTED_ROUTE_STALE`, `ROUTE_METHOD_NOT_ALLOWED`, and `ROUTED_RESPONSE_TOO_LARGE`.
 
 ### Secrets
 

package/cli.mjs

@@ -28,6 +28,9 @@ Commands:
   allowance   Manage your agent allowance (create, fund, balance, status)
   tier        Manage tier subscription (status, set)
   projects    Manage projects (provision, list, query, inspect, delete)
+  apply       Alias for deploy apply; supports --rehearse for migration rehearsal
+  snapshots   Create/list/restore/delete project data snapshots
+  branches    Create/list/renew/delete contained project branches
   admin       Platform-admin operations (lease-perpetual, archive, reactivate)
   cloud       Cloud portability archive export (archives create/download/status)
   archives    Inspect and verify portable project archives locally
@@ -73,6 +76,9 @@ Examples:
   run402 allowance create
   run402 allowance fund
   run402 deploy apply --manifest app.json
+  run402 apply --manifest app.json --rehearse --json
+  run402 snapshots list prj_...
+  run402 branches create prj_... --ttl-days 7 --json
   run402 cloud archives create prj_... --wait --output ./project.r402ar --json
   run402 core projects import ./project.r402ar --name imported-project --env-file ./required.env --json
   run402 jobs submit --file job.json
@@ -175,6 +181,21 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "apply": {
+    const { runDeployV2 } = await import("./lib/deploy-v2.mjs");
+    await runDeployV2("apply", [sub, ...rest].filter(Boolean));
+    break;
+  }
+  case "snapshots": {
+    const { run } = await import("./lib/snapshots.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "branches": {
+    const { run } = await import("./lib/branches.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "admin": {
     const { run } = await import("./lib/admin.mjs");
     await run(sub, rest);

package/lib/branches.mjs

@@ -0,0 +1,113 @@
+import { getSdk } from "./sdk.mjs";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import {
+  assertAllowedValue,
+  assertKnownFlags,
+  flagValue,
+  hasHelp,
+  normalizeArgv,
+  parseIntegerFlag,
+  positionalArgs,
+} from "./argparse.mjs";
+import { resolveProjectId } from "./config.mjs";
+
+const HELP = `run402 branches — Contained project data branches
+
+Usage:
+  run402 branches create [project-id] [--from-snapshot <snapshot-id>] [--name <label>] [--email-mode sandbox|off] [--enable-cron] [--ttl-days <n>] [--json]
+  run402 branches list [project-id] [--json]
+  run402 branches renew [project-id] <branch-project-id> [--ttl-days <n>] [--json]
+  run402 branches delete [project-id] <branch-project-id> [--json]
+`;
+
+const FLAG_VALUES = ["--from-snapshot", "--name", "--email-mode", "--ttl-days"];
+const FLAGS = new Set([...FLAG_VALUES, "--enable-cron", "--json", "--help", "-h"]);
+
+export async function run(sub, args = []) {
+  const all = [sub, ...args].filter(Boolean);
+  if (!sub || hasHelp(all)) {
+    console.log(HELP);
+    return;
+  }
+  const rest = normalizeArgv(args);
+  assertKnownFlags(rest, [...FLAGS], FLAG_VALUES);
+  switch (sub) {
+    case "create": return create(rest);
+    case "list": return list(rest);
+    case "renew": return renew(rest);
+    case "delete": return deleteBranch(rest);
+    default:
+      fail({
+        code: "UNKNOWN_SUBCOMMAND",
+        message: `Unknown branches subcommand: ${sub}`,
+        hint: "Run `run402 branches --help` for usage.",
+        details: { command: "branches", subcommand: sub },
+      });
+  }
+}
+
+async function create(args) {
+  const projectId = resolveOptionalProject(positionalArgs(args, FLAG_VALUES)[0]);
+  const emailMode = flagValue(args, "--email-mode") ?? undefined;
+  if (emailMode !== undefined) assertAllowedValue(emailMode, ["sandbox", "off"], "--email-mode");
+  const ttlDaysFlag = flagValue(args, "--ttl-days");
+  const ttlDays = ttlDaysFlag === null ? undefined : parseIntegerFlag("--ttl-days", ttlDaysFlag, { min: 1, max: 30 });
+  try {
+    const branch = await getSdk().branches.create(projectId, {
+      ...(flagValue(args, "--from-snapshot") ? { fromSnapshotId: flagValue(args, "--from-snapshot") } : {}),
+      ...(flagValue(args, "--name") ? { name: flagValue(args, "--name") } : {}),
+      ...(emailMode ? { emailMode } : {}),
+      ...(args.includes("--enable-cron") ? { enableCron: true } : {}),
+      ...(ttlDays !== undefined ? { ttlDays } : {}),
+    });
+    console.log(JSON.stringify({ ok: true, branch }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function list(args) {
+  const projectId = resolveOptionalProject(positionalArgs(args, FLAG_VALUES)[0]);
+  try {
+    const result = await getSdk().branches.list(projectId);
+    console.log(JSON.stringify({ project_id: projectId, ...result }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function renew(args) {
+  const { projectId, branchProjectId } = resolveProjectAndBranch(args, "run402 branches renew [project-id] <branch-project-id>");
+  const ttlDaysFlag = flagValue(args, "--ttl-days");
+  const ttlDays = ttlDaysFlag === null ? undefined : parseIntegerFlag("--ttl-days", ttlDaysFlag, { min: 1, max: 30 });
+  try {
+    const branch = await getSdk().branches.renew(projectId, branchProjectId, {
+      ...(ttlDays !== undefined ? { ttlDays } : {}),
+    });
+    console.log(JSON.stringify({ ok: true, branch }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function deleteBranch(args) {
+  const { projectId, branchProjectId } = resolveProjectAndBranch(args, "run402 branches delete [project-id] <branch-project-id>");
+  try {
+    await getSdk().branches.delete(projectId, branchProjectId);
+    console.log(JSON.stringify({ ok: true, project_id: projectId, branch_project_id: branchProjectId, deleted: true }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function resolveOptionalProject(value) {
+  if (value && String(value).startsWith("prj_")) return value;
+  return resolveProjectId(null);
+}
+
+function resolveProjectAndBranch(args, usage) {
+  const pos = positionalArgs(args, FLAG_VALUES);
+  if (pos.length === 1) return { projectId: resolveProjectId(null), branchProjectId: pos[0] };
+  if (pos.length === 2 && pos[0].startsWith("prj_")) return { projectId: pos[0], branchProjectId: pos[1] };
+  fail({ code: "BAD_USAGE", message: `Usage: ${usage}` });
+}

package/lib/core.mjs

@@ -6,6 +6,7 @@ const HELP = `run402 core — Local Run402 Core commands
 
 Usage:
   run402 core projects import <archive-path> --name <project-name> [options]
+  run402 core projects apply  <archive-path> --name <project-name> [options]
 
 Options:
   --name <name>             New Core project name (default imported-project)
@@ -36,7 +37,7 @@ export async function run(sub, args = []) {
     });
   }
   const action = args[0];
-  if (action === "import") return importProject(args.slice(1));
+  if (action === "import" || action === "apply") return importProject(args.slice(1));
   fail({
     code: "UNKNOWN_SUBCOMMAND",
     message: `Unknown core projects subcommand: ${action}`,

package/lib/deploy-v2.mjs

@@ -43,8 +43,8 @@ import { createUpdateCheckScheduler, emitUpdateNotice } from "./update-check.mjs
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
 
 Usage:
-  run402 deploy apply --manifest <path> [--project <id>] [--check|--print-spec|--plan|--require-plan <id>] [--quiet|--final-only]
-  run402 deploy apply --spec '<json>' [--project <id>] [--check|--print-spec|--plan|--require-plan <id>] [--quiet|--final-only]
+  run402 deploy apply --manifest <path> [--project <id>] [--check|--print-spec|--plan|--rehearse|--require-plan <id>] [--quiet|--final-only] [--json]
+  run402 deploy apply --spec '<json>' [--project <id>] [--check|--print-spec|--plan|--rehearse|--require-plan <id>] [--quiet|--final-only] [--json]
   run402 deploy apply --dir <build-output> [--manifest <path>] [--project <id>]
   cat spec.json | run402 deploy apply [--project <id>]
 
@@ -95,7 +95,11 @@ Options:
   --check                 Validate and normalize locally. No gateway calls or uploads.
   --print-spec            Print the normalized ReleaseSpec JSON. No gateway calls or uploads.
   --plan                  Ask the gateway for a reviewed plan. No upload or commit.
+  --rehearse              Plan, upload missing content, run the plan against a contained branch, and print the rehearsal report. Does not commit unless --commit is also passed.
+  --teardown <policy>     Rehearsal branch cleanup policy: keep (default), on_pass, or always.
+  --commit                After a passing rehearsal, commit the original plan.
   --require-plan <id>     Apply only if this reviewed plan still matches.
+  --json                  No-op compatibility flag; success output is always JSON.
   --quiet                 Suppress per-event JSON-line stderr (final result still on stdout)
   --final-only            Alias for --quiet; final success/error envelope is still preserved
   --allow-warning <code>  Continue past this reviewed warning code (repeatable)
@@ -186,6 +190,42 @@ Output:
   stdout: { "events": [...] }
 `;
 
+const VERIFY_HELP = `run402 deploy verify — Verify gateway and edge coherence
+
+Usage:
+  run402 deploy verify <operation_id> [--project <id>] [--wait] [--timeout <seconds>] [--json]
+  run402 deploy verify --operation <operation_id> [--project <id>] [--wait] [--timeout <seconds>] [--json]
+
+Checks that the gateway's live release and the edge pointers observed by
+Run402 agree for the deployment operation. Use --wait to poll until the report
+is coherent or the timeout elapses.
+
+Options:
+  --operation <id>       Operation id to verify. Equivalent to the positional id.
+  --project <id>         Project ID that owns the operation (default: active project)
+  --wait                 Poll until coherent or timeout
+  --timeout <seconds>    Maximum wait time with --wait (default 60)
+  --json                 No-op compatibility flag; output is always JSON
+
+Exit codes:
+  0  coherent
+  2  valid report, but not coherent before timeout
+  1  usage, auth, network, or gateway error
+
+Output:
+  stdout: { "status": "coherent"|"not_coherent", "coherent": boolean, "report": {...} }
+  stderr: one JSON poll progress line per attempt when --wait is set
+`;
+
+const REHEARSE_HELP = `run402 deploy rehearse — Run a persisted plan on a contained branch
+
+Usage:
+  run402 deploy rehearse <plan_id> [--project <id>] [--teardown keep|on_pass|always] [--json]
+
+Use \`run402 apply --manifest app.json --rehearse --json\` for the canonical
+one-shot plan → upload → rehearse report flow.
+`;
+
 const RELEASE_HELP = `run402 deploy release — Inspect deploy release inventory and diffs
 
 Usage:
@@ -283,10 +323,12 @@ exit 0; inspect would_serve and diagnostic_status in the result payload.
 
 export async function runDeployV2(sub, args) {
   if (sub === "apply") return await applyCmd(args);
+  if (sub === "rehearse") return await rehearseCmd(args);
   if (sub === "promote") return await promoteCmd(args);
   if (sub === "resume") return await resumeCmd(args);
   if (sub === "list") return await listCmd(args);
   if (sub === "events") return await eventsCmd(args);
+  if (sub === "verify") return await verifyCmd(args);
   if (sub === "release") return await releaseCmd(args);
   if (sub === "diagnose") return await diagnoseCmd(args);
   if (sub === "resolve") return await resolveCmd(args);
@@ -297,6 +339,59 @@ export async function runDeployV2(sub, args) {
   });
 }
 
+async function rehearseCmd(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(REHEARSE_HELP);
+    return;
+  }
+  const valueFlags = new Set(["--project", "--teardown"]);
+  const allowedFlags = ["--project", "--teardown", "--json", "--help", "-h"];
+  const positionals = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (valueFlags.has(arg)) {
+      if (args[i + 1] === undefined || String(args[i + 1]).startsWith("--")) {
+        fail({ code: "BAD_USAGE", message: `${arg} requires a value`, details: { flag: arg } });
+      }
+      i += 1;
+      continue;
+    }
+    if (String(arg).startsWith("-")) {
+      if (!allowedFlags.includes(arg)) {
+        fail({ code: "BAD_USAGE", message: `Unknown flag for deploy rehearse: ${arg}`, details: { flag: arg, allowed_flags: allowedFlags } });
+      }
+      continue;
+    }
+    positionals.push(arg);
+  }
+  const planId = positionals[0];
+  if (!planId || positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 deploy rehearse <plan_id> [--project <id>] [--teardown keep|on_pass|always] [--json]" });
+  }
+  const teardown = flagValue(args, "--teardown") ?? "keep";
+  if (!["keep", "on_pass", "always"].includes(teardown)) {
+    fail({ code: "BAD_USAGE", message: "--teardown must be one of: keep, on_pass, always", details: { flag: "--teardown", value: teardown } });
+  }
+  const project = flagValue(args, "--project") ?? undefined;
+  if (!isCoreApiTarget() && !loadLiveControlPlaneSession()) {
+    allowanceAuthHeaders(`/apply/v1/plans/${planId}/rehearse`);
+  }
+  try {
+    const rehearsal = await withAutoApprove(() =>
+      getSdk()._applyEngine.rehearse(planId, { project, teardown }),
+    );
+    console.log(JSON.stringify({
+      ok: rehearsal.report.status === "passed",
+      rehearsal,
+      commit_command: `run402 deploy apply --require-plan ${planId}`,
+    }, null, 2));
+    if (rehearsal.report.status !== "passed") process.exit(1);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 const PROMOTE_HELP = `run402 deploy promote — Operator pointer-swap recovery (v1.58+)
 
 Usage:
@@ -520,8 +615,10 @@ function parseApplyArgs(args) {
     allowWarningCodes: [],
     mode: null,
     planFingerprint: null,
+    rehearsalTeardown: "keep",
+    commitAfterRehearse: false,
   };
-  const allowedFlags = ["--manifest", "--spec", "--dir", "--project", "--quiet", "--final-only", "--allow-warning", "--allow-warnings", "--check", "--print-spec", "--plan", "--require-plan", "--plan-fingerprint", "--help", "-h"];
+  const allowedFlags = ["--manifest", "--spec", "--dir", "--project", "--quiet", "--final-only", "--json", "--allow-warning", "--allow-warnings", "--check", "--print-spec", "--plan", "--rehearse", "--teardown", "--commit", "--require-plan", "--plan-fingerprint", "--help", "-h"];
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -529,7 +626,7 @@ function parseApplyArgs(args) {
       console.log(APPLY_HELP);
       process.exit(0);
     }
-    if (arg === "--manifest" || arg === "--spec" || arg === "--dir" || arg === "--project" || arg === "--allow-warning" || arg === "--require-plan" || arg === "--plan-fingerprint") {
+    if (arg === "--manifest" || arg === "--spec" || arg === "--dir" || arg === "--project" || arg === "--allow-warning" || arg === "--require-plan" || arg === "--plan-fingerprint" || arg === "--teardown") {
       const value = args[i + 1];
       if (value === undefined || (typeof value === "string" && value.startsWith("--"))) {
         fail({
@@ -571,6 +668,15 @@ function parseApplyArgs(args) {
         opts.allowWarningCodes.push(value);
       } else if (arg === "--require-plan") {
         setApplyMode(opts, { kind: "applyReviewed", planId: value }, "--require-plan");
+      } else if (arg === "--teardown") {
+        if (!["keep", "on_pass", "always"].includes(value)) {
+          fail({
+            code: "BAD_USAGE",
+            message: "--teardown must be one of: keep, on_pass, always",
+            details: { flag: "--teardown", value },
+          });
+        }
+        opts.rehearsalTeardown = value;
       } else {
         opts.planFingerprint = value;
       }
@@ -578,10 +684,13 @@ function parseApplyArgs(args) {
       continue;
     }
     if (arg === "--quiet" || arg === "--final-only") { opts.quiet = true; continue; }
+    if (arg === "--json") { continue; }
     if (arg === "--allow-warnings") { opts.allowWarnings = true; continue; }
     if (arg === "--check") { setApplyMode(opts, "check", "--check"); continue; }
     if (arg === "--print-spec") { setApplyMode(opts, "printSpec", "--print-spec"); continue; }
     if (arg === "--plan") { setApplyMode(opts, "plan", "--plan"); continue; }
+    if (arg === "--rehearse") { setApplyMode(opts, "rehearse", "--rehearse"); continue; }
+    if (arg === "--commit") { opts.commitAfterRehearse = true; continue; }
     if (typeof arg === "string" && arg.startsWith("-")) {
       fail({
         code: "BAD_USAGE",
@@ -612,6 +721,13 @@ function parseApplyArgs(args) {
       });
     }
   }
+  if (opts.commitAfterRehearse && opts.mode !== "rehearse") {
+    fail({
+      code: "BAD_USAGE",
+      message: "--commit can only be used with --rehearse.",
+      details: { flag: "--commit" },
+    });
+  }
 
   return opts;
 }
@@ -1027,6 +1143,56 @@ async function applyCmd(args) {
       console.log(JSON.stringify(result.plan, null, 2));
       return;
     }
+    if (opts.mode === "rehearse") {
+      const sdk = getSdk(sdkOpts);
+      const planned = await sdk._applyEngine.plan(releaseSpec, { idempotencyKey });
+      const planId = planned.plan.plan_id;
+      if (!planId) {
+        fail({
+          code: "DRY_RUN_PLAN_NOT_COMMITTABLE",
+          message: "Rehearsal requires a persisted plan_id, but the plan response did not include one.",
+          details: { project_id: releaseSpec.project },
+        });
+      }
+      await sdk._applyEngine.upload(planned.plan, {
+        project: releaseSpec.project,
+        byteReaders: planned.byteReaders,
+        onEvent: makeStderrEventWriter(opts.quiet),
+      });
+      const rehearsal = await withAutoApprove(() =>
+        sdk._applyEngine.rehearse(planId, {
+          project: releaseSpec.project,
+          teardown: opts.rehearsalTeardown,
+        }),
+      );
+      if (rehearsal.report.status !== "passed") {
+        console.log(JSON.stringify({
+          ok: false,
+          project_id: releaseSpec.project,
+          plan_id: planId,
+          rehearsal,
+          commit_command: `run402 deploy apply --require-plan ${planId}${planned.plan.plan_fingerprint ? ` --plan-fingerprint ${planned.plan.plan_fingerprint}` : ""}`,
+        }, null, 2));
+        process.exit(1);
+      }
+      if (opts.commitAfterRehearse) {
+        const committed = await sdk._applyEngine.commit(planId, {
+          project: releaseSpec.project,
+          onEvent: makeStderrEventWriter(opts.quiet),
+          idempotencyKey,
+        });
+        console.log(JSON.stringify({ ok: true, project_id: releaseSpec.project, plan: planned.plan, rehearsal, commit: committed }, null, 2));
+        return;
+      }
+      console.log(JSON.stringify({
+        ok: true,
+        project_id: releaseSpec.project,
+        plan: planned.plan,
+        rehearsal,
+        commit_command: `run402 deploy apply --require-plan ${planId}${planned.plan.plan_fingerprint ? ` --plan-fingerprint ${planned.plan.plan_fingerprint}` : ""}`,
+      }, null, 2));
+      return;
+    }
     const requiredPlan = opts.mode && opts.mode.kind === "applyReviewed"
       ? { planId: opts.mode.planId, ...(opts.mode.planFingerprint ? { planFingerprint: opts.mode.planFingerprint } : {}) }
       : undefined;
@@ -1456,6 +1622,100 @@ async function eventsCmd(args) {
   }
 }
 
+async function verifyCmd(args) {
+  const parsed = parseDeploySubcommandArgs(args, {
+    command: "deploy verify",
+    help: VERIFY_HELP,
+    valueFlags: ["--project", "--operation", "--timeout"],
+    booleanFlags: ["--wait", "--json"],
+  });
+  const positionals = expectPositionals(parsed.positionals, {
+    command: "run402 deploy verify <operation_id> [--project <id>] [--wait]",
+    max: 1,
+  });
+  const positionalOperationId = positionals[0] ?? null;
+  const flaggedOperationId = parsed.flags["--operation"] ?? null;
+  if (positionalOperationId && flaggedOperationId && positionalOperationId !== flaggedOperationId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Pass the operation id either positionally or with --operation, not both.",
+      details: { positional: positionalOperationId, operation: flaggedOperationId },
+    });
+  }
+  const operationId = flaggedOperationId ?? positionalOperationId;
+  if (!operationId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <operation_id>.",
+      hint: "run402 deploy verify <operation_id> [--project <id>] [--wait]",
+    });
+  }
+  const project = resolveProjectId(parsed.flags["--project"] ?? null);
+  const wait = Boolean(parsed.flags["--wait"]);
+  const timeoutSeconds = parsed.flags["--timeout"] === undefined
+    ? 60
+    : parsePositiveInt(parsed.flags["--timeout"], "--timeout");
+
+  allowanceAuthHeaders("/apply/v1/operations");
+
+  try {
+    let result;
+    if (wait) {
+      result = await getSdk()._applyEngine.waitEdgeCoherent(operationId, {
+        project,
+        timeoutMs: timeoutSeconds * 1000,
+        onPoll: (event) => {
+          console.error(JSON.stringify({
+            type: "deploy.verify.poll",
+            coherent: event.report.coherent,
+            attempts: event.attempts,
+            elapsed_ms: event.elapsedMs,
+            pending_count: event.report.pending_count,
+            path_count: event.report.path_count,
+            total_path_count: event.report.total_path_count,
+            paths_truncated: event.report.paths_truncated,
+            paths: summarizeEdgeCoherencePaths(event.report.paths),
+          }));
+        },
+      });
+    } else {
+      const report = await getSdk()._applyEngine.edgeCoherence(operationId, { project });
+      result = { coherent: report.coherent, attempts: 1, elapsedMs: 0, report };
+    }
+    const output = {
+      status: result.coherent ? "coherent" : "not_coherent",
+      coherent: result.coherent,
+      operation_id: result.report.operation_id,
+      project_id: result.report.project_id,
+      attempts: result.attempts,
+      elapsed_ms: result.elapsedMs,
+      report: result.report,
+    };
+    console.log(JSON.stringify(output, null, 2));
+    if (!result.coherent) process.exitCode = 2;
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function summarizeEdgeCoherencePaths(paths) {
+  if (!Array.isArray(paths)) return [];
+  return paths.map((path) => ({
+    path: path.path,
+    host: path.host,
+    state: path.state,
+    observed_confidence: path.observed_confidence,
+    expected_release_id: path.expected_release_id,
+    observed_release_id: path.observed_release_id,
+    expected_release_generation: path.expected_release_generation,
+    observed_release_generation: path.observed_release_generation,
+    status: path.status,
+    x_cache: path.x_cache,
+    age_seconds: path.age_seconds,
+    error: path.error,
+  }));
+}
+
 async function releaseCmd(args) {
   const action = args[0];
   if (!action || action === "--help" || action === "-h") {
@@ -1705,7 +1965,7 @@ function parseDeploySubcommandArgs(rawArgs, { command, help, valueFlags = [], bo
   const args = normalizeArgv(rawArgs);
   const valueFlagSet = new Set(valueFlags);
   const booleanFlagSet = new Set(booleanFlags);
-  const numericFlagSet = new Set(["--limit", "--site-limit"]);
+  const numericFlagSet = new Set(["--limit", "--site-limit", "--timeout"]);
   const allowedFlags = new Set([...valueFlags, ...booleanFlags, "--help", "-h"]);
   const flags = {};
   const positionals = [];

package/lib/deploy.mjs

@@ -7,9 +7,11 @@ Usage:
 
 Subcommands:
   apply --manifest <file>       Apply a v2 ReleaseSpec manifest
+  rehearse <plan_id>            Rehearse a persisted plan on a contained branch
   resume <operation_id>         Resume a stuck operation
   list [--project <id>]         List recent deploy operations
   events <operation_id>         Fetch event stream for an operation
+  verify <operation_id>         Verify gateway and edge coherence
   diagnose <url>                Diagnose public URL routing
   resolve --url <url>           Low-level resolve diagnostics
   release ...                   Inspect release inventory and diffs
@@ -48,11 +50,13 @@ export async function run(args) {
   }
 
   switch (sub) {
-    case "apply":
+  case "apply":
+    case "rehearse":
     case "promote":
     case "resume":
     case "list":
     case "events":
+    case "verify":
     case "diagnose":
     case "resolve":
     case "release": {

package/lib/projects.mjs

@@ -33,6 +33,7 @@ Subcommands:
   delete [id] --confirm                   Immediately and irreversibly delete a project (cascade purge) and remove from local state. Requires --confirm.
   promote-user [id] <email>               Promote a user to project_admin role
   demote-user  [id] <email>               Demote a user from project_admin role
+  export [id] [archive options]           Export a portable Run402 Core archive
 
 Examples:
   run402 projects quote
@@ -56,6 +57,7 @@ Examples:
   run402 projects apply-expose prj_abc123 --file manifest.json
   run402 projects get-expose prj_abc123
   run402 projects delete prj_abc123 --confirm
+  run402 projects export prj_abc123 --wait --output ./project.r402ar --json
 
 Global options (any command):
   --wallet <name>   Use a named wallet (profile) for this command. Precedence:
@@ -799,6 +801,10 @@ const FLAGS_BY_SUB = {
     values: ["--file", "--migration-file", "--migration-sql"],
   },
   delete: { known: ["--confirm"], values: [] },
+  export: {
+    known: ["--scope", "--auth", "--consistency", "--idempotency-key", "--output", "--poll-interval", "--timeout", "--wait", "--json", "--json-stream"],
+    values: ["--scope", "--auth", "--consistency", "--idempotency-key", "--output", "--poll-interval", "--timeout"],
+  },
 };
 
 function validateFlags(sub, args) {
@@ -845,6 +851,11 @@ export async function run(sub, args) {
     case "validate-expose": await validateExpose(args); break;
     case "get-expose":   { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await getExpose(projectId); break; }
     case "delete":    { const { projectId, rest } = resolvePositionalProject(args, { rejectBareFirst: true }); await deleteProject(projectId, rest); break; }
+    case "export": {
+      const { run } = await import("./cloud.mjs");
+      await run("archives", ["create", ...args]);
+      break;
+    }
     case "promote-user": { const { projectId, rest } = resolvePositionalProject(args); await promoteUser(projectId, rest[0]); break; }
     case "demote-user":  { const { projectId, rest } = resolvePositionalProject(args); await demoteUser(projectId, rest[0]); break; }
     default: