run402 4.0.1 → 4.0.3

package/README.md

@@ -41,10 +41,13 @@ run402 up --manifest run402.deploy.ts --check
 run402 up --manifest run402.deploy.ts --plan
 run402 up --manifest run402.deploy.ts --require-plan plan_...
 run402 up --manifest run402.deploy.json --project prj_...
+run402 up verify --project prj_...
 ```
 
 `up` is a thin CLI shim over the Node SDK action runner. It discovers `run402.deploy.json` then `app.json`, validates the deploy input before any mutation, resolves the project as `--project` → `.run402/project.json` → manifest `project_id` → approved creation from `--name` → approved active-project fallback, then applies the manifest. `--name` is creation/link metadata only; it is not a manifest field and never renames an existing project. When everything is already configured, plain `run402 up` deploys. Non-interactive recursive prerequisites/local writes require `-y/--yes`.
 
+For app manifests with `verify.http[]`, `up` runs HTTP checks after deploy. Fresh Run402 edge sentinel misses (`x-run402-edge` or sentinel JSON bodies) become `propagation_pending` with diagnostics instead of hard failure while the host binding is still converging. Use `--propagation-budget-s <seconds>` to tune the default 120 second wait, `--no-propagation-wait` to return immediately, and `run402 up verify` to rerun the same checks without upload, deploy, project creation, or resource mutation.
+
 For typed `run402.deploy.ts` configs, pass `--manifest` explicitly because TypeScript/JavaScript configs execute local code. Use `--check` for local-only import/normalize/file validation, `--print-spec` to inspect the normalized `ReleaseSpec`, `--plan` for a gateway-reviewed non-deploying plan, and `--require-plan <plan_id>` to apply only that reviewed intent. Warning flags are not used with `--require-plan`; the reviewed plan binds the exact warning/destructive set. Run402 Core skips Cloud allowance/tier prerequisites and fails closed when no Core project is selected.
 
 ### Allowance
@@ -71,6 +74,7 @@ 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 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
@@ -79,7 +83,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, 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`, and `target_file`.
+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`).
+
+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
 

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,15 @@ Output:
   stdout: { "events": [...] }
 `;
 
+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,6 +296,7 @@ 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);
@@ -297,6 +311,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 +587,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 +598,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 +640,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 +656,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 +693,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 +1115,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;
@@ -1677,6 +1815,7 @@ async function printResolveEnvelope(input) {
       summary: summary.summary,
       request,
       warnings: summary.warnings,
+      edge_propagation: resolution.edge_propagation ?? null,
       resolution,
       next_steps: summary.next_steps,
     }, null, 2));

package/lib/deploy.mjs

@@ -7,6 +7,7 @@ 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
@@ -48,7 +49,8 @@ export async function run(args) {
   }
 
   switch (sub) {
-    case "apply":
+  case "apply":
+    case "rehearse":
     case "promote":
     case "resume":
     case "list":

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:

package/lib/snapshots.mjs

@@ -0,0 +1,137 @@
+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 snapshots — Project database restore points
+
+Usage:
+  run402 snapshots create [project-id] [--json]
+  run402 snapshots list [project-id] [--kind <kind>] [--limit <n>] [--after <cursor>] [--json]
+  run402 snapshots get [project-id] <snapshot-id> [--json]
+  run402 snapshots restore [project-id] <snapshot-id> [--include-auth] [--confirm <token>] [--json]
+  run402 snapshots delete [project-id] <snapshot-id> [--json]
+
+Restore is a two-step handshake. First call without --confirm to get a
+restore_plan.confirm.token, then re-run with --confirm after reviewing the
+data-loss statement.
+`;
+
+const FLAG_VALUES = ["--kind", "--limit", "--after", "--confirm"];
+const FLAGS = new Set([...FLAG_VALUES, "--include-auth", "--json", "--help", "-h"]);
+const SNAPSHOT_KINDS = ["manual", "pre_migration", "pre_restore", "scheduled"];
+
+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 "get": return get(rest);
+    case "restore": return restore(rest);
+    case "delete": return deleteSnapshot(rest);
+    default:
+      fail({
+        code: "UNKNOWN_SUBCOMMAND",
+        message: `Unknown snapshots subcommand: ${sub}`,
+        hint: "Run `run402 snapshots --help` for usage.",
+        details: { command: "snapshots", subcommand: sub },
+      });
+  }
+}
+
+async function create(args) {
+  const projectId = resolveOptionalProject(positionalArgs(args, FLAG_VALUES)[0]);
+  try {
+    const snapshot = await getSdk().snapshots.create(projectId);
+    console.log(JSON.stringify({ ok: snapshot.status === "ready", snapshot }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function list(args) {
+  const projectId = resolveOptionalProject(positionalArgs(args, FLAG_VALUES)[0]);
+  const kind = flagValue(args, "--kind") ?? undefined;
+  if (kind !== undefined) assertAllowedValue(kind, SNAPSHOT_KINDS, "--kind");
+  const limitFlag = flagValue(args, "--limit");
+  const limit = limitFlag === null ? undefined : parseIntegerFlag("--limit", limitFlag, { min: 1, max: 100 });
+  try {
+    const result = await getSdk().snapshots.list(projectId, {
+      ...(kind ? { kind } : {}),
+      ...(limit !== undefined ? { limit } : {}),
+      ...(flagValue(args, "--after") ? { after: flagValue(args, "--after") } : {}),
+    });
+    console.log(JSON.stringify({ project_id: projectId, ...result }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function get(args) {
+  const { projectId, snapshotId } = resolveProjectAndSnapshot(args, "run402 snapshots get [project-id] <snapshot-id>");
+  try {
+    const snapshot = await getSdk().snapshots.get(projectId, snapshotId);
+    console.log(JSON.stringify({ snapshot }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function restore(args) {
+  const { projectId, snapshotId } = resolveProjectAndSnapshot(args, "run402 snapshots restore [project-id] <snapshot-id> [--confirm <token>]");
+  const includeAuth = args.includes("--include-auth");
+  const confirm = flagValue(args, "--confirm");
+  try {
+    if (confirm) {
+      const result = await getSdk().snapshots.restore(projectId, snapshotId, confirm, { includeAuth });
+      console.log(JSON.stringify({ ok: result.status === "ready", restore: result }, null, 2));
+      return;
+    }
+    const plan = await getSdk().snapshots.restorePlan(projectId, snapshotId, { includeAuth });
+    console.log(JSON.stringify({
+      ok: true,
+      project_id: projectId,
+      snapshot_id: snapshotId,
+      ...plan,
+      confirm_command: `run402 snapshots restore ${projectId} ${snapshotId} --confirm ${JSON.stringify(plan.restore_plan.confirm.token)}${includeAuth ? " --include-auth" : ""} --json`,
+    }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function deleteSnapshot(args) {
+  const { projectId, snapshotId } = resolveProjectAndSnapshot(args, "run402 snapshots delete [project-id] <snapshot-id>");
+  try {
+    await getSdk().snapshots.delete(projectId, snapshotId);
+    console.log(JSON.stringify({ ok: true, project_id: projectId, snapshot_id: snapshotId, deleted: true }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function resolveOptionalProject(value) {
+  if (value && String(value).startsWith("prj_")) return value;
+  return resolveProjectId(null);
+}
+
+function resolveProjectAndSnapshot(args, usage) {
+  const pos = positionalArgs(args, FLAG_VALUES);
+  if (pos.length === 1) return { projectId: resolveProjectId(null), snapshotId: pos[0] };
+  if (pos.length === 2 && pos[0].startsWith("prj_")) return { projectId: pos[0], snapshotId: pos[1] };
+  fail({ code: "BAD_USAGE", message: `Usage: ${usage}` });
+}