# Run402 — HTTP API reference

> Wayfinder: https://run402.com/llms.txt
> SDK reference (recommended): https://run402.com/llms-sdk.txt
> CLI reference: https://run402.com/llms-cli.txt
> MCP reference: https://run402.com/llms-mcp.txt
> OpenAPI: https://run402.com/openapi.json
> Source of truth for this file: site/llms-full.txt in github.com/kychee-com/run402-private

This is the canonical, machine-readable reference for the Run402 HTTP API at `https://api.run402.com`. **Use this only when you can't use the SDK / CLI / MCP** — those are the recommended surfaces for coding agents.

## Pick the SDK first

Run402 ships four wrappers around the same HTTP API. In order of preference for coding agents:

1. **`@run402/sdk`** ⭐ — typed TypeScript / JavaScript kernel. Every method is typed, every error is a typed subclass of `Run402Error`, never throws on network shape. **Use this if you're authoring code.** → <https://run402.com/llms-sdk.txt>
2. **`run402` CLI** — JSON in / JSON out, exit code on failure. For scripted shells. → <https://run402.com/llms-cli.txt>
3. **`run402-mcp`** — MCP tools auto-loaded into Claude Desktop / Cursor / Cline / Claude Code. → <https://run402.com/llms-mcp.txt>
4. **HTTP API (this file)** — only if the language has no SDK or you're integrating at a layer below.

The CLI and MCP server are thin shims over the SDK, and the SDK is a thin wrapper over this HTTP API. If you can use the SDK, do — fewer process boundaries, typed errors, identical behavior. This file exists for completeness; it is not the recommended path.

## API base & host rules

`https://api.run402.com` is the API. **Never POST to `https://run402.com`** — that's the static docs site (returns 405 on writes).

- Single AWS region (us-east-1), 2 AZs. Aurora Postgres 16 + ECS Fargate + S3 + CloudFront. Operator: Kychee, Inc.
- Health: `GET /health`. Status: `GET /status`. x402 discovery: `GET /.well-known/x402`.
- Project rate limit: **100 req/sec** per project. Exceeding returns 429 with `retry_after`.
- CORS: `Access-Control-Allow-Origin: *` (intentional — for browser-side x402 / MPP clients). Allowed request headers: `apikey`, `Content-Type`, `Authorization`, `Prefer`, `Accept-Profile`, `Content-Profile`, `Idempotency-Key`, `SIGN-IN-WITH-X`, `X-Confirm-Drain`, `X-Confirm-Delete`.

## Authentication surfaces

Seven authentication shapes, never mixed on the same request:

| Header / shape | Where it works | Provided by |
|---|---|---|
| `X-402-Payment: <signed-payment>` | Paid endpoints (`POST /tiers/v1/:tier`, `POST /generate-image/v1`, `POST /contracts/v1/call`, `POST /contracts/v1/signers`, `POST /contracts/v1/signers/:signer_id/drain`, `POST /faucet/v1`) | `@x402/fetch` client; the SDK does this for you. |
| `SIGN-IN-WITH-X: <base64 CAIP-122 payload>` | Wallet-level free actions (`POST /projects/v1`, all `/apply/v1/*` writes, `POST /fork/v1`, `POST /message/v1`, `GET /ping/v1`, `POST /agent/v1/contact`, `GET /tiers/v1/status`) | `@x402/extensions/sign-in-with-x` helpers. EVM (EIP-191) or Solana (Ed25519). |
| `Authorization: Bearer <service_key>` | Project-admin operations (`/projects/v1/admin/:project_id/*`, `/contracts/v1/signers/*`, `/mailboxes/v1/*`, `/email/v1/domains*`, `/subdomains/v1` writes, `/domains/v1` writes, `/ai/v1/translate`, `/ai/v1/moderate`, `/ai/v1/usage`) | Returned by `POST /projects/v1`. Never expires. **Never embed in browser code.** |
| `apikey: <anon_key>` *(or `<service_key>`)* | All client-facing surfaces: `/rest/v1/*`, `/auth/v1/*`, `/storage/v1/*`, `/content/v1/*`, `/functions/v1/:name`, `GET /apply/v1/operations/:operation_id`, `GET /apply/v1/operations/:operation_id/events`, `POST /apply/v1/operations/:operation_id/resume` (read paths) | `anon_key` returned by `POST /projects/v1`. RLS applies. |
| `apikey + Authorization: Bearer <access_token>` | Per-user actions: `GET /auth/v1/user`, `POST /auth/v1/logout`, `PUT /auth/v1/user/password`, RLS-scoped writes on `/rest/v1/*` | `access_token` from `POST /auth/v1/token`. |
| `Authorization: Bearer <ci-session-jwt>` | Seven CI-callable routes: all `/content/v1/plans*` writes, all `/apply/v1/plans*` writes, `GET /apply/v1/operations/:operation_id` + `/events`, `POST /apply/v1/operations/:operation_id/resume`. Token has `token_use === "ci_session"`. | Returned by `POST /ci/v1/token-exchange` after exchanging a GitHub Actions OIDC JWT. 15-min TTL bounded by binding expiry. See "OIDC federation for CI/CD" below. |
| `Authorization: Bearer <operator-session-jwt>` | Read-only operator-console reads (`GET /agent/v1/operator/overview`, `GET /agent/v1/operator/projects/:project_id/contents`, `POST /agent/v1/operator/session/refresh`). Token has `token_use === "operator_session"`, `scope ["operator.read"]`, `aud "run402.agent.v1.operator"`. Rejected at every mutating route. | Minted by `POST /agent/v1/operator/session/email(/verify)` (magic-link) or `/passkey/options`+`/passkey/verify` (WebAuthn login). 30-min TTL, 12h absolute cap, revocable. See "Operator console" below. |
| Admin-key (operator only) | `POST /ai/v1/addons`, `DELETE /ai/v1/addons`, `POST /mailboxes/v1/:mailbox_id/status`, `GET /admin/v1/operator/overview` | Run402 platform operators. Not agent-facing. |

`anon_key` and `service_key` never expire. Lease enforcement is server-side. Access tokens (`/auth/v1/token`) expire in 1h; refresh tokens expire in 30d, single-use.

**Ownership & authorization (v1.77 — org-owned control plane).** A wallet address **authenticates**, it does not own. SIWX resolves your wallet to a control-plane *principal*; a project is owned by an **org (organization)** via `projects.organization_id`, and what a principal may do is decided by its org *membership* role (`owner > admin > developer > billing > viewer`) or a per-project *grant* (used for agent/CI principals that aren't broad members) — never by `wallet_address == signer`. Effects: project objects expose `org_id` (owning org) + `created_by` (provisioning principal) instead of `wallet_address`; control-plane denials return `403 FORBIDDEN` (never 404 — project existence isn't leaked); high-stakes ops (delete, transfer-of-ownership, membership change) require an active **owner** membership regardless of principal type. **Agent-first cold-start is unchanged:** a fresh wallet that subscribes + provisions becomes the owner of its own org-of-one automatically (no email/passkey/claim/approval) — the org/membership layer is invisible until a second principal joins. Co-ownership and individual revocation (one membership row, no key rotation) follow directly. The `run402` CLI / MCP / SDK surface for `org`/membership management ships as a fast-follow; SIWX auth itself is unchanged.

## Operator console — read-only organization overview

An API-first, **read-only** surface for the human operator (or the agent acting on their behalf). It authenticates by **email control** — no signing wallet, no custody — and grants read of every wallet whose verified `agent_contacts` email matches the session email. The reference web console is just a consumer of these endpoints.

**Endpoints:**

| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
| `/agent/v1/operator/session/email` | POST | none (rate-limited) | Send a magic-link sign-in (no account-existence oracle) |
| `/agent/v1/operator/session/email/verify` | POST | magic-link token | Exchange the fragment token → operator session |
| `/agent/v1/operator/session/passkey/options` | POST | none | WebAuthn login options |
| `/agent/v1/operator/session/passkey/verify` | POST | WebAuthn assertion | Exchange assertion → operator session |
| `/agent/v1/operator/session/passkey/enroll/options` | POST | operator session | WebAuthn registration options (enroll a passkey) |
| `/agent/v1/operator/session/passkey/enroll/verify` | POST | operator session | Verify registration → persist the passkey |
| `/agent/v1/operator/session/refresh` | POST | operator session | Rotate + re-issue the session token |
| `/agent/v1/operator/session/device` | POST | none (email-less) | Start a CLI device-authorization (RFC 8628); returns `device_code`, `user_code`, verification URIs |
| `/agent/v1/operator/session/device/approve` | POST | operator session (recent auth) | Approve/deny a pending `user_code` (binds the decision; mints no session) |
| `/agent/v1/operator/session/device/token` | POST | none (`device_code` is the credential) | Poll for the session; RFC-8628 error body (`authorization_pending` / `slow_down` / `access_denied` / `expired_token`) until approved |
| `/agent/v1/operator/session/revoke` | POST | operator session | Sign out — revoke the current session (its `jti`); idempotent `204` |
| `/agent/v1/operator/overview` | GET | operator session **or** control-plane session **or** SIWX | Tier-A account summary (counts only) |
| `/agent/v1/operator/projects` | GET | operator session **or** SIWX | Named cross-account project inventory (`projects list --all`): name + site_url + custom domains + owning org |
| `/agent/v1/operator/projects/{project_id}/contents` | GET | operator session (passkey) **or** SIWX | Tier-B inventory names (never values) |

**Auth: the operator session.** A read-scoped HS256 bearer (`typ: "run402.operator-session+jwt"`, `aud: "run402.agent.v1.operator"`, `scope: ["operator.read"]`, `token_use: "operator_session"`), signed with a dedicated secret (asserted distinct from the tenant-JWT and CI-session secrets). Minted two ways; both return `{ operator_session_token, token_type: "Bearer", expires_in, absolute_expires_at, email, wallets[] }`:

- **Magic-link:** `POST /agent/v1/operator/session/email {email}` returns an **identical** 200 whether or not the email has an account (no account-existence oracle); a single-use link (token in the URL **fragment**) is emailed only to an email controlling ≥1 verified wallet. Exchange the fragment token via `POST /agent/v1/operator/session/email/verify {token}`.
- **Passkey-login:** `POST /agent/v1/operator/session/passkey/options {email}` → `POST /agent/v1/operator/session/passkey/verify {email, response}` (standard WebAuthn authentication against the operator's enrolled passkey; no PRF, no signing wallet).
- **Refresh:** `POST /agent/v1/operator/session/refresh` (with the operator-session bearer) rotates the token. 30-min access TTL; 12h absolute re-auth cap; server-side revocable.
- **CLI device login (RFC 8628):** `POST /agent/v1/operator/session/device` (no email) returns a `device_code` + `user_code` + `verification_uri`/`verification_uri_complete`; the operator opens the URL and `POST /agent/v1/operator/session/device/approve {user_code, decision?}` (operator-session bearer authenticated within the last few minutes) binds the approve/deny decision without minting a session; the CLI polls `POST /agent/v1/operator/session/device/token {device_code}` and receives the session on approval (an RFC-8628 `{ error }` body — `authorization_pending` / `slow_down` / `access_denied` / `expired_token` — until then).
- **Sign out:** `POST /agent/v1/operator/session/revoke` (operator-session bearer) revokes the current session by its `jti`; idempotent `204`, effective on the next request.

**Tier-A summary read:** `GET /agent/v1/operator/overview` — accepts an operator-session bearer (union across the email's verified wallets), a **control-plane session** bearer (the console's write-capable sign-in reading its OWN footprint: union across the principal's verified emails plus its siwx wallet authenticators; `scope.kind` is `"principal"`), **or** a `SIGN-IN-WITH-X` header (that wallet's slice). The bearer is classified by its `token_use` claim — no silent fallback. Service/admin keys are NOT accepted here, and a control-plane session is Tier-A only (it is NOT accepted on the Tier-B contents read). Returns a multi-organization shape `{ scope, operator, rollup, organizations[], wallets[], advisories[] }` with **counts only** (functions/secrets/domains/mailboxes) — never inventory names.

**Cross-account project inventory (`projects list --all`):** `GET /agent/v1/operator/projects` — the named, domain-aware project inventory across the operator's verified-email wallet union (operator-session bearer), or a single wallet's slice (`SIGN-IN-WITH-X`). Returns `{ projects: [{ project_id, name, tier, site_url, custom_domains, status, org_id, created_by, created_at }], scope }` — the same row shape as `GET /projects/v1`, so one renderer covers both. Soft-deleted (tombstone) projects are never listed; archived hidden by default — opt in with `?include=archived` (any other value → 400). Names + public addressing only; no secret/key value. Service/admin keys are NOT accepted here. Authority parity with the overview: a project appears iff one of the union's wallets resolves to a principal holding an active org membership on its owning org (or an active project grant).

**Tier-B inventory read:** `GET /agent/v1/operator/projects/:project_id/contents` — secret **names** (never values), function names, domains, subdomains, mailbox slugs. An operator session needs **fresh proof** (passkey-login, or a magic-link auth within the last 5 min); SIWX is inherently fresh. The project must be owned by a wallet in the caller's set (fresh DB read).

**Disclosure ceiling:** read-only by construction — the operator session 401s at every mutating route (enforced by a central route auth/effect manifest + a CI gate, not by convention). No secret value, private key, or token appears in any tier. Support/debug reads go through the admin-only, audited `GET /admin/v1/operator/overview` (mandatory `email|wallet|org_id` target). Later phases add email-safe action-scoped mutations and a browser signing wallet; Phase 0 (this) is strictly read-only.

## Control-plane console — hosted owner login (write-capable session)

Distinct from the read-only operator session above. The **control-plane session** is the human owner's **write-capable** login for org management (members, invites, audit, project handoffs). It is a different actor, token class, and data scope from the tenant end-user hosted auth UI (`/auth/sign-in`, the `@run402/astro` `<SignIn>` surface, which logs in a *project's* end-users) — the two `/auth/*`-shaped flows are never conflated.

The hosted browser pages live on the console origin (`console.run402.com`); the gateway owns the auth endpoints (the console holds no privileged secret — it is a pure-static consumer). Tokens are held **in memory only** (never `localStorage`).

**Endpoints (`/agent/v1/control-plane/*`):**

| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
| `/agent/v1/control-plane/session/email` | POST | none (rate-limited) | Send a magic-link sign-in (no account-existence oracle) |
| `/agent/v1/control-plane/session/email/verify` | POST | magic-link token | Exchange the fragment token → control-plane session |
| `/agent/v1/control-plane/session/passkey/options` | POST | none | WebAuthn login options |
| `/agent/v1/control-plane/session/passkey/verify` | POST | WebAuthn assertion | Exchange assertion → control-plane session |
| `/agent/v1/control-plane/oauth/{provider}/start` | GET | none | 302 to the provider (`google` / `github`). `503` until OAuth creds are provisioned |
| `/agent/v1/control-plane/oauth/{provider}/callback` | GET | provider redirect | Resolve identity **by verified email** → mint → land on `CONSOLE_ORIGIN#cp_session` (or `#oauth_needs_confirmation` on an email conflict) |
| `/agent/v1/control-plane/session` | GET | control-plane session | Whoami — principal, `amr`, active memberships |
| `/agent/v1/control-plane/session/refresh` | POST | control-plane session | Rotate + re-issue the session token |
| `/agent/v1/control-plane/session/revoke` | POST | control-plane session | Sign out — revoke the current session (its `jti`) |
| `/agent/v1/control-plane/passkey/enroll/options` | POST | control-plane session | WebAuthn registration options (enroll a passkey) |
| `/agent/v1/control-plane/passkey/enroll/verify` | POST | control-plane session (step-up) | Verify registration → persist the passkey. Also claims any pending org invites deferred on the passkey requirement (response carries `invites_claimed`) |
| `/agent/v1/control-plane/step-up/options` | POST | control-plane session | Fresh-WebAuthn step-up options for a high-stakes op class |
| `/agent/v1/control-plane/step-up/verify` | POST | control-plane session | Record the fresh passkey elevation (then retry the op) |
| `/agent/v1/control-plane/recovery/issue` | POST | control-plane session (step-up) | (Re)issue recovery codes — shown once |
| `/agent/v1/control-plane/recovery/consume` | POST | recovery code | Recovery ceremony → session (`amr: ["recovery_code"]`, never satisfies step-up) |
| `/agent/v1/control-plane/authenticators` | GET | control-plane session | List active authenticators |
| `/agent/v1/control-plane/authenticators/{authenticator_id}` | DELETE | control-plane session (step-up) | Revoke one authenticator (last-owner-passkey guarded) |
| `/agent/v1/control-plane/cli/authorize/{flow_id}` | GET | control-plane session | CLI loopback-PKCE: load the pending flow for the approve page |
| `/agent/v1/control-plane/cli/approve` | POST | control-plane session (step-up) | Approve the CLI flow → return the loopback redirect URL with the auth code |
| `/agent/v1/control-plane/oauth/{provider}/link` | POST | control-plane session (step-up) | Start an OAuth flow in LINK mode → `{ auth_url }`; the callback attaches the identity to the CURRENT principal (completes `needs_confirmation`) |
| `/agent/v1/control-plane/emails` | POST | control-plane session (step-up) | Request attaching an additional email (generic response — no account-existence oracle) |
| `/agent/v1/control-plane/write-auth/challenges` | POST | control-plane session | Open a passkey write-intent ceremony for one action+target → `{ challenge_id, confirm_url, expires_at }` |
| `/agent/v1/control-plane/write-auth/verify` | POST | WebAuthn assertion | Verify the write-intent assertion → mint the target-scoped write-auth session (opaque token, returned once). In CLI loopback mode the mint is deferred — returns `{ delivery: "cli_loopback", redirect_to }` instead |
| `/agent/v1/control-plane/write-auth/cli/token` | POST | claim code + PKCE | Headless-CLI delivery: exchange the loopback claim `code` + `code_verifier` + `state` → mint the write-auth session, return the token once. Open the challenge with `cli_redirect_uri` + `code_challenge` (S256) + `state` to use this leg |
| `/agent/v1/control-plane/write-auth/sessions` | GET | control-plane session | List active write-auth sessions bound to this session |
| `/agent/v1/control-plane/write-auth/sessions/{write_auth_session_id}/revoke` | POST | control-plane session | Revoke one write-auth session |
| `/agent/v1/control-plane/write-auth/revoke-all` | POST | control-plane session | Revoke every write-auth session for the principal |
| `/agent/v1/control-plane/emails/verify` | POST | control-plane session + attach token | Confirm the attach (inbox + same-session proof) → verified email on this principal; `409 EMAIL_BELONGS_TO_OTHER_PRINCIPAL` → merge |
| `/agent/v1/control-plane/merge` | POST | control-plane session (step-up, passkey) | Merge a duplicate principal into this one — body `{ source_session_token, source_principal_id? }`; Phase 1 needs an authority-empty source |

**Auth: the control-plane session.** A bearer JWT `typ: "run402.control-plane-session+jwt"`, signed with `CONTROL_PLANE_SESSION_SECRET` (asserted distinct from `JWT_SECRET`, `CI_SESSION_SECRET`, and `OPERATOR_SESSION_SECRET` — the fourth token-class-confusion guard). Login mints it; `resolveAuthContext` turns it into the AuthContext the org policy matrix authorizes against. High-stakes ops (delete, transfer-of-ownership, membership/invite change, authenticator change, CLI approve) require a fresh **passkey** step-up — a recent password/magic-link proof does NOT satisfy it; the gateway returns `STEP_UP_REQUIRED` and the client re-runs the step-up ceremony then retries. OAuth identities **link by verified email** (an OAuth account whose email already belongs to an owner is *not* auto-linked — the callback lands on `#oauth_needs_confirmation`; sign in as that owner, then complete the attach with the explicit link flow: `POST /agent/v1/control-plane/oauth/{provider}/link` from account settings). One human with identities split across two principals (e.g. a GitHub login keyed to a different email) consolidates them with `POST /agent/v1/control-plane/merge` — both-sides possession proof, atomic credential re-pointing, source disabled with audit traceability.

**Hosted browser legs (on `console.run402.com`):** the sign-in / sign-up pages drive the email / passkey / OAuth endpoints; an OAuth-handoff landing reads the `#cp_session=<token>` (or `#oauth_needs_confirmation=1&email=…&provider=…`) URL fragment, scrubs it via `replaceState`, and establishes the in-memory session; a CLI loopback approve / passkey-ceremony page completes `run402 operator login` end-to-end (the gateway 302s the browser there from the CLI loopback authorize, the user runs the passkey ceremony + approves, and the browser is sent to the `127.0.0.1` loopback redirect with the auth code). The public SDK/CLI client surface (`r.operator.session.*`, nested `r.org.*`, `StepUpRequiredError`, operator loopback-PKCE login) shipped in `run402` v2.40.0 / v2.41.0.

**OAuth provisioning runbook (deploy-time, no code change).** `services/control-plane-oauth.ts` fails closed with `503 "Control-plane <provider> OAuth is not configured"` whenever `CONTROL_PLANE_{GOOGLE,GITHUB}_CLIENT_ID/SECRET` are empty. To go live: (1) register the Google + GitHub OAuth apps with redirect URI = `CONTROL_PLANE_OAUTH_REDIRECT_BASE` + `/agent/v1/control-plane/oauth/:provider/callback`; (2) provision `CONTROL_PLANE_GOOGLE_CLIENT_ID/SECRET` + `CONTROL_PLANE_GITHUB_CLIENT_ID/SECRET` in AWS Secrets Manager and wire them into the gateway task definition (alongside `CONTROL_PLANE_SESSION_SECRET`); (3) redeploy the gateway and verify `/oauth/{google,github}/start` no longer 503, the provider redirect fires, and the callback links by verified email and completes the `CONSOLE_ORIGIN#cp_session` handoff. CORS for the `Authorization`-bearing control-plane + operator routes allowlists the console origin (not `*`).

## Tiers, projects & lifecycle

| Tier | Cost | Lease | Storage | API calls | Functions | Max function bundle |
|------|------|-------|---------|-----------|-----------|---------------------|
| Prototype | **FREE** (testnet USDC, $0.10 to verify x402 setup) | 7 days | 250 MB | 500K | 15 | 1 MB |
| Hobby | $5 | 30 days | 1 GB | 5M | 50 | 5 MB |
| Team | $20 | 30 days | 10 GB | 50M | 1500 | 25 MB |

Real-money tiers: USDC on Base (chain `eip155:8453`) or pathUSD on Tempo (MPP) or Stripe credits. Testnet is Base Sepolia (`eip155:84532`). Same wallet key works on both rails.

```
POST /tiers/v1/:tier         # x402; auto-detects subscribe / renew / upgrade
GET  /tiers/v1               # tier pricing, no auth
GET  /tiers/v1/status        # current tier, organization_lifecycle_state, lease_perpetual, non-terminal projects (SIWX)
POST /projects/v1/quote      # estimate provisioning cost (free, no auth)
```

```
POST /projects/v1            # SIWX; optional { org_id }; returns { project_id, org_id, anon_key, service_key, schema_slot }
GET  /projects/v1            # SIWX, control-plane session (operator console; membership-scoped), or admin; server inventory: name + site_url + custom_domains + owning org (org_id) + status; ?limit=50&after=cursor&org_id=<uuid> (org filter is authorize-before-reveal). Soft-deleted (tombstone) projects are never listed; archived hidden by default — opt in with ?include=archived (any other include value → 400)
GET    /projects/v1/:project_id  # control-plane session or SIWX (viewer+ on owning org, or admin); authoritative single-project read - identity, org_id, tier, lifecycle, site_url + custom_domains, last_deploy, mailbox, usage vs tier limits; no secret values; authorize-before-reveal
PATCH /projects/v1/:project_id  # control-plane session or SIWX; rename — body { name }; admin+ on owning org (or project:write grant); authorize-before-reveal
DELETE /projects/v1/:project_id      # service_key/admin, or owner via session (passkey step-up) / SIWX (fresh signature); cascade purge
GET  /wallets/v1/:address/projects   # SIWX (signer must equal :address) or admin; lists projects owned by orgs the address's principal is an active member of
GET  /wallets/v1/:address/label      # public; { address, label } — server-side display name for a wallet (null if unset)
PUT  /wallets/v1/:address/label      # SIWX (signer must equal :address); body { label }; null|"" clears. Display metadata only
```

**Org members & project grants (v1.77 authority graph — the owner-gated management door).** SIWX authenticates → a control-plane *principal*; ownership/authorization is org membership (role lattice `owner > admin > developer > billing > viewer`) or per-project grant. These routes manage them. Member mutations require an active **owner** membership on the org; grant mutations require **owner** on the project's owning org; every mutation is audited and the org always keeps ≥1 active owner (last-owner guard).

```
GET    /agent/v1/whoami                                   # SIWX; { principal, memberships:[{org_id,display_name,role,status}] }
GET    /orgs/v1                                            # SIWX; orgs the caller is an active member of, with role + display_name
POST   /orgs/v1                                            # SIWX/session + step-up; create an empty org (prototype) { display_name? } → { org_id }. Creator = owner; no tier at create; soft per-owner free-org cap (FREE_ORG_OWNER_LIMIT_EXCEEDED)
GET    /orgs/v1/:org_id                                    # SIWX/session (any active member); one org { org_id, display_name, tier, role }. Authorize-before-reveal
PATCH  /orgs/v1/:org_id                                    # SIWX/session (owner) + step-up; rename org { display_name } (null/"" clears). Authorize-before-reveal
GET    /orgs/v1/:org_id/members                            # SIWX (any active member); list members { principal_id, type, role, status, wallet }
POST   /orgs/v1/:org_id/members                            # SIWX (owner); add a member { wallet, role }. New wallet → provisioned as a human; existing wallets added by their principal (type is informational)
PATCH  /orgs/v1/:org_id/members/:principal_id              # SIWX (owner); change role { role }. Last-owner guarded
DELETE /orgs/v1/:org_id/members/:principal_id              # SIWX (owner); revoke member (status=revoked, one row, no key rotation). Last-owner guarded
POST   /projects/v1/:project_id/grants                     # SIWX (owner of project's org); issue a grant { wallet, capability, policy?, expires_at? } to an agent/ci principal
DELETE /projects/v1/:project_id/grants/:grant_id           # SIWX (owner of project's org); revoke a grant
GET    /orgs/v1/:org_id/audit                              # SIWX/session (admin+); control-plane audit trail (?limit=&before=)
GET    /orgs/v1/:org_id/invites                            # SIWX/session (any member); list pending email invites
POST   /orgs/v1/:org_id/invites                            # SIWX/session (owner) + step-up; invite by email { email, role, invite_ttl_hours? } → claimed at first login. Sends a notification email (re-POST = resend, rate-limited to 1 send per org+email per 5 min); 201 carries email_sent: true|false for pending invites
DELETE /orgs/v1/:org_id/invites/:principal_id              # SIWX/session (owner) + step-up; revoke a pending invite
POST   /agent/v1/operator/claim-wallet-org/challenge      # session (no step-up — step-up is on the claim); issue a single-use nonce to claim a wallet-owned org { wallet } → { nonce }
POST   /agent/v1/operator/claim-wallet-org                # session + step-up + SIGN-IN-WITH-X wallet proof (signs the nonce); become owner of the wallet-agent's org (ownership transfer; wallet stays on agent; agent→developer). { org_id?, display_name? }. Multi-org → { status:select_org, selectable_orgs }
```

**Control-plane login + session + step-up (v1.78 — passkey-principals-onboarding).** A person logs in (passkey / email magic-link / Google / GitHub) → a principal-bound **control-plane session** bearer (distinct from tenant `internal.sessions`), WRITE-capable subject to org role + **step-up**. High-stakes ops (delete / transfer / membership / invite) require a fresh passkey (a recent magic-link does NOT satisfy a passkey requirement; recovery codes NEVER satisfy step-up). The control-plane session bearer is sent as `Authorization: Bearer <token>` and is accepted everywhere a SIWX wallet is.

```
POST   /agent/v1/control-plane/session/email              # public; send a magic link (rate-limited; generic response, no oracle)
POST   /agent/v1/control-plane/session/email/verify       # public; consume token → mint session (amr=email) { control_plane_session_token, expires_in, principal_id }
POST   /agent/v1/control-plane/session/passkey/options    # public; WebAuthn login options for an email's passkeys
POST   /agent/v1/control-plane/session/passkey/verify     # public; verify assertion → mint session (amr=passkey)
GET    /agent/v1/control-plane/session                    # control-plane session; whoami { principal, memberships, amr, amr_times }
POST   /agent/v1/control-plane/session/refresh            # control-plane session; rotate the access token
POST   /agent/v1/control-plane/session/revoke             # control-plane session; sign out
POST   /agent/v1/control-plane/passkey/enroll/options     # control-plane session + step-up; register a passkey (options)
POST   /agent/v1/control-plane/passkey/enroll/verify      # control-plane session + step-up; register a passkey (verify)
POST   /agent/v1/control-plane/step-up/options            # control-plane session; step-up WebAuthn options for a high-stakes op
POST   /agent/v1/control-plane/step-up/verify             # control-plane session; verify step-up → freshness + action-bound elevation
POST   /agent/v1/control-plane/recovery/issue             # control-plane session + step-up; (re)issue recovery codes (shown once)
POST   /agent/v1/control-plane/recovery/consume           # public; recovery ceremony → session (amr=recovery_code; must enrol a passkey before admin actions)
GET    /agent/v1/control-plane/authenticators             # control-plane session; list my active authenticators (no secrets)
DELETE /agent/v1/control-plane/authenticators/:authenticator_id         # control-plane session + step-up; revoke one (owner-passkey policy enforced)
GET    /agent/v1/control-plane/cli/authorize/:flow_id     # control-plane session; read a CLI loopback-PKCE flow (client + loopback port)
POST   /agent/v1/control-plane/cli/approve                # control-plane session + step-up (passkey); approve a CLI login → { redirect_url }
POST   /agent/v1/control-plane/cli/token                  # public; exchange { code, code_verifier, state } → session (provenance=loopback_pkce)
POST   /agent/v1/control-plane/oauth/:provider/link       # control-plane session + step-up; start OAuth in LINK mode → { auth_url } (attach the identity to the CURRENT principal)
POST   /agent/v1/control-plane/emails                     # control-plane session + step-up; request attaching an additional email (generic response, no oracle)
POST   /agent/v1/control-plane/emails/verify              # control-plane session; confirm the attach (inbox + same-session proof); 409 EMAIL_BELONGS_TO_OTHER_PRINCIPAL → merge
POST   /agent/v1/control-plane/merge                      # control-plane session + step-up (passkey); merge a duplicate principal { source_session_token, source_principal_id? }
POST   /agent/v1/control-plane/write-auth/challenges      # control-plane session; open a passkey write-intent ceremony { action, org_id|project_id } → { challenge_id, confirm_url }
POST   /agent/v1/control-plane/write-auth/verify          # public (the WebAuthn assertion IS the proof); mint → { write_auth_token } (once), OR in CLI mode → { delivery:"cli_loopback", redirect_to }
POST   /agent/v1/control-plane/write-auth/cli/token       # public; headless-CLI loopback delivery: { code, code_verifier, state } (PKCE S256) → { write_auth_token } (once)
GET    /agent/v1/control-plane/write-auth/sessions        # control-plane session; list active write-auth sessions bound to this session
POST   /agent/v1/control-plane/write-auth/sessions/:write_auth_session_id/revoke  # control-plane session; revoke one
POST   /agent/v1/control-plane/write-auth/revoke-all      # control-plane session; revoke all for the principal
```

**Passkey write-auth (human-write-auth, v1.85).** A signed-in human (email/passkey — no wallet) gains WRITE authority on provision + deploy via a **passkey signed intent**: open a challenge for ONE action on ONE target (`org.project.create` on an org, or `project.deploy` on a project), approve it on the gateway-rendered confirmation page (`confirm_url`, console origin, raw WebAuthn — the action sheet is server-rendered so page JS can't rewrite it), and receive an opaque **write-auth token**. Send it as `X-Run402-Write-Auth: Bearer <token>` ALONGSIDE the control-plane session bearer on `POST /projects/v1`, `POST /apply/v1/plans[/:plan_id/commit]`, `POST /apply/v1/operations/:operation_id/resume`, and `POST /content/v1/plans[/:plan_id/commit]`. The session is target-scoped (never platform-wide), 30 min idle / 4 h absolute, dies with the cp session, and covers **routine** slices only — destructive/membership/payment/secret-reveal surfaces always require a SIWX wallet or fresh step-up. Authorization (org membership/grant) is re-checked live on every write; the write-auth session adds the signed-intent requirement, it never replaces authz. SIWX wallet auth on these routes is unchanged. Passkeys authenticate; they never pay — paid operations keep the existing x402/Stripe rails.

**CLI write-login (loopback-PKCE, RFC 8252).** A headless CLI gets a write-capable control-plane session without a stored secret: it starts a `127.0.0.1:PORT` server, opens the browser to `GET /agent/v1/control-plane/cli/authorize?redirect_uri=&code_challenge=&state=&nonce=` (302 → the console runs the passkey ceremony + approves), receives the auth code on the loopback redirect, then exchanges it at `/cli/token` (PKCE S256 + state) for a session minted with `provenance=loopback_pkce`. A `device_flow` session is read/low-stakes only — high-stakes ops return `STEP_UP_REQUIRED` with `details.reason="device_flow_forbidden"`.

**Email-addressed transfers (folded into the unified transfer noun).** To hand a project to someone by **email**, address the unified initiate route with `to_email` instead of `to_wallet`: `POST /projects/v1/:project_id/transfers { to_email, message?, retain_collaborator?: { role: "developer" } }` (owner/admin SIWX or control-plane session + step-up). The recipient claims it via `POST /agent/v1/transfers/:transfer_id/claim` into an org they own (or a new wallet-less one); preview/cancel/inbox use the same kind-agnostic `/agent/v1/transfers/*` endpoints. Reuses the transfer engine's atomic ownership flip + authority re-home (grants + CI delegates revoked) + audit. See the Project Transfers table below. (The former standalone `/agent/v1/handoffs/*` surface was removed.)

**Retain-the-builder on handoff (v1.91, add-project-handoff-retain-collaborator).** A handoff normally severs the sender's access entirely (authority is re-homed to the new org). The sender MAY instead offer to stay on by building the project for the new owner: pass `retain_collaborator: { role: "developer" }` on init (the subject is always the initiating owner — you can only offer to keep *yourself* on; `developer` is the only accepted role, capped so a sender can never retain owner/admin of the recipient's org). The recipient sees a `retain_collaborator` block in the preview (who, the role, and that the access spans the WHOLE org) and must **explicitly** pass `accept_retained_collaborator: true` at claim — opt-in; omitting it severs exactly as before. On acceptance the sender's principal becomes a plain `developer` member of the new org (created in the claim transaction, after the authority wipe), with no expiry; the new owner can remove them anytime via the member-revoke route. Tradeoff: a membership is org-wide, so if the new owner later adds other projects to that same org the retained developer can reach them too (until removed) — surfaced in the preview block.

**Delegates (v1.78 — the credential an agent actually holds).** A *delegate* is a scoped, capped, expiring, revocable credential an owner mints for an agent/ci principal so the thing the agent holds equals the authority its grant was given. A delegate only ever NARROWS a grant (authz = grant ∩ scope ∩ cap ∩ expiry), is NEVER an owner (cannot delete/transfer/manage members), fails closed if the project is transferred to another org, and is killed instantly by one revoke. Per-rail kinds: `run402_agent_key` (control-plane bearer, returned once), `ci_oidc` (the GitHub-OIDC CI federation), `tempo_access_key` + `base_disposable_eoa` (payment rails, spend-cap enforced). Owner-gated, audited.

```
POST   /projects/v1/:project_id/delegates                    # SIWX (owner of project's org); issue { grant_id, kind, scope:{v:1,capabilities[],projects?}, spend_cap?, expires_at? }. run402_agent_key → token returned ONCE
GET    /projects/v1/:project_id/delegates                    # SIWX (owner of project's org); list delegates (names/scope/cap only — never secret material)
DELETE /projects/v1/:project_id/delegates/:delegate_id       # SIWX (owner of project's org); revoke (immediate; base rail stops refills + sweeps)
POST   /projects/v1/:project_id/delegates/:delegate_id/rotate # SIWX (owner of project's org); rotate (revoke + reissue same scope/cap; fresh token for run402_agent_key)
```

```
GET    /projects/v1/admin/:project_id/usage    # service_key; usage vs limits
GET    /projects/v1/admin/:project_id/schema   # service_key; tables, columns, RLS policies
POST   /projects/v1/admin/:project_id/sql      # service_key + lifecycleGate; run SQL (DDL + queries). Returns { rows, row_count }
POST   /projects/v1/expose/validate    # SIWX; validate manifest without live project schema
POST   /projects/v1/admin/:project_id/expose/validate # service_key; validate manifest against project schema + optional migration SQL
POST   /projects/v1/admin/:project_id/expose   # service_key + lifecycleGate; apply RLS manifest (see "Expose manifest")
GET    /projects/v1/admin/:project_id/expose   # service_key; current manifest, with source: "applied" | "introspected"
POST   /projects/v1/admin/:project_id/promote-user   # service_key + lifecycleGate; { email } -> grants project_admin
POST   /projects/v1/admin/:project_id/demote-user    # service_key + lifecycleGate
```

### Lifecycle (~104-day soft-delete grace)

After lease expires, a project moves through `active → past_due → frozen → dormant → purged`:

| State | Day | Control plane | Data plane | Scheduled fns | Subdomain |
|-------|-----|---------------|------------|---------------|-----------|
| `active` | — | read+write | read+write | running | claimed |
| `past_due` | 0 | read+write | read+write | running | claimed |
| `frozen` | +14 | **403** | read+write | running | reserved |
| `dormant` | +44 | **403** | read+write | **paused** | reserved |
| `purged` | +104 | terminal | terminal | terminal | claimable +14d |

The data plane keeps serving end users throughout grace. Only owner control-plane writes (deploys, SQL execution, expose apply, secret rotation, mailbox and KMS signer mutations, subdomain/domain claims, function upload, and auth/admin writes) are gated. Read endpoints remain available where they do not mutate project state. Tier renewal at any point reactivates the project and clears all timers in one transaction.

Lifecycle gating returns **HTTP 403** with `code: PROJECT_PAST_DUE` / `PROJECT_FROZEN` / `PROJECT_DORMANT` and `details: { lifecycle_state, entered_state_at, next_transition_at }`. (HTTP 402 is reserved for x402 payment challenges from the `@x402/express` middleware — overloading 402 caused `@x402/fetch` to mis-parse Run402 envelopes as x402 challenges.)

## Provisioning (typed example)

```typescript
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { toClientEvmSigner } from "@x402/evm";
import { createSIWxPayload, encodeSIWxHeader } from "@x402/extensions/sign-in-with-x";
import { privateKeyToAccount } from "viem/accounts";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";
import { randomBytes } from "node:crypto";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
const signer = toClientEvmSigner(account, publicClient);

const x402 = new x402Client();
x402.register("eip155:84532", new ExactEvmScheme(signer));   // testnet — register the SPECIFIC chain, not eip155:*
const fetchPaid = wrapFetchWithPayment(fetch, x402);

// 1) Subscribe to prototype tier
await fetchPaid("https://api.run402.com/tiers/v1/prototype", { method: "POST" });

// 2) Provision a project (SIWX-authenticated)
const siwxPayload = await createSIWxPayload({
  domain: "api.run402.com",
  uri: "https://api.run402.com/projects/v1",
  statement: "Sign in to Run402",
  version: "1",
  nonce: randomBytes(16).toString("hex"),
  issuedAt: new Date().toISOString(),
  expirationTime: new Date(Date.now() + 5 * 60_000).toISOString(),
  chainId: "eip155:84532",
  type: "eip191",
}, account);

const res = await fetch("https://api.run402.com/projects/v1", {
  method: "POST",
  headers: { "Content-Type": "application/json", "SIGN-IN-WITH-X": encodeSIWxHeader(siwxPayload) },
  body: JSON.stringify({ name: "my-app" }),
});
const { project_id, anon_key, service_key } = await res.json();
```

`anon_key` and `service_key` are permanent project identifiers; lease enforcement is server-side. **Don't embed `service_key` in browser code** — CORS is intentionally open (`*`), so a leaked service_key is exploitable from any origin.

## REST API (PostgREST proxy)

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/rest/v1/:table` | GET | apikey | Read rows |
| `/rest/v1/:table` | POST | apikey | Insert rows (single object or array for bulk) |
| `/rest/v1/:table` | PATCH | apikey | Update rows (chain with `?col=eq.val`) |
| `/rest/v1/:table` | DELETE | apikey | Delete rows |

PostgREST query syntax: `?select=`, `?col=eq.value`, `?col=gt.5`, `?order=col.desc`, `?limit=N`, `?offset=N`. `Prefer: return=representation` returns the inserted/updated row.

`apikey` is auto-forwarded as `Authorization: Bearer` to PostgREST. Pick:
- `apikey: <anon_key>` → role `anon` (RLS applies)
- `apikey: <service_key>` → role `service_role` (bypasses RLS, server-side only)
- `apikey: <anon_key>` + `Authorization: Bearer <access_token>` → role `authenticated` (RLS scoped to user)

## Expose manifest — dark-by-default tables

**Tables you create are unreachable via `/rest/v1/*` until your manifest declares them with `expose: true`.** This eliminates the "agent created a table, forgot RLS, data leaked" footgun. The manifest is the single source of truth; convergent (applying the same manifest twice is a no-op; items removed between applies have their policies, grants, triggers, and views dropped).

JSON Schema: <https://run402.com/schemas/manifest.v1.json>.

Validate before applying:

- `POST /projects/v1/expose/validate` uses SIWX wallet auth (active tier not required) and validates against an empty project schema plus optional `migration_sql`.
- `POST /projects/v1/admin/:project_id/expose/validate` uses the project `service_key` and validates against the current project schema plus optional `migration_sql`.

Both validation endpoints are non-mutating: they do not apply the manifest, execute SQL, write deploy plans, upload content, commit releases, update `internal.project_manifest`, or reload PostgREST. Body:

```json
{
  "manifest": { "version": "1", "tables": [], "views": [], "rpcs": [] },
  "migration_sql": "optional CREATE TABLE/VIEW/FUNCTION or ALTER TABLE ADD COLUMN SQL, parsed only"
}
```

They return `200 OK` when validation runs, even when `has_errors: true`:

```json
{
  "has_errors": false,
  "errors": [],
  "warnings": []
}
```

Issues use `{ "type", "severity", "detail", "fix?" }`. Manifest shape failures are returned as `schema-shape` errors in the same envelope. Statements in `migration_sql` that look like DDL but are not understood by the lightweight parser produce `validation-inconclusive` warnings; SQL is never executed.

```bash
curl -X POST https://api.run402.com/projects/v1/admin/$PROJECT_ID/expose \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "$schema": "https://run402.com/schemas/manifest.v1.json",
    "version": "1",
    "tables": [
      { "name": "items", "expose": true, "policy": "user_owns_rows",
        "owner_column": "user_id", "force_owner_on_insert": true },
      { "name": "audit", "expose": false }
    ],
    "views": [
      { "name": "leaderboard", "base": "items", "select": ["user_id", "score"], "expose": true }
    ],
    "rpcs": [
      { "name": "compute_streak", "signature": "(user_id uuid)", "grant_to": ["authenticated"] }
    ]
  }'
```

Built-in policies:

| Policy | Allows |
|---|---|
| `user_owns_rows` | Rows where `owner_column = auth.uid()`. With `force_owner_on_insert: true`, a BEFORE INSERT trigger sets it automatically. **Default for user-scoped data.** |
| `public_read_authenticated_write` | Anyone reads. Any authenticated user writes any row. |
| `public_read_write_UNRESTRICTED` | Fully open. Requires `i_understand_this_is_unrestricted: true`. |
| `custom` | Provide `custom_sql` with `CREATE POLICY` statements. |

Views run with `security_invoker=true` — they inherit the underlying table's RLS. RPCs need explicit listing in `rpcs[]` (a database event trigger revokes PUBLIC EXECUTE on every newly-created function; views and RPCs not in the manifest are unreachable).

`GET /projects/v1/admin/:project_id/expose` returns the live state with `source: "applied"` (came from a prior apply) or `"introspected"` (no manifest applied; reconstructed from DB state).

**Preferred path: ship the manifest as `database.expose` in your `ApplySpec`.** The gateway validates it against the migration SQL atomically with the rest of the apply — see "Unified apply" below.

## SQL guardrails

`POST /projects/v1/admin/:project_id/sql` blocks: `CREATE EXTENSION`, `COPY ... PROGRAM`, `ALTER SYSTEM`, `SET search_path`, `CREATE/DROP SCHEMA`, `GRANT/REVOKE`, `CREATE/DROP ROLE`. Use the manifest for access control instead of `GRANT`.

Each project lives in its own Postgres schema. Cross-schema access is blocked. The PostgREST `db-pre-request` hook validates JWT claims match the project. Schema names use the form `pNNNN`.

### Idempotent migrations

`CREATE TABLE IF NOT EXISTS` only handles "already exists" — it won't add new columns. For evolving schemas, wrap `ALTER TABLE` in a `DO` block:

```sql
CREATE TABLE IF NOT EXISTS items (id serial PRIMARY KEY, title text NOT NULL);
DO $$ BEGIN
  ALTER TABLE items ADD COLUMN priority int DEFAULT 0;
EXCEPTION WHEN duplicate_column THEN NULL;
END $$;
```

Safe to re-run on every deploy.

## Unified apply — `/apply/v1`

The canonical write primitive (v1.48+). One `ApplySpec` lands the entire app — migrations + RLS manifest + secrets + functions + site files + CDN assets + web routes + subdomains — atomically. The spec type is `ApplySpec` (which extends `ReleaseSpec` with an optional `assets` slice). Bytes flow through content-addressed storage (CAS) so unchanged files dedupe across writes.

### State machine

```
plan        POST /apply/v1/plans
upload      PUT presigned S3 URLs (per missing content sha; bytes never go through the gateway body)
commit      POST /apply/v1/plans/:plan_id/commit
  → validate         (spec well-formed; references resolve; CAS bytes present for every SHA)
  → stage            (function versions, site deployment, secret set, subdomain reservation)
  → migrate-gate     (only if migrations present; /rest/v1/* returns 503 + Retry-After for ~60s)
  → migrate          (advisory-locked transaction; new id = run, same id+checksum = noop, mismatch = hard error)
  → schema-settle    (canary SELECT until PostgREST reloads; up to 12×500ms)
  → activate         (single transaction: flip release pointers, clear gate)
  → ready
poll        GET  /apply/v1/operations/:operation_id              (until status terminal: ready | failed | rolled_back)
events      GET  /apply/v1/operations/:operation_id/events        (phase event stream, polling target)
list        GET  /apply/v1/operations                   (pageable operations, newest first)
resume      POST /apply/v1/operations/:operation_id/resume        (if schema_settling or activation_pending)
```

### Routes

| Path | Method | Auth | Cost | Description |
|------|--------|------|------|-------------|
| `/apply/v1/plans` | POST | SIWX + lifecycleGate | Free with tier | Plan a release. Returns the v2 plan envelope: `kind: "plan_response"`, nullable `plan_id`/`operation_id`, gateway-computed `manifest_digest`, `missing_content[]`, top-level resource diff buckets, `summary`, `warnings[]`, `expected_events[]`, optional `payment_required`. Plan body limit 5 MB; bytes always go direct-to-S3. Naturally idempotent on `(project_id, manifest_digest)`. Add `?dry_run=true` to compute the same envelope without creating plan/operation rows; dry-run requires an inline spec and rejects `manifest_ref`. |
| `/apply/v1/plans/:plan_id/commit` | POST | SIWX + lifecycleGate | Free with tier | Drive the state machine. Idempotency-Key honored. Returns `{ operation_id, release_id, status, urls?, error? }`. |
| `/apply/v1/operations` | GET | apikey | Free | Operations for the project, newest first. Query: `limit` (default 50, max 100), `before` (operation id cursor), `status` (single or comma-separated), `since` (ISO timestamp), `project_id` (must match authenticated project), `include_total=true` (opt-in exact count). Response includes `operations`, `has_more`, `next_cursor`, and `total` only when requested. |
| `/apply/v1/operations/:operation_id` | GET | apikey | Free | Snapshot the operation: `status`, `payment_required`, structured `error`, `activate_attempts`, `target_release_id`. |
| `/apply/v1/operations/:operation_id/events` | GET | apikey | Free | Phase event stream. Polling target until terminal. |
| `/apply/v1/operations/:operation_id/resume` | POST | SIWX | Free | Re-run the failed phase forward when in `activation_pending` or `schema_settling`. **NOT lifecycle-gated** — completes already-authorized work. Migrations are NEVER replayed. |
| `/apply/v1/releases/:release_id/promote` | POST | SIWX or CI session (`deploy`) + lifecycleGate | Free | Pointer-swap recovery: point `live_release_id` at a prior release without re-running the apply pipeline. Body `{ project_id, allow_warning_codes? }`. Refuses non-`ready` releases and no-op self-promotes. Emits structured warnings (`MIGRATIONS_NOT_REVERSIBLE`, `FUNCTION_VERSION_MISMATCH`, `ASSET_GC`) that the caller can opt into via `allow_warning_codes`. Flushes `ssr_cache` for the project's bound hosts. Logs to operation history as `operation_kind: "promote"`. |
| `/apply/v1/releases/:release_id` | GET | apikey | Free | Get the activation-time materialized state of a specific release. Response: `kind: "release_inventory"`, `state_kind: "effective"` (active/superseded) or `"desired_manifest"` (failed/staged). Capability `agent-deploy-observability`. |
| `/apply/v1/releases/active` | GET | apikey | Free | Get the active release's CURRENT LIVE state — reads live tables. A `setSecret` call between activation and now appears here. Response's `state_kind: "current_live"`. Distinct from `/releases/:release_id` which is the activation-time snapshot. 404 `NO_ACTIVE_RELEASE` if no active release. |
| `/apply/v1/releases/diff` | GET | apikey | Free | Diff two releases. Query params: `from=<release_id\|empty\|active>&to=<release_id\|active>`. Cross-project → 404 `RESOURCE_NOT_FOUND`. `from === to` → 400 `DIFF_SAME_RELEASE`. `to=empty` → 400 `INVALID_DIFF_TARGET`. Migrations are MONOTONIC (`applied_between_releases: string[]`), distinct from the plan response's `{new, noop}` shape. |
| `/apply/v1/resolve` | GET | apikey | Free | Diagnose stable host/path resolution for a project-owned host. Query params: `host=<hostname>`, optional `path` (default `/`) and `method` (default `GET`). Returns binding status, active release id/generation, route/static manifest SHAs, static manifest metadata, normalized path, match kind, static SHA, cache class/policy, authorization result, fallback state, and legacy immutable-risk diagnostics. |

### Plan response and dry-run

`POST /apply/v1/plans` now returns the agent-deploy-observability plan envelope:

```json
{
  "kind": "plan_response",
  "schema_version": "agent-deploy-observability.v1",
  "plan_id": "plan_...",
  "operation_id": "op_...",
  "base_release_id": "rel_...",
  "manifest_digest": "<sha256>",
  "is_noop": false,
  "summary": "Adds one site path",
  "warnings": [],
  "expected_events": ["stage.start", "activate.start", "ready"],
  "missing_content": [{ "sha256": "<sha256>", "size": 123, "present": false }],
  "migrations": { "new": [], "noop": [] },
  "site": { "added": [], "removed": [], "changed": [] },
  "functions": { "added": [], "removed": [], "changed": [] },
  "secrets": { "added": [], "removed": [] },
  "subdomains": { "added": [], "removed": [] },
  "routes": { "added": [], "removed": [], "changed": [] },
  "static_assets": {
    "unchanged": 0,
    "changed": 0,
    "added": 1,
    "removed": 0,
    "newly_uploaded_cas_bytes": 123,
    "reused_cas_bytes": 0,
    "deployment_copy_bytes_eliminated": 0,
    "legacy_immutable_warnings": [],
    "previous_immutable_failures": [],
    "cas_authorization_failures": []
  }
}
```

With `POST /apply/v1/plans?dry_run=true`, the gateway validates, resolves the base, checks missing content, computes the same diff/warnings/events envelope, and returns `plan_id: null` and `operation_id: null`. No `internal.apply_plans`, `internal.apply_operations`, or idempotency-key rows are written. Dry-run requires the full spec inline; `manifest_ref` returns HTTP 400 `DRY_RUN_REQUIRES_INLINE_SPEC`.

Static site releases now materialize a canonical `run402.static_manifest.v1` alongside the route manifest. The `static_assets` diff summarizes how many static paths are unchanged/changed/added/removed, how many CAS bytes are newly required vs reused, legacy immutable-cache risks, previous immutable same-path hard failures, and any CAS authorization failures. Activation verifies the static manifest and every referenced CAS object before flipping the active release pointer.

### Static public paths

By default, apply-v1 uses implicit public paths for backwards compatibility: a release static asset such as `events.html` is directly reachable as `/events.html`, `index.html` is reachable as `/`, and `docs/index.html` is reachable as `/docs/`.

Use `site.public_paths` when the public URL table should be separate from private release asset filenames:

```json
{
  "site": {
    "replace": {
      "events.html": { "sha256": "<hex>", "size": 4096, "content_type": "text/html" }
    },
    "public_paths": {
      "mode": "explicit",
      "replace": {
        "/events": { "asset": "events.html", "cache_class": "html" }
      }
    }
  }
}
```

In explicit mode, only paths in `public_paths.replace` are direct static URLs. The asset filename above is not directly reachable as `/events.html`. Explicit mode is sticky: later `site.patch` changes that omit `site.public_paths` inherit the existing explicit public table, so newly added assets do not become public by filename. To change public paths in v1, send a complete `public_paths.replace` table. To intentionally restore filename-derived reachability, send `site.public_paths: { "mode": "implicit" }`; plan warnings flag this because public reachability may widen.

Public path keys must be absolute paths such as `/events` with no query string, fragment, raw or encoded slash/backslash separator tricks, dot segments, control characters, duplicate canonical paths, or internal Run402 namespaces such as `/_cas/*` and `/_run402/*`. Entries currently accept only `{ "asset", "cache_class" }`; arbitrary response headers are rejected in v1. Each `asset` must be a relative release static asset path in the final materialized release.

Release inventory includes `static_public_paths[]` with `public_path`, `asset_path`, `reachability_authority` (`implicit_file_path`, `explicit_public_path`, or `route_static_alias`), `direct`, `cache_class`, and route-only `methods` when applicable. Authenticated `GET /apply/v1/resolve` diagnostics include the matched `asset_path`, `reachability_authority`, and `direct` flag.

### Secrets are out-of-band, not in the spec

As of capability `secrets-isolation` (2026-05-03), `secrets.set` and `secrets.replace_all` are no longer accepted by `/apply/v1/plans` (HTTP 400 `INVALID_SPEC`). Set values via `POST /projects/v1/admin/{id}/secrets` with body `{ "key": "KEY1", "value": "..." }` BEFORE the deploy, then declare them on the deploy with `secrets.require: ["KEY1","KEY2"]`. The plan response includes a `MISSING_REQUIRED_SECRET` warning for keys that don't exist yet (HTTP 201 — non-blocking). The commit hard-errors with HTTP 422 if a required key is deleted between plan and commit. `secrets.delete[]` removes keys atomically with the activate phase. **Hard limit: 4 KiB per secret value (UTF-8 byte length)**; larger values reject with HTTP 413 `SECRET_VALUE_TOO_LARGE`. **Secret keys must match `^[A-Z_][A-Z0-9_]{0,127}$`.** Caveat: secret values are still passed to AWS Lambda as environment variables, so they are visible in CloudWatch Logs Insights queries against the function's log group. Treat the Lambda environment as the residual exposure surface; the platform does not encrypt them inside Lambda's environment block.

### Plan-time warning envelope (`WarningEntry`)

Every `/apply/v1/plans` response carries a `warnings: WarningEntry[]` field (always present; empty array when no warnings). The shape:

```json
{
  "code": "MISSING_REQUIRED_SECRET",
  "severity": "high",
  "requires_confirmation": true,
  "message": "Required secret keys are not yet set: OPENAI_API_KEY",
  "affected": ["OPENAI_API_KEY"],
  "details": { "missing_keys": ["OPENAI_API_KEY"] }
}
```

Agents that want a "set then deploy" UX should detect `code: "MISSING_REQUIRED_SECRET"` in `warnings[]` and prompt the user (or auto-call setSecret) before committing. The plan stays valid for 24h; the warning is recomputed on every plan-cache hit so a key set after the initial plan is reflected on the next read.

### Release reads (capability `agent-deploy-observability`)

Three GET endpoints expose materialized release state for agents that need to answer "what is currently deployed?" or "what changed between two releases?":

- `GET /apply/v1/releases/<release_id>` returns the **activation-time snapshot** — the materialized state captured when the release was activated. Persists across `setSecret` / function-config / subdomain mutations. `state_kind: "effective"` for active/superseded releases (snapshot read); `state_kind: "desired_manifest"` for failed/staged releases (manifest replay).

- `GET /apply/v1/releases/active` returns the **CURRENT LIVE state** of the project — reads live tables. A `setSecret` call between activation and now WILL appear in this response. `state_kind: "current_live"`. Returns 404 `NO_ACTIVE_RELEASE` if the project has no active release. Use this when the agent needs to know what the deployed app sees RIGHT NOW.

- `GET /apply/v1/releases/diff?from=<release_id|empty|active>&to=<release_id|active>` returns the same diff envelope shape as the plan response, with `kind: "release_diff"`. Migrations are monotonic (`applied_between_releases: string[]`), distinct from the plan response's `{new, noop}` shape.

All three endpoints are always available and always return JSON envelopes for errors — never HTML 404 (that was the bug #106/#107 closed).

### Stable host/path diagnostics

`GET /apply/v1/resolve?host=<hostname>&path=/assets/app.js&method=GET` is an authenticated read for agent diagnostics. The `apikey` must belong to the project bound to the host. Run402 subdomains and active custom domains resolve to the current live release; deployment-specific preview hosts stay on the deployment-id path and are not rewritten through this stable-host resolver.

Successful responses include:

```json
{
  "hostname": "example.com",
  "host_binding_id": "custom:example.com",
  "binding_status": "active",
  "project_id": "prj_1741340000_0042",
  "channel": "production",
  "release_id": "rel_...",
  "release_generation": 12,
  "route_manifest_sha256": "<sha256-or-null>",
  "static_manifest_sha256": "<sha256-or-null>",
  "static_manifest_metadata": {
    "file_count": 4,
    "total_bytes": 12345,
    "cache_classes": { "html": 1, "immutable_versioned": 2, "revalidating_asset": 1 },
    "cache_class_sources": { "inferred": 4 },
    "spa_fallback": "/index.html"
  },
  "normalized_path": "/assets/app.abc123.js",
  "match": "static_exact",
  "static_sha256": "<sha256>",
  "asset_path": "assets/app.abc123.js",
  "reachability_authority": "implicit_file_path",
  "direct": true,
  "content_type": "application/javascript",
  "cache_class": "immutable_versioned",
  "cache_policy": "public, max-age=31536000, immutable",
  "authorized": true,
  "authorization_result": "authorized",
  "cas_object": {
    "sha256": "<sha256>",
    "exists": true,
    "expected_size": 1234,
    "actual_size": 1234
  },
  "fallback_state": "not_used",
  "legacy_immutable_risk": [],
  "emergency_fallback": { "enabled": false },
  "result": 200
}
```

For matched static objects, `authorization_result` is `authorized`, `missing_cas_object`, `unauthorized_cas_object`, `size_mismatch`, or `unfinalized_or_deleting_cas_object`; static manifest compatibility failures use `match`, `authorization_result`, and `fallback_state` value `unsupported_manifest_version`; cached stable-host misses can report `fallback_state: "negative_cache_hit"`. Bad CAS states report `result: 503` without leaking internal CAS URLs. HTML static hits also include `response_variant` diagnostics with `varies_by: ["hostname"]` and a `variant_inputs_hash`, because transformed HTML cache identity can differ by canonical hostname even when the raw static SHA is shared.

Misses are diagnostic, not redirects: absent paths return `match: "none"`/`result: 404`; missing manifests or missing fallback targets return `result: 503`; invalid canonical paths return `match: "path_error"` with `error_code`. The response never exposes internal CAS URLs.

### Content negotiation (`/content/v1/*`)

Bytes always travel through CAS. The plan response lists missing SHAs; you negotiate uploads via:

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/content/v1/plans` | POST | apikey | Tell the gateway which SHAs you have, get presigned PUT URLs (single or multipart) for the missing ones. |
| `/content/v1/plans/:plan_id/commit` | POST | apikey | Finalize: complete multipart uploads, promote staged objects to CAS. |

PUT each `parts[].url` directly; for multipart, capture each `ETag` and pass them in the `commit` body as `parts: [{ part_number, etag }]`.

### SSR ISR cache (`/cache/v1/*`) — capability `ssr-isr-cache` (v1.52)

Paired with `@run402/astro` v1.0+ (the Astro SSR preset). The gateway holds an origin-side ISR cache backed by CAS — every cacheable SSR response is stored as `_cas/<sha[0:2]>/<rest>` keyed by canonical `{host}:{release_id}:{locale}:{method}:{pathname}{?normalizedSearch}`. Cache writes are generation-guarded; concurrent MISS renders for the same key on one task share a single Lambda invocation (in-process single-flight dedup).

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/cache/v1/invalidate` | POST | Bearer service_key | Invalidate cache rows. Body discriminates on `kind`: `"exact"` (`{ host, path }`), `"prefix"` (`{ host, prefix }`), `"all"` (`{ host }`), or `"many"` (`{ urls: [...] }`). Host MUST be owned by caller's project; cross-project returns 403 `R402_CACHE_INVALIDATION_HOST_FORBIDDEN`. DELETE + per-(project, host) generation increment happen atomically. |
| `/cache/v1/inspect` | GET | Bearer service_key | Inspect cache row state for a canonical key. Query params: `host`, `path`, `locale?` (default project default), `release_id?` (default project active). Returns `{ status: "HIT" \| "MISS", host?, path?, locale?, releaseId?, cachedAt?, expiresAt?, writtenUnderGeneration?, contentSha256?, headers? }`. Status is NEVER `BYPASS` — inspect does not issue a request. |

**Cacheability rules** (response is stored ONLY when ALL apply):
- Method is GET or HEAD
- Status is in default cacheable set: `200, 301, 302, 410`
- Response has `Cache-Control: public, s-maxage=N` with `N > 0`
- No `Set-Cookie` header
- No `Cache-Control: private` or `no-store`
- No `Vary` (except `Accept-Language`, which is in the cache key as `locale`)
- Body ≤ 1 MiB
- No `auth.*` helper called during render (taint check via SSR Lambda metadata envelope; any `auth.user()` / `auth.requireUser()` / payment primitives flip `cacheBypassTainted` and disqualify the response from ISR storage)

**Read-time bypass** (lookup skipped entirely): method ≠ GET/HEAD, ANY `Cookie` header, ANY `Authorization` header. Bypass reason emitted as `x-run402-cache-reason: { method | cookie | auth }`.

**Debug headers** on every SSR response (gateway-generated, overrides user-set values of the same name): `x-run402-request-id`, `x-run402-release-id`, `x-run402-function`, `x-run402-cache` (`HIT` / `MISS` / `BYPASS`), `x-run402-cache-reason` (on `BYPASS` only — one of `no_s_maxage | private | auth | cookie | set_cookie | unsupported_vary | method | too_large | non_cacheable_status`), `x-run402-cache-age` (on `HIT` only, in seconds), `x-run402-locale`. On uncaught function error: adds `x-run402-error-code: R402_SSR_RUNTIME_ERROR`.

**Cleanup** runs on the hourly scheduler tick: expired rows past 1h grace, stale-release rows (`release_id != project.live_release_id`) past 24h grace. Underlying CAS objects reaped on the normal hourly CAS GC tick once the last `ssr_cache` ref drops.

### `spec.i18n` — routed locale context

```json
"i18n": {
  "defaultLocale": "en",
  "locales": ["en", "es", "fr", "pt-BR"],
  "detect": ["cookie:r402_locale", "accept-language"]
}
```

Top-level slice on `ReleaseSpec`, NOT under a `spec` wrapper — `i18n` sits alongside `database`, `functions`, `site`, `assets`, etc. inside the JSON manifest you POST to `/apply/v1/plans`. The "spec" prefix in prose is the TypeScript type name (`ReleaseSpec.i18n`), not a JSON path.

**Cookie naming convention.** The platform-canonical cookie name is **`r402_locale`** — use it unless you have a reason not to. Server-side negotiation only sees cookies + headers (never `localStorage`), so apps with a language switcher MUST write the cookie alongside whatever client-side persistence they do:

```js
document.cookie = `r402_locale=${lang}; path=/; max-age=31536000; samesite=lax`;
```

If your app already ships with a different name (e.g., `wl_locale` from a Next.js/wrangler import) you can keep it — just pass `"cookie:wl_locale"` in `detect[]`. The matching is exact, so a typo (`cookie:r402-locale` vs `cookie:r402_locale`) is a silent miss.

**Canonical casing — validated at deploy time (landed).** Locales must be in their RFC 5646 §2.1.1 canonical form: primary language subtag lowercase, 4-alpha script subtag Titlecase, 2-alpha region subtag UPPERCASE, 3-digit region subtag preserved, variant + extension + private-use subtags lowercase. So `pt-BR` not `pt-br`, `zh-Hant` not `zh-hant`, `es-419` not `ES-419`. Both `locales[]` entries AND `defaultLocale` are validated. The platform rejects non-canonical entries at `/apply/v1/plans` with `R402_LOCALE_NOT_CANONICAL` carrying both `input` and `canonical` (the suggested fix) in the envelope's `fix:` field, plus a human-readable "Did you mean ..." message. The reason for reject-rather-than-canonicalize: your translation table (e.g. `section_translations.language`) needs to match byte-for-byte, and canonicalizing-on-input would create a silent split between the spec and your DB column. Better to reject at deploy than to surface as a runtime 404. Pick canonical, use it consistently. Underscore separators (`pt_BR`, common when copied from Java/Linux locale strings) are also rejected — RFC 5646 §2.1 specifies `-` as the subtag separator.

**Negotiation runtime.** Walks `detect[]` in order; first hit wins. Accept-Language gets RFC 4647 §3.4 longest-prefix lookup (`zh-Hant-TW` → `zh-Hant` → `zh`) with a stable q-tie sort. Cookie matching is case-insensitive on the cookie value, case-sensitive on the cookie name. The negotiated value is byte-identical to a `locales[]` entry by construction. Surfaces in user code as:
- `Astro.locals.run402.locale` (in `@run402/astro` pages / middleware)
- `getRun402Context(request).locale` (in plain Node22 functions via `@run402/functions`)
- `x-run402-locale` + `x-run402-default-locale` request headers (raw access)
- `event.context.locale` + `.defaultLocale` (raw routed-envelope consumers)

When the active release has no `i18n` slice, all of the above are `null` (not "default-locale"). Apps that need to render *something* should `?? 'en'` (or whatever fallback they prefer) at the read site.

### `ApplySpec` shape

`ApplySpec` extends `ReleaseSpec` with an optional `assets` slice for CDN-served key/value content. Release-scoped slices are `database`, `secrets`, `functions`, `site`, `subdomains`, `routes`, `checks`. A spec with only release-scoped slices and no `assets` is a valid `ApplySpec` — release-only intent is structurally inferred, not a separate method.

```jsonc
{
  "project_id": "prj_1741340000_0042",
  "base": { "release": "current" },             // or { "release": "empty" } for a clean slate

  "database": {
    "migrations": [
      {
        "id": "001_init",
        "checksum": "<sha256-hex of the SQL bytes>",
        "sql": "CREATE TABLE IF NOT EXISTS items (id serial PRIMARY KEY, title text NOT NULL);"
      }
    ],
    "expose": {
      "version": "1",
      "tables": [
        { "name": "items", "expose": true, "policy": "user_owns_rows",
          "owner_column": "user_id", "force_owner_on_insert": true }
      ]
    }
  },

  "secrets": {
    "require": ["OPENAI_API_KEY"],
    "delete": ["OLD_KEY"]
  },

  "functions": {
    "replace": {
      "summarize": {
        "runtime": "node22",
        "source": { "sha256": "<hex>", "size": 1234, "content_type": "application/javascript" },
        "config": { "timeout_seconds": 10, "memory_mb": 256 },
        "schedule": null
      }
    },
    "patch": { "delete": ["legacy-func"] }
  },

  "routes": {
    "replace": [
      {
        "pattern": "/api/*",
        "methods": ["GET", "POST"],
        "target": { "type": "function", "name": "api" }
      }
    ]
  },

  "site": {
    "replace": {
      "index.html": { "sha256": "<hex>", "size": 512, "content_type": "text/html" }
    },
    "public_paths": {
      "mode": "explicit",
      "replace": {
        "/": { "asset": "index.html", "cache_class": "html" }
      }
    }
  },

  "subdomains": { "set": ["my-app"] }
}
```

**Replace vs patch per resource.** `site.replace` = "this is the whole site" (paths absent are removed). `site.patch.put` / `patch.delete` = surgical updates. Same replace/patch shape applies to `functions`; `routes.replace` replaces the route table; `routes: null` or omitted carries routes forward; `routes.replace: []` clears the route table. `secrets` is intentionally value-free (`require[]` / `delete[]` only), and `subdomains` has its own set/add/remove/delete shape. Top-level absence = leave untouched. Migrations are append-only (a new `id` runs once; same `id`+`checksum` is a noop; a different checksum is `MIGRATION_CHECKSUM_MISMATCH`).

### Web Routes

`ApplySpec.routes` maps same-origin browser paths on deployed sites to serverless functions or exact static URL aliases. Route targets are public browser ingress and do not require a Run402 API key at the public edge; direct `/functions/v1/:name` remains API-key protected.

Author routes as a replace-mode array, not as a path-keyed map:

```json
{
  "functions": {
    "replace": {
      "admin": { "runtime": "node22", "source": { "sha256": "<hex>", "size": 2048 } },
      "api": { "runtime": "node22", "source": { "sha256": "<hex>", "size": 2048 } }
    }
  },
  "site": {
    "replace": {
      "events.html": { "sha256": "<hex>", "size": 4096, "content_type": "text/html" }
    }
  },
  "routes": {
    "replace": [
      { "pattern": "/admin", "methods": ["GET"], "target": { "type": "function", "name": "admin" } },
      { "pattern": "/admin/*", "target": { "type": "function", "name": "admin" } },
      { "pattern": "/api/*", "methods": ["GET", "POST", "OPTIONS"], "target": { "type": "function", "name": "api" } },
      { "pattern": "/events", "methods": ["GET"], "target": { "type": "static", "file": "events.html" } }
    ]
  }
}
```

`routes: null` or omitted carries the base release routes forward. `routes.replace: []` clears the route table. Each target function must exist in the same materialized release. Each static target file must exist in the final materialized static site after applying `site.replace` or `site.patch`, including when a carried-forward route table is preserved across a site deletion.

Supported route patterns:

- Exact absolute paths: `/admin`, `/login`, `/og.png`.
- Final prefix wildcards only for function targets: `/api/*`, `/admin/*`.
- No query strings, no regex, no mid-pattern wildcards, max 100 routes, max 256 bytes per pattern.

Function target shape:

```json
{ "type": "function", "name": "api" }
```

Function route `methods` may be omitted for all supported methods, or set to any non-empty subset of `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, and `OPTIONS`. `GET` routes also match `HEAD`.

Static alias target shape:

```json
{ "type": "static", "file": "events.html" }
```

Static aliases are exact-only. Prefix patterns such as `/docs/*` are rejected for static targets. Static alias `methods` are required and must be `["GET"]` or `["GET", "HEAD"]`; both materialize to effective `GET` + `HEAD`. `target.file` is a materialized static-site file path, relative to the site root: no leading slash, query, fragment, backslash, trailing slash/directory shorthand, empty segment, `.` segment, or `..` segment.

The same normalized path may appear more than once only when effective methods are disjoint. For example, `/login` can serve a static alias for `GET`/`HEAD` and a function for `POST`; overlapping effective methods are rejected.

Matching is deterministic and identical on managed subdomains, deployment hosts, and verified custom domains. Exact routes beat prefix routes; among prefixes, the longest prefix wins. Exact `/admin` matches both `/admin` and `/admin/`. `/admin/*` matches `/admin/settings` but not `/admin`, `/admin/`, `/admin.css`, or `/administrator`. Query strings do not affect selection and are forwarded unchanged for functions. `GET` routes also match `HEAD`. If a method path-matches a route but no allowed method matches, Run402 returns `405 Method Not Allowed` with the union of allowed methods for that path; matched route failures fail closed and never fall through to static HTML.

Static aliases serve the target file bytes at the public alias URL. They do not redirect to or expose the underlying file path, rewrite query strings, run header rules, or invoke framework routing. In the static manifest they materialize as route-only entries (`direct: false`, `reachability_authority: "route_static_alias"`) backed by release static assets. Direct static serving and static aliases share content type, cache-control, HTML mutation, conditional request behavior, and `HEAD` response behavior. A missing static alias target returns a platform static-route error and does not fall back to SPA HTML.

Plan/read surfaces include `routes: { manifest_sha256, entries }` on release inventory and `routes: { added, removed, changed }` in plan/release diffs. Static aliases render as route entries with `target: { "type": "static", "file": "<path>" }`; warning and error `affected[]` strings use phrasing such as `/events -> static file events.html`.

Route warnings include `PUBLIC_ROUTED_FUNCTION`, `ROUTE_TARGET_CARRIED_FORWARD`, `ROUTE_SHADOWS_STATIC_PATH`, `WILDCARD_ROUTE_SHADOWS_STATIC_PATHS`, `ROUTE_TABLE_NEAR_LIMIT`, `STATIC_ALIAS_SHADOWS_STATIC_PATH`, `STATIC_ALIAS_RELATIVE_ASSET_RISK`, `STATIC_ALIAS_DUPLICATE_CANONICAL_URL`, `STATIC_ALIAS_REDUNDANT_PUBLIC_PATH`, `STATIC_ALIAS_EXTENSIONLESS_NON_HTML`, `STATIC_ALIAS_TABLE_NEAR_LIMIT`, and `PUBLIC_PATH_MODE_WIDENS_TO_IMPLICIT`. Static aliases currently count toward the same temporary combined 100-entry route cap as function routes; `STATIC_ALIAS_TABLE_NEAR_LIMIT` includes `details.limit_scope: "combined_routes_temporary"` until a separate static-alias cap lands.

Non-goals: static aliases are not rewrites, redirects, Web Output, framework adapters, edge runtime, streaming, ISR, image optimization, query transforms, header rules, or route-level x402 policy.

Function targets keep the standard Node 22 Fetch Request -> Response contract: `export default async (req: Request) => Response`. For routed function requests, `req.method` is the original browser method and `req.url` is the full public URL, including scheme, host, path, and query string (`https://<sub>.run402.com/...`, deployment host, or the verified custom domain).

```js
export default async function handler(req) {
  const url = new URL(req.url);

  if (url.pathname === "/admin/oauth/google") {
    const redirectUri = new URL("/admin/oauth/google/callback", url.origin);
    const authUrl = new URL("https://accounts.google.com/o/oauth2/v2/auth");
    authUrl.searchParams.set("client_id", process.env.GOOGLE_CLIENT_ID ?? "replace-me");
    authUrl.searchParams.set("redirect_uri", redirectUri.toString());
    authUrl.searchParams.set("response_type", "code");
    authUrl.searchParams.set("scope", "openid email profile");
    authUrl.searchParams.set("state", crypto.randomUUID());
    return Response.redirect(authUrl, 302);
  }

  if (url.pathname === "/admin/oauth/google/callback") {
    const headers = new Headers({ location: "/admin" });
    headers.append("Set-Cookie", "sid=example; HttpOnly; Secure; SameSite=Lax; Path=/");
    headers.append("Set-Cookie", "flash=welcome; Secure; SameSite=Lax; Path=/; Max-Age=30");
    return new Response(null, { status: 303, headers });
  }

  return new Response("<h1>Admin</h1>", {
    headers: { "content-type": "text/html; charset=utf-8" },
  });
}
```

The OAuth `redirect_uri` above is derived from `req.url`, so the same code works on `*.run402.com`, deployment hosts, and verified custom domains.

Routed request fields available to user code:

| Field | Contract |
|---|---|
| `req.method` | Original browser method. `GET` routes also match `HEAD`; a `HEAD` request still reaches the handler as `HEAD`. |
| `req.url` | Full public URL with scheme, host, path, and query. Use `new URL(req.url)` for routing and OAuth callback URLs. |
| `req.headers` | Browser headers forwarded through a duplicate-safe internal list and exposed through Fetch `Headers`. Cookie data is available through the `cookie` header. |
| `await req.text/json/arrayBuffer()` | Buffered request body, max 6 MiB. Streaming request bodies are not supported. |
| Route metadata | Internal only. Run402 transports `run402.routed_http.v1` context between edge/gateway and Lambda; user handlers should use Fetch `Request`, not the raw envelope. |

Routed response behavior from user code:

| Field | Contract |
|---|---|
| `Response.status` | HTTP 200-599 except `101 Switching Protocols`. WebSockets are not supported. |
| `Response.headers` | Forwarded as duplicate-safe headers. Append multiple `Set-Cookie` values with `headers.append("Set-Cookie", value)`; Run402 preserves them as separate browser headers. |
| `Location` | Redirect targets are forwarded unchanged. Use absolute URLs when leaving the current origin. |
| `Response.body` | Buffered response body, max 6 MiB. `HEAD` responses send headers without body bytes. SSE and streaming responses are not supported. |
| Cache | Dynamic route responses are never stored in Run402's shared CDN cache. If no `Cache-Control` is set, Run402 adds `Cache-Control: private, no-store` and `x-run402-cache: dynamic-bypass`. |
| CORS | Run402 does not add default wildcard CORS. Implement `OPTIONS` and CORS headers in the function when cross-origin access is intended. |

Internally, Run402 converts the Fetch response to `run402.routed_http.v1`; agents should treat this as implementation detail unless they are debugging gateway internals:

```json
{
  "status": 302,
  "headers": [["location", "/dashboard"]],
  "cookies": ["sid=abc; HttpOnly; Secure; SameSite=Lax; Path=/"],
  "body": null
}
```

Custom-domain readiness checklist:

- Verify the route first on the managed subdomain or deployment host, then verify the same path on the custom domain.
- Confirm the deploy operation is `ready` and release/deployment inventory shows `routes.entries` plus a non-null `routes.manifest_sha256`.
- Confirm the custom domain is verified and serving the intended deployment. Custom domains use the Cloudflare Worker route manifest but must behave the same as managed domains.
- If the managed domain works but the custom domain returns a routed failure, check for `ROUTED_INVOKE_WORKER_SECRET_MISSING` or `ROUTE_MANIFEST_LOAD_FAILED`; those indicate Worker/gateway configuration or manifest propagation, not user handler code.

Troubleshooting route failures:

| Code | Meaning | Recovery |
|---|---|---|
| `ROUTE_MANIFEST_LOAD_FAILED` | The host selected a route, but the active route manifest could not be loaded. | Wait for the operation to reach `ready`, confirm `routes.manifest_sha256` is present, then redeploy or contact Run402 support if the manifest stays unavailable. |
| `ROUTED_INVOKE_WORKER_SECRET_MISSING` | Custom-domain Worker is missing the shared gateway invoke secret. | Managed domains may still work. Re-sync/deploy Worker config or contact Run402 support. |
| `ROUTED_INVOKE_AUTH_FAILED` | Gateway rejected the internal routed invoke signature. | Retry after propagation; persistent failures indicate shared secret or clock/config drift. |
| `ROUTED_ROUTE_STALE` | The selected route no longer matches the active release or host after revalidation. | Wait for route propagation, then retry or redeploy the same route table. |
| `ROUTE_METHOD_NOT_ALLOWED` | The path matched a route, but the HTTP method was not allowed. | Add the method to `methods`, add an `OPTIONS` route for CORS preflight, or remove the method restriction. |
| `STATIC_ROUTE_TARGET_NOT_FOUND` | A static alias matched, but its materialized target file could not be served. | Confirm the route target `file` exists in the final release's static site and redeploy. |
| `ROUTED_RESPONSE_TOO_LARGE` | Handler response body exceeded the 6 MiB routed response limit. | Return a smaller body, move large assets to static deploy/storage, or redirect to a downloadable object. |

For browser sessions, functions own app auth, CSRF checks, OAuth callbacks, cookie flags (`HttpOnly`, `Secure`, `SameSite`), Origin checks, and Fetch Metadata checks.

### Plan response

```json
{
  "plan_id": "plan_...",
  "operation_id": "op_...",
  "base_release_id": "rel_...",
  "manifest_digest": "<server-computed JCS+sha256 of your spec>",
  "missing_content": [{ "sha256": "<hex>", "size": 512, "present": false }],
  "diff": {
    "is_noop": false,
    "resources": {
      "site": { "paths_added": ["index.html"], "paths_changed": [], "paths_removed": [] },
      "database": { "migrations": [{ "id": "001_init", "status": "new" }] },
      "functions": { "added": ["summarize"], "changed": [], "removed": [] },
      "secrets": { "added": ["OPENAI_API_KEY"], "changed": [], "removed": [] },
      "subdomains": { "added": ["my-app"], "removed": [] },
      "routes": { "added": [], "removed": [], "changed": [] }
    }
  },
  "payment_required": null
}
```

For each `missing_content[i]` where `present: false`, hand the SHA + size to `POST /content/v1/plans` to get presigned PUT URLs.

### Commit response

```json
{
  "operation_id": "op_...",
  "release_id": "rel_...",
  "status": "ready",
  "urls": { "site": "https://<subdomain>.run402.com" }
}
```

If `status` is non-terminal (`schema_settling`, `activation_pending`), poll `GET /apply/v1/operations/:operation_id`. The auto-resume worker retries automatically; agents can also call `POST /apply/v1/operations/:operation_id/resume` to re-drive the failed phase forward immediately.

### Error fields specific to deploys

`code` is one of `INVALID_SPEC`, `MIGRATION_FAILED`, `MIGRATION_CHECKSUM_MISMATCH`, `MIGRATE_GATE_ACTIVE`, `PLAN_NOT_FOUND`, `OPERATION_NOT_FOUND`, `NOT_RESUMABLE`. Two additional fields: `phase` (`validate | plan | stage | migrate | schema_settling | activate | commit | resume`) and `operation_id` for correlation.

`mutation_state: "rolled_back"` means the active release is unchanged (commonly with `MIGRATION_CHECKSUM_MISMATCH`). `mutation_state: "unknown"` means commit returned 5xx — use `Idempotency-Key` to retry safely or check `GET /apply/v1/operations/:operation_id` first.

## OIDC federation for CI/CD — `/ci/v1/*` (v1.36)

GitHub Actions push-to-deploy without storing wallet keys in CI. A wallet-signed delegation links a GitHub OIDC subject pattern to a project; the workflow exchanges its GitHub OIDC JWT for a 15-min run402 session JWT and uses it on the seven CI-callable deploy routes (`/content/v1/plans*`, `/apply/v1/plans*`, `/apply/v1/operations/:operation_id` + `/events` + `/resume`). Same trust model as Vercel, Supabase, Netlify, Cloudflare etc. — connecting the workflow grants the workflow runtime authority over the project.

**Dual-authority disclosure.** Code deployed via CI runs with the project's runtime authority — `RUN402_SERVICE_KEY` in env, `adminDb()` (BYPASSRLS), and configured secrets via `process.env`. Database authority too — `spec.database` ships migrations, RLS/expose changes, and schema-altering SQL. The wallet-signed delegation's `Statement` field discloses both surfaces verbatim — the wallet UI shows the consent text at sign time. Revoking a binding stops future CI gateway requests but does NOT undo already-deployed code, stop in-flight deploy operations, rotate exfiltrated keys, or remove deployed functions. Compromise recovery: revoke + SIWE-deploy a known-good release + rotate any service-role key the deployed code may have read.

### Routes

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/ci/v1/bindings` | POST | SIWX (project owner) | Create a binding. Body: `{ project_id, provider: "github-actions", subject_match, allowed_actions: ["deploy"], allowed_events?, route_scopes?, github_repository_id?, expires_at?, nonce, signed_delegation }`. `route_scopes` is optional and defaults to `[]` (no route authority); when set, use exact/final-wildcard route patterns such as `["/admin","/admin/*"]`. The `signed_delegation` is a SIWE/SIWX-shaped wallet-signed message; gateway parses + verifies it byte-for-byte against canonical `Statement` and `Resources` builders. Returns 201 with the binding row, 409 on duplicate-active `(project_id, issuer, subject_match)`, 400 on `nonce_replay` (same wallet+nonce already used). |
| `/ci/v1/bindings` | GET | SIWX | List bindings for a project. Query: `?project=<project_id>` (required). Includes revoked. |
| `/ci/v1/bindings/:binding_id` | GET | SIWX | Binding detail with full parsed `created_sig`. |
| `/ci/v1/bindings/:binding_id/revoke` | POST | SIWX | Idempotent kill switch. Sets `revoked_at = NOW()`. Existing CI sessions are rejected on their next gateway request (per-request DB recheck). |
| `/ci/v1/bindings/:binding_id/asset-scopes` | POST | SIWX (binding owner) | Replace `asset_key_scopes` on the binding — gates the `spec.assets` slice for CI sessions. Body: `{ asset_key_scopes: string[] }`. Each scope is either an exact key (`astro/hero.jpg`) or a wildcard prefix (`astro/*`); bare `*` / `**` rejected. Capped at 64 entries, 256 chars each. Empty array means "no asset authority" (CI sessions hitting `assets.put` / `assets.sync` get 403 `CI_ASSET_SCOPE_DENIED`). 404 on unknown binding, 409 on revoked binding (cannot mutate), 403 on wallet/owner mismatch. Idempotent — same scope list is a no-op. |
| `/ci/v1/token-exchange` | POST | **none — the OIDC JWT is the auth** | RFC 8693-shaped JSON token exchange. Body: `{ grant_type: "urn:ietf:params:oauth:grant-type:token-exchange", subject_token: <github-oidc-jwt>, subject_token_type: "urn:ietf:params:oauth:token-type:jwt", project_id }`. JSON only (NOT form-encoded). Body cap 12 KiB; `subject_token` cap 8192 bytes. Returns `{ access_token, token_type: "Bearer", expires_in, scope: "deploy" }`. `expires_in` may be < 900 if the binding's `expires_at` is closer than 15 minutes. |

### Token exchange — verification order

1. Validate RFC 8693 request shape and `subject_token.length <= 8192`.
2. Decode the JWT payload (NOT header) to read `iss`. Look up in `internal.trusted_oidc_issuers`. Unknown issuers → 401 `invalid_token` **without any external JWKS fetch**.
3. `jose.jwtVerify` with `algorithms: ["RS256"]` pinned and `clockTolerance: 30s`. Post-check `payload.aud === "https://api.run402.com"` exactly (rejects array-containing).
4. Validate required GitHub claims as non-empty strings: `sub`, `run_id`, `sha`, `actor`, `workflow_ref`, `repository`, `repository_id`, `event_name`.
5. Fetch candidates via the partial index `(project_id, issuer) WHERE revoked_at IS NULL`. Filter in app code by subject-pattern: exact match wins over wildcard, longer prefix wins among wildcards. Equal specificity → 403 `ambiguous_binding`.
6. Enforce `event_name ∈ binding.allowed_events`. Mismatch → 403 `event_not_allowed`. Default `allowed_events` is `['push', 'workflow_dispatch']` — `pull_request` and `pull_request_target` denied unless explicitly opted in. **This catches `pull_request_target` (the dangerous fork-PR variant) which substring-matching `:pull_request` in `sub` would miss.**
7. Enforce `payload.repository_id === binding.github_repository_id` if non-NULL. Mismatch → 403 `repository_id_mismatch`. NULL = soft-bound, accepted on `subject_match` alone (audit-logged distinctly as `ci_token_exchanged_softly_bound`).
8. Atomic conditional UPDATE on the binding (`WHERE id = $1 AND revoked_at IS NULL AND expires_at not stale`). 0 rows → 403 `access_denied` (revoked between SELECT and UPDATE).

### Subject pattern syntax

`subject_match` accepts an exact OIDC subject string OR a string ending in a single `*` wildcard (matched as string-prefix, NOT regex). Reject: empty, control chars, multiple `*`, `*` not at the end, bare `*`, length > 256. Characters like `.`, `+`, `[`, `]`, `?` are accepted as literals — they're legal in git refs/tags/environment names.

Examples:
- Exact: `repo:user/repo:ref:refs/heads/main` — only the `main` branch.
- Branch wildcard: `repo:user/repo:ref:refs/heads/*` — any branch.
- Tag pattern: `repo:user/repo:ref:refs/tags/v*` — any `v*` tag.
- Environment-gated (recommended for prod): `repo:user/repo:environment:production` — only workflows declaring `environment: production` (which can require manual approval in GitHub).

**Caveat:** any matching workflow in the repo with `permissions: id-token: write` can attempt token-exchange — not necessarily only the intended deploy workflow. Use environment-gated subject patterns and branch protection to mitigate. `workflow_ref` constraint columns are deferred to a follow-up.

### CI deploy spec restriction (allowlist, not blocklist)

When a CI session calls `POST /apply/v1/plans`, the gateway enforces a strict allowlist on the request body:

- **Allowed top-level `spec` fields:** `project`, `database`, `functions`, `site`, `assets`, `base`, `routes`. Anything else (including `secrets`, `subdomains`, `checks`, or future `ApplySpec` additions) → 403 `forbidden_spec_field`.
- **Forbidden by property presence** (rejected even when empty): `spec.secrets`, `spec.subdomains`, `spec.checks`. So `spec.secrets: {}` rejects.
- **`spec.routes` requires delegated route scopes.** Bindings without `route_scopes` reject non-null `spec.routes` with 403 `forbidden_spec_field`. With scopes, the plan step compares the replace-mode route table to the current base table and rejects 403 `CI_ROUTE_SCOPE_DENIED` if any added, removed, or changed route is outside those scopes. Unchanged out-of-scope routes may be re-applied; `spec.routes: null` is allowed as preserve semantics.
- **`spec.assets` requires delegated asset key scopes.** Mutations to `assets.put` / `assets.sync` / `assets.delete` reject 403 `CI_ASSET_SCOPE_DENIED` for any key falling outside `asset_key_scopes` on the binding. Scopes are either exact keys or `prefix/*` wildcards. `assets.sync.prune` requires a wildcard scope that fully contains the sync `prefix`. Defaults to NULL (closed) on bindings created via `POST /ci/v1/bindings`; mutate after the fact via `POST /ci/v1/bindings/:binding_id/asset-scopes`.
- **`spec.base` restricted** to absent OR exactly `{ release: "current" }`. `{ release: "empty" }` and `{ release_id: ... }` reject (could nuke or pull state from a forbidden release).
- **`manifest_ref` rejected** when non-null. CI is limited to inline specs under the 5 MB body cap. Public-repo CLI must do client-side preflight rejection on these fields when in CI mode.

SIWE-authed requests bypass the restriction (the wallet has full authority).

### CI plan / operation tagging

Plans created via a CI session are tagged with `created_via_ci_binding_id`. CI commit (`POST /apply/v1/plans/:plan_id/commit`) and resume (`POST /apply/v1/operations/:operation_id/resume`) reject HTTP 403 `forbidden_plan` if the plan was not created by the same binding — **same-binding-only**. This blocks the bypass where a CI session would commit a wallet-created plan that contains forbidden fields, AND prevents one CI binding from completing another binding's work. Wallet-authenticated commit/resume bypasses the guard (operator override).

### Error codes specific to CI federation

`invalid_token`, `access_denied`, `insufficient_scope`, `event_not_allowed`, `repository_id_mismatch`, `ambiguous_binding`, `forbidden_spec_field`, `CI_ROUTE_SCOPE_DENIED`, `CI_ASSET_SCOPE_DENIED`, `forbidden_plan`, `nonce_replay`, `delegation_statement_mismatch`, `delegation_resource_uri_mismatch`, `signer_mismatch`, `delegation_oversized`, `delegation_parse_failed`, `delegation_signature_invalid`.

### Composition on the seven CI-callable routes

The seven routes accept either their existing auth OR a CI session. Mandatory route order on the CI path: **auth helper → ciProjectResolver → lifecycleGate → restrictDeploySpecForCi (plan only) → ciPlanGuard (commit/resume only — runs BEFORE idempotency) → idempotencyMiddleware (commit only) → handler.**

| Route | Existing auth | Also accepts CI session |
|---|---|---|
| `POST /content/v1/plans` | apikey | ✓ |
| `POST /content/v1/plans/:plan_id/commit` | apikey | ✓ |
| `POST /apply/v1/plans` | SIWX | ✓ (with deploy-spec restriction) |
| `POST /apply/v1/plans/:plan_id/commit` | SIWX | ✓ (with plan guard) |
| `GET /apply/v1/operations/:operation_id` | apikey | ✓ |
| `GET /apply/v1/operations/:operation_id/events` | apikey | ✓ |
| `POST /apply/v1/operations/:operation_id/resume` | SIWX | ✓ (with plan guard) |

Routes outside this list reject CI session bearers with their normal auth response.

## Managed jobs

Managed jobs are run402-owned async compute shapes for workloads that exceed request-time functions. Job types are run402-configured allowlist entries; no public kysigned FFLONK job type is currently registered. Callers submit input and a hard cost cap for a supported `job_type`; run402 owns image selection, instance type, AZ, retries, billing, logs, and artifact storage.

Auth: `Authorization: Bearer <service_key>`. Do not send public image names or resource knobs; unsupported fields are rejected.

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/jobs/v1/runs` | POST | service_key + lifecycleGate | Submit a job. Requires `Idempotency-Key`. Accepts an optional `callback_url` (see below). Returns `202` for a new job, `200` for an idempotency hit, `409` when the same key is reused with a different body, `429` for project concurrency/queue quota, and `503 Retry-After` when the platform queue is full. |
| `/jobs/v1/runs` | DELETE | service_key + lifecycleGate | Purge all project-scoped managed-job run records. Queued/running jobs are included in the purge; any known EC2 runner instances are terminated before records are deleted. Returns `{deleted_jobs, cancelled_active_jobs, terminated_instances}`. |
| `/jobs/v1/runs/:job_id` | GET | service_key | Poll project-scoped job status/result. |
| `/jobs/v1/runs/:job_id` | DELETE | service_key + lifecycleGate | Cancel queued/running jobs. Terminal jobs are returned unchanged. Running cancellation terminates the runner instance when known. |
| `/jobs/v1/runs/:job_id/logs` | GET | service_key | CloudWatch-backed runner logs. Query: `tail` (default 100, max 1000), `since` (inclusive epoch ms). Returns chronological `{ logs: [...] }`. |
| `/jobs/v1/runs/:job_id/artifacts/:filename` | GET | service_key | Download a completed job's recorded artifact. Streams the raw bytes with the artifact's content-type — same Bearer auth as the rest of `/jobs/v1`. `404` if the job isn't completed or the filename wasn't recorded. |

Submit body:

```json
{
  "job_type": "example.managed_job.v1",
  "input": {
    "input_json": {
      "envelopeId": "env_123"
    }
  },
  "max_cost_usd_micros": 50000,
  "callback_url": "https://hooks.example.com/run402/jobs"
}
```

`callback_url` (optional) is an absolute `https://` URL (max 2048 chars; `http://` and malformed URLs are rejected with `400 invalid_job_request`, code `INVALID_CALLBACK_URL`). When set, run402 pushes one durable webhook to it as soon as the job reaches a terminal state (`completed` / `failed` / `cancelled`), so you do not need to poll. Delivery is at-least-once (bounded retries with exponential backoff, then a dead-letter state) and **unsigned**. The body is the canonical webhook envelope:

```json
{
  "id": "job_abc123:terminal",
  "type": "job_completed",
  "created_at": "2026-05-17T10:09:38.000Z",
  "schema_version": "1",
  "idempotency_key": "job_abc123:terminal",
  "payload": {
    "job_id": "job_abc123",
    "status": "completed",
    "artifacts": { "result.json": { "url": "https://api.run402.com/jobs/v1/runs/job_abc123/artifacts/result.json", "content_type": "application/json", "sha256": "9b21fa…", "size_bytes": 1234 } }
  }
}
```

`type` is one of `job_completed` / `job_failed` / `job_cancelled`; `payload.artifacts` is present on success and `payload.error` (`{ code, message }`) on failure. The `Run402-Webhook-Id` header equals the `idempotency_key` (`<job_id>:terminal`). Because delivery is at-least-once, **dedupe on that header and re-fetch authoritative state via `GET /jobs/v1/runs/:job_id` before acting** — the callback is a trigger, not the source of truth. `callback_url` is submit-only and is never returned by the GET endpoint.

Status response shape is intentionally compact:

```json
{
  "job_id": "job_abc123",
  "job_type": "example.managed_job.v1",
  "status": "running",
  "created_at": "2026-05-17T10:00:00.000Z",
  "started_at": "2026-05-17T10:01:12.000Z"
}
```

Terminal success includes artifact references and derivation metadata:

```json
{
  "job_id": "job_abc123",
  "job_type": "example.managed_job.v1",
  "status": "completed",
  "created_at": "2026-05-17T10:00:00.000Z",
  "started_at": "2026-05-17T10:01:12.000Z",
  "completed_at": "2026-05-17T10:09:38.000Z",
  "artifacts": {
    "result.json": { "url": "https://api.run402.com/jobs/v1/runs/job_abc123/artifacts/result.json", "content_type": "application/json", "sha256": "9b21fa…", "size_bytes": 1234 },
    "worker.log": { "url": "https://api.run402.com/jobs/v1/runs/job_abc123/artifacts/worker.log", "content_type": "text/plain", "sha256": "c1d4e9…", "size_bytes": 88210 }
  },
  "metadata": {
    "wall_seconds": 506,
    "cost_usd_micros": 40600,
    "raw_cost_usd_micros": 40600,
    "absorbed_overage_usd_micros": 0,
    "image_digest": "sha256:abc123...",
    "spot_rate_usd_hr_micros": 288800,
    "instance_type": "r5.4xlarge",
    "az": "us-east-1d",
    "peak_rss_gb": 61.1,
    "interrupt_count": 0,
    "attempt_count": 1,
    "billing_status": "charged"
  }
}
```

Each artifact entry is `{ url, content_type, sha256?, size_bytes? }`. Download the bytes with `GET <url>` (equivalently `GET /jobs/v1/runs/:job_id/artifacts/:filename`) using the same `Authorization: Bearer <service_key>` as the rest of `/jobs/v1` — it streams the raw artifact, not JSON, with `Cache-Control: private, no-store`. `sha256`/`size_bytes` let you verify integrity before use and are omitted for jobs created before per-artifact capture (the `url` still serves).

Statuses: `queued`, `running`, `completed`, `failed`, `cancelled`. Spot interruptions are retried internally; callers observe a later `running` attempt unless retry/fallback would exceed `max_cost_usd_micros`, in which case the job fails with `MAX_COST_EXCEEDED`. Other stable failure codes include `SPOT_INTERRUPTED`, `JOB_TIMEOUT`, `RUNTIME_ERROR`, `RUNNER_LAUNCH_FAILED`, `INPUT_UNAVAILABLE`, and `IMAGE_UNAVAILABLE`.

Billing: successful jobs debit the project organization once with ledger kind `managed_job`, idempotency key `managed_job:<job_id>`, reference type/id `managed_job`/`<job_id>`, and per-attempt derivation metadata. The charge is capped at `max_cost_usd_micros`; any estimation overage above the cap is absorbed by run402 and reported as `absorbed_overage_usd_micros`.

## File storage (content-addressed)

**Writes go through `apply`, not a separate upload endpoint.** The `ApplySpec.assets` slice (or the SDK's `r.project(id).assets.*` namespace) is the canonical write path; bytes flow through CAS the same way site files and function source do. Reads, signed URLs, listings, and CDN diagnose stay on `/storage/v1/*` below.

### Writing assets (the apply path)

Put the keys in your `ApplySpec`:

```jsonc
{
  "project_id": "prj_...",
  "assets": {
    "put": {
      "logo.svg":      { "sha256": "<hex>", "size": 1024, "content_type": "image/svg+xml" },
      "docs/spec.pdf": { "sha256": "<hex>", "size": 92341, "content_type": "application/pdf",
                         "visibility": "private" }
    },
    "delete": ["old-asset.png"],
    "sync":   { "prefix": "static/", "prune": true, "delete_set_digest": "<hex>", "base_revision": "<hex>" }
  }
}
```

Submit `POST /apply/v1/plans` to get presigned PUT URLs for any missing SHAs (via the same `missing_content[]` and `/content/v1/plans` flow the deploy slices use), upload the bytes, then `POST /apply/v1/plans/:plan_id/commit`. Asset promotion happens in the same activation transaction that flips the release pointer — assets and the site/HTML that references them flip live at the same instant.

SDK equivalents (preferred — typed, handles plan/commit/retry for you):

- `r.project(id).apply({ assets: {...} })` — explicit slice, mixes freely with `database`/`site`/`functions`/etc.
- `r.project(id).assets.put(key, source, opts?)` — single asset; sugar over a 1-item apply.
- `r.project(id).assets.putMany(items, opts?)` — isomorphic in-memory batch.
- `r.project(id).assets.uploadDir(dir, opts?)` — Node directory walk, additive.
- `r.project(id).assets.syncDir(dir, { prune: true, confirm })` — Node directory walk with explicit prune (drift-protected via `base_revision`; HTTP 409 `ASSET_SYNC_DRIFT` if inventory changed between plan and commit).
- `r.project(id).assets.prepareDir(dir, opts?)` — returns `{ manifest, applySlice }` with deterministic CDN URLs + SRI hashes pre-commit; lets you render HTML against final URLs and commit HTML + assets atomically.

`visibility: "public"` (default) and `immutable: true` (default) together yield a content-addressed `cdn_url` with `Cache-Control: public, max-age=31536000, immutable` and an `sri` value for `<script integrity="…">`. Mutable assets trigger CloudFront invalidation on every event that changes served bytes (re-write, visibility flip, delete) — but the immutable URL is correct from write time, so prefer it. `visibility: "private"` returns `cdn_url: null` everywhere; use `assets.sign(key, opts)` to mint a signed URL on demand.

### Image variants (v1.49)

Image uploads through `assets.put` automatically generate three WebP variants — `thumb` (320w), `medium` (800w), `large` (1920w) — plus a blurhash placeholder and display-oriented dimensions. The response `AssetRef` for an image source ≥ 320×320 carries extra fields:

```jsonc
{
  // existing fields: key, sha256, size_bytes, content_type, url, immutable_url, cdn_url, cdn_immutable_url, sri, etag
  "width_px": 4032,
  "height_px": 3024,
  "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
  "blurhash_data_url": "data:image/png;base64,iVBORw0KGgo...",
  "asset_schema": "v1.54",
  "variant_spec_version": "v1",
  "display_url": "...",
  "display_immutable_url": "...",
  "variants": {
    "thumb":  { "url", "cdn_url", "width_px": 320,  "height_px": 240,  "format": "webp", "sha256" },
    "medium": { "url", "cdn_url", "width_px": 800,  "height_px": 600,  "format": "webp", "sha256" },
    "large":  { "url", "cdn_url", "width_px": 1920, "height_px": 1440, "format": "webp", "sha256" }
  }
}
```

`display_url` equals `cdn_url` for browser-displayable formats (jpeg/png/webp/avif). For HEIC/HEIF sources, the source bytes are **preserved verbatim in CAS** (uploaded SHA == stored SHA, audit-friendly) and an additional `display_jpeg` variant is generated; `display_url` points at the JPEG so the image renders correctly in browsers without app-author HEIC awareness. Variants share the source's user-facing key as their revocation `source_key`, so deleting the source revokes all variant URLs and issues a CloudFront invalidation per URL.

Sources below 320×320 (and not HEIC) skip variant generation — the original IS the thumb — but `width_px`, `height_px`, `blurhash`, and `blurhash_data_url` are still populated. Per-call opt-out is intentionally not exposed; operators can disable the encoder entirely via `IMAGE_VARIANTS_ENABLED=false` on the gateway task.

**`blurhash_data_url` (v1.54 — additive).** Pre-decoded PNG data URL (~600-1200 bytes, 16×16 pixels) computed once at upload time from the pinned BlurHash decoder. `<Run402Image>` (in `@run402/astro` v1.0.0+) emits this verbatim as the `<img>` element's `background-image` so the placeholder is visible during fetch with zero render-time decode + zero client-side blurhash work. Apps that decode blurhash themselves at runtime can keep using the existing `blurhash` field; the two coexist for backwards-compat.

**`asset_schema` (v1.54 — additive).** Stamps the highest shape contract this AssetRef satisfies: `"v1.49"` / `"v1.50"` / `"v1.54"` / `null`. Read by `<Run402Image>` strict-mode when configured with `imageDefaults: { strict: { onSchema: ">=v1.49" } }` — legacy AssetRefs uploaded before this field landed have `asset_schema: null` and bypass strict-mode entirely (the schema-filter form is what makes "strict for new uploads, lenient for legacy" work on mixed-vintage CMS projects). The check constraint on the column rejects non-`v<MAJOR>.<MINOR>` forms; pre-release suffixes like `v1.49-rc.1` are forbidden by construction. Backfill caps at `"v1.49"` even on fully-populated rows (asymmetry rule — backfill cannot retroactively verify v1.50's "metadata explicitly handled" property; only the upload-path can stamp `"v1.54"`). See `docs/migrations/asset-image-variants-v1-51-backfill.md` for the operator backfill workflow.

Encoder is bounded: concurrency cap (default 2), queue depth (default 4), pixel cap (default 40 MP), per-axis cap (default 12000 px), per-variant timeout (default 10 s). Errors map to canonical codes: `IMAGE_DECODE_FAILED` (HTTP 422), `IMAGE_INPUT_TOO_LARGE` (413), `IMAGE_ENCODE_TIMEOUT` (504), `TOO_MANY_ENCODES_QUEUED` (429 with `Retry-After: 2`).

**Write-path parity.** Both `r.assets.put(...)` and the unified apply hero `r.project(id).apply({ assets: { put: [...] } })` produce the same `AssetRef` shape. Picker / SSR code can use either entry point and read `variants.thumb.cdn_url`, `display_url`, `blurhash`, etc., from the same fields.

**SDK helpers (`@run402/sdk` v2.3+).** The widened `AssetRef` carries two convenience fields and one new tag emitter:

- `ref.thumbUrl` — `variants.thumb.cdn_url ?? displayUrl` for image refs, **`undefined` for non-images**. Single field for grid thumbnails. TypeScript narrows, so a picker that does `<img src={ref.thumbUrl}>` is a compile error against a non-image ref instead of a broken-image icon at runtime.
- `ref.displayUrl` — `display_url ?? cdn_url` for image refs, **`undefined` for non-images**. Use for hero / single-image render paths; HEIC sources transparently get the JPEG transcode.
- `ref.imgTag(alt?)` — existing helper, now defaults `<img src>` to `display_url ?? cdn_url` (HEIC-aware) and opportunistically emits `width`/`height` attributes when known (eliminates Cumulative Layout Shift). Never throws on absence — safe for any AssetRef.
- `ref.imgTagWithSrcSet({ alt?, sizes, loading? })` — emits a `<picture>` with WebP-only `<source>` (three sizes) and `display_url` as the `<img>` fallback. Throws at call time on (a) missing/empty `sizes` (browsers over-fetch the largest candidate without it), or (b) missing `variants` (non-image / sub-320 / pre-v1.49 ref) — the error message tells the caller to use `imgTag()` instead. No silent fallback to a bare `<img>`.

**Storing `AssetRef` in your DB — canonical schema.** Store the **full `AssetRef` returned by `r.assets.put(...)` as a JSONB column**. That preserves the variant SHAs + immutable URLs the gateway computed at upload time — they're NOT recomputable from `(source_sha256, key)` alone because each variant has its own content hash. Mutable URLs (`url`, `cdn_url`) remain stable strings across re-uploads to the same key; immutable URLs are pinned to the source SHA. Other patterns (storing just `sha256` and refetching, or hand-picking columns) lock you into a migration when v1.49+ variant URLs or v1.50 metadata arrive.

Read it back with `r.assets.fromRef(rawJsonbValue)` from `@run402/functions` — a pure-local helper (no network) that re-types the stored value as a fully-populated `AssetRef` with camelCase aliases. Tolerant of pre-v1.49 stored shapes (returns an `AssetRef` without the variant fields rather than throwing), so older rows keep working as the platform widens the shape.

```ts
import { assets } from '@run402/functions';
// Postgres: SELECT hero_asset FROM sections WHERE id = $1
const row = await db.query(...);
const hero = assets.fromRef(row.hero_asset);
// hero.cdnUrl, hero.variants.large?.cdn_url, hero.blurhash, ...
```

**AVIF deferred from v1 — the specific footgun.** Browsers pick `<picture>` sources by `<source type=...>` precedence, NOT by size. A single AVIF source at full-res (1920w) would be picked for thumbnail slots by AVIF-capable browsers, defeating the size variant set — mobile users on cellular download the 1920w hero where they should have gotten the 320w thumb. Two ways AVIF can land safely when it returns: (a) generate AVIF at all three sizes (`thumb-avif`, `medium-avif`, `large-avif`) and order `<picture>` sources size-DESC so the largest-fit-smallest rule still matches first, OR (b) ship a dedicated `imgTagHero()` helper that emits a single `<source type="image/avif">` only when the caller explicitly asked for the hero use-case (full-res, above-the-fold). Until one of these lands, callers that need AVIF should request it via `assets.put({ variants: ['avif-hero'] })` (the per-call opt-in shape on the v0.2 roadmap) — NOT by mixing AVIF + WebP in a single `<picture>` and hoping browsers pick well.

**Astro integration (`@run402/astro`).** Two forms — pick by complexity. The preset's `Run402PresetOptions` extends `Partial<AstroUserConfig>`, so any field you'd pass to `defineConfig({...})` flows through `run402({...})` unchanged. **The composable form is the recommended shape for any non-trivial project** (tailwind, React, custom vite plugins, virtual modules, custom `outDir`); the one-liner is a starter-template convenience.

```js
// astro.config.mjs — composable form (recommended)
import tailwind from '@astrojs/tailwind';
import run402 from '@run402/astro';

export default run402({
  // any AstroUserConfig field — vite, build, srcDir, image, redirects,
  // experimental, etc. — flows through untouched
  vite: { plugins: [myVirtualModulePlugin()] },
  integrations: [tailwind()],
  output: 'server', // pass explicitly to silence the SSR-default warning
});
```

```js
// astro.config.mjs — one-liner (starter-template shortcut only)
import run402 from '@run402/astro';
export default run402();
```

**SSR-default warning.** Calling `run402()` without an explicit `output` defaults to `'server'` (every page SSR unless it sets `export const prerender = true`). The preset logs a one-time warning at config load so existing SSG sites don't silently flip every page. To migrate an SSG site, pass `run402({ output: 'static' })` and opt routes INTO SSR per-page; to silence the warning on a greenfield SSR project, pass `output: 'server'` explicitly.

```astro
---
import { Image } from '@run402/astro/Image.astro';
---
<Image src="./images/hero.jpg" alt="..." sizes="100vw" priority />
```

The component emits a `<picture>` with the WebP variant ladder, an `<img>` fallback (display_jpeg for HEIC, display_url otherwise), `width`/`height` attributes for CLS prevention, and an inline blurhash placeholder. Build-time cache at `node_modules/.run402/assetMap.json` means re-builds with unchanged sources are free. Set `RUN402_PROJECT_ID` env var (or pass `run402({ projectId })`). Build-time-known image references only in v0.1 — CMS-driven runtime images keep using `r.assets.put` server-side. See `@run402/astro` README for full prop reference.

**Runtime CMS images: `<Run402Image>` (v1.51+, `@run402/astro` v1.0.0+).** For images coming from a DB row at SSR time (the common CMS pattern), use the runtime component. Two consumption paths — same shape, byte-identical HTML output:

```astro
---
// Astro context
import { Run402Image } from '@run402/astro/components';
import { r } from '../lib/run402';
const hero = r.assets.fromRef(Astro.locals.row.hero_asset);
---
<Run402Image asset={hero} alt="..." sizes="100vw" priority />
```

```tsx
// React context (islands or React-only consumers)
import { Run402Image } from '@run402/astro/react';
import type { AssetRef } from '@run402/functions';

export function Hero({ asset }: { asset: AssetRef }) {
  return <Run402Image asset={asset} alt="..." sizes="100vw" priority />;
}
```

Renders `<picture>` with the WebP variant ladder + JPEG `display_jpeg` fallback for HEIC sources + the pre-decoded `blurhash_data_url` as the `<img>` `background-image` (zero render-time decode, byte-deterministic across Node versions). The pre-decoded placeholder is the v1.54 addition over the original `<Run402Picture>` — `<Run402Picture>` decodes blurhash → PNG at render time, `<Run402Image>` reads the gateway-pre-computed data URL directly.

**Strict mode** opts the project into hard-failing on degraded renders, catching the silent-degradation failure mode (where 28 of 30 tenant assets render correctly and 2 silently degrade) at build / render time instead of in production. Configure via project-level default:

```js
// astro.config.mjs
import run402 from '@run402/astro';
export default run402({
  imageDefaults: {
    strict: { onSchema: ">=v1.49" },  // mixed-vintage CMS projects
    // OR: strict: true,              // greenfield, every render strict-checked
    // OR: strict: false,             // explicit lenient (default)
  },
});
```

Strict failures throw `R402_ASTRO_IMAGE_STRICT_DEGRADED` carrying a `subcode` field (`NO_VARIANTS` / `NO_INTRINSICS` / `NO_PLACEHOLDER` / `NO_CDN_URL` / `WRONG_SHAPE`) so the operator sees exactly which field shape regressed. The schema-filter form (`{ onSchema: ">=v1.49" }`) is the right choice for mixed-vintage CMS projects: legacy AssetRefs (no `asset_schema` field) bypass strict-mode entirely, new uploads (carrying `asset_schema`) are strict-checked. This is what makes "strict for new, lenient for legacy" actually usable at scale.

**HEIC correctness floor.** When the AssetRef's `content_type` is `image/heic` (or `image/heif`) AND `variants.display_jpeg` is absent, the component hard-fails unconditionally with `R402_ASTRO_IMAGE_HEIC_NO_TRANSCODE` — regardless of strict mode, regardless of schema-filter, regardless of any other prop. The reason is that `<img src="<heic-url>">` renders **zero pixels** in Firefox + Chrome (~75% of global browser share); silent broken-image rendering would be debugging hell. Operator path forward: run the asset-image-variants backfill with `--regenerate-heic-transcodes` to materialize `display_jpeg` for already-stored HEIC, OR re-upload through the v1.54 gateway pipeline, OR replace the asset with a non-HEIC source. See `docs/migrations/asset-image-variants-v1-51-backfill.md` in the run402-private repo.

**Default-mode degradation manifest.** In non-strict mode the component STILL records every degraded render to a build-time manifest at `<outDir>/run402/image-degradations.json` (deduplicated by `(sha256, missing-fields-set)`). Wire it into CI as a regression gate — `[ $(jq length dist/run402/image-degradations.json) -eq 0 ]` is the one-liner that fails the build on any degradation. For golden-file comparison, commit a `image-degradations-golden.json` baseline and diff against the new build's manifest; any new entry is the regression.

**12 error codes documented at `https://run402.com/errors/`:** `_ASSET_MISSING` / `_ASSET_STRING_URL` / `_ASSET_WRONG_SHAPE` / `_NON_IMAGE_ASSET` / `_ALT_REQUIRED` / `_CONFLICTING_CLASS_PROPS` / `_CONFLICTING_LOADING_PROPS` / `_HEIC_NO_TRANSCODE` / `_SIZES_REQUIRED` / `_STRICT_DEGRADED` / `_RESERVED_DATA_ATTR` / `_WRONG_ENTRY_POINT`. Every code is a `Run402ImageError` instance carrying `code` + `message` + `suggestedFix` (paste-ready) + `docs` URL anchor.

**`<Run402Picture>` vs `<Run402Image>`.** The original v1.0 `<Run402Picture>` is still exported from `@run402/astro/components` — it's the lighter choice when you don't need strict-mode + pre-decoded placeholders + React-port support. Existing pages using `<Run402Picture>` keep working; no migration required. New surfaces should prefer `<Run402Image>` for the CI regression gate.

### Asset metadata + EXIF policy + media-picker queries (v1.50)

`assets.put` accepts **caller-provided metadata** for the CMS-shadow-table pattern (filename, uploaded_by, tags, etc.) and a per-upload **EXIF policy** controlling what gets stored in the indexed `image_exif` column. `assets.list` adds **sort** + **filter** to make the route a usable media-picker backend (newest-first paginated, filterable by uploader / tag / format / dimensions).

**Caller metadata (`metadata` on put, top-level on list rows):**

```jsonc
{
  "project_id": "prj_...",
  "assets": {
    "put": [
      {
        "key": "images/hero.jpg",
        "sha256": "<hex>", "size_bytes": 5242880, "content_type": "image/jpeg",
        "metadata": {
          "filename":   "hero-2026-q1.jpg",
          "uploaded_by": "user_a3f2",
          "tags":       ["banner", "homepage"]
        }
      }
    ]
  }
}
```

Rules — validated at plan time (HTTP 400 `INVALID_ASSET_METADATA` on violation):

- Flat object only; values must be `string | number | boolean | string[]`. Nested objects rejected.
- Serialized size ≤ 4 KB (SQL CHECK enforced as backstop).
- Last-write-wins on re-upload. Omitting `metadata` on a subsequent put for the same key clears any prior value. (No separate mutation endpoint — re-upload to change.)
- Numbers must be finite; arrays-of-non-strings rejected.

**EXIF policy (`exif_policy` on put, `image_exif_policy` on list rows):**

```jsonc
{
  "assets": {
    "put": [
      { "key": "photo.jpg", "sha256": "<hex>", "size_bytes": 4000000,
        "content_type": "image/jpeg",
        "exif_policy": "strip" }
    ]
  }
}
```

- `"keep"` (default) — full EXIF object stored in `image_exif`. Use when EXIF data is useful (creative apps, AI-gen images, news photography) or when the app owner has handled end-user consent.
- `"strip"` — allowlist applied to `image_exif`. Only `camera_make`, `camera_model`, `lens_model`, `exposure_time`, `f_number`, `iso`, `focal_length`, `datetime_taken`, `datetime_digitized`, `datetime_modified` survive. GPS / serial numbers / owner identifiers / maker-notes / software / copyright / unknown tags are all dropped.
- **Original CAS bytes are NEVER mutated under either policy.** Stripping affects only the queryable copy in `image_exif`; apps that need full EXIF can read the served bytes and parse themselves.
- Invalid policy values → HTTP 400 `INVALID_EXIF_POLICY`.

**In-function shortcut** (`@run402/functions` ≥ paired-with-v1.50):

```ts
const ref = await assets.put("images/hero.jpg", bytes, {
  metadata: { filename: "hero.jpg", uploaded_by: userId, tags: ["banner"] },
  exifPolicy: "strip",
  contentType: "image/jpeg",
});
// ref.metadata, ref.image_format, ref.image_info, ref.image_exif,
// ref.image_exif_policy populated alongside ref.width_px / .height_px / .blurhash.
```

The SDK validates `metadata` and `exifPolicy` client-side BEFORE the HTTP call (throws `Error("INVALID_ASSET_METADATA: …")` / `"INVALID_EXIF_POLICY: …"`). Headers used on the wire: `x-run402-asset-metadata` (URL-safe base64 of UTF-8 JSON) + `x-run402-asset-exif-policy: keep|strip`.

**List query — sort + filter:**

```http
GET /storage/v1/blobs
  ?prefix=images/
  &sort=createdAt:desc
  &filter_uploaded_by=user_a3f2
  &filter_tag=banner
  &filter_format=jpeg
  &filter_min_width=1920
  &limit=40
```

| Query param | Default | Description |
|-------------|---------|-------------|
| `sort` | `key:asc` | `key:asc` (legacy) / `createdAt:asc` / `createdAt:desc`. Other values → 400 `INVALID_SORT`. |
| `filter_uploaded_by` | — | Equality on `metadata->>'uploaded_by'`. |
| `filter_tag` | — | Array-contains on `metadata->'tags'`. |
| `filter_format` | — | Equality on `image_format` (`jpeg`/`png`/`webp`/`avif`/`heic`/`tiff`/`svg`/`bmp`). |
| `filter_is_image` | — | `true` → `image_format IS NOT NULL`; `false` → IS NULL. |
| `filter_min_width` / `filter_max_width` | — | Inclusive integer range on `width_px`. |
| `filter_min_height` / `filter_max_height` | — | Inclusive integer range on `height_px`. |

Any other `filter_*` key → HTTP 400 `INVALID_FILTER_KEY` with the supported-keys list in the error message. Every filter predicate is backed by a partial index (no hidden seq-scans).

**Cursor semantics:**

- `sort=key:asc` cursor is the bare `key` string (legacy-compatible — existing clients keep paginating exactly as before).
- `sort=createdAt:*` cursor is base64url JSON `{s, ts, key}` with sort-tag-tied semantics: re-listing with the same cursor under a different sort returns 400 `INVALID_CURSOR_FOR_SORT` instead of silently jumping mid-stream.

**List row shape (top-level v1.50 fields):**

```jsonc
{
  "key": "images/hero.jpg",
  "size_bytes": 5242880,
  "content_type": "image/jpeg",
  "sha256": "<hex>",
  "visibility": "public",
  "immutable_suffix": "3a7fc02e",
  "created_at": "2026-05-20T10:00:00.000Z",
  "updated_at": "2026-05-20T10:00:00.000Z",

  "width_px": 1920,
  "height_px": 1080,
  "blurhash": "LEHV6n…",
  "blurhash_data_url": "data:image/png;base64,iVBORw0KGgo...",
  "asset_schema": "v1.54",

  "metadata": { "filename": "hero.jpg", "uploaded_by": "user_a3f2", "tags": ["banner"] },
  "image_format": "jpeg",
  "image_info": { "has_alpha": false, "color_space": "srgb", "bit_depth": 8 },
  "image_exif": { "camera_make": "Canon", "camera_model": "EOS R5", "exposure_time": "1/250" },
  "image_exif_policy": "strip"
}
```

`metadata` is JSON `null` (not absent) when no metadata was supplied. The image fields are `null` for non-image uploads. Width/height/blurhash come from the v1.49 image-variants pipeline; v1.50 layers `image_format`/`info`/`exif`/`exif_policy` on the same flat shape; v1.54 layers `blurhash_data_url` (pre-decoded PNG data URL for `<Run402Image>` placeholders) and `asset_schema` (shape-contract stamp for `<Run402Image>` strict-mode) on the same row.

**Indexes (v1.50 migration):**

- partial btree `(project_id, (metadata->>'uploaded_by'))` for `filter_uploaded_by`
- partial GIN `(metadata->'tags')` for `filter_tag`
- partial `(project_id, created_at DESC, key) WHERE image_format IS NOT NULL` for "images, newest first"
- partial `(project_id, image_format) WHERE image_format IS NOT NULL` for `filter_format`
- partial `(project_id, width_px, height_px) WHERE image_format IS NOT NULL` for dimension ranges

**Eliminates the CMS shadow-table pattern.** Apps that previously kept a `media_assets` table to mirror storage (filename / uploader / tags / dimensions, with dual-write hazards on every upload + delete) collapse it into a single source of truth on `internal.blobs`. The Kychon `admin-content-management` change is the driving consumer.

**Out of scope for v1.50:** mutating served bytes to honor `exifPolicy: 'strip'` (would require a derivative file; a future "redacted-variants" feature). LQIP / dominant color / perceptual hash (require full decode beyond what variants already does). Filter on undeclared fields (every supported predicate is backed by an index).

### Reading, signing, listing, diagnosing

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/storage/v1/blob/:key` | GET | optional | Stream an asset. Public assets need no auth. Private assets require a service_key or project_admin apikey. Supports `Range:` byte-range requests. |
| `/storage/v1/blob/:key` | DELETE | service_key or project_admin apikey | Remove an asset and decrement project storage. Equivalent to `apply({ assets: { delete: [key] } })` for single-key removal. |
| `/storage/v1/blob/:key/sign` | POST | service_key or project_admin apikey | Time-boxed S3 presigned GET. Body: `{ ttl_seconds? }`. Default 1h, max 7d. |
| `/storage/v1/blobs` | GET | service_key or project_admin apikey | List assets. Query: `prefix`, `limit` (strict positive integer 1-1000, default 100), `cursor`, plus **v1.50** `sort` and `filter_*` (see "Asset metadata + EXIF policy" below). Malformed, fractional, zero, or negative limits return 400. |
| `/storage/v1/blobs/diagnose` | GET | service_key or project_admin apikey | Inspect live CDN state for a public asset URL. Query: `url=<full-blob-url>`. Returns `{ project_id, key, expected_sha256, observed_sha256, vantage: "gateway-us-east-1", probe_method: "GET_RANGE_0_0", probe_may_have_warmed_cache: true, cache: { x_cache, age_seconds, cache_kind }, invalidation: { id, status }, hint }`. SSRF-guarded — only `*.run402.com` and the requesting project's active custom domains. |

Storage admin and mutation routes require the `apikey` header to carry a project `service_key` or a JWT with role `project_admin`; browser-safe `anon_key` is limited to public asset reads and internal CAS upload completions created by content plans.

Public assets are served at:
- `https://pr-<public_id>.run402.com/_blob/<key>` (auto-subdomain, always available)
- Any claimed subdomain at `<sub>.run402.com/_blob/<key>`
- Any mapped custom domain at `<your-domain>/_blob/<key>`

## Functions (Node 22 serverless)

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/functions/v1` | GET | SIWX or admin | List functions (wallet sees own, admin sees all). |
| `/functions/v1/:name` | GET / POST / PATCH / DELETE | apikey | Invoke. Sub-paths forwarded to the function. |
| `/projects/v1/admin/:project_id/functions` | GET | service_key | List deployed functions. |
| `/projects/v1/admin/:project_id/functions/:name` | PATCH | service_key | Change schedule / timeout / memory without redeploying code. Present `schedule` must be a cron string or `null`; present `config` must be an object. `config.timeout` and `config.memory` must be finite JSON integers within tier limits. |
| `/projects/v1/admin/:project_id/functions/:name` | DELETE | service_key | Delete a function. |
| `/projects/v1/admin/:project_id/functions/:name/trigger` | POST | service_key | Manually trigger (same as cron tick). Lifecycle-gated and counted against demo function-invocation limits. |
| `/projects/v1/admin/:project_id/functions/:name/logs` | GET | service_key | Recent CloudWatch logs. Query: `tail` (default 50, max 1000), `since` (inclusive epoch ms), `request_id` (`req_...`). Returns latest matching entries in chronological order with optional `event_id`, `log_stream_name`, `ingestion_time`, and `request_id`. |
| `/projects/v1/:project_id/functions/:name/rebuild` | POST | SIWX (owner) | Re-bundle ONE function from its stored source with deps pinned to their exact recorded versions — picks up a platform wrapper/runtime fix without editing source (`code_hash` unchanged, no new release). Returns `{ name, rebuilt, old_fingerprint, new_fingerprint, runtime_version_before, runtime_version_after, code_hash }`. Functions deployed before dependency locking return `409 CANNOT_REBUILD_UNLOCKED_DEPS`. |
| `/projects/v1/:project_id/functions/rebuild` | POST | SIWX (owner) | Re-bundle ALL functions in the project (same wrapper-only guarantee). Per-function failures are isolated and never abort the batch. Returns `{ rebuilt_count, total, results[] }` where each result is a rebuild record or `{ name, rebuilt: false, error, code? }`. |

**Refresh stale function runtimes (capability `function-runtime-rebuild`).** A platform-side fix to the function wrapper (e.g. the SSR `auth.*` / `ctx.host` fixes) only reaches a deployed function when it is re-bundled. Functions record a build fingerprint, so `GET /functions/v1` returns a per-function `runtime_stale` flag and `GET /agent/v1/operator/status` carries a `runtime` block (stale count + list). The two `rebuild` routes above are wallet-authed and ownership-checked; they re-bundle from your stored source with dependencies pinned to their exact recorded versions, so the only change is the gateway wrapper/runtime. Strictly opt-in (functions are never auto-rebuilt) and allowed during billing grace — they require wallet identity but **no** active tier.

Handler signature: `export default async (req: Request) => Response`.

`deps` accepts npm specs: bare names → latest at deploy time, pinned (`lodash@4.17.21`) and ranges (`date-fns@^3.0.0`) honored. Max 30 entries, 200 chars each. Native binary modules (`sharp`, native `bcrypt`, `canvas`) are rejected at deploy time. **Don't list `@run402/functions` in `deps`** — it's auto-bundled.

**Per-request context (`getRun402Context`).** Non-Astro Node22 functions (webhooks, auth endpoints, admin tools) read the per-request context the gateway populates as `x-run402-*` headers via the zero-dep `getRun402Context(request)` helper from `@run402/functions`. Returns the same shape `Astro.locals.run402` exposes — `{ requestId, projectId, releaseId, host, locale, defaultLocale }` — so Astro and plain-function code share one mental model. Header names stay private to the helper; if the gateway renames any `x-run402-*` header in v2, the helper signature is unchanged.

```ts
import { getRun402Context, routedHttp, text } from '@run402/functions';

export default routedHttp(async (req) => {
  const { requestId, locale, host } = getRun402Context(req);
  console.log(`[${requestId}] serving ${host} in ${locale ?? 'default'}`);
  return text(`Hello, ${host}`);
});
```

Accepts a Web `Request`, a `Headers` instance, or a plain `Record<string, string | string[]>` header map — covers `routedHttp`-wrapped handlers, raw envelope consumers, and pre-existing Node-style handlers without forcing a refactor. Missing or empty header values surface as `null` (never throws), so safe to destructure without guards.

Scheduled function tier limits: prototype 1 / 15 min, hobby 3 / 5 min, team 10 / 1 min. The gateway invokes scheduled functions with `X-Run402-Trigger: cron` and body `{ "trigger": "cron", "scheduled_at": "<ISO>" }`. Cold start ~2–2.5s; warm ~200–500ms; warm window ~5–15 min.

Function Web Routes expose a browser-visible request handle on every routed function response: `X-Run402-Request-Id: req_...`. Platform-generated routed errors and wrapper-generated uncaught function errors also include JSON `request_id`. To diagnose a browser 500, copy that value and fetch logs with `GET /projects/v1/admin/:project_id/functions/:name/logs?request_id=req_...`; pass `since=<epoch_ms>` for incidents older than the recent default lookup window. Public routed error bodies stay sanitized: stack traces, SQL details, secrets, cookies, authorization headers, payment headers, request bodies, and environment variables are not exposed to browsers.

`request_id` is the routed/function invocation correlation handle. `trace_id` below belongs to Run402-originated gateway error envelopes and is still the support handle for control-plane errors; do not use `trace_id` to search function logs.

### In-handler helpers

`@run402/functions` is auto-bundled. Inside a function:

```ts
import { auth, db, adminDb, email, ai } from "@run402/functions";

export default async () => {
  // `auth.requireUser()` redirects (HTML) or throws an R402_AUTH_REQUIRED
  // envelope (JSON) on anonymous requests. Don't catch — the platform
  // decides the response shape from the Accept header.
  const user = await auth.requireUser();

  // db() forwards the verified actor automatically — no .eq("user_id", ...)
  // needed because RLS already binds the visitor's rows via
  // run402.current_user_id() on the project schema.
  const mine = await db().from("items").select("*");
  await adminDb().from("audit").insert({ event: "items_read", user_id: user.id });
  return Response.json(mine);
};
```

- **`auth.user()`** — `Actor | null`. Triggers cache-bypass taint.
- **`auth.requireUser()`** — `Actor`. 303 / 401 on anonymous.
- **`auth.requireRole(role)`** / **`auth.requireMembership(m)`** — gate helpers; imply requireUser.
- **`auth.requireFresh({ maxAge, amr? })`** — per-AMR freshness step-up.
- **`auth.fetch(input, init?)`** — same-origin-only fetch with manual-redirect default.
- **`auth.csrfToken()`** / **`auth.csrfField()`** — double-submit token for hosted forms.
- **`auth.sessions.createResponseFromIdentity({...})`** / **`auth.sessions.endResponse()`** — custom identity bridge / sign-out.
- **`db(req?)`** — caller-context PostgREST. When called inside an SSR request with a verified actor, mints a 60s actor JWT automatically so `run402.current_user_id()` resolves in RLS.
- **`adminDb()`** — bypass RLS. Routes via `/admin/v1/rest/*` (gateway-internal).
- **`adminDb().sql(query, params?)`** — raw parameterized SQL.
- **`email.send(opts)`** — auto-discovers the project's mailbox.
- **`ai.translate(text, to, opts?)`** / **`ai.moderate(text)`** — see "AI helpers".

Hallucinated names (`getUser`, `getSession`, `currentUser`, `getCurrentUser`, `getServerSession`, `auth.protect`, `auth.signIn`, `auth.logout`, …) throw `R402_AUTH_UNKNOWN_EXPORT` with a structured fix-it pointing at the canonical helper.

`process.env.SECRET_NAME` for declared secrets. `process.env.RUN402_SERVICE_KEY` and `process.env.RUN402_API_BASE` are auto-injected.

### Lifecycle hooks

Functions named `on-<event>` are invoked on platform events. Currently supported: `on-signup` — fires after first user signup with body `{ "user": { "id", "email", "created_at" } }` and `X-Run402-Trigger: signup`. Fire-and-forget.

## Secrets

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/projects/v1/admin/:project_id/secrets` | GET | service_key or project_admin | List secret keys with metadata (`{key, created_at, updated_at}`). Values are write-only and never exposed (capability secrets-isolation, 2026-05-03). The legacy `value_hash` field was removed — there is no read-side surface for derived value information. |
| `/projects/v1/admin/:project_id/secrets` | POST | service_key or project_admin | `{ key, value }`. Key must match `^[A-Z_][A-Z0-9_]{0,127}$`. Value capped at 4 KiB UTF-8 (HTTP 413 `SECRET_VALUE_TOO_LARGE` over). Encrypted at rest via AWS KMS with `EncryptionContext: { project_id, key }`; decryption requires the same context, so a row copied across projects (or under a forged key) will not decrypt. |
| `/projects/v1/admin/:project_id/secrets/:key` | DELETE | service_key or project_admin | Delete. |

Secrets become `process.env.<KEY>` inside every function on next invocation. Tier limits: prototype 10, hobby 50, team 200.

## User auth (`/auth/v1/*`)

All `/auth/v1/*` endpoints require the project `apikey` header. Endpoints acting on a specific user additionally require `Authorization: Bearer <access_token>`.

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/auth/v1/signup` | POST | apikey | `{ email, password }`. With `service_key` + `is_admin: true`, creates a `project_admin` user. Public password signup is allowed only when project `public_signup` is `open`; service keys bypass that policy. |
| `/auth/v1/token` | POST | apikey | Password login. Returns `{ access_token, token_type, expires_in, refresh_token, user }`. JWTs include `amr`, `auth_time`, and `aal`; passkey sessions also include `passkey_id`. |
| `/auth/v1/token?grant_type=refresh_token` | POST | apikey | Refresh. Refresh tokens are single-use and preserve the original auth assurance metadata. |
| `/auth/v1/token?grant_type=authorization_code` | POST | apikey | Exchange OAuth code for tokens. |
| `/auth/v1/token?grant_type=magic_link` | POST | apikey | Exchange magic-link token for access_token. Response includes `magic_link: { intent, client_state, state_source, state_trusted }`. Trusted service-key invites may carry `amr: ["magic_link","trusted_invite"]` for first admin passkey bootstrap. |
| `/auth/v1/magic-link` | POST | apikey or service_key | Send passwordless link. `{ email, redirect_url, intent?, client_state? }`. `intent`: `signin` (default), `invite`, `claim`, `recovery`. `invite` requires a service key. Token single-use, 15-min TTL, rate limited per email/project/IP. |
| `/auth/v1/admin/users` | POST | service_key | Create or update a project auth user and optionally send a trusted invite. Lifecycle-gated for non-active projects and DB-rate-limited by project, email, and service-key identity. Body: `{ email, is_admin?, send_invite?, redirect_url?, client_state? }`. Returns `{ id, email, is_admin, email_verified_at, created, invite_sent }`. |
| `/auth/v1/oauth/google/start` | POST | apikey | Start Google OAuth flow. Returns `authorization_url`. PKCE. Allowed redirect origins: `http://localhost:*` + claimed subdomains + custom domains — auto-derived. |
| `/auth/v1/user` | GET | apikey + Bearer | Current user with linked identities and passkey state. Optional `?app_origin=` validates the app origin and returns `has_passkey_for_current_rp` + `current_rp_id`. |
| `/auth/v1/logout` | POST | apikey + Bearer | Invalidate refresh token. |
| `/auth/v1/sessions/end` | POST | none (tenant host) | Programmatic sign-out for the `@run402/functions` `auth.sessions.endResponse()` helper. Best-effort revokes the session in the `__Host-Http-r402_session` cookie (when present) and always returns a clear-cookie + `{ ok: true }`. Not apikey/CSRF-gated — the cookie is `SameSite=Lax`. Idempotent. |
| `/auth/v1/user/password` | PUT | apikey + Bearer | Change / reset / set password. |
| `/auth/v1/passkeys/register/options` | POST | apikey + Bearer | Create WebAuthn registration options. Body: `{ app_origin }`. Returns `{ challenge_id, options }`. |
| `/auth/v1/passkeys/register/verify` | POST | apikey + Bearer | Verify WebAuthn registration. Body: `{ challenge_id, response, label? }`. Returns passkey metadata. Rate-limited by project, user, RP ID, and IP before WebAuthn verification. Admin users on projects with `require_passkey_for_project_admin=true` need a recent passkey session to add additional admin-elevating passkeys. |
| `/auth/v1/passkeys/login/options` | POST | apikey | Create WebAuthn login options. Body: `{ app_origin, email? }`. Email hints are accepted without exposing `allowCredentials`, preserving account-enumeration resistance. |
| `/auth/v1/passkeys/login/verify` | POST | apikey | Verify WebAuthn login. Body: `{ challenge_id, response }`. Rate-limited by project, RP ID, IP, and invalid challenge attempts before challenge consumption. Returns the standard auth session response with `amr: ["passkey"]`, `aal: "aal2"`, and `passkey_id` in the access token. |
| `/auth/v1/passkeys` | GET | apikey + Bearer | List current user's active passkeys. |
| `/auth/v1/passkeys/:passkey_id` | DELETE | apikey + Bearer | Delete current user's passkey. For required-passkey admins, deletion requires recent passkey auth and cannot delete the last eligible admin passkey. |
| `/auth/v1/settings` | PATCH | service_key | Project auth settings. Lifecycle-gated for non-active projects. Body may include `{ allow_password_set, preferred_sign_in_method, public_signup, require_passkey_for_project_admin }`. `preferred_sign_in_method`: `password`, `magic_link`, `oauth_google`, `passkey`, or `null`. `public_signup`: `open`, `known_email`, `invite_only`. |
| `/auth/v1/providers` | GET | apikey | List enabled providers and auth settings: password, magic_link, passkey, password_set, oauth, and settings. |
| `/auth/v1/account/security` | GET | apikey + Bearer | Account security surface for the signed-in user: linked identities, registered passkeys, password-set state; with `?app_origin`, current-RP passkey availability. |

Passkey `app_origin` must be an exact allowed app origin: claimed `https://<subdomain>.run402.com`, the project's own `https://pr-<public_id>.run402.com`, active custom domains, or `http://localhost[:port]` when local origins are allowed. Paths, query strings, fragments, parent/sibling domains, wildcard hosts, trailing dots, userinfo, unvalidated `pr-*`, and `127.0.0.1` are rejected. If an HTTP `Origin` header is present, it must exactly match `app_origin`.

Access tokens: 1h JWT. Refresh tokens: 30d, single-use. Roles: `anon`, `authenticated`, `project_admin`, `service_role`. If `require_passkey_for_project_admin=true`, non-passkey admin logins are downgraded to `authenticated` and the session response includes `{ elevation_required: true, required_method: "passkey", effective_role: "authenticated", intended_role: "project_admin" }`.

### Hosted auth — account management & headless ceremony

Browser auth on `<project>.run402.app` (or a verified custom domain) is best driven by the `@run402/astro` components (`<SignIn>`, `<SignUp>`, `<UserButton>`, `<AccountSecurity>`). For non-Astro browser apps, the routes below are the **documented-advanced** JSON contract those components call: cookie-authenticated (the `__Host-Http-r402_session` browser-session cookie), with a double-submit CSRF token + same-origin `Origin`/`Referer` on every state-changing POST. The hosted HTML pages and the 303-redirect ceremony themselves (`GET/POST /auth/sign-in`, `/auth/sign-up`, `/auth/sign-out`, `/auth/re-auth`, the `/auth/magic-link` interstitial + its confirm/direct terminals, and the OAuth-start redirect) are the browser surface, not an agent API — machine clients use the `/auth/v1/*` JWT routes above.

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/auth/account/sessions` | GET | browser-session cookie | List the signed-in user's live sessions (the current one flagged). Read-only (no CSRF). |
| `/auth/account/sessions/revoke` | POST | browser-session cookie | Revoke one session by `{ session_id }`, scoped to the actor. |
| `/auth/account/sign-out-everywhere` | POST | browser-session cookie | Revoke every session except the current one. Returns `{ ok, revoked_count }`. |
| `/auth/account/password` | POST | browser-session cookie | Set/change password `{ new_password }` (≤72 bytes). Freshness step-up (5 min) else `R402_AUTH_FRESHNESS_REQUIRED`; rotates the user's other sessions. |
| `/auth/account/passkeys/remove` | POST | browser-session cookie | Remove a passkey `{ passkey_id }` (freshness-gated). Allow+warn if it leaves no password and no passkeys. To ADD a passkey use the register ceremony below. |
| `/auth/account/identities/unlink` | POST | browser-session cookie | Unlink a connected OAuth identity `{ provider, subject }` (freshness-gated); rotates other sessions. |
| `/auth/magic-link/send` | POST | None (host-resolved) | Email a single-use hosted magic link. Non-enumerating (identical 200 regardless); rate-limited. Body `{ email, return_to? }`. |
| `/auth/passkeys/login/options` | POST | None (host-resolved) | Hosted WebAuthn login options. Optional `{ email }` hint without exposing `allowCredentials`. |
| `/auth/passkeys/login/verify` | POST | None (host-resolved) | Verify the WebAuthn assertion, mint the browser-session cookie (`amr: passkey`), return `{ ok, redirect_to }`. No JWT — machine clients use `/auth/v1/passkeys/login/verify`. |
| `/auth/passkeys/register/options` | POST | browser-session cookie | Hosted WebAuthn registration options for the signed-in actor (user id from the session, never the body). |
| `/auth/passkeys/register/verify` | POST | browser-session cookie | Verify the registration `{ challenge_id, response, label? }`, persist the passkey, re-mint the session with `amr: passkey`. |

## Email & mailboxes

Each project can have up to 5 mailboxes at `<slug>@<domain>`. `<domain>` is the project's verified custom email sender domain (`internal.email_domains` row with `status='verified' AND inbound_enabled=TRUE`) when one exists, and `mail.run402.com` otherwise. On a verified custom domain, the reserved-slug blocklist (`info`, `support`, `help`, etc.) does NOT apply — the customer owns the namespace. Free with active tier. Creating a 6th returns 409.

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/mailboxes/v1` | POST | service_key | Create. `{ slug }`. Up to 5 per project; 409 at the cap. |
| `/mailboxes/v1` | GET | service_key | List project's mailboxes. |
| `/mailboxes/v1/:mailbox_id` | GET | service_key | Get details (address, usage, limits). |
| `/mailboxes/v1/:mailbox_id` | DELETE | service_key + lifecycleGate | Tombstone. Address reuse cooldown 90 days. |
| `/mailboxes/v1/:mailbox_id/messages` | POST | service_key | Send. Template or raw HTML; raw mode accepts up to 5 attachments, 15 MB total. |
| `/mailboxes/v1/:mailbox_id/messages` | GET | service_key | List sent messages. |
| `/mailboxes/v1/:mailbox_id/messages/:message_id` | GET | service_key | Get message with replies. |
| `/mailboxes/v1/:mailbox_id/messages/:message_id/raw` | GET | service_key | Raw RFC-822 bytes for DKIM / zk-email verification. Inbound only. Max 30 MB. |
| `/mailboxes/v1/:mailbox_id/webhooks` | POST | service_key | Register `{ url, events }`. Events: `delivered`, `bounced`, `complained`, `replied`. |
| `/mailboxes/v1/:mailbox_id/webhooks` | GET | service_key | List webhooks. Read-only; not lifecycle-gated. |
| `/mailboxes/v1/:mailbox_id/webhooks/:webhook_id` | GET | service_key | Get webhook. Read-only; not lifecycle-gated. |
| `/mailboxes/v1/:mailbox_id/webhooks/:webhook_id` | PATCH | service_key | Update url and/or events. |
| `/mailboxes/v1/:mailbox_id/webhooks/:webhook_id` | DELETE | service_key | Delete (404 if missing). |
| `/mailboxes/v1/:mailbox_id/webhooks/deliveries/:delivery_id/redrive` | POST | service_key | Re-queue a dead-lettered (`failed_permanent`) webhook delivery. Only dead-lettered deliveries can be redriven (else 409). Lifecycle-gated. Returns `{ status: "requeued", delivery }`. |
| `/mailboxes/v1/:mailbox_id/status` | POST | admin | Reactivate suspended mailbox (operator only). |

Two send modes for `POST /mailboxes/v1/:mailbox_id/messages`:

- **Template**: `{ to, template, variables, from_name? }` — templates: `project_invite` (`project_name`, `invite_url`), `magic_link` (`project_name`, `link_url`, `expires_in`), `notification` (`project_name`, `message` ≤500 chars).
- **Raw HTML**: `{ to, subject, html, text?, from_name? }` — `html` ≤1 MB, `subject` ≤998 chars. `text` auto-generated from HTML if omitted.

Tier limits: prototype 10/day, hobby 50/day, team 500/day. Unique recipients per lease: 25 / 200 / 1000.

### Custom sender domains

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/email/v1/domains` | POST | service_key | Register a sender domain. Body: `{ domain }`. Returns DKIM CNAMEs + recommended SPF/DMARC. |
| `/email/v1/domains` | GET | service_key | Verification status. |
| `/email/v1/domains` | DELETE | service_key | Remove (auto-disables inbound first). Lifecycle-gated for non-active projects. |
| `/email/v1/domains/inbound` | POST | service_key | Enable inbound on a verified custom domain. Returns the MX record. |
| `/email/v1/domains/inbound` | DELETE | service_key | Disable inbound. Lifecycle-gated for non-active projects. |

Once verified, all outbound email sends from `<slug>@<your-domain>` automatically. Custom-domain ownership is wallet-scoped — once verified by one project, sibling projects on the same wallet reuse it.

### Email packs

Tier daily limits are hard caps (10 / 50 / 500) protecting `mail.run402.com` reputation. To send more, register a custom sender domain AND buy email packs ($5 / 10,000, never expire). See "Billing" below.

## AI helpers

| Path | Method | Auth | Cost | Description |
|------|--------|------|------|-------------|
| `/generate-image/v1` | GET | None | Free | Endpoint info (pricing, aspect ratios). |
| `/generate-image/v1` | POST | x402 | $0.03 | Generate PNG. Body: `{ prompt, aspect? }`. Aspect: `square` / `landscape` / `portrait`. Returns `{ image: "<base64-png>", content_type, aspect }`. |
| `/ai/v1/translate` | POST | service_key | Add-on | Translate text. Body: `{ text, to, from?, context? }`. Max 10,000 chars. Invalid requests are rejected before consuming rate-limit budget. Returns `{ text, from, to }`. |
| `/ai/v1/moderate` | POST | service_key | Free | OpenAI categories. Body: `{ text }`. Invalid requests are rejected before consuming rate-limit budget. Returns `{ flagged, categories, category_scores }`. |
| `/ai/v1/usage` | GET | service_key | Free | Translation quota for the current billing period. |
| `/ai/v1/addons` | POST | admin | Free | Activate translation add-on for a project (operator only). `included_words` must be a positive safe integer. |
| `/ai/v1/addons` | DELETE | admin | Free | Deactivate translation add-on (operator only). |

Translation rate limits: 60 req/min translate, 120 req/min moderate, per project.

## KMS signers

AWS KMS-backed Ethereum wallets per project. **Private keys never leave KMS.** Pricing: **$0.04/day rental** + **$0.000005/call sign fee**. Wallet creation requires **$1.20 cash credit** (30 days prepaid). **Non-custodial** — see [terms](https://run402.com/humans/terms.html#non-custodial-kms-wallets).

| Path | Method | Auth | Cost | Description |
|------|--------|------|------|-------------|
| `/contracts/v1/signers` | POST | service_key + cash | Rent | Provision. Body: `{ chain, recovery_address? }`. Chains: `base-mainnet`, `base-sepolia`. Returns wallet with `non_custodial_notice`. |
| `/contracts/v1/signers` | GET | service_key | Free | List wallets (includes deleted). |
| `/contracts/v1/signers/:signer_id` | GET | service_key | Free | Metadata + live native balance + USD-micros (Chainlink price feed cached 5 min). |
| `/contracts/v1/signers/:signer_id/recovery-address` | POST | service_key | Free | Set/clear. Used at day-90 deletion to auto-drain. |
| `/contracts/v1/signers/:signer_id/alert` | POST | service_key + lifecycleGate | Free | Set non-negative integer wei threshold for low-balance email (24h cooldown). |
| `/contracts/v1/signers/:signer_id/drain` | POST | service_key + lifecycleGate | Sign + gas | Drain native balance. Header: `X-Confirm-Drain: <signer_id>`. Optional `Idempotency-Key`; reusing a key with different drain inputs returns 409 carrying the stored call's `status`/`call_error`/`tx_hash`, and a matched replay of a drain that failed before broadcast re-executes under the same `call_id`. **Works on suspended wallets** (the safety valve), but project lifecycle must still allow control-plane writes. |
| `/contracts/v1/signers/:signer_id` | DELETE | service_key + lifecycleGate | Free | Schedule KMS key deletion (7-day window). Header: `X-Confirm-Delete: <signer_id>`. Refused with 409 if balance ≥ dust; inconsistent wallet rows with no KMS key return a controlled repair error. |
| `/contracts/v1/call` | POST | service_key + lifecycleGate | Sign + gas | Submit write call. Body: `{ signer_id, chain, contract_address, abi_fragment, function_name, args, value_wei? }`; `contract_address` must be a valid EVM address and `value_wei` must be a non-negative decimal integer string or safe integer. Optional `Idempotency-Key` is request-fingerprinted; mismatched replays return 409 carrying the stored call's `status`/`call_error`/`tx_hash` (poll the `call_id` if it's in-flight; mint a new key if it's terminally failed). A matched replay of a call that failed before anything was broadcast (e.g. an estimate-gas revert) re-executes under the same `call_id`; a matched replay of a broadcast-phase or legacy failure returns the stored failure as 502 with `retryable: false` + a `new_idempotency_key` next-action. Returns 202 `{ call_id, tx_hash, status: "pending" }`. |
| `/contracts/v1/deploy` | POST | service_key + lifecycleGate | Sign + gas | Deploy a contract from the wallet (KMS-signs a tx with `to: null + data: bytecode`). Body: `{ signer_id, chain, bytecode, value_wei? }`; `bytecode` is the full creation calldata (creation bytecode + ABI-encoded constructor args, concatenated by the caller) as 0x-prefixed even-length hex ≤ 128 KB. Same auth, lifecycle, idempotency, and billing as `/contracts/v1/call` (one sign fee per deploy + gas at-cost). Returns 202 `{ call_id, tx_hash, status: "pending", contract_address }` — the `contract_address` is the deterministic CREATE address computed from `(wallet.address, nonce)` and returned **synchronously**, so the caller knows where the contract will live without waiting for confirmation. |
| `/contracts/v1/read` | POST | None | Free | Read-only call (anonymous, no signing, no billing). |
| `/contracts/v1/calls/:call_id` | GET | service_key | Free | Call status, gas used, gas cost USD-micros, receipt, error. |

Suspension: a wallet that can't cover the next day's rent is suspended (rejects `POST /contracts/v1/call` with 402). Reactivates on cash top-up. After 90 days suspended, the KMS key is permanently destroyed (7-day AWS deletion window). Funds-rescue: drain works on suspended wallets, and a `recovery_address` triggers auto-drain at day 90.

## Subdomains & custom domains

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/subdomains/v1` | POST | service_key | Claim or reassign. Idempotent — upserts. Auto-reassigns to latest deployment on subsequent deploys. Rules: 3-63 chars, lowercase alphanumeric + hyphens, no consecutive hyphens, must start/end with alphanumeric. Reserved: `api`, `www`, `admin`, `sites`, `mail`, `ftp`, `cdn`, `static`. |
| `/subdomains/v1` | GET | service_key or admin | List (service_key sees own, admin sees all). |
| `/subdomains/v1/:name` | GET | None | Lookup details (public). |
| `/subdomains/v1/:name` | DELETE | service_key or admin | Release. Lifecycle-gated for non-admin callers on non-active projects. |
| `/domains/v1` | POST | service_key or admin | Register a custom domain. Body: `{ domain, subdomain_name }`. Returns DNS instructions (CNAME + TXT verification). |
| `/domains/v1` | GET | service_key or admin | List custom domains. |
| `/domains/v1/:domain` | GET | service_key or admin | Status (`pending` / `active`). Service-key callers can read only domains owned by their project; admin callers can read any domain. |
| `/domains/v1/:domain` | DELETE | service_key or admin | Release. Lifecycle-gated for non-admin callers on non-active projects. |

Subdomains are reserved for the original owner during the 104-day grace; they become claimable 14 days after `purged`. Custom domains automatically follow the linked subdomain to the latest deployment.

## Apps marketplace (publish & fork)

| Path | Method | Auth | Cost | Description |
|------|--------|------|------|-------------|
| `/apps/v1` | GET | None | Free | List public forkable apps. `?tag=` filter. |
| `/apps/v1/:version_id` | GET | None | Free | Get app metadata: name, description, stats, required secrets, required actions, min tier, fork pricing. |
| `/projects/v1/admin/:project_id/publish` | POST | service_key | Free | Publish project as a forkable version. Body: `{ visibility?, fork_allowed?, description?, tags?, required_secrets? }`. |
| `/projects/v1/admin/:project_id/versions` | GET | service_key | Free | List published versions. |
| `/projects/v1/admin/:project_id/versions/:version_id` | PATCH | service_key | Free | Update metadata. |
| `/projects/v1/admin/:project_id/versions/:version_id` | DELETE | service_key | Free | Delete a version. |
| `/fork/v1` | GET | None | Free | Endpoint info. |
| `/fork/v1` | POST | SIWX | Free with tier | Fork a version. Body: `{ version_id, name, subdomain?, bootstrap? }`. If the source has a `bootstrap` function, it runs after fork; result appears as `bootstrap_result` (or `bootstrap_error`). |

Publishing snapshots schema (`pg_dump`), function source, site files (by deployment ID), and secret names (never values). **Not copied:** live data, secret values, auth users/sessions, storage uploads.

Fork creates a fully independent project: fresh DB with the same schema, functions redeployed, site redeployed, new keys, new budget, new URL. No shared state. Readiness statuses: `ready`, `configuration_required`, `manual_setup_required`.

## Billing (real-money tiers, Stripe alternative)

x402 is the default. Stripe is the alternative for humans who prefer credit cards.

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/orgs/v1/email` | POST | None | Create email-based organization. Body: `{ email }`. Idempotent — duplicate emails return the existing organization. Verification email links are currently disabled, so responses include `verification_sent: false` and `verification_supported: false`. |
| `/orgs/v1/lookup` | GET | Admin or SIWX | Look up an organization by `?wallet=0x..` or `?email=..` (exactly one). Returns `{ org_id, available_usd_micros, email_credits_remaining, tier, lease_expires_at, auto_recharge_enabled, auto_recharge_threshold }`. SIWX caller must match `?wallet`; `?email` lookups are admin-only. |
| `/orgs/v1/:org_id/billing` | GET | Admin or SIWX (linked) | Organization balance/tier/lease by id (UUID). The SIWX wallet must be linked to the organization. Use the `?wallet=`/`?email=` lookup above to resolve an `org_id`. |
| `/orgs/v1/:org_id/billing/history` | GET | Admin or SIWX (linked) | Recent ledger entries for the organization. |
| `/orgs/v1/:org_id/wallets` | POST | Admin or SIWX (= linked wallet) | Link a wallet to an organization (hybrid Stripe + x402). SIWX caller must match the wallet being linked. |
| `/orgs/v1/:org_id/checkouts` | POST | Admin or org role ≥ billing | Create a Stripe checkout for an organization. Body is `{ product: "balance_topup", amount_usd_micros, success_url?, cancel_url? }`, `{ product: "tier", tier, success_url?, cancel_url? }`, or `{ product: "email_pack", success_url?, cancel_url? }`. Amounts must be positive safe integers, at least 500,000, and in whole-cent increments. Return URLs must use trusted Run402 or localhost origins. Returns `{ org_id, product, checkout_url, topup_id }`. |
| `/orgs/v1/:org_id/billing/auto-recharge` | PATCH | Admin or org role ≥ billing | Enable auto-purchase on low email credits. Requires saved Stripe payment method. Body: `{ enabled, threshold? }`; `threshold` must be a non-negative safe integer. Unknown organizations return 404 `organization_not_found`. 3 consecutive failures auto-disable. |

Currency: micro-USD (1 USD = 1,000,000 micro-USD). Prototype testnet payment = 100,000 (testnet only); Hobby = 5,000,000; Team = 20,000,000.

Settlement headers on every paid response: `X-Run402-Settlement-Rail: allowance | x402` + `X-Run402-Allowance-Remaining: <micros>` (when allowance was used).

## Faucet (testnet)

| Path | Method | Auth | Cost | Description |
|------|--------|------|------|-------------|
| `/faucet/v1` | POST | None | Free | Get 0.25 USDC on Base Sepolia. Body: `{ address }`. Rate limit: 1 drip per IP per 24h. |

The faucet returns a `transaction_hash` immediately, but USDC is not spendable until the tx confirms (~5s). Wait for confirmation before subscribing — or `insufficient_funds` will fail your subscribe call.

## Utility

| Path | Method | Auth | Description |
|------|--------|------|-------------|
| `/.well-known/x402` | GET | None | x402 discovery — lists every paid endpoint with price + scheme. |
| `/health` | GET | None | Liveness probe used by ALB/ECS. Returns 200 `{"status":"healthy"}` when up, 503 `{"status":"unhealthy"}` otherwise. Per-dependency state and gateway version are admin-only (see operator endpoints in CLAUDE.md). |
| `/health/storage` | GET | None | Credential-free boolean storage probe for the off-AWS status monitor. Returns 200 `{"status":"ok"}` / 503 `{"status":"error"}`. Discloses no architecture detail (no bucket name, no `checks` map, no version). |
| `/ping/v1` | GET | SIWX | Validates SIWX. Returns the recovered wallet address. |
| `/message/v1` | GET | None | Endpoint info. |
| `/message/v1` | POST | SIWX | Send a message to the Run402 team (delivered via Telegram). Free with active tier. |
| `/agent/v1/contact` | GET | None | Endpoint info. |
| `/agent/v1/contact` | POST | SIWX | Register your agent's `{ name, email?, webhook? }` so we can reach you on platform events. New or changed emails start a reply challenge and return `assurance_level` (`wallet_only`, `email_pending`, `email_verified`, `passkey_pending`, `operator_passkey`) without exposing the challenge secret. |
| `/agent/v1/contact/status` | GET | SIWX | Current contact plus email/passkey binding state, proof timestamps, and cooldown retry timing. |
| `/agent/v1/contact/verify-email` | POST | SIWX | Start or resend the operator email reply challenge for the active contact email. Cooldown-aware; returns status. |
| `/agent/v1/contact/passkey/enroll` | POST | SIWX | Send a short-lived operator passkey enrollment link to the verified email. Requires `email_verified`; token is not returned to the agent. |
| `/agent/v1/contact/passkey/register/options` | POST | None | Browser endpoint for the emailed link. Body: `{ token, app_origin? }`. Returns `{ challenge_id, options }` for WebAuthn registration on the Run402 operator origin. |
| `/agent/v1/contact/passkey/register/verify` | POST | None | Browser endpoint for the emailed link. Body: `{ token, challenge_id, response, label? }`. Verifies WebAuthn registration with user verification and returns operator passkey metadata. |
| `/agent/v1/notifications` | GET | SIWX | Read the notification audit log. Paginated: `?type=...&since=<iso>&limit=N&offset=N`. Returns `{notifications: [{id, recipient_email, kind, event_type, channel, delivery_status, delivery_error, attempt_count, is_test, related_*, created_at, redacted_at, payload}], pagination: {...}}`. Redacted rows return `payload: null`. Single-wallet scope by default; cross-wallet rollup requires `email_verified`. |
| `/agent/v1/notifications/:notification_id` | GET | SIWX | Retrieve a single audit row by UUID. Same scoping rules as list. |
| `/agent/v1/notifications/preferences` | GET | SIWX | Read operator notification preferences: `{channels:{email,webhook}, webhook_url, webhook_signing_secret_configured, digest_cadence (off\|daily\|weekly\|monthly), digest_day_of_week (1=Mon..7=Sun), digest_hour_utc (0-23), threshold_alerts (off\|digest_only\|immediate), lifecycle_events (off\|critical_only\|all), security_events:"always", locale, timezone}`. |
| `/agent/v1/notifications/preferences` | PATCH | SIWX | Update preferences. Cross-wallet effects require `email_verified`. `webhook_url` changes require `operator_passkey`. `security_events != "always"` → 400. |
| `/agent/v1/notifications/test` | POST | SIWX | Trigger a real test send (audit row marked `is_test=true`). Requires `email_verified`. Rate-limited per wallet at 1/min (returns 429 + Retry-After). |
| `/agent/v1/webhook-secret/rotate` | POST | SIWX | Generate a new HMAC signing secret. Returned **exactly once** as `webhook_signing_secret`. Previous secret remains valid for `grace_window_hours: 24`. Requires `operator_passkey` assurance. |
| `/agent/v1/operator/status` | GET | SIWX | Compact operator-health snapshot: `{operator_contact:{email_status, passkey_status, recovery_gap}, critical_items[], skipped_notifications[], organizations[], projects[], active_thresholds[]}`. Consumed by `run402 doctor` + the MCP `get_operator_status` tool. |

Operator assurance is mailbox and credential continuity, not a humanhood or uniqueness claim. Phase 1 proves the submitted operator email can reply to Run402's challenge; phase 2 proves a passkey was enrolled through that verified email channel on the Run402 origin.

## Project transfer (v1.59)

Two-party SIWX-signed handoff between wallets. A contractor (wallet A) builds a project on Run402 for a company; when the contract wraps, A initiates a transfer to the company's wallet (B). B reviews the project's full footprint (custom domains, subdomains, function names, secret NAMES — never values, mailboxes, CI bindings to be revoked, KMS signers, billing implications) and accepts with their own SIWX. Either party can cancel; otherwise auto-expire at 72h.

| Endpoint | Method | Auth | Behavior |
|----------|--------|------|----------|
| `/projects/v1/:project_id/transfers` | POST | SIWX (owner/admin) or control-plane session (+ step-up) | Initiate. Body addresses the recipient by **exactly one** of `to_wallet` (wallet handoff → `/accept`) or `to_email` (email handoff → `/claim`), plus `{billing_policy?='migrate', message?, kysigned_record_id?, retain_collaborator?: { role: "developer" }}`. `retain_collaborator` is email-only. Both or neither → `400 VALIDATION_FAILED`. Wallet form returns `{transfer_id, expires_at, project_summary, your_unused_lease_days, lease_refundable:false, terms_sha256}`; email form returns `{status:'ok', transfer_id, to_email, expires_at}`. Errors: `400 INVALID_RECIPIENT`, `400 INVALID_BILLING_POLICY`, `403 FORBIDDEN`, `409 PENDING_TRANSFER_EXISTS`, `409 PROJECT_NOT_TRANSFERABLE`. |
| `/agent/v1/transfers/incoming` | GET | SIWX or control-plane session | Kind-agnostic inbox: pending transfers offered to the caller's wallet (`recipient_kind:'wallet'`) ∪ to the caller's verified emails (`recipient_kind:'email'`). Each entry carries `preview_path`. |
| `/agent/v1/transfers/outgoing` | GET | SIWX or control-plane session | Kind-agnostic outbox: wallet transfers the caller initiated ∪ email handoffs offered by orgs the caller owns/admins. |
| `/agent/v1/transfers/:transfer_id` | GET | SIWX or control-plane session (either party) | Kind-agnostic safe preview document: project_name, custom_domains, subdomains, functions, secret_names (NEVER values), mailbox_summary, ci_bindings_to_be_revoked, signers ([] in Phase 1A), github_repo_note, billing_implications, `retain_collaborator` (nullable), plus `recipient_kind` + `to_email` (email) or `to_wallet` (wallet). Errors: `403 FORBIDDEN`, `404 TRANSFER_NOT_FOUND`. |
| `/agent/v1/transfers/:transfer_id/accept` | POST | SIWX (= to_wallet) | **Wallet completion.** B accepts. Atomic transaction: org flip + grant/CI-delegate revoke + notification enqueue + secrets-rotation advisory stamp + audit row, all in one COMMIT. Returns `{project_id, from_wallet, to_wallet, new_organization_id, completed_at, secrets_rotation_advised:true, secret_names_inherited:[...], secrets_count_inherited, github_repo_note}`. Errors: `412 OPERATOR_EMAIL_NOT_VERIFIED`, `409 RECIPIENT_ORGANIZATION_NOT_ACTIVE`, `409 PROJECT_NOT_TRANSFERABLE`, `409 PROJECT_OWNER_CHANGED`, `410 TRANSFER_EXPIRED`, `409 TRANSFER_ALREADY_PROCESSED`, `409 WRONG_COMPLETION_FOR_TRANSFER_KIND` (email-addressed — claim it via `POST /agent/v1/transfers/:transfer_id/claim` on the same id), `404 TRANSFER_NOT_FOUND`, `403 FORBIDDEN`. |
| `/agent/v1/transfers/:transfer_id/claim` | POST | SIWX or control-plane session (addressed-email principal) | **Email completion.** Claim an email-addressed transfer. Body `{org_id?, accept_retained_collaborator?}` — an org you own, or omit to create a new wallet-less org. Same atomic flip + authority re-home + audit as `/accept`; `accept_retained_collaborator: true` opts into the previewed retained-developer membership. Returns `{status:'accepted', project_id, to_organization_id, created_new_org, retained_collaborator_principal_id}`. Errors: `409 WRONG_COMPLETION_FOR_TRANSFER_KIND` (wallet-addressed — use `/accept`), `409 TRANSFER_ALREADY_PROCESSED`, `410 TRANSFER_EXPIRED`, `412 OPERATOR_EMAIL_NOT_VERIFIED`, `403 FORBIDDEN`, `404 TRANSFER_NOT_FOUND`. |
| `/agent/v1/transfers/:transfer_id/cancel` | POST | SIWX (either party) or control-plane session (offering-org owner/admin) | Kind-agnostic cancel; routes by recipient kind. Body: `{reason?: string}`. Errors: `404`, `409 TRANSFER_ALREADY_PROCESSED`, `403 FORBIDDEN`. |

**Stale-offer safety.** Accept and cancel routes scope by `transfer_id`, NOT by `project_id`. If A creates t1 → cancels → creates t2, B accepting t1 returns `409 TRANSFER_ALREADY_PROCESSED` against t1 rather than silently accepting t2.

**Atomic accept transaction.** The wallet flip, CI binding revoke, notification queue inserts (one per recipient), and audit metadata all commit together. A crash before COMMIT rolls back everything; a crash after COMMIT leaves a consistent state. `clock_timestamp()` is used for expiry checks (NOT `NOW()` — `NOW()` is transaction-start time and can stale under lock waits). No `DELETE FROM organization_wallets` — would orphan A's other projects under v1.46 derived billing.

**Project state freeze while pending.** `transferFreezeMiddleware` blocks owner-side control-plane mutations on the project while a pending transfer exists. Returns `409 PROJECT_HAS_PENDING_TRANSFER` with `details.transfer_id` and `next_action.cancel_url`. Data-plane (`/rest/v1/*`, `/storage/v1/*`, function invocation, mailbox send/receive) and payment-path routes (`POST /tiers/v1/:tier`, `POST /orgs/v1/:org_id/checkouts`, `PATCH /orgs/v1/:org_id/billing/auto-recharge`) are explicitly NOT gated.

**KySigned Phase 1A stub.** The optional `kysigned_record_id` field is recorded as-is in Phase 1A without verification. Phase 1B (separate change `add-project-transfer-kysigned-attestation`) activates real on-chain SignatureRegistry presence check + canonical-hash comparison (RFC 8785 / EIP-712) + replay protection.

**What doesn't transfer.** A's on-chain balance (stays with A's wallet), A's prepaid tier lease (remains on A's organization; `your_unused_lease_days` surfaced in init response), A's `agent_contacts` (B has their own — that's why the verified-email pre-condition exists), A's GitHub repository (outside the platform; preview includes verbatim `github_repo_note`), and wallet-scoped KMS signers (stay with A). Secret VALUES transfer (B can read them); B is prompted via the persistent `secrets_rotation_advised_at` advisory until they re-write each inherited secret.

**72h expiry** is hard-coded in Phase 1A. Hourly sweep in `services/leases.ts` ticks expired pending rows to `status='expired'` and enqueues `project_transfer_expired` events to BOTH parties.

**Four notification events** (`project_transfer_initiated`, `_completed`, `_cancelled` are mandatory `recovery` class; `_expired` is optional `lifecycle`). All four enqueue INSIDE the same DB transaction as the state change so a crash between COMMIT and enqueue cannot drop the mandatory event.

**Modified responses** (additive — existing consumers ignore unknown fields):
- `GET /tiers/v1/status` returns `incoming_transfers[]` with `preview_path` per entry; each `projects[]` entry may include `secrets_rotation_advised: {advised_at, reason}` after accept.

## Operator Health Notifications (v1.55)

Unified substrate for operator-facing notifications — periodic digests, immediate lifecycle events, and (v1.5) threshold alerts. All routed through verified operator email (and optionally HMAC-signed webhook).

**Recipient resolution.** Every notification looks up the verified operator email via `agent_contacts.email WHERE email_verification_status='verified'`, joined through `organization_wallets` for organization events and `projects` for project events. When no verified recipient exists, the system persists a `missing_verified_recipient` audit row visible via `GET /agent/v1/notifications` and `run402 doctor` rather than silently dropping the event.

**Notification classes.** Two operator-facing v1 classes share one substrate:
- `digest` (cadence: weekly default, Monday 09:00 UTC) — leads with a single most-urgent item per the deterministic 5-tier ranking (imminent lifecycle transition > critical threshold > recovery rail gap > tight lease/balance > most-active project). All-clear weeks produce a three-line "all good" digest, not a skipped send.
- `lifecycle_event` (immediate) — `organization_past_due`, `organization_frozen`, `organization_purge_final_warning`, `organization_purged`, `rotation_*`, `webhook_disabled`, `balance_runway_critical`, `passkey_unused_warning`. (v1.57 renamed from per-project `project_*`; renderer still accepts the old names for in-flight queue items during the one-release compat window. Multi-wallet accounts deliver one notification per distinct verified email across all linked wallets.)

Threshold alerts are computed in v1 and surfaced in digest/`GET /operator/status`; immediate delivery ships in v1.5.

**Mandatory classes.** `security`, `recovery`, `billing_critical`, and `destructive_lifecycle` events fire regardless of preference toggles. They cannot be silenced by `cadence: off` or `lifecycle_events: off`; emails explain this in the body. Optional classes carry an RFC 8058 `List-Unsubscribe` header with one-click support.

**Fixed thresholds** (identical for all operators, with hysteresis):
- Storage: warn at 75%, critical at 90%, recovery below 70%
- API calls / month: warn at 80% (or projected exhaustion in 7d), critical at 95% (or projected in 48h)
- Emails / day: warn at 80%, critical at 95% (reset on daily quota reset)
- Wallet balance: warn when smoothed-burn runway < 7 days
- Tier lease: 14 / 7 / 1 days out
- KMS signer rent: less than 30 days covered

**Assurance ladder.** SIWX wallet auth → read own + organization-scoped notifications. `email_verified` → cross-wallet rollup reads + multi-wallet preference mutation. `operator_passkey` → webhook URL changes, secret rotation, recovery-adjacent settings.

**Webhook signing.** Stripe-shape `Run402-Signature: t=<unix>,v1=<hex>` where `v1 = HMAC_SHA256(secret, "${t}.${rawBody}")`. Receivers should reject `|now - t| > 5 minutes` for replay protection. Dual-secret 24h grace window after rotation (current + previous both accepted). Use the SDK helper:

```ts
import { verifyWebhook } from "@run402/functions";

export default async (req: Request) => {
  const rawBody = await req.text();
  const result = verifyWebhook(req.headers, rawBody, process.env.RUN402_WEBHOOK_SECRET!);
  if (!result.valid) return new Response(`bad signature: ${result.reason}`, { status: 401 });
  // …handle event…
  return new Response("ok");
};
```

**Webhook delivery safety.** HTTPS-only URLs. DNS re-resolution at every delivery attempt + every redirect target (defeats DNS rebinding). Blocks loopback, RFC 1918, link-local, cloud metadata (169.254.169.254), multicast, IPv6 ULA. 5s request timeout, 3 max redirects, 1 MiB response cap. 4xx (not 429) → permanent; 5xx + 429 + network → transient retry via the queue's exponential backoff (1m/5m/30m/2h/12h, max 5 attempts). Webhook auto-disables after 10 consecutive failures and emits a `webhook_disabled` security-class notification.

**Retention.** Delivery attempts: 90 days (payload redacted after, metadata kept through 365 days). Mandatory-class metadata: longer per legal policy. Test rows: 30 days. Purged projects leave redacted tombstone rows, never dangling FKs.

**Webhook payload shape.** `{id, type, created_at, schema_version: "1", idempotency_key, payload: {event_type, occurred_at, scope_kind, scope_id, metadata}}`. The `id` and `idempotency_key` are the same UUID, equal to the `operator_notifications.id` audit row, so receivers can dedupe across worker retries.

## Idempotency

All paid endpoints support `Idempotency-Key` header to prevent double-charging on retries. Same key + method + path = same response, no duplicate charge. Keys valid 24h.

Supported on: `POST /tiers/v1/:tier`, `POST /projects/v1`, `POST /apply/v1/plans/:plan_id/commit`, `POST /fork/v1`, `POST /generate-image/v1`, `POST /contracts/v1/call`, `POST /contracts/v1/signers/:signer_id/drain`. (`/apply/v1/plans` itself is naturally idempotent: same `(project_id, manifest_digest)` returns the same uncommitted plan within 24h.)

## Error envelope (canonical)

Every non-2xx JSON response carries the same envelope. **Branch on `code`, never on English `message`.**

```json
{
  "error": "payment_required",
  "message": "Project is frozen. Renew the wallet's tier to restore control-plane access.",
  "code": "PROJECT_FROZEN",
  "category": "lifecycle",
  "source": "gateway",
  "retryable": false,
  "safe_to_retry": true,
  "mutation_state": "none",
  "trace_id": "trc_0123456789abcdef0123456789abcdef",
  "details": {
    "project_id": "prj_...",
    "lifecycle_state": "frozen",
    "entered_state_at": "2026-03-20T14:22:00.000Z",
    "next_transition_at": "2026-04-19T14:22:00.000Z"
  },
  "next_actions": [
    { "type": "renew_tier", "method": "POST", "path": "/tiers/v1/hobby", "auth": "x402" },
    { "type": "check_usage", "method": "GET", "path": "/projects/v1/admin/prj_.../usage", "auth": "service_key" }
  ]
}
```

Canonical fields:

- `error` — short label; safe to surface in UI.
- `message` — human-readable explanation.
- `code` — stable UPPER_SNAKE_CASE branch key. **Branch on this.**
- `category` — `validation | auth | billing | quota | rate_limit | lifecycle | not_found | conflict | deploy | storage | upstream | internal`.
- `source` — `"gateway"` on every gateway-produced envelope (the run402 boundary: transport / JSON-parse / auth / rate-limit). An application or function error carries **no** `source` (or the app's own value), so a caller of a tenant function deterministically distinguishes a run402-boundary error from the app's own error. See **Boundary errors** below.
- `retryable` — retrying later may succeed without changing the request.
- `safe_to_retry` — repeating the request is not expected to duplicate or corrupt a mutation.
- `mutation_state` — `none | not_started | committed | rolled_back | partial | unknown`.
- `trace_id` — gateway error-envelope support handle; include when reporting Run402-originated control-plane issues.
- `request_id` — may appear on routed function responses, not in the canonical gateway envelope. Use it with function logs for routed/function diagnostics.
- `details` — structured cause/context; always an object.
- `next_actions` — `[{ type, method?, path?, auth?, why? }]`. `type` ∈ `retry | authenticate | submit_payment | renew_tier | check_usage | resume_deploy | edit_request | edit_migration | contact_support`.

### Retry semantics

- Validation, auth, not-found, conflict, payment, lifecycle, quota → `retryable: false`, `safe_to_retry: true`. Fix the request.
- `RATE_LIMITED`, `MIGRATE_GATE_ACTIVE` → `retryable: true`, `safe_to_retry: true`. Wait `retry_after` seconds, retry.
- 5xx on GET → `retryable: true`, `safe_to_retry: true`. Retry.
- 5xx on POST/PUT/PATCH/DELETE → `retryable: true`, `safe_to_retry: false`, `mutation_state: "unknown"`. Use `Idempotency-Key` to retry, or check state via the relevant GET first.

### Boundary errors — errors that can precede your function

A call to a tenant function can fail **before your handler runs**: the gateway parses the request body, authenticates the `apikey`/Bearer token, and applies rate limits at the **boundary**. Your function can't rewrap these — it never runs (auth is the gate) or never sees the raw bytes (the body is pre-parsed). Every such envelope is stamped `source: "gateway"`; an application error carries no `source`. The contract is two-layered: **run402 owns** transport / JSON-parse / auth / rate-limit; **your function owns** its domain errors. Branch on `source` to know which catalog to resolve against — run402's (these codes, at `run402.com/errors/#<CODE>`) or your app's.

Pre-handler boundary codes:

- `VALIDATION_FAILED` — 400 / 413 / 415. Unparseable JSON body, body over the size limit, or unsupported content encoding. `next_action`: send a well-formed JSON body (413 → route large bytes through `/apply/v1/plans`).
- `AUTH_REQUIRED` — 401. The `apikey` header (or Bearer token) is missing. `next_action`: authenticate with the project anon_key / JWT.
- `INVALID_AUTH` — 401. The `apikey`/token is present but malformed, expired, or signature-invalid. `next_action`: use a fresh anon_key / JWT.
- `RATE_LIMITED` — 429. Per-caller token bucket empty; honor `Retry-After` (refills once per second).

run402 keeps its own codes and does **not** mimic any app's vocabulary; adopting run402's canonical envelope shape for your own (post-handler) errors — so a caller sees one shape across both layers — is **recommended, not required**.

### R402_* SSR Runtime Codes (capability `astro-ssr-runtime`, v1.52)

Stable codes for Astro SSR build / runtime / cache / deploy failures. Each carries `code`, `message`, `suggestedFix`, `docs`, and (when statically determinable) `file`, `line`. Protocol-stable — emitted as the exact uppercase string in JSON envelopes, response headers, logs, and CLI output.

Error envelopes carry a `docs:` URL of the form `https://run402.com/errors/#<CODE>`. The HTML page at `run402.com/errors/` has real anchor IDs that scroll on click; the per-code section below mirrors the same content for agents reading this plaintext doc. Heading IDs are stable identifiers — never renamed without a major version bump.

#### R402_ASTRO_VERSION_UNSUPPORTED

Astro version outside the adapter's pinned peer range (`>=6.0.0 <7.0.0`). Thrown at the start of `astro:config:setup` before any other adapter work runs.

- **When:** Build start, when `assertAstroVersionSupported()` runs.
- **Fix:** Pin Astro to `^6` in `package.json`. The adapter re-validates before widening the range; track support state in `@run402/astro` CHANGELOG.md.

#### R402_ASTRO_DYNAMIC_IMAGE_UNSUPPORTED

Astro `<Image>` component with a runtime-resolved `src` (e.g., `<Image src={page.heroUrl}>`). Detected by source-tree scan before vite build.

- **When:** Build, by `detectDynamicImage()`.
- **Fix:** For CMS-driven runtime image refs, upload via `r.assets.put(file, { variants: ['webp', 'display_jpeg', 'blurhash'] })` and render an `<img>` against the returned `AssetRef.cdn_url` (or the `Run402Picture.astro` component if it ships in your version). Static-import form (`import hero from "../assets/hero.svg"; <Image src={hero} />`) is allowed.

#### R402_ASTRO_SERVER_ISLAND_UNSUPPORTED

Astro server-island directive (`server:defer` or `server:only`) detected. Server islands are deferred to a future Run402 release (v1.5+).

- **When:** Build, by `detectServerIslands()`.
- **Fix:** Use client islands (`client:load`, `client:idle`, `client:visible`) or move the rendering into the page's frontmatter. SSR is still the default — only the *island* mechanism is rejected.

#### R402_ASTRO_SESSIONS_UNSUPPORTED

Astro Sessions API used — either `Astro.session.*` in source files OR `experimental.session` in `astro.config.*`. Deferred to a future Run402 release.

- **When:** Build, by `detectSessionsApi()`.
- **Fix:** Use signed HTTP-only cookies via `Astro.cookies` or a custom DB-backed session via `db()`. Remove `experimental: { session: ... }` from your astro config.

#### R402_ASTRO_MIDDLEWARE_UNSUPPORTED

Astro middleware shape the SSR runtime can't honor (rare — most middleware passes through unchanged).

- **Fix:** Replace the unsupported middleware feature with one of the documented patterns in `kychee-com/run402` → `astro/README.md`.

#### R402_ASTRO_BUILD_FAILED

Catchall for `astro:build:*` hook failures not covered by a more specific code. Inspect `message` + log for the underlying cause.

#### R402_ASTRO_UNSUPPORTED_OUTPUT

`output: 'static'` configured but the project has SSR-only routes (or vice versa). Typically surfaces when migrating from a different Astro adapter.

- **Fix:** Use `output: 'server'` (the preset default) and mark per-route static via `export const prerender = true`.

#### R402_BUNDLE_NATIVE_DEP_UNSUPPORTED

Function bundle includes a native (`.node`) dependency that can't run on the Lambda runtime.

- **When:** Deploy, by the bundle scanner in `services/functions.ts`.
- **Fix:** Remove the native dep OR replace with a Run402 primitive (`r.assets.put` for image work, `r.ai.*` for ML inference, `r.email.send` for SES).

#### R402_BUNDLE_UNRESOLVED_IMPORT

User code imports a module name that's neither a Node builtin, `@run402/functions`, nor declared in the function's `--deps`.

- **Fix:** Add the dep to `--deps` (per-function package.json) OR remove the import.

#### R402_SNAPSTART_INIT_IO

Lambda SnapStart snapshot capture failed because user code performed network/DB IO at module scope.

- **When:** Deploy. The function still deploys and runs, but SnapStart cold-start optimization will not apply until the next deploy with module-scope IO removed.
- **Fix:** Move network / DB calls from module scope into the request handler (Astro frontmatter or APIRoute body).

#### R402_SDK_OUTSIDE_REQUEST_CONTEXT

A `@run402/functions` SDK call (e.g., `db()`, `getUser()`, `r.assets.put`, `r.cache.invalidate`, `r.email.send`) was made outside an active request context. The SDK uses AsyncLocalStorage to resolve `host`, `projectId`, auth state.

- **When:** Runtime, on any SDK call from a `setTimeout`, post-response background work, or module-scope IIFE.
- **Fix:** Move the call into a request handler OR pass an absolute URL where applicable (e.g., `r.cache.invalidate(new URL('https://eagles.kychon.com/the-guys'))`).

#### R402_SSR_RUNTIME_ERROR

Uncaught exception during Astro render. Public response carries only `code`, `message`, `requestId`, `releaseId` — no stack.

- **Fix:** Full stack trace via `run402 logs --request-id <req>` against the project. Filter by `request_id` in the function's CloudWatch log group.

#### R402_CACHE_UNSUPPORTED_VARY

Response carries a `Vary:` header value the cache layer can't safely partition on (e.g., `Vary: User-Agent`). Response is BYPASSED (not stored), but the request still serves normally.

- **Fix:** Drop the `Vary:` header OR limit it to one of the cache-aware values: `Accept-Encoding`, `Accept-Language`, `Cookie` (treated as auth-tainted), `x-run402-locale`.

#### R402_CACHE_AUTH_TAINTED

Informational diagnostic only — the cache layer is logging that this response was bypassed because user code called a payment / auth primitive during render. No fix needed unless you intended the response to be cacheable.

#### R402_CACHE_INVALIDATION_HOST_REQUIRED

`r.cache.invalidate(path)` called outside a request context with the path-string form. The SDK has no host to scope against.

- **Fix:** Pass an absolute URL — `r.cache.invalidate(new URL('https://your.run402.com/path'))` — OR move the call into a request handler.

#### R402_CACHE_INVALIDATION_HOST_FORBIDDEN

`r.cache.invalidate(...)` or `POST /cache/v1/invalidate` targeted a host that is not owned by the caller's project. Cross-project invalidation is rejected to preserve tenant isolation.

- **Fix:** Invalidate only hosts attached to your project (list via `r.domains.list()`).

#### R402_LOCALE_NOT_CANONICAL

A `spec.i18n.locales[]` entry or `spec.i18n.defaultLocale` isn't in RFC 5646 §2.1.1 canonical casing. The envelope's `fix:` field carries `{ input, canonical }` so an automated agent can apply the suggested fix without parsing the message.

- **When:** Deploy, at `/apply/v1/plans` validation (before any DB write).
- **Fix:** Use the canonical form named in the error message. Rules: primary language lowercase (`en`, `pt`, `zh`), 4-alpha script Titlecase (`Latn`, `Hant`), 2-alpha region UPPERCASE (`US`, `BR`, `GB`), 3-digit region preserved (`419`), variants + extensions lowercase. RFC 5646 §2.1 separator is `-` not `_`. The platform rejects rather than canonicalizes so your spec and DB-stored translation keys (`section_translations.language`, etc.) stay byte-identical — silent canonicalization on input would split the spec from the DB column.

#### R402_DEPLOY_STAGE_FAILED

A specific deploy stage (`stage` field on the envelope: `staging` / `migrating` / `schema_settling` / `activating`) failed. Mostly forward-fixable: re-apply with a corrected migration / spec.

- **Fix:** Stage-specific. Inspect `error.message` and `error.code` on the operation row via `GET /apply/v1/operations/:operation_id`.

#### R402_AUTH_REQUIRED / R402_AUTH_INSUFFICIENT_ROLE / R402_AUTH_INSUFFICIENT_MEMBERSHIP / R402_AUTH_FRESHNESS_REQUIRED

`auth.requireUser()` / `auth.requireRole(role)` / `auth.requireMembership(m)` / `auth.requireFresh({ maxAge, amr? })` failed. The platform decides the response shape from the `Accept` header: HTML requests get a 303 to `/auth/sign-in?returnTo=…` (or `/auth/re-auth` for freshness); JSON requests get the canonical 401/403 envelope.

- **Fix:** Don't catch. The platform handles redirect-vs-envelope automatically.

#### R402_AUTH_SESSION_EXPIRED / R402_AUTH_SESSION_INVALID

The `__Host-Http-r402_session` cookie failed strict parsing OR `expires_at` / `hard_expires_at` passed OR the keyed-HMAC verifier rejected it. Cookie is cleared on response so the browser drops it.

- **Fix:** User signs in again. If the parser regex is the issue (custom cookie minting?), use `auth.sessions.createResponseFromIdentity({...})` which produces a canonical cookie.

#### R402_AUTH_CSRF_ORIGIN_MISMATCH

Cookie-authenticated unsafe-method (POST/PUT/PATCH/DELETE) request whose `Origin` header doesn't equal the request's own origin (scheme + host + port). `Origin: null` (sandboxed iframes / opaque origins) always fails. Referer fallback uses full-origin equality (not host-only). Both absent → fails closed.

- **Fix:** Browser must submit from same origin. For a route that legitimately accepts cross-origin Bearer requests, declare `auth.precedence: "bearer"` (CSRF gate is cookie-only).

#### R402_AUTH_CSRF_TOKEN_MISMATCH

A hosted-auth form submitted without the platform CSRF token, or with a token that didn't match the double-submit derivation. Origin enforcement is the primary control; this token is defense in depth.

- **Fix:** Render forms with `auth.csrfField()` so the `_csrf` hidden input is present.

#### R402_AUTH_BEARER_COOKIE_MISMATCH / R402_AUTH_INVALID_BEARER

Cookie + Bearer both present and either pointing at different actors (`MISMATCH`) or the Bearer is malformed/expired alongside a valid cookie (`INVALID_BEARER`). Valid cookie + malformed Bearer rejects rather than silently proceeding as the cookie's actor.

- **Fix:** Send one credential, not both — or declare `auth.precedence` to opt out.

#### R402_AUTH_RETURN_TO_INVALID

A hosted-auth route received a `returnTo` value that wasn't either path-relative (begins `/` but not `//`) or absolute with origin equal to the current request origin. Rejected values: protocol-relative, foreign origins, embedded credentials, control characters, unsupported schemes.

- **Fix:** Pass a relative path (`/forum/topic-1`) or a same-origin absolute URL.

#### R402_AUTH_UNKNOWN_EXPORT

Consumer code accessed a hallucinated SDK name: bare imports like `getUser` / `getSession` / `currentUser` / `getCurrentUser` / `getServerSession`, or property access on the `auth` object like `auth.protect` / `auth.signIn` / `auth.logout` / `auth.middleware`. The `details.canonical_name` field carries the replacement.

- **Fix:** Use `auth.user()` / `auth.requireUser()` / `auth.requireRole(role)` / `auth.sessions.endResponse()`.

#### R402_AUTH_ACTOR_HEADER_SPOOF

A client-supplied reserved-prefix header (`x-run402-*` / `run402-*` / `x-r402-*` / `run402.actor.*`) reached the gateway. The header was stripped at ingress; the diagnostic is logged so spoof attempts surface in metrics.

- **Fix:** Don't set those headers from the client. The gateway populates them via its trusted ingress pipeline.

#### R402_AUTH_FETCH_ABSOLUTE_URL

`auth.fetch(input, init?)` rejected a URL synchronously (before network I/O). Rejected shapes: cross-origin absolute URLs, embedded credentials, non-HTTP(S) schemes (`javascript:`/`data:`/`file:`), protocol-relative URLs (`//evil/...`), subdomain spoofs, port mismatches.

- **Fix:** `auth.fetch` is for same-origin SSR fetches. Cross-origin calls go through your own service module.

#### R402_AUTH_IDENTITY_LINK_CONFLICT

`auth.identities.link({provider, subject, proof})` would create a duplicate `(project_id, provider, subject)` link.

- **Fix:** First valid linker wins; the second gets 409. UI surfaces "this identity is already linked to another principal" and offers a recovery flow.

#### R402_AUTH_SESSION_BRIDGE_UNVERIFIED

Either `auth.sessions.createResponseFromIdentity({...})` couldn't verify the supplied proof, OR consumer code tried to access an internal-only session-creation primitive via property access (`auth.sessions._unsafeCreate`).

- **Fix:** Supply a verifiable proof shape (`{kind: "siwx", signature, message, nonce?}` etc.). Raw-userId session minting is NOT in the public SDK.

#### R402_AUTH_UNKNOWN_IDENTITY

`auth.sessions.createResponseFromIdentity({...})` resolved the proof but no `internal.identities` row matched AND `createUser: true` was not set.

- **Fix:** Pass `createUser: true` if first-sign-in should create the user; otherwise route the visitor to a sign-up flow.

#### R402_AUTH_TENANT_SUFFIX_REQUIRED

The gateway refuses to set `__Host-Http-r402_session` on hosts under `*.run402.com` unless the project is in the internal staging allowlist. PSL-registered tenant suffix hosts (target: `*.run402.app`) and verified custom domains are always allowed.

- **Fix:** Move to a verified custom domain or wait for the project to be allowlisted.

#### R402_AUTH_REDUNDANT_USER_FILTER

`db()` query against an RLS-bound table included `.eq("user_id", user.id)` — RLS already filters via `run402.current_user_id()`. The redundant filter risks masking RLS misconfiguration.

- **Fix:** Remove the `.eq("user_id", ...)` filter. If the filter is intentional (e.g., admin cross-user query), add a `// run402-allow-user-filter: <reason>` annotation on the preceding line.

#### R402_AUTH_AUTHZ_VERSION_PROHIBITED

Consumer migration tried to `UPDATE internal.sessions SET authz_version = ...` directly. Only platform-owned grant-mutation triggers bump `authz_version`.

- **Fix:** Register your custom grants table in the project's authz manifest so the platform installs the trigger.

See also [`@run402/astro` README](https://www.npmjs.com/package/@run402/astro) and the CLI reference at `run402.com/llms-cli.txt` for the surrounding error-envelope shape + retry semantics.

### Code surface

`VALIDATION_FAILED`, `AUTH_REQUIRED`, `INVALID_AUTH`, `FORBIDDEN`, `ADMIN_REQUIRED`, `PAYMENT_REQUIRED`, `RATE_LIMITED`, `QUOTA_EXCEEDED`, `PROJECT_NOT_FOUND`, `RESOURCE_NOT_FOUND`, `PROJECT_PAST_DUE`, `PROJECT_FROZEN`, `PROJECT_DORMANT`, `MIGRATE_GATE_ACTIVE`, `PLAN_NOT_FOUND`, `OPERATION_NOT_FOUND`, `INVALID_STATE`, `NOT_RESUMABLE`, `MIGRATION_FAILED`, `MIGRATION_CHECKSUM_MISMATCH`, `STORAGE_UNAVAILABLE`, `UPSTREAM_UNAVAILABLE`, `INTERNAL_ERROR`.

### Passthrough boundaries

PostgREST-native errors on `/rest/v1/*`, function responses from `/functions/v1/:name`, and S3 responses to presigned PUT URLs are **not** wrapped — they're returned verbatim. Anything the gateway rejects before forwarding uses the envelope.

### 402 response shape (paid endpoints — x402 challenges only)

HTTP 402 is reserved for **x402 payment challenges** from `@x402/express`, on paid endpoints (`POST /tiers/v1/:tier`, `POST /generate-image/v1`, `POST /contracts/v1/signers`, `POST /contracts/v1/call`, `POST /faucet/v1`). When you call one without valid x402 payment:

```json
{
  "error": "Payment required",
  "message": "To set tier 'prototype', include x402 payment of $0.10 USDC.",
  "code": "PAYMENT_REQUIRED",
  "category": "billing",
  "retryable": false,
  "safe_to_retry": true,
  "mutation_state": "none",
  "trace_id": "trc_...",
  "details": { "tier": "prototype", "price": "$0.10" },
  "next_actions": [{ "type": "submit_payment", "auth": "x402" }],
  "accepts": [
    { "scheme": "exact", "network": "eip155:8453", "price": "$0.10", "payTo": "0x..." }
  ]
}
```

Application-level "you can't do this" errors (quota exceeded, lifecycle gating, insufficient balance, missing add-on) return **HTTP 403** with the same envelope shape. Examples: `code: QUOTA_EXCEEDED` for tier-limit overruns, `code: PROJECT_FROZEN` for grace-state lifecycle gating, `code: NO_ACTIVE_TIER` for wallet-auth without an active subscription. The `next_actions[].auth: "x402"` field still points clients at the actual paid endpoint for remediation. (Pre-2026-05-01 these returned 402; the SDK's `@x402/fetch` wrapper mis-parsed them as x402 challenges.)

### 503 — migrate gate active

`/rest/v1/*` and control-plane writes return 503 + `Retry-After` for ~60s during the migrate→activate window of a deploy. End-user data-plane traffic only sees this for the brief mid-flight schema window. Retry after `retry_after` seconds.

## Bundling, deps & function runtime details

User functions are bundled at deploy time with esbuild. `@run402/functions` is auto-bundled (the gateway depends on it as a registry npm package and esbuild inlines it). User-declared `--deps` are npm-installed into a per-deploy temp dir and esbuild-bundled alongside the user's code.

There is no Lambda layer step. Bumping `@run402/functions` in the gateway is a normal redeploy. The `internal.functions` table records `runtime_version` (the bundled `@run402/functions` version) and `deps_resolved` (actually-installed dep versions) on every deploy.

Hardening: per-deploy `npm install` runs with `--ignore-scripts`, an exact env allowlist (no AWS / RUN402 / DB env vars), public-registry-only enforcement plus a lockfile audit that rejects non-`registry.npmjs.org` transitives, recursive `.node` scan, total tmpDir cap of 200 MB, 60s timeout with process-group kill, and a 5-concurrent-deploy semaphore. The esbuild resolver plugin enforces user-source isolation: only Node builtins, `@run402/functions`, and declared `--deps` resolve.

## Wallet bootstrapping

You need a wallet with USDC on Base (real or testnet) to pay Run402. Three paths:

- **Coinbase AgentKit** — MPC wallet on Base with built-in x402 support. `npm create onchain-agent@latest`.
- **AgentPayy** — auto-bootstraps an MPC wallet on Base via Coinbase CDP.
- **Generate one yourself with `viem`**:

  ```bash
  npm install viem
  ```

  ```ts
  import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
  const privateKey = generatePrivateKey();
  const account = privateKeyToAccount(privateKey);
  // SAVE the private key securely.
  ```

For testnet, `POST /faucet/v1 { address }` requests 0.25 USDC from Base Sepolia.

## Two payment rails — same wallet key

- **x402** (default): USDC on Base. Standard HTTP 402 protocol.
- **MPP**: pathUSD on Tempo Moderato (testnet) / Tempo (mainnet). Stripe's Machine Payments Protocol.

The same wallet key works on both chains; switching rails just changes which chain pays.

## Where to go next

- Building in TypeScript? → <https://run402.com/llms-sdk.txt>
- Shell / CI / scripted agent? → <https://run402.com/llms-cli.txt>
- Claude Desktop / Cursor / Cline / Claude Code? → <https://run402.com/llms-mcp.txt>
- Wayfinder: <https://run402.com/llms.txt>
- OpenAPI: <https://run402.com/openapi.json>
- Latest changes: <https://run402.com/updates.txt>