@run402/sdk 1.53.0 → 1.54.0

package/README.md

@@ -156,25 +156,69 @@ const resumed = await r.deploy.resume(operationId);
 
 ### Errors
 
-All failures throw subclasses of `Run402Error`:
+All failures throw subclasses of `Run402Error`. Every subclass carries a stable
+`kind` discriminator string and an `isRun402Error` brand:
+
+| Class | `kind` | When | Notable fields |
+|---|---|---|---|
+| `PaymentRequired` | `"payment_required"` | HTTP 402 | x402 payment requirements in `body` |
+| `ProjectNotFound` | `"project_not_found"` | Project ID not in the credential provider | `projectId` |
+| `Unauthorized` | `"unauthorized"` | HTTP 401 / 403 | — |
+| `ApiError` | `"api_error"` | Other non-2xx responses | `status`, `body` |
+| `NetworkError` | `"network_error"` | Fetch rejected with no HTTP response | `cause` |
+| `LocalError` | `"local_error"` | Local-host issues (filesystem, signing) | `cause` |
+| `Run402DeployError` | `"deploy_error"` | Structured envelope from the deploy state machine (v1.34+) | `code`, `phase`, `operationId`, `safeToRetry`, `mutationState`, `nextActions` |
+
+**Branch with type guards, not `instanceof`.** `instanceof X` is an identity
+check on the class object — it fails silently when the consumer's runtime
+holds a different copy of the SDK (duplicate npm installs, bundler chunk
+splits, ESM/CJS interop, V8-isolate realms). The exported guards
+(`isPaymentRequired`, `isDeployError`, …) check `isRun402Error` + `kind`,
+which is identity-free and survives all of those scenarios. `instanceof`
+continues to work for back-compat in the simple single-copy case.
 
-| Class | When | Notable fields |
-|---|---|---|
-| `PaymentRequired` | HTTP 402 | x402 payment requirements |
-| `ProjectNotFound` | Project ID not in the credential provider | — |
-| `Unauthorized` | HTTP 401 / 403 | — |
-| `ApiError` | Other non-2xx responses | `status`, `body` |
-| `NetworkError` | Fetch rejected with no HTTP response | — |
-| `LocalError` | Local-host issues (filesystem, signing) | — |
-| `Run402DeployError` | Structured envelope from the deploy state machine (v1.34+) | `code`, `phase`, `operationId`, `safeToRetry`, `mutationState`, `nextActions` |
+```ts
+import {
+  run402,
+  isPaymentRequired,
+  isDeployError,
+  type ReleaseSpec,
+} from "@run402/sdk/node";
 
-Branch on the structured fields, not English `message` text:
+declare const spec: ReleaseSpec;
+const r = run402();
+
+try {
+  await r.deploy.apply(spec);
+} catch (e) {
+  if (isPaymentRequired(e)) {
+    // e is narrowed to PaymentRequired
+    // present payment requirements to the user — read e.body, e.context, etc.
+  } else if (isDeployError(e) && e.safeToRetry) {
+    // e is narrowed to Run402DeployError; it's safe to retry with the same idempotency key
+  } else throw e;
+}
+```
+
+`Run402Error.toJSON()` returns a canonical envelope, so `JSON.stringify(e)`
+produces a populated structured object instead of the empty `"{}"` plain
+`Error` produces. Use this for telemetry, MCP tool results, CLI JSON output,
+and any inter-process boundary where the error needs to survive serialization.
+
+#### Retry idempotent operations with `withRetry`
+
+`withRetry(fn, opts?)` wraps any async call with exponential backoff. It uses
+`isRetryableRun402Error` (the canonical "should I retry this?" policy: 408 /
+425 / 429 / 5xx / `NetworkError` / gateway-flagged `retryable` or
+`safeToRetry`) by default. Pair it with the SDK method's own
+`idempotencyKey` so retried mutations dedup server-side:
 
 ```ts
 import {
   run402,
-  PaymentRequired,
-  Run402DeployError,
+  withRetry,
+  isPaymentRequired,
+  isDeployError,
   type ReleaseSpec,
 } from "@run402/sdk/node";
 
@@ -182,16 +226,31 @@ declare const spec: ReleaseSpec;
 const r = run402();
 
 try {
-  await r.deploy.apply(spec);
+  const release = await withRetry(
+    () => r.deploy.apply(spec, { idempotencyKey: "deploy-2026-05-01" }),
+    {
+      attempts: 3,
+      onRetry: (e, attempt, delayMs) =>
+        process.stderr.write(`retry ${attempt} in ${delayMs}ms\n`),
+    },
+  );
+  console.log(release.urls);
 } catch (e) {
-  if (e instanceof PaymentRequired) {
-    // present payment requirements to the user
-  } else if (e instanceof Run402DeployError && e.safeToRetry) {
-    // safe to retry — same idempotency key
+  if (isPaymentRequired(e)) {
+    // ... present payment
+  } else if (isDeployError(e)) {
+    // log structured envelope for triage
+    process.stderr.write(JSON.stringify(e) + "\n");
   } else throw e;
 }
 ```
 
+Defaults: 3 attempts (1 initial + 2 retries), 250 ms base delay, 5 s cap. Pass
+a custom `retryIf` to override the default policy (e.g., retry on
+`PaymentRequired` if your sandbox auto-funds). After exhausting attempts
+`withRetry` throws the LAST error — your catch handler sees the original
+structured envelope, not a wrapper.
+
 The SDK never calls `process.exit`. Each interface (MCP tools, CLI, your code) wraps with its own error behavior.
 
 ## Stability

package/core-dist/keystore.d.ts

@@ -7,6 +7,7 @@ export interface StoredProject {
 }
 export interface KeyStore {
     active_project_id?: string;
+    previous_active_project_id?: string;
     projects: Record<string, StoredProject>;
 }
 /**

package/core-dist/keystore.js

@@ -1,7 +1,34 @@
-import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { getKeystorePath } from "./config.js";
+function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
+    const lockDir = path + ".lock";
+    mkdirSync(dirname(path), { recursive: true });
+    for (let i = 0; i < retries; i++) {
+        try {
+            mkdirSync(lockDir, { mode: 0o700 });
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "EEXIST")
+                throw e;
+            const until = Date.now() + delayMs;
+            while (Date.now() < until) { /* spin */ }
+            continue;
+        }
+        try {
+            return fn();
+        }
+        finally {
+            try {
+                rmdirSync(lockDir);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    throw new Error(`Could not acquire keystore lock after ${retries} retries: ${lockDir}`);
+}
 /**
  * Load the keystore from disk.
  * Auto-migrates legacy formats:
@@ -13,7 +40,6 @@ export function loadKeyStore(path) {
     try {
         const data = readFileSync(p, "utf-8");
         const parsed = JSON.parse(data);
-        // Auto-migrate array format (CLI legacy) to object format
         if (Array.isArray(parsed)) {
             const projects = {};
             for (const item of parsed) {
@@ -29,7 +55,6 @@ export function loadKeyStore(path) {
             return { projects };
         }
         if (parsed && typeof parsed === "object" && parsed.projects) {
-            // Strip legacy fields (tier, lease_expires_at, expires_at) from projects
             for (const proj of Object.values(parsed.projects)) {
                 const rec = proj;
                 delete rec.tier;
@@ -38,6 +63,7 @@ export function loadKeyStore(path) {
             }
             return {
                 ...(parsed.active_project_id && { active_project_id: parsed.active_project_id }),
+                ...(parsed.previous_active_project_id && { previous_active_project_id: parsed.previous_active_project_id }),
                 projects: parsed.projects,
             };
         }
@@ -62,27 +88,40 @@ export function getProject(projectId, path) {
 }
 export function saveProject(projectId, project, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    store.projects[projectId] = project;
-    saveKeyStore(store, p);
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        store.projects[projectId] = project;
+        saveKeyStore(store, p);
+    });
 }
 export function updateProject(projectId, update, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    const existing = store.projects[projectId];
-    if (existing) {
-        store.projects[projectId] = { ...existing, ...update };
-        saveKeyStore(store, p);
-    }
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        const existing = store.projects[projectId];
+        if (existing) {
+            store.projects[projectId] = { ...existing, ...update };
+            saveKeyStore(store, p);
+        }
+    });
 }
 export function removeProject(projectId, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    delete store.projects[projectId];
-    if (store.active_project_id === projectId) {
-        delete store.active_project_id;
-    }
-    saveKeyStore(store, p);
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        delete store.projects[projectId];
+        if (store.active_project_id === projectId) {
+            const fallback = store.previous_active_project_id;
+            if (fallback && fallback !== projectId && store.projects[fallback]) {
+                store.active_project_id = fallback;
+            }
+            else {
+                delete store.active_project_id;
+            }
+            delete store.previous_active_project_id;
+        }
+        saveKeyStore(store, p);
+    });
 }
 export function getActiveProjectId(path) {
     const store = loadKeyStore(path);
@@ -90,8 +129,13 @@ export function getActiveProjectId(path) {
 }
 export function setActiveProjectId(projectId, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    store.active_project_id = projectId;
-    saveKeyStore(store, p);
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        if (store.active_project_id && store.active_project_id !== projectId) {
+            store.previous_active_project_id = store.active_project_id;
+        }
+        store.active_project_id = projectId;
+        saveKeyStore(store, p);
+    });
 }
 //# sourceMappingURL=keystore.js.map

package/dist/errors.d.ts

@@ -2,8 +2,34 @@
  * Error hierarchy for the Run402 SDK. Every failure throws a subclass of
  * {@link Run402Error}. Consumers (MCP handlers, CLI commands, user functions)
  * translate these into their native error shapes at the edge.
+ *
+ * Branch on {@link Run402Error.kind} (or the exported `is*` type guards) rather
+ * than `instanceof`. Discriminator-based checks survive duplicate SDK installs,
+ * bundler chunk splits, ESM/CJS interop, and V8-isolate realm boundaries —
+ * any setting where a class object's identity might differ from the consumer's
+ * own class object reference. `instanceof X` continues to work for callers
+ * holding a single SDK copy (back-compat); the guards are the recommended path.
+ */
+/**
+ * Stable string discriminator on every {@link Run402Error} subclass. Use this
+ * (or the exported `is*` guards) to branch on errors safely across SDK copies
+ * and realms — value comparison, no class-identity dependency.
  */
+export type Run402ErrorKind = "payment_required" | "project_not_found" | "unauthorized" | "api_error" | "network_error" | "local_error" | "deploy_error";
 export declare abstract class Run402Error extends Error {
+    /**
+     * Structural brand. Always `true` on any {@link Run402Error} subclass
+     * instance, regardless of which SDK copy created it. The exported
+     * {@link isRun402Error} guard checks this field instead of `instanceof`,
+     * so cross-realm and cross-bundle errors still match.
+     */
+    readonly isRun402Error: true;
+    /**
+     * Stable string discriminator. Branch on `e.kind === "..."` (or the
+     * exported subclass guards) rather than `e instanceof X`. Equality on
+     * `kind` survives duplicate SDK copies and cross-realm errors.
+     */
+    abstract readonly kind: Run402ErrorKind;
     /** HTTP status, or null for local/network failures that produced no response. */
     readonly status: number | null;
     /** Parsed response body, or null when no body was received. */
@@ -27,28 +53,60 @@ export declare abstract class Run402Error extends Error {
     /** Advisory next actions from the gateway. Rendering them must not execute them. */
     readonly nextActions?: unknown[];
     constructor(message: string, status: number | null, body: unknown, context: string);
+    /**
+     * Canonical structured envelope for `JSON.stringify`. Without this, an
+     * `Error` instance serializes as `"{}"` (its built-in fields are
+     * non-enumerable), losing every structured detail an agent needs for
+     * triage. Subclasses with extra fields (e.g. {@link Run402DeployError})
+     * override and spread `super.toJSON()`.
+     */
+    toJSON(): Record<string, unknown>;
 }
 /** HTTP 402 — the gateway requires payment (lease expired, insufficient balance, or x402 quote). */
 export declare class PaymentRequired extends Run402Error {
+    static readonly DEFAULT_CODE = "PAYMENT_REQUIRED";
+    static readonly DEFAULT_CATEGORY = "payment_required";
+    static readonly DEFAULT_RETRYABLE = false;
+    readonly kind: "payment_required";
 }
 /** Project ID is not present in the credential provider (local miss) or the gateway returned 404. */
 export declare class ProjectNotFound extends Run402Error {
+    static readonly DEFAULT_CODE = "PROJECT_NOT_FOUND";
+    static readonly DEFAULT_CATEGORY = "not_found";
+    static readonly DEFAULT_RETRYABLE = false;
+    readonly kind: "project_not_found";
     readonly projectId: string;
     constructor(projectId: string, context: string, status?: number | null, body?: unknown);
 }
 /** HTTP 401 or 403 — authentication missing, invalid, or insufficient for the operation. */
 export declare class Unauthorized extends Run402Error {
+    static readonly DEFAULT_CODE = "UNAUTHORIZED";
+    static readonly DEFAULT_CATEGORY = "auth";
+    static readonly DEFAULT_RETRYABLE = false;
+    readonly kind: "unauthorized";
 }
 /** Any other non-2xx HTTP response from the gateway. */
 export declare class ApiError extends Run402Error {
+    static readonly DEFAULT_CODE = "API_ERROR";
+    static readonly DEFAULT_CATEGORY = "api";
+    static readonly DEFAULT_RETRYABLE = false;
+    readonly kind: "api_error";
 }
 /** The underlying `fetch` threw before producing a response (DNS, connection reset, offline). */
 export declare class NetworkError extends Run402Error {
+    static readonly DEFAULT_CODE = "NETWORK_ERROR";
+    static readonly DEFAULT_CATEGORY = "network";
+    static readonly DEFAULT_RETRYABLE = true;
+    readonly kind: "network_error";
     readonly cause: unknown;
     constructor(message: string, cause: unknown, context: string);
 }
 /** Local/filesystem error — input validation, missing path, unreadable dir. No HTTP involved. */
 export declare class LocalError extends Run402Error {
+    static readonly DEFAULT_CODE = "LOCAL_ERROR";
+    static readonly DEFAULT_CATEGORY = "local";
+    static readonly DEFAULT_RETRYABLE = false;
+    readonly kind: "local_error";
     readonly cause?: unknown;
     constructor(message: string, context: string, cause?: unknown);
 }
@@ -69,6 +127,7 @@ export interface Run402DeployErrorFix {
     [key: string]: unknown;
 }
 export declare class Run402DeployError extends Run402Error {
+    readonly kind: "deploy_error";
     readonly code: Run402DeployErrorCode;
     readonly phase: string | null;
     readonly resource: string | null;
@@ -92,5 +151,37 @@ export declare class Run402DeployError extends Run402Error {
         body?: unknown;
         context: string;
     });
+    toJSON(): Record<string, unknown>;
 }
+/** True if `e` is any {@link Run402Error} subclass instance, regardless of which SDK copy created it. */
+export declare function isRun402Error(e: unknown): e is Run402Error;
+/** True if `e` is a {@link PaymentRequired}. Survives duplicate SDK copies and realms. */
+export declare function isPaymentRequired(e: unknown): e is PaymentRequired;
+/** True if `e` is a {@link ProjectNotFound}. */
+export declare function isProjectNotFound(e: unknown): e is ProjectNotFound;
+/** True if `e` is an {@link Unauthorized}. */
+export declare function isUnauthorized(e: unknown): e is Unauthorized;
+/** True if `e` is an {@link ApiError}. */
+export declare function isApiError(e: unknown): e is ApiError;
+/** True if `e` is a {@link NetworkError}. */
+export declare function isNetworkError(e: unknown): e is NetworkError;
+/** True if `e` is a {@link LocalError}. */
+export declare function isLocalError(e: unknown): e is LocalError;
+/** True if `e` is a {@link Run402DeployError}. */
+export declare function isDeployError(e: unknown): e is Run402DeployError;
+/**
+ * Canonical "should I retry this?" policy. Returns true when `e` is a
+ * {@link Run402Error} AND any of:
+ *   - `e.retryable === true` (gateway flagged it)
+ *   - `e.safeToRetry === true` (gateway flagged it)
+ *   - `e.kind === "network_error"` (fetch never produced a response)
+ *   - `e.status` is 408 (Request Timeout), 425 (Too Early), or 429 (Too Many
+ *     Requests)
+ *   - `e.status` is a 5xx server error
+ *
+ * Returns false for non-Run402 errors so it can be safely called with
+ * `unknown` from a catch block. Used as the default `retryIf` in
+ * {@link withRetry}.
+ */
+export declare function isRetryableRun402Error(e: unknown): boolean;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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

package/dist/errors.js

@@ -2,8 +2,22 @@
  * Error hierarchy for the Run402 SDK. Every failure throws a subclass of
  * {@link Run402Error}. Consumers (MCP handlers, CLI commands, user functions)
  * translate these into their native error shapes at the edge.
+ *
+ * Branch on {@link Run402Error.kind} (or the exported `is*` type guards) rather
+ * than `instanceof`. Discriminator-based checks survive duplicate SDK installs,
+ * bundler chunk splits, ESM/CJS interop, and V8-isolate realm boundaries —
+ * any setting where a class object's identity might differ from the consumer's
+ * own class object reference. `instanceof X` continues to work for callers
+ * holding a single SDK copy (back-compat); the guards are the recommended path.
  */
 export class Run402Error extends Error {
+    /**
+     * Structural brand. Always `true` on any {@link Run402Error} subclass
+     * instance, regardless of which SDK copy created it. The exported
+     * {@link isRun402Error} guard checks this field instead of `instanceof`,
+     * so cross-realm and cross-bundle errors still match.
+     */
+    isRun402Error = true;
     /** HTTP status, or null for local/network failures that produced no response. */
     status;
     /** Parsed response body, or null when no body was received. */
@@ -33,12 +47,22 @@ export class Run402Error extends Error {
         this.body = body;
         this.context = context;
         const envelope = canonicalEnvelope(body);
-        if (typeof envelope?.code === "string")
-            this.code = envelope.code;
-        if (typeof envelope?.category === "string")
-            this.category = envelope.category;
-        if (typeof envelope?.retryable === "boolean")
-            this.retryable = envelope.retryable;
+        const ctor = this.constructor;
+        const envelopeCode = typeof envelope?.code === "string" ? envelope.code : undefined;
+        const envelopeCategory = typeof envelope?.category === "string" ? envelope.category : undefined;
+        const envelopeRetryable = typeof envelope?.retryable === "boolean" ? envelope.retryable : undefined;
+        if (envelopeCode !== undefined)
+            this.code = envelopeCode;
+        else if (ctor.DEFAULT_CODE !== undefined)
+            this.code = ctor.DEFAULT_CODE;
+        if (envelopeCategory !== undefined)
+            this.category = envelopeCategory;
+        else if (ctor.DEFAULT_CATEGORY !== undefined)
+            this.category = ctor.DEFAULT_CATEGORY;
+        if (envelopeRetryable !== undefined)
+            this.retryable = envelopeRetryable;
+        else if (ctor.DEFAULT_RETRYABLE !== undefined)
+            this.retryable = ctor.DEFAULT_RETRYABLE;
         if (typeof envelope?.safe_to_retry === "boolean")
             this.safeToRetry = envelope.safe_to_retry;
         if (typeof envelope?.mutation_state === "string")
@@ -51,6 +75,31 @@ export class Run402Error extends Error {
         if (Array.isArray(envelope?.next_actions))
             this.nextActions = envelope.next_actions;
     }
+    /**
+     * Canonical structured envelope for `JSON.stringify`. Without this, an
+     * `Error` instance serializes as `"{}"` (its built-in fields are
+     * non-enumerable), losing every structured detail an agent needs for
+     * triage. Subclasses with extra fields (e.g. {@link Run402DeployError})
+     * override and spread `super.toJSON()`.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            kind: this.kind,
+            message: this.message,
+            status: this.status,
+            code: this.code,
+            category: this.category,
+            retryable: this.retryable,
+            safeToRetry: this.safeToRetry,
+            mutationState: this.mutationState,
+            traceId: this.traceId,
+            context: this.context,
+            details: this.details,
+            nextActions: this.nextActions,
+            body: this.body,
+        };
+    }
 }
 function canonicalEnvelope(body) {
     return body && typeof body === "object" && !Array.isArray(body)
@@ -59,9 +108,17 @@ function canonicalEnvelope(body) {
 }
 /** HTTP 402 — the gateway requires payment (lease expired, insufficient balance, or x402 quote). */
 export class PaymentRequired extends Run402Error {
+    static DEFAULT_CODE = "PAYMENT_REQUIRED";
+    static DEFAULT_CATEGORY = "payment_required";
+    static DEFAULT_RETRYABLE = false;
+    kind = "payment_required";
 }
 /** Project ID is not present in the credential provider (local miss) or the gateway returned 404. */
 export class ProjectNotFound extends Run402Error {
+    static DEFAULT_CODE = "PROJECT_NOT_FOUND";
+    static DEFAULT_CATEGORY = "not_found";
+    static DEFAULT_RETRYABLE = false;
+    kind = "project_not_found";
     projectId;
     constructor(projectId, context, status = null, body = null) {
         super(`Project ${projectId} not found`, status, body, context);
@@ -70,12 +127,24 @@ export class ProjectNotFound extends Run402Error {
 }
 /** HTTP 401 or 403 — authentication missing, invalid, or insufficient for the operation. */
 export class Unauthorized extends Run402Error {
+    static DEFAULT_CODE = "UNAUTHORIZED";
+    static DEFAULT_CATEGORY = "auth";
+    static DEFAULT_RETRYABLE = false;
+    kind = "unauthorized";
 }
 /** Any other non-2xx HTTP response from the gateway. */
 export class ApiError extends Run402Error {
+    static DEFAULT_CODE = "API_ERROR";
+    static DEFAULT_CATEGORY = "api";
+    static DEFAULT_RETRYABLE = false;
+    kind = "api_error";
 }
 /** The underlying `fetch` threw before producing a response (DNS, connection reset, offline). */
 export class NetworkError extends Run402Error {
+    static DEFAULT_CODE = "NETWORK_ERROR";
+    static DEFAULT_CATEGORY = "network";
+    static DEFAULT_RETRYABLE = true;
+    kind = "network_error";
     cause;
     constructor(message, cause, context) {
         super(message, null, null, context);
@@ -84,6 +153,10 @@ export class NetworkError extends Run402Error {
 }
 /** Local/filesystem error — input validation, missing path, unreadable dir. No HTTP involved. */
 export class LocalError extends Run402Error {
+    static DEFAULT_CODE = "LOCAL_ERROR";
+    static DEFAULT_CATEGORY = "local";
+    static DEFAULT_RETRYABLE = false;
+    kind = "local_error";
     cause;
     constructor(message, context, cause) {
         super(message, null, null, context);
@@ -92,6 +165,7 @@ export class LocalError extends Run402Error {
     }
 }
 export class Run402DeployError extends Run402Error {
+    kind = "deploy_error";
     code;
     phase;
     resource;
@@ -113,5 +187,87 @@ export class Run402DeployError extends Run402Error {
         this.logs = init.logs ?? null;
         this.rolledBack = init.rolledBack ?? false;
     }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            phase: this.phase,
+            resource: this.resource,
+            operationId: this.operationId,
+            planId: this.planId,
+            fix: this.fix,
+            logs: this.logs,
+            rolledBack: this.rolledBack,
+            retryable: this.retryable,
+        };
+    }
+}
+// ─── Type guards ─────────────────────────────────────────────────────────────
+//
+// Identity-free guards. Each one checks the structural brand and (for subclass
+// guards) the `kind` discriminator. Use these instead of `instanceof X` so the
+// check survives duplicate SDK installs, bundler chunk splits, ESM/CJS interop,
+// and V8-isolate realm boundaries — anywhere the consumer's class object
+// reference might differ from the throw site's.
+/** True if `e` is any {@link Run402Error} subclass instance, regardless of which SDK copy created it. */
+export function isRun402Error(e) {
+    return Boolean(e &&
+        typeof e === "object" &&
+        e.isRun402Error === true);
+}
+/** True if `e` is a {@link PaymentRequired}. Survives duplicate SDK copies and realms. */
+export function isPaymentRequired(e) {
+    return isRun402Error(e) && e.kind === "payment_required";
+}
+/** True if `e` is a {@link ProjectNotFound}. */
+export function isProjectNotFound(e) {
+    return isRun402Error(e) && e.kind === "project_not_found";
+}
+/** True if `e` is an {@link Unauthorized}. */
+export function isUnauthorized(e) {
+    return isRun402Error(e) && e.kind === "unauthorized";
+}
+/** True if `e` is an {@link ApiError}. */
+export function isApiError(e) {
+    return isRun402Error(e) && e.kind === "api_error";
+}
+/** True if `e` is a {@link NetworkError}. */
+export function isNetworkError(e) {
+    return isRun402Error(e) && e.kind === "network_error";
+}
+/** True if `e` is a {@link LocalError}. */
+export function isLocalError(e) {
+    return isRun402Error(e) && e.kind === "local_error";
+}
+/** True if `e` is a {@link Run402DeployError}. */
+export function isDeployError(e) {
+    return isRun402Error(e) && e.kind === "deploy_error";
+}
+/**
+ * Canonical "should I retry this?" policy. Returns true when `e` is a
+ * {@link Run402Error} AND any of:
+ *   - `e.retryable === true` (gateway flagged it)
+ *   - `e.safeToRetry === true` (gateway flagged it)
+ *   - `e.kind === "network_error"` (fetch never produced a response)
+ *   - `e.status` is 408 (Request Timeout), 425 (Too Early), or 429 (Too Many
+ *     Requests)
+ *   - `e.status` is a 5xx server error
+ *
+ * Returns false for non-Run402 errors so it can be safely called with
+ * `unknown` from a catch block. Used as the default `retryIf` in
+ * {@link withRetry}.
+ */
+export function isRetryableRun402Error(e) {
+    if (!isRun402Error(e))
+        return false;
+    if (e.retryable === true || e.safeToRetry === true)
+        return true;
+    if (e.kind === "network_error")
+        return true;
+    const s = e.status;
+    if (s === 408 || s === 425 || s === 429)
+        return true;
+    if (typeof s === "number" && s >= 500)
+        return true;
+    return false;
 }
 //# sourceMappingURL=errors.js.map