run402 1.56.0 → 1.57.1

package/README.md

@@ -57,10 +57,13 @@ run402 projects schema <id>                              # introspect tables + R
 ```bash
 run402 sites deploy-dir ./dist                # incremental upload (plan/commit transport)
 run402 deploy --manifest app.json             # one-call full stack deploy
+run402 deploy release active                  # inspect current-live release inventory
+run402 deploy release diff --from empty --to active
 run402 subdomains claim my-app                # → my-app.run402.com (auto-reassigns on next deploy)
 ```
 
 `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 `{ status: "ok", release: ... }` or `{ status: "ok", diff: ... }`; use them after deploys to compare release inventory without starting another mutation.
 
 ### GitHub Actions OIDC deploys
 

package/lib/deploy-v2.mjs

@@ -110,11 +110,70 @@ Output:
   stdout: { "status": "ok", "events": [...] }
 `;
 
+const RELEASE_HELP = `run402 deploy release — Inspect deploy release inventory and diffs
+
+Usage:
+  run402 deploy release get <release_id> [--project <id>] [--site-limit <n>]
+  run402 deploy release active [--project <id>] [--site-limit <n>]
+  run402 deploy release diff --from <empty|active|release_id> --to <active|release_id> [--project <id>] [--limit <n>]
+
+Subcommands:
+  get       Fetch the inventory for a specific release id
+  active    Fetch the current-live release inventory for the project
+  diff      Diff two release targets
+
+Output:
+  get/active: { "status": "ok", "release": {...} }
+  diff:       { "status": "ok", "diff": {...} }
+`;
+
+const RELEASE_GET_HELP = `run402 deploy release get — Fetch a release inventory by id
+
+Usage:
+  run402 deploy release get <release_id> [--project <id>] [--site-limit <n>]
+
+Options:
+  --project <id>          Project ID that owns the release (default: active project)
+  --site-limit <n>        Maximum site path entries to include (gateway default: 5000)
+
+Output:
+  stdout: { "status": "ok", "release": {...} }
+`;
+
+const RELEASE_ACTIVE_HELP = `run402 deploy release active — Fetch the active release inventory
+
+Usage:
+  run402 deploy release active [--project <id>] [--site-limit <n>]
+
+Options:
+  --project <id>          Project ID to inspect (default: active project)
+  --site-limit <n>        Maximum site path entries to include (gateway default: 5000)
+
+Output:
+  stdout: { "status": "ok", "release": {...} }
+`;
+
+const RELEASE_DIFF_HELP = `run402 deploy release diff — Diff two release targets
+
+Usage:
+  run402 deploy release diff --from <empty|active|release_id> --to <active|release_id> [--project <id>] [--limit <n>]
+
+Options:
+  --from <target>         Diff source: empty, active, or rel_...
+  --to <target>           Diff target: active or rel_...
+  --project <id>          Project ID to inspect (default: active project)
+  --limit <n>             Maximum entries per site diff bucket (gateway default: 1000)
+
+Output:
+  stdout: { "status": "ok", "diff": {...} }
+`;
+
 export async function runDeployV2(sub, args) {
   if (sub === "apply") return await applyCmd(args);
   if (sub === "resume") return await resumeCmd(args);
   if (sub === "list") return await listCmd(args);
   if (sub === "events") return await eventsCmd(args);
+  if (sub === "release") return await releaseCmd(args);
   fail({
     code: "BAD_USAGE",
     message: `Unknown deploy subcommand: ${sub}`,
@@ -498,6 +557,118 @@ async function eventsCmd(args) {
   }
 }
 
+async function releaseCmd(args) {
+  const action = args[0];
+  if (!action || action === "--help" || action === "-h") {
+    console.log(RELEASE_HELP);
+    process.exit(0);
+  }
+  if (action === "get") return await releaseGetCmd(args.slice(1));
+  if (action === "active") return await releaseActiveCmd(args.slice(1));
+  if (action === "diff") return await releaseDiffCmd(args.slice(1));
+  fail({
+    code: "BAD_USAGE",
+    message: `Unknown deploy release subcommand: ${action}`,
+    details: { subcommand: action },
+  });
+}
+
+async function releaseGetCmd(args) {
+  const opts = { releaseId: null, project: null, siteLimit: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--help" || args[i] === "-h") { console.log(RELEASE_GET_HELP); process.exit(0); }
+    if (args[i] === "--project" && args[i + 1]) { opts.project = args[++i]; continue; }
+    if (args[i] === "--site-limit" && args[i + 1]) { opts.siteLimit = parsePositiveInt(args[++i], "--site-limit"); continue; }
+    if (!args[i].startsWith("-") && !opts.releaseId) opts.releaseId = args[i];
+  }
+  if (!opts.releaseId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <release_id>.",
+      hint: "run402 deploy release get <release_id>",
+    });
+  }
+
+  const project = resolveProjectId(opts.project);
+
+  try {
+    const sdkOpts = { project };
+    if (opts.siteLimit !== null) sdkOpts.siteLimit = opts.siteLimit;
+    const release = await getSdk().deploy.getRelease(opts.releaseId, sdkOpts);
+    console.log(JSON.stringify({ status: "ok", release }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function releaseActiveCmd(args) {
+  const opts = { project: null, siteLimit: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--help" || args[i] === "-h") { console.log(RELEASE_ACTIVE_HELP); process.exit(0); }
+    if (args[i] === "--project" && args[i + 1]) { opts.project = args[++i]; continue; }
+    if (args[i] === "--site-limit" && args[i + 1]) { opts.siteLimit = parsePositiveInt(args[++i], "--site-limit"); continue; }
+  }
+
+  const project = resolveProjectId(opts.project);
+
+  try {
+    const sdkOpts = { project };
+    if (opts.siteLimit !== null) sdkOpts.siteLimit = opts.siteLimit;
+    const release = await getSdk().deploy.getActiveRelease(sdkOpts);
+    console.log(JSON.stringify({ status: "ok", release }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function releaseDiffCmd(args) {
+  const opts = { project: null, from: null, to: null, limit: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--help" || args[i] === "-h") { console.log(RELEASE_DIFF_HELP); process.exit(0); }
+    if (args[i] === "--project" && args[i + 1]) { opts.project = args[++i]; continue; }
+    if (args[i] === "--from" && args[i + 1]) { opts.from = args[++i]; continue; }
+    if (args[i] === "--to" && args[i + 1]) { opts.to = args[++i]; continue; }
+    if (args[i] === "--limit" && args[i + 1]) { opts.limit = parsePositiveInt(args[++i], "--limit"); continue; }
+  }
+  if (!opts.from || !opts.to) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --from or --to release target.",
+      hint: "run402 deploy release diff --from empty --to active",
+    });
+  }
+  if (opts.to === "empty") {
+    fail({
+      code: "BAD_USAGE",
+      message: "--to cannot be empty. Use active or a release id.",
+      details: { flag: "--to", value: opts.to },
+    });
+  }
+
+  const project = resolveProjectId(opts.project);
+
+  try {
+    const sdkOpts = { project, from: opts.from, to: opts.to };
+    if (opts.limit !== null) sdkOpts.limit = opts.limit;
+    const diff = await getSdk().deploy.diff(sdkOpts);
+    console.log(JSON.stringify({ status: "ok", diff }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function parsePositiveInt(value, flag) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    fail({
+      code: "BAD_USAGE",
+      message: `${flag} must be a positive integer.`,
+      details: { flag, value },
+    });
+  }
+  return parsed;
+}
+
 // ─── Manifest → ReleaseSpec ──────────────────────────────────────────────────
 
 function mapManifestToReleaseSpec(spec) {

package/lib/deploy.mjs

@@ -21,6 +21,7 @@ Subcommands (recommended for new manifests):
   run402 deploy resume <operation_id>       resume a stuck operation
   run402 deploy list [--project <id>]       list recent deploy operations
   run402 deploy events <operation_id>       fetch event stream for an operation
+  run402 deploy release ...                 inspect release inventory and diffs
 
 Manifest format (JSON, v2 ReleaseSpec — recommended):
   {
@@ -303,13 +304,15 @@ export async function run(args) {
   //   run402 deploy resume <op>   → resume an activation_pending operation
   //   run402 deploy list          → list recent deploy operations
   //   run402 deploy events <op>   → fetch recorded event stream for an operation
+  //   run402 deploy release ...   → release inventory/diff observability
   //   run402 deploy --manifest …  → legacy bundle deploy (routes through v2)
   const sub = args[0];
   switch (sub) {
     case "apply":
     case "resume":
     case "list":
-    case "events": {
+    case "events":
+    case "release": {
       const { runDeployV2 } = await import("./deploy-v2.mjs");
       await runDeployV2(sub, args.slice(1));
       return;

package/lib/sites.mjs

@@ -299,7 +299,7 @@ async function deployDir(args) {
       const { plan } = await getSdk().deploy.plan({
         project: projectId,
         site: { replace: fileSet },
-      });
+      }, { dryRun: true });
       console.log(JSON.stringify({
         status: "ok",
         dry_run: true,
@@ -308,6 +308,8 @@ async function deployDir(args) {
         operation_id: plan.operation_id,
         manifest_digest: plan.manifest_digest,
         diff: plan.diff,
+        warnings: plan.warnings,
+        expected_events: plan.expected_events ?? [],
         missing_content_count: plan.missing_content.filter((p) => !p.present).length,
       }, null, 2));
     } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "1.56.0",
+  "version": "1.57.1",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {

package/sdk/dist/index.d.ts

@@ -130,5 +130,5 @@ export { Deploy } from "./namespaces/deploy.js";
 export { Ci, CI_AUDIENCE, CI_GITHUB_ACTIONS_ISSUER, CI_GITHUB_ACTIONS_PROVIDER, DEFAULT_CI_DELEGATION_CHAIN_ID, V1_CI_ALLOWED_ACTIONS, V1_CI_ALLOWED_EVENTS_DEFAULT, assertCiDeployableSpec, buildCiDelegationResourceUri, buildCiDelegationStatement, normalizeCiDelegationValues, validateCiNonce, validateCiSubjectMatch, } from "./namespaces/ci.js";
 export { ScopedRun402 } from "./scoped.js";
 export type { CiAllowedAction, CiAllowedEvent, CiBindingErrorCode, CiBindingRow, CiCreateBindingInput, CiDelegationValues, CiDeployErrorCode, CiErrorCode, CiListBindingsInput, CiListBindingsResult, CiProvider, CiTokenExchangeErrorCode, CiTokenExchangeInput, CiTokenExchangeRequestBody, CiTokenExchangeResponse, NormalizedCiDelegationValues, ParsedDelegation, } from "./namespaces/ci.types.js";
-export type { ApplyOptions, CommitResponse, CommitStatus, ContentRef, ContentSource, DatabaseSpec, DeployDiff, DeployEvent, DeployOperation, DeployResult, ExposeManifest, FileSet, FsFileSource, FunctionSpec, FunctionsSpec, MigrationSpec, MissingContent, OperationSnapshot, OperationStatus, PaymentRequiredHint, PlanRequest, PlanResponse, ReleaseSpec, RouteSpec, SecretsSpec, SiteSpec, SmokeCheck, StartOptions, SubdomainsSpec, WarningEntry, } from "./namespaces/deploy.types.js";
+export type { ApplyOptions, ActiveReleaseInventory, CommitResponse, CommitStatus, ContentRef, ContentSource, DatabaseSpec, DeployObservabilityWarningEntry, DeployDiff, DeployEvent, DeployOperation, DeployResult, ExposeManifest, FileSet, FsFileSource, FunctionSpec, FunctionsDiff, FunctionsSpec, LegacyWarningEntry, MigrationAppliedEntry, MigrationSpec, MissingContent, OperationSnapshot, OperationStatus, PaymentRequiredHint, PlanDiffEnvelope, PlanMigrationDiff, PlanRequest, PlanResponse, ReleaseDiffOptions, ReleaseDiffTarget, ReleaseDiffToTarget, ReleaseFunctionEntry, ReleaseInventory, ReleaseInventoryBase, ReleaseInventoryByIdOptions, ReleaseInventoryOptions, ReleaseInventoryStateKind, ReleaseInventoryStatus, ReleaseSnapshotInventory, ReleaseSpec, ReleaseToReleaseDiff, RouteSpec, SecretsSpec, SecretsDiff, SiteDiff, SitePathEntry, SiteSpec, SmokeCheck, StartOptions, SubdomainsSpec, SubdomainsDiff, WarningEntry, } from "./namespaces/deploy.types.js";
 //# sourceMappingURL=index.d.ts.map

package/sdk/dist/index.d.ts.map

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

package/sdk/dist/namespaces/deploy.d.ts

@@ -19,7 +19,7 @@
  * behavior; this file is the implementation.
  */
 import type { Client } from "../kernel.js";
-import type { ApplyOptions, DeployEvent, DeployEventsResponse, DeployListResponse, DeployOperation, DeployResult, OperationSnapshot, PlanResponse, ReleaseSpec, StartOptions } from "./deploy.types.js";
+import type { ApplyOptions, ActiveReleaseInventory, DeployEvent, DeployEventsResponse, DeployListResponse, DeployOperation, DeployResult, OperationSnapshot, PlanResponse, ReleaseDiffOptions, ReleaseInventory, ReleaseInventoryByIdOptions, ReleaseInventoryOptions, ReleaseSpec, ReleaseToReleaseDiff, StartOptions } from "./deploy.types.js";
 export declare class Deploy {
     private readonly client;
     constructor(client: Client);
@@ -41,6 +41,7 @@ export declare class Deploy {
      */
     plan(spec: ReleaseSpec, opts?: {
         idempotencyKey?: string;
+        dryRun?: boolean;
     }): Promise<{
         plan: PlanResponse;
         byteReaders: Map<string, ByteReader>;
@@ -113,17 +114,39 @@ export declare class Deploy {
         project: string;
     }): Promise<DeployEventsResponse>;
     /**
-     * Fetch a release by id. (Endpoint may not be live in early v2 builds —
-     * falls through to the gateway's standard 404 handling in that case.)
+     * Fetch a release inventory by id. The endpoint requires `apikey` auth, so
+     * pass the owning project id. `siteLimit` controls how many site paths the
+     * gateway includes before reporting `site.totals.paths`.
      */
-    getRelease(releaseId: string): Promise<unknown>;
+    getRelease(opts: ReleaseInventoryByIdOptions): Promise<ReleaseInventory>;
+    getRelease(releaseId: string, opts: ReleaseInventoryOptions): Promise<ReleaseInventory>;
     /**
-     * Diff two releases. (Endpoint may not be live in early v2 builds.)
+     * @deprecated Pass `{ project, releaseId }` or
+     * `getRelease(releaseId, { project })`. This legacy shape throws a
+     * `LocalError` before any request because the gateway now requires apikey
+     * auth scoped to a project.
      */
-    diff(opts: {
-        from: string;
-        to: string;
-    }): Promise<unknown>;
+    getRelease(releaseId: string, opts?: Partial<ReleaseInventoryOptions>): Promise<ReleaseInventory>;
+    /**
+     * Fetch the currently active release inventory for a project. If the project
+     * has not activated a release yet, the gateway returns an empty current-live
+     * inventory with `release_id: null`.
+     */
+    getActiveRelease(opts: ReleaseInventoryOptions): Promise<ActiveReleaseInventory>;
+    /**
+     * Diff two materialized release targets for a project. `from` may be
+     * `"empty"`, `"active"`, or a release id. `to` may be `"active"` or a
+     * release id; the gateway treats `"active"` as the current-live target.
+     */
+    diff(opts: ReleaseDiffOptions): Promise<ReleaseToReleaseDiff>;
+    /**
+     * @deprecated Pass `project` with the diff selectors. This legacy shape
+     * throws a `LocalError` before any request because the gateway now requires
+     * apikey auth scoped to a project.
+     */
+    diff(opts: Omit<ReleaseDiffOptions, "project"> & {
+        project?: string;
+    }): Promise<ReleaseToReleaseDiff>;
 }
 /**
  * A deferred byte reader: returns the bytes when called. The `label` is a

package/sdk/dist/namespaces/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/namespaces/deploy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAa3C,OAAO,KAAK,EACV,YAAY,EAKZ,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,YAAY,EAWZ,iBAAiB,EAGjB,YAAY,EACZ,WAAW,EACX,YAAY,EACb,MAAM,mBAAmB,CAAC;AAyB3B,qBAAa,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAE3C;;;;OAIG;IACG,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,YAAY,CAAC;IA8B9E;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IAI3E;;;;OAIG;IACG,IAAI,CACR,IAAI,EAAE,WAAW,EACjB,IAAI,GAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAO,GACrC,OAAO,CAAC;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;KAAE,CAAC;IAIxE;;;;;OAKG;IACG,MAAM,CACV,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE;QACJ,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;KACxC,GACA,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;OAKG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;QACvC,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;KACb,GACL,OAAO,CAAC,YAAY,CAAC;IAMxB;;;;;;;;;OASG;IACG,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GACtE,OAAO,CAAC,YAAY,CAAC;IAqBxB;;;;OAIG;IACG,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAC9B,OAAO,CAAC,iBAAiB,CAAC;IAQ7B;;;;;;OAMG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACjD,OAAO,CAAC,kBAAkB,CAAC;IAsB9B;;;;;;;;OAQG;IACG,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC,oBAAoB,CAAC;IAmBhC;;;OAGG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMrD;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CAMjE;AA2nBD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/namespaces/deploy.ts"],"names":[],"mappings":"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"}

package/sdk/dist/namespaces/deploy.js

@@ -70,7 +70,8 @@ export class Deploy {
         }
         await uploadMissing(this.client, spec.project, plan.missing_content, byteReaders, emit);
         emit({ type: "commit.phase", phase: "validate", status: "started" });
-        const commit = await commitInternal(this.client, plan.plan_id, opts.idempotencyKey);
+        const { planId } = requirePersistedPlan(plan, "applying deploy");
+        const commit = await commitInternal(this.client, planId, opts.idempotencyKey);
         return await pollUntilReady(this.client, commit, plan.diff, plan.warnings, emit, spec.project);
     }
     /**
@@ -86,7 +87,7 @@ export class Deploy {
      * response and a byte-reader map keyed by sha256 (used by `upload`).
      */
     async plan(spec, opts = {}) {
-        return planInternal(this.client, spec, opts.idempotencyKey);
+        return planInternal(this.client, spec, opts.idempotencyKey, opts.dryRun);
     }
     /**
      * Low-level upload: ensure every ref the gateway reported as missing for
@@ -196,27 +197,57 @@ export class Deploy {
             throw translateDeployError(err, "events", null, operationId);
         }
     }
-    /**
-     * Fetch a release by id. (Endpoint may not be live in early v2 builds —
-     * falls through to the gateway's standard 404 handling in that case.)
-     */
-    async getRelease(releaseId) {
-        return this.client.request(`/deploy/v2/releases/${releaseId}`, {
-            context: "fetching release",
-        });
+    async getRelease(releaseIdOrOpts, maybeOpts = {}) {
+        const opts = typeof releaseIdOrOpts === "string"
+            ? { ...maybeOpts, releaseId: releaseIdOrOpts }
+            : releaseIdOrOpts;
+        if (!opts.project) {
+            throw new LocalError("r.deploy.getRelease requires a project id ({ project: 'prj_...', releaseId: 'rel_...' })", "fetching release inventory");
+        }
+        if (!opts.releaseId) {
+            throw new LocalError("r.deploy.getRelease requires a release id", "fetching release inventory");
+        }
+        const headers = await apikeyHeaders(this.client, opts.project);
+        return this.client.request(appendQuery(`/deploy/v2/releases/${encodeURIComponent(opts.releaseId)}`, {
+            site_limit: opts.siteLimit,
+        }), { headers, context: "fetching release inventory" });
     }
     /**
-     * Diff two releases. (Endpoint may not be live in early v2 builds.)
+     * Fetch the currently active release inventory for a project. If the project
+     * has not activated a release yet, the gateway returns an empty current-live
+     * inventory with `release_id: null`.
      */
+    async getActiveRelease(opts) {
+        if (!opts?.project) {
+            throw new LocalError("r.deploy.getActiveRelease requires a project id ({ project: 'prj_...' })", "fetching active release inventory");
+        }
+        const headers = await apikeyHeaders(this.client, opts.project);
+        return this.client.request(appendQuery("/deploy/v2/releases/active", {
+            site_limit: opts.siteLimit,
+        }), { headers, context: "fetching active release inventory" });
+    }
     async diff(opts) {
+        if (!opts?.project) {
+            throw new LocalError("r.deploy.diff requires a project id ({ project: 'prj_...', from, to })", "diffing releases");
+        }
+        const headers = await apikeyHeaders(this.client, opts.project);
         const qs = new URLSearchParams({ from: opts.from, to: opts.to });
-        return this.client.request(`/deploy/v2/releases/diff?${qs}`, {
-            context: "diffing releases",
-        });
+        if (opts.limit !== undefined)
+            qs.set("limit", String(opts.limit));
+        return this.client.request(`/deploy/v2/releases/diff?${qs.toString()}`, { headers, context: "diffing releases" });
     }
 }
+function appendQuery(path, params) {
+    const qs = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            qs.set(key, String(value));
+    }
+    const query = qs.toString();
+    return query.length > 0 ? `${path}?${query}` : path;
+}
 // ─── Internal pipeline ───────────────────────────────────────────────────────
-async function planInternal(client, spec, idempotencyKey) {
+async function planInternal(client, spec, idempotencyKey, dryRun = false) {
     const ciCredentials = isCiClient(client);
     validateSpec(spec);
     if (ciCredentials)
@@ -228,7 +259,7 @@ async function planInternal(client, spec, idempotencyKey) {
     // needs `spec` in the body (with at least the project), so we keep a
     // minimal stub there.
     const inlineBody = { spec: normalized };
-    if (idempotencyKey)
+    if (idempotencyKey && !dryRun)
         inlineBody.idempotency_key = idempotencyKey;
     const inlineBytes = new TextEncoder().encode(JSON.stringify(inlineBody)).byteLength;
     let body;
@@ -236,6 +267,15 @@ async function planInternal(client, spec, idempotencyKey) {
         body = inlineBody;
     }
     else {
+        if (dryRun) {
+            throw new Run402DeployError("Dry-run deploy planning requires an inline spec under the gateway body cap; the normalized deploy plan would require manifest_ref.", {
+                code: "DRY_RUN_REQUIRES_INLINE_SPEC",
+                phase: "validate",
+                resource: "manifest_ref",
+                retryable: false,
+                context: "planning deploy",
+            });
+        }
         if (ciCredentials) {
             throw new Run402DeployError("CI deploys must use inline specs under the gateway body cap; the normalized deploy plan would require manifest_ref.", {
                 code: "forbidden_spec_field",
@@ -256,7 +296,7 @@ async function planInternal(client, spec, idempotencyKey) {
     }
     let plan;
     try {
-        plan = normalizePlanResponse(await client.request("/deploy/v2/plans", {
+        plan = normalizePlanResponse(await client.request(dryRun ? "/deploy/v2/plans?dry_run=true" : "/deploy/v2/plans", {
             method: "POST",
             body,
             context: "planning deploy",
@@ -626,22 +666,24 @@ async function startInternal(client, spec, opts) {
     const resultPromise = (async () => {
         await uploadMissing(client, spec.project, plan.missing_content, byteReaders, emit);
         emit({ type: "commit.phase", phase: "validate", status: "started" });
-        const commit = await commitInternal(client, plan.plan_id, opts.idempotencyKey);
+        const { planId } = requirePersistedPlan(plan, "starting deploy");
+        const commit = await commitInternal(client, planId, opts.idempotencyKey);
         return await pollUntilReady(client, commit, plan.diff, plan.warnings, emit, spec.project);
     })();
     // Avoid an unhandled-rejection at construction time. Consumers must call
     // .result() to actually observe the error.
     resultPromise.catch(() => { });
     let snapshot = null;
+    const { operationId } = requirePersistedPlan(plan, "starting deploy");
     const startHeaders = await apikeyHeaders(client, spec.project);
     const fetchSnapshot = async () => {
         if (snapshot && TERMINAL_STATUSES.includes(snapshot.status))
             return snapshot;
-        snapshot = await client.request(`/deploy/v2/operations/${encodeURIComponent(plan.operation_id)}`, { headers: startHeaders, context: "fetching deploy operation" });
+        snapshot = await client.request(`/deploy/v2/operations/${encodeURIComponent(operationId)}`, { headers: startHeaders, context: "fetching deploy operation" });
         return snapshot;
     };
     return {
-        id: plan.operation_id,
+        id: operationId,
         async snapshot() {
             return fetchSnapshot();
         },
@@ -757,11 +799,42 @@ function validateSpec(spec) {
 }
 function normalizePlanResponse(plan) {
     const raw = plan;
+    const warnings = Array.isArray(raw.warnings) ? raw.warnings : [];
+    if (raw.kind === "plan_response") {
+        const diff = {
+            is_noop: raw.is_noop,
+            summary: raw.summary,
+            warnings,
+            migrations: raw.migrations,
+            site: raw.site,
+            functions: raw.functions,
+            secrets: raw.secrets,
+            subdomains: raw.subdomains,
+        };
+        return {
+            ...plan,
+            warnings,
+            diff,
+            payment_required: raw.payment_required ?? null,
+        };
+    }
     return {
         ...plan,
-        warnings: Array.isArray(raw.warnings) ? raw.warnings : [],
+        warnings,
     };
 }
+function requirePersistedPlan(plan, context) {
+    if (plan.plan_id && plan.operation_id) {
+        return { planId: plan.plan_id, operationId: plan.operation_id };
+    }
+    throw new Run402DeployError("Dry-run plan responses cannot be uploaded or committed because they do not create plan or operation rows.", {
+        code: "DRY_RUN_PLAN_NOT_COMMITTABLE",
+        phase: "plan",
+        resource: "plan_id",
+        retryable: false,
+        context,
+    });
+}
 function emitPlanWarnings(plan, emit) {
     if (plan.warnings.length > 0) {
         emit({ type: "plan.warnings", warnings: plan.warnings });