feat(sdk): add discriminated errors, type guards, toJSON, withRetry

The April 2026 SDK DX consultation called out `instanceof Run402Error`
as fragile across SDK copies and realms — duplicate npm installs,
bundler chunk splits, ESM/CJS interop, and V8-isolate boundaries all
silently break identity-based checks. Coding agents run in environments
they don't control, so a failed `instanceof` shows up as "my error
handler doesn't catch the right errors" with no diagnostic.

This change adds value-based discriminators alongside the existing
class hierarchy. All additions are non-breaking — `instanceof` keeps
working for single-copy single-realm callers.

New surface (exported from @run402/sdk and @run402/sdk/node):
- Run402ErrorKind: union of "payment_required" | "project_not_found"
  | "unauthorized" | "api_error" | "network_error" | "local_error"
  | "deploy_error".
- Run402Error.kind: stable string discriminator on every subclass.
- Run402Error.isRun402Error: structural brand for cross-copy detection.
- Run402Error.toJSON(): canonical envelope (name/kind/message/status/
  code/category/retryable/safeToRetry/mutationState/traceId/context/
  details/nextActions/body). Run402DeployError extends with phase/
  resource/operationId/planId/fix/logs/rolledBack. JSON.stringify on
  any subclass now produces a populated object instead of "{}".
- Type guards: isRun402Error, isPaymentRequired, isProjectNotFound,
  isUnauthorized, isApiError, isNetworkError, isLocalError,
  isDeployError, isRetryableRun402Error.
- withRetry(fn, opts?): exponential-backoff helper using
  isRetryableRun402Error as the default policy. Defaults: 3 attempts,
  250ms base, 5s cap. Throws the LAST error after exhausting attempts
  so the caller's catch handler sees the original structured envelope.
  Pair with idempotencyKey baked into the closure for safe mutation
  retries.

Fixed two anonymous Run402Error subclasses in
sdk/src/namespaces/projects.ts (which TypeScript correctly rejected
once `kind` became abstract) — replaced with LocalError, which is
the right class for local-config-missing errors.

Docs: rewrote the "Errors" sections in sdk/README.md and
sdk/llms-sdk.txt to lead with the type-guard pattern, document the
Run402ErrorKind union, and show the canonical `withRetry` recipe paired
with idempotencyKey. The CI gate (sdk-docs-fidelity) verifies every
TS-fenced example compiles against the new types.

Tests: 45 new unit tests in sdk/src/errors.test.ts (kind discriminators,
brand, each guard's narrowing, isRetryableRun402Error policy across
status codes / flags / kinds, toJSON envelope shape including subclass
fields, instanceof back-compat) and sdk/src/retry.test.ts (happy path,
retry on retryable failures, non-retryable short-circuit, last-error
preservation, custom retryIf, onRetry callback ordering and buggy-logger
isolation, exponential backoff timing capped by maxDelayMs, closure
idempotency-key passthrough).

Side fix (npm test glob): the root package.json's test script had
unquoted globs (`sdk/src/**/*.test.ts`), which the shell expanded
without globstar — silently dropping every depth-1 test in
core/src, sdk/src, and src. Local `npm test` reported 266; CI's
inline quoted-glob command saw 566. Quoted the globs in
package.json so local matches CI. Net effect: 300 previously-hidden
tests now run on every local `npm test`.

Spec at run402-private/openspec/changes/sdk-error-discrimination/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

package.json

@@ -29,7 +29,7 @@
     "test:skill": "node --test --import tsx SKILL.test.ts",
     "test:sync": "node --test --import tsx sync.test.ts",
     "test:docs": "npm run check:docs --workspace=@run402/sdk -- --skip-build",
-    "test": "node --experimental-test-module-mocks --test --import tsx SKILL.test.ts sync.test.ts core/src/**/*.test.ts sdk/src/**/*.test.ts src/**/*.test.ts && node --test cli-e2e.test.mjs cli-help.test.mjs && npm run test:docs",
+    "test": "node --experimental-test-module-mocks --test --import tsx SKILL.test.ts sync.test.ts 'core/src/**/*.test.ts' 'sdk/src/**/*.test.ts' 'src/**/*.test.ts' && node --test cli-e2e.test.mjs cli-help.test.mjs && npm run test:docs",
     "test:e2e": "node --test cli-e2e.test.mjs cli-help.test.mjs",
     "test:help": "node --test cli-help.test.mjs",
     "test:integration": "node --test --import tsx core/src/siwx-integration.integ.ts",

sdk/README.md

@@ -143,42 +143,101 @@ 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";
 
 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

sdk/llms-sdk.txt

@@ -104,42 +104,78 @@ const info = await r.projects.info(projectId);
 
 ## Errors
 
-All failures throw subclasses of `Run402Error`. Branch on instance, not English message:
+All failures throw subclasses of `Run402Error`. Every subclass carries a stable
+`kind` string discriminator and an `isRun402Error` brand. Branch with the
+exported type guards (or by comparing `e.kind`) — NOT with `instanceof X`:
+identity-based checks fail 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). `instanceof` continues to work for
+single-copy single-realm callers as a back-compat path.
+
+| 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` |
 
-| Class | When | Notable fields |
-|---|---|---|
-| `PaymentRequired` | HTTP 402 | x402 payment requirements in `body` |
-| `ProjectNotFound` | Project ID not in the credential provider | `projectId` |
-| `Unauthorized` | HTTP 401 / 403 | — |
-| `ApiError` | Other non-2xx responses | `status`, `body` |
-| `NetworkError` | Fetch rejected with no HTTP response | `cause` |
-| `LocalError` | Local-host issues (filesystem, signing) | — |
-| `Run402DeployError` | Structured envelope from the deploy state machine (v1.34+) | `code`, `phase`, `operationId`, `safeToRetry`, `mutationState`, `nextActions` |
+The exported `Run402ErrorKind` union type (`"payment_required" | "project_not_found" | "unauthorized" | "api_error" | "network_error" | "local_error" | "deploy_error"`) supports exhaustive `switch` statements with TypeScript exhaustiveness checking.
 
 ```ts
 import {
   run402,
-  PaymentRequired,
-  Run402DeployError,
+  withRetry,
+  isPaymentRequired,
+  isDeployError,
   type ReleaseSpec,
 } from "@run402/sdk/node";
 
 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)) {
+    // narrowed to PaymentRequired — read e.body for the x402 quote
+  } else if (isDeployError(e)) {
+    // narrowed to Run402DeployError — log the structured envelope for triage
+    process.stderr.write(JSON.stringify(e) + "\n");
   } else throw e;
 }
 ```
 
 `Run402DeployError.code` is one of `MIGRATION_FAILED`, `MIGRATION_CHECKSUM_MISMATCH`, `BASE_RELEASE_CONFLICT`, `PAYMENT_REQUIRED`, `SCHEMA_SETTLE_TIMEOUT`, `ACTIVATION_FAILED`, `STORAGE_UNAVAILABLE`, `SITE_STAGE_FAILED`, `FUNCTION_BUILD_FAILED`, `CONTENT_UPLOAD_FAILED`, `INVALID_SPEC`, `OPERATION_NOT_FOUND`, `MIGRATE_GATE_ACTIVE`, `INTERNAL_ERROR`, `NETWORK_ERROR`, `PROJECT_NOT_FOUND` (or any other string the gateway emits — consumers SHALL treat unknown codes as opaque). Pair it with the structured `nextActions` advisory array carried in the error body.
 
+### Type guards and the canonical retry policy
+
+The SDK exports identity-free guards plus a single canonical "should I retry this?" function:
+
+- `isRun402Error(e)` — true for any `Run402Error` subclass instance, regardless of which SDK copy created it.
+- `isPaymentRequired(e)`, `isProjectNotFound(e)`, `isUnauthorized(e)`, `isApiError(e)`, `isNetworkError(e)`, `isLocalError(e)`, `isDeployError(e)` — narrow `unknown` to the named subclass.
+- `isRetryableRun402Error(e)` — encapsulates the retry policy: `e.retryable || e.safeToRetry || kind === "network_error" || status in {408, 425, 429} || status >= 500`. Returns `false` for non-Run402 inputs so it's safe to call from any `catch` block.
+
+`Run402Error.toJSON()` returns a canonical envelope (`name`, `kind`, `message`, `status`, `code`, `category`, `retryable`, `safeToRetry`, `mutationState`, `traceId`, `context`, `details`, `nextActions`, `body`). `Run402DeployError.toJSON()` extends it with `phase`, `resource`, `operationId`, `planId`, `fix`, `logs`, `rolledBack`. `JSON.stringify(error)` produces a populated structured object — never the empty `"{}"` plain `Error` produces.
+
+### `withRetry(fn, opts?)`
+
+`withRetry` runs an async function with exponential backoff. Defaults: 3 attempts (1 + 2 retries), 250 ms base delay, 5 s cap. Uses `isRetryableRun402Error` as the default retry decision. Pair with the SDK method's own `idempotencyKey` so retried mutations dedup server-side — the closure carries the same key on every attempt.
+
+`RetryOptions`: `attempts?: number`, `baseDelayMs?: number`, `maxDelayMs?: number`, `retryIf?: (error, attempt) => boolean`, `onRetry?: (error, attempt, delayMs) => void`.
+
+After exhausting attempts, `withRetry` throws the LAST observed error — your catch handler sees the original structured envelope, not a wrapper. A buggy `onRetry` that throws is swallowed; the retry chain is unaffected.
+
 ## The patterns
 
 ### Paste-and-go assets — content-addressed URLs with SRI