@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/AUTHORING.md

@@ -41,9 +41,10 @@ rounds — weak models drop or corrupt it. Split the operation into a
 
 - The prepare operation is non-destructive. A start call takes only the
   scalar intent fields; every response returns a fresh `attempt_token`
-  referencing a server-side record (`ctx.choice.issue` with
-  `storage.mode: "server"`) that stores every settled decision. Continue
-  calls take `attempt_token` plus only the NEW answers.
+  referencing a server-side record (a `ctx.handle` draft kind from
+  `defineDraft`, declared on the schema with `kind.field()`) that stores
+  every settled decision. Continue calls take `attempt_token` plus only the
+  NEW answers.
 - `needs_input` rounds list only the still-pending selections; settled
   decisions may ride along in a display-only field but are never re-sent.
 - When nothing is pending, the prepare operation returns `status: "ready"`
@@ -55,15 +56,14 @@ rounds — weak models drop or corrupt it. Split the operation into a
   for what the user picked.
 - Expired or foreign tokens fail factually (nothing happened; start a new
   attempt with the scalar fields) — no answer salvage from a dead token.
-- **The provider must enforce consumption itself.** `ctx.choice` server
-  storage keeps tokens parseable until TTL — `parse` does not invalidate
-  them, so a confirm handler that only parses can be replayed into a second
-  booking or payment. After a successful execution, record the result under
-  the token's digest in `ctx.state` and make replays idempotent: a repeated
-  confirm returns the original created payload without touching upstream,
-  and later prepare rounds on the consumed token fail factually with the
-  existing reference. Record the result only after upstream success, so an
-  interrupted confirm stays retryable.
+- **Commit is one-shot with replay; providers no longer hand-roll dedup.**
+  `ctx.handle.read` and `ctx.handle.update` never consume a draft, so a
+  confirm handler must execute upstream work through `ctx.handle.commit`. It
+  runs the work once, stores the result under the handle, and a repeated
+  confirm returns `{ status: "replayed", result }` without touching upstream.
+  A failing upstream call restores the draft to `active`, so an interrupted
+  confirm stays retryable; later prepare rounds on a committed draft fail
+  factually with `HANDLE_COMMITTED`.
 
 The invariant behind all of it: complex flow state is the system's job, not
 the model's. The model carries exactly one opaque key between calls.
@@ -73,38 +73,303 @@ payment state tokens in the platform monorepo.
 
 ### Description template
 
-Every operation `description` MUST be at least 150 characters and follow this structure:
+Every operation declares a `descriptionKey`. Its English locale value should
+follow this structure:
 
 ```
 <What the tool does in one sentence>. Use when <specific scenarios>. Do NOT use for <counter-scenarios; point to alternatives>. Returns <key output fields>. <Important caveats: rate limits, auth, freshness>.
 ```
 
-Example:
+Example declaration and locale entry:
 ```ts
-description:
-  "Retrieves KMA ultra-short-term weather observation for a given grid coordinate in South Korea, " +
-  "including temperature, humidity, wind speed, precipitation, and sky condition. " +
-  "Use when the user asks about current or hourly weather at a specific Korean location. " +
-  "Do NOT use for forecasts beyond 2 days — use kma_mid_forecast instead. " +
-  "Returns hourly data in KST timezone; null values indicate data unavailable. " +
-  "Rate-limited to 1000 calls/day on the free tier.",
+descriptionKey: "operations.realtimeWeather.description",
+```
+
+```json
+{
+  "operations": {
+    "realtimeWeather": {
+      "description": "Retrieves KMA ultra-short-term weather observations for a South Korean grid coordinate. Use when the user asks about current or hourly weather. Do NOT use for forecasts beyond two days; use the mid-range forecast operation instead. Returns hourly KST data; null values mean unavailable data."
+    }
+  }
+}
 ```
 
 ### Language policy
 
-- **Structural text**: English (operation `description`, Zod `.describe()`, `whenToUse`, `whenNotToUse`, `derivations`, `inputExamples.scenario/rationale`).
-- **Values only**: native language (fixtures payloads, `inputExamples[].input` values like "대방동", "KRW-BTC", entity catalog entries).
+- **Structural text**: locale keys (`descriptionKey`, the other `*Key`/`*Keys`
+  fields, schema `.describeKey()`, and `examples[].scenarioKey`/`rationaleKey`).
+- **Values only**: native language (fixtures payloads and `examples[].input`
+  values like "대방동", "KRW-BTC", entity catalog entries).
 
 ### Required per operation
 
-- `description` — 150+ chars English (error-level rule)
-- Every Zod field in input AND output has `.describe()` including nested objects + array items (error-level rule)
+- `riskClass` — authored as `read`, `write`, `destructive`, or `external-send`
+- `descriptionKey` — backed by every required provider locale catalog
+- `connectionMode` — explicit for `credentials`, `oauth2`, and `oauth2_proxied` providers
+- Every Zod field in input AND output has `.describeKey()` including nested objects + array items (error-level rule)
 - `fixtures.request` + `fixtures.response` both present (error-level rule)
 - Exactly one of `healthCheck`, `healthCheckUnsupported`, or `healthJourneys[].coversOperations` coverage per operation. Prefer `healthCheck` for safe read-only upstream probes; use `healthCheckUnsupported` only with a specific reason for destructive, paid, credential-sensitive, flaky, or otherwise unsafe probes. Use a provider-level health journey when a destructive or credential-sensitive flow can be proven safely only as a multi-step boundary test, such as stopping at a payment WebView URL.
 
+### Capability declarations
+
+Declare each capability used by provider operations. Capabilities without
+configuration use a bare object, for example `http: {}`, `state: {}`, or
+`cache: {}`. `handle` is the exception: it takes an array of kinds
+(`handle: [WaitingDraft]`) and requires `state: {}` alongside it. `trace` is
+ambient and must not be declared: every operation
+context receives it. `allowedHosts`, `proxy`, `secrets`, and `context` declare
+policy or metadata only; they do not create context members and are not
+capability bindings.
+
+Declare `runtimeTarget: "vanilla"` for portable provider business logic. Use
+`runtimeTarget: "engine"` only for an approved session-bearing provider that
+must remain engine-resident. A vanilla target cannot declare `native`.
+
+Proxy vendor application keys, usernames, and passwords are engine-owned. Do
+not list `APIFUSE__PROXY__SMARTPROXY_APP_KEY`,
+`APIFUSE__PROXY__NODEMAVEN_USERNAME`, or
+`APIFUSE__PROXY__NODEMAVEN_PASSWORD` in provider `secrets`; `proxy` contains
+policy intent only.
+
+Hosted runtime settings are engine-owned as well: every `APIFUSE__CDP_POOL__*`
+variable, the Cloudflare OCR/STT tokens and account identifier,
+`APIFUSE__OCR__API_KEY`, and `APIFUSE__CACHE__KEY_PEPPER`. `defineProvider`
+rejects them in `secrets`; the engine reads them from its own environment.
+Provider code must not probe those names either — to learn whether OCR is
+configured, read `ctx.ocr.available` (see the OCR section below).
+
+### Engine mode
+
+Provider processes attach their capability bindings through an engine. Today the
+default is the in-process engine; ADR-0011 replaces it with the authenticated
+remote engine in a phased migration, and `serve` logs every boot as
+`provider_engine_mode` (`deprecated: true` for in-process). You do not need to
+change anything now.
+
+A deployment names the mode with the engine-owned `APIFUSE__ENGINE__MODE`
+variable (`in-process` or `remote`; trimmed and case-folded, blank means unset);
+hosts may pass `engineMode` to `serve`/`createServerApp`/`startDevServer`
+instead. The manifest wins when the two disagree, so provider code cannot
+silently downgrade what the deployment asked for; the disagreement is reported in
+the boot event's `warnings`. An unrecognized value is warned about and ignored —
+it never crashes the process. `APIFUSE__ENGINE__MODE` cannot be declared in
+`secrets` (`APIFUSE__ENGINE__*` is engine-owned).
+
+`remote` has no client in this release: the server attaches an engine that fails
+every request with `PROVIDER_ENGINE_MODE_UNSUPPORTED` and reports `503` on
+`/readyz`. It never falls back to in-process. `apifuse dev` and `apifuse record`
+refuse to start instead.
+
+`GET /health` is liveness only and stays engine-blind; `GET /readyz` reports the
+resolved engine attachment and is what readiness/startup probes should use — but
+only for a provider already pinned to an SDK release that serves the route.
+Earlier pins answer `404`, and a failing readiness/startup probe is not
+self-healing, so manifests move to `/readyz` after the pin wave, never before.
+
+`GET /__apifuse/diagnostics/runtime` is the internal runtime diagnostics route on
+the same listener. It answers one JSON report (`schemaVersion: 1`) sampled over a
+short window (`?windowMs=`, default 250, clamped to 50..5000): `cpu.window`
+(`process.cpuUsage()` delta as cores, user/system split), `cpu.lifetime`,
+`memory`, `eventLoop` (`performance.eventLoopUtilization`), `activeResources`
+(`process.getActiveResourcesInfo()` counts by type) and, on Linux, `procfs`
+with per-thread CPU ticks, context switches, wait channel and file-descriptor
+counts by kind from `/proc/self`. Bun 1.2 and 1.3 stub the two Node APIs, so
+their `reported` flag is `false` there; `cpu.window` and `procfs.threads`
+(sorted hottest first, named `bun`, `HTTP Client`, `HeapHelper`, ...) are the
+signals that tell an idle process that still burns CPU apart from a busy one.
+The route is read-only and carries no secrets. It is internal by the same
+boundary as `/health` and `/readyz`: the generated provider NetworkPolicy admits
+only the gateway on this port and the gateway dials canonical operation paths
+only, so operators reach it with `kubectl port-forward` and the tenant-facing
+API never does.
+
+### Deployment intent
+
+Deployment intent (runtime profile, resources, HPA, Redis, extra TCP ports) has
+exactly one authored home: the optional `deployment` key inside
+`defineProvider({...})`. The SDK passes it through verbatim; the APIFuse
+registry resolves omitted fields from the runtime profile and rejects anything
+it cannot resolve.
+
+- Declare only what differs from the profile. Profile defaults:
+  `runtime: "shared"`, `language: "typescript"`, `replicas: 1`,
+  `hpa: { enabled: true, minReplicas: 1, maxReplicas: 1, targetCPUUtilizationPercentage: 70 }`,
+  resources `25m/128Mi` (shared) or `200m/256Mi` (browser), `buildContext: "."`.
+  Most providers therefore declare no `deployment` key at all.
+- The deployment `runtime` axis (`shared | dedicated | browser`) is distinct
+  from the execution `runtime` (`standard | shared | browser`) declared next to
+  it.
+- Do not author a standalone `deploy.ts`, a `deployment` extra on a spread
+  default export (`export default { ...provider, deployment }`), or a
+  re-exported config module. A repository that still carries `deploy.ts`
+  migrates with `apifuse migrate-deployment .`: it hoists the file's non-default
+  values into the declaration, proves the result resolves identically, and
+  deletes the file. The `/deploy.ts` CODEOWNERS entry stays until the platform
+  stops honoring a re-added legacy file (`--drop-codeowners-lock` then). A
+  refusal names the manual step.
+- `apifuse check` warns during the migration window
+  (`deployment/legacy-deploy-file`, `deployment/spread-export`,
+  `deployment/redundant-default`); the rules become errors once no repository
+  carries the legacy file.
+
+```ts
+const buildProvider = defineProvider({
+  id: "example",
+  version: "1.0.0",
+  runtime: "standard",
+  deployment: { cache: { redis: { enabled: true } } },
+  // ...
+});
+```
+
 ### Factored operations
 
-Use `defineOperation()` when an operation is large enough to live beside helper functions or in a separate module. It preserves the same type inference as inline `defineProvider()` operations and can be placed directly in the provider `operations` map. `defineProvider()` accepts Zod and Standard Schema v1-compatible schemas. If config validation fails, the SDK names the field to fix, for example `runtime`, `auth.mode`, `operations.<id>.handler`, or `operations.<id>.fixtures.response`.
+`defineProvider(declaration)` returns the builder that accepts `operations`, so
+inline handlers are typed only after capability declarations are fixed. Export
+one declaration-derived context alias from the provider entry point:
+
+```ts
+import {
+  defineProvider,
+  type ProviderContext,
+  type ProviderDeclaration,
+} from "@apifuse/provider-sdk/provider";
+
+const declaration = {
+  // ...id, version, runtime, meta
+  http: {},
+} as const satisfies ProviderDeclaration;
+
+export type Ctx = ProviderContext<typeof declaration>;
+const buildProvider = defineProvider(declaration);
+```
+
+Separate operation files need one provider-local type import and no generic
+handler signature:
+
+```ts
+import { defineOperation } from "@apifuse/provider-sdk/provider";
+import type { Ctx } from "../index.js";
+
+export const search = defineOperation<Ctx>()({
+  // ...input, output, fixtures, health check
+  async handler(ctx, input) {
+    return fetchSearch(ctx.http, input);
+  },
+});
+```
+
+`ProviderContextOf<typeof buildProvider>` remains an equivalent convenience
+alias. Helpers should accept the one SDK client they use rather than the
+provider context. Zod and Standard Schema v1 schemas retain input/output
+inference. Invalid configs name the offending field, such as `auth.mode` or
+`operations.<id>.fixtures.response`.
+
+### Replay-safe fixtures
+
+Keep public operation schemas strict: date fields should accept absolute dates,
+not relative tokens. Inside `fixtures.request` only, the SDK resolves `+Nd` and
+`+Nd:YYYYMMDD` (1–365 days ahead) before import-time schema validation and
+stores the resolved request in provider metadata. Health-check case inputs use
+the same resolver when a probe runs. The default calendar is **KST**, including
+the 15:00–23:59 UTC window when KST is already on the next day.
+
+`fixtures.recordedAt` is the KST `YYYY-MM-DD` date when the response evidence
+was captured. It must be a real, non-future calendar date. Response date fields
+are expected to align with `recordedAt`, not with the newly resolved request;
+this permits stable recorded evidence alongside a replay-safe request.
+
+```ts
+const FlightInput = z.object({
+  departureDate: z.string().date(), // public calls remain absolute-date only
+});
+
+const searchFlights = {
+  input: FlightInput,
+  output: FlightOutput,
+  async handler(ctx, input) {
+    return fetchAndNormalizeFlights(ctx, input);
+  },
+  fixtures: {
+    request: { departureDate: "+45d" },
+    response: recordedFlightResponse, // dates reflect the capture below
+    recordedAt: "2026-07-15",
+  },
+  healthCheckUnsupported: { reason: "Upstream search is cost-bearing." },
+};
+```
+
+For code that explicitly calls the shared resolver, omit the third argument to
+use KST or pass `"UTC"` deliberately:
+
+```ts
+import { resolveHealthCheckInputDateTokens } from "@apifuse/provider-sdk/server";
+
+const kstInput = resolveHealthCheckInputDateTokens({ date: "+45d" });
+const utcInput = resolveHealthCheckInputDateTokens({ date: "+45d" }, new Date(), "UTC");
+```
+
+Do not re-resolve a health assertion's dates in UTC when its case input used the
+default KST calendar.
+
+### Sensitive vs public fields
+
+The platform fixture-privacy ratchet flags name-, phone-, and address-shaped keys
+unless the schema at that path declares them one way or the other. Declare every hit:
+
+- `sensitive(schema, kind)` / `fields.*()` — anything about a person: user, profile,
+  passenger, driver, or member names, emails, member ids, personal phone numbers.
+  Emits `x-apifuse-sensitive: true`; the value is redacted in published artifacts.
+- `publicField(schema)` — reviewed public data: business, shop, product, artist, or
+  facility names, hospital/hotel/station phones, timezone names. Emits
+  `x-apifuse-sensitive: false`; nothing is redacted. It is a review verdict, not a mute.
+  Credential-shaped keys (token, password, apiKey, …) cannot be declared public.
+
+Apply either helper to the leaf, before `.optional()`/`.nullable()`/`.default()`;
+`publicField()` over a wrapper that hides a `sensitive()` leaf throws at definition time.
+
+### Real-handler E2E in standard tests
+
+`runStandardTests(provider)` validates declarations and fixtures but reports a
+per-operation warning because it has no handler E2E coverage. Opt in with an
+`upstreamStub`: the runner calls each fixture-backed real handler with its
+already-resolved fixture request, routes ProviderContext upstream transports to
+the stub, and validates the result against the output schema. It never compares
+the result to the recorded response because that evidence belongs to
+`recordedAt`.
+
+```ts
+import { runStandardTests } from "@apifuse/provider-sdk/testing";
+import provider from "../index.js";
+
+runStandardTests(provider, {
+  upstreamStub: ({ transport, method, url }) => {
+    if (
+      transport === "http" &&
+      method === "GET" &&
+      url === "https://api.example.test/flights"
+    ) {
+      return Response.json({ flights: [{ id: "fixture-flight" }] });
+    }
+    return undefined; // fails the test: live-network passthrough is forbidden
+  },
+});
+```
+
+The stub also identifies `stealth`, `browser`, and `native` interactions. Return
+a Web `Response` or `{ status, headers, body }`; an unmatched call fails with
+the operation, transport, and method named in the error. Browser handlers expose
+method-level calls such as `goto`, `evaluate`, and `locator.click`, so provide a
+canned result for each method the handler uses. Native connections similarly
+identify `connectTcp`/`connectTls` and subsequent `write` calls. The offline
+`ctx.stealth` rejects a stealth-owned request header (`User-Agent`,
+`Sec-Fetch-*`, `sec-ch-ua*`, ...) with `STEALTH_HEADER_OVERRIDE_UNSUPPORTED`
+before calling the stub, through the same check the production transport runs,
+so a header spread from a shared constants module or read from a variable fails
+the test instead of the first production request. Direct global
+`fetch` or socket usage is outside this ProviderContext seam and should not be
+used by provider handlers.
 
 ### Health assertion context
 
@@ -130,15 +395,11 @@ healthCheck: {
 ```
 <!-- @magic-end:sample -->
 
-### Strongly recommended (warn-level rules)
-
-- `description` includes "use" AND "when" phrasing
-- `inputExamples` with 2+ scenarios for complex input (nested objects, enums, format-sensitive strings)
-- `derivations` for parameters not directly visible in the user query (e.g., `gridX` derived from geocoding)
-
 ### Optional but valuable
 
-- `annotations`: `{ readOnly, destructive, idempotent, openWorld, rateLimit }` — agentic safety signals
+- `examples`: usage examples with locale-keyed `scenarioKey`, an `input`, and optional `rationaleKey`
+- `approval`: only when it deliberately differs from the `riskClass` default (`read → never`, `write → risk-based`, otherwise `always`)
+- `titleKey`, `summaryKey`, `markdownKey`, `whenToUseKeys`, `whenNotToUseKeys`, and `normalizationNotesKeys`: locale-keyed operation prose
 - `tags`: operation-level semantic tags for retrieval (e.g., `["weather", "korea", "realtime"]`)
 - `relatedOperations`: `{ alternatives?: string[] }` — links to fallback/sibling operations
 
@@ -152,10 +413,12 @@ level, then call `ctx.stt` from operation handlers or auth-flow handlers.
 ```ts
 export default defineProvider({
   id: "example-provider",
-  // ...metadata, auth, operations, allowedHosts
+  // ...metadata, auth, allowedHosts
   stt: { mode: "required" },
+})({
   operations: {
     verifyAudioOtp: {
+      riskClass: "read",
       input: z.object({
         audioBase64: z.string().describe("Base64-encoded short OTP audio"),
         mediaType: z.string().optional().describe("Audio MIME type"),
@@ -216,6 +479,40 @@ Best-practice rules:
 - Submission checks and health checks must not invoke live STT by default.
   Provide explicit smoke evidence when a provider depends on audio OTP behavior.
 
+### OCR runtime capability: availability is the SDK's verdict
+
+Declare `ocr: { mode: "required" | "optional" }` and call `ctx.ocr` from
+operation handlers or auth-flow handlers. Whether a working backend is wired
+in is decided by the SDK, never by provider code: `ctx.ocr.available` is
+`true` when `createOcrClientFromEnv` found a configured backend and `false`
+for the unsupported/error client that undeclared or misconfigured providers
+receive. Branch on that flag for behavior that depends on OCR being present
+(for example, whether a CAPTCHA field is required from the user), and keep the
+`OCR_UNAVAILABLE` / `UNSUPPORTED_OCR_BACKEND` error fallback for the call
+itself: `available: true` promises a configured backend, not a successful
+upstream call.
+
+```ts
+async start(ctx) {
+  const image = await fetchCaptcha(ctx);
+  return ctx.auth.nextForm({
+    turnId: "credentials",
+    fields: {
+      captchaText: { type: "string", required: !ctx.ocr.available, /* ... */ },
+    },
+    data: { captchaImage: image, ocrConfigured: ctx.ocr.available },
+  });
+}
+```
+
+Do not re-implement the predicate by reading `APIFUSE__OCR__*` or
+`APIFUSE__CLOUDFLARE__ACCOUNT_ID`: those names are engine-owned, the
+runtime-boundary lint reports the read, and a drift between the copy and the
+SDK's own selection logic downgrades every login to the manual path silently.
+
+A custom `OcrContext` override (`serve({ ocr })`, `createFlowContext({ ocr })`,
+or a hand-written test double) must set `available` explicitly as a plain data
+property; the SDK's own clients do, and `bindOcrTelemetry` preserves it.
 
 ### Health journey DX for SMS/payment flows
 
@@ -273,15 +570,17 @@ const paymentWebviewJourney = defineHealthJourney({
 	],
 });
 
-export default defineProvider({
+const buildProvider = defineProvider({
 	id: "example-provider",
-	// ...metadata, auth, operations, allowedHosts
+	// ...metadata, auth, allowedHosts
 	healthJourneys: [paymentWebviewJourney],
 });
+
+export default buildProvider({ operations });
 ```
 <!-- @magic-end:sample -->
 
-The journey runner supplies `ctx.gateway`, `ctx.sms.waitForOtp()`, `ctx.journal.sideEffect()`, `ctx.state`, and `ctx.event.operation()` to the optional journey `run` function. Provider authors should keep `run` small: call the covered operations in step order, stop at the declared safe boundary, and let the generated health metadata carry schedule, timeout, required secret, and SMS matcher information to the health monitor.
+The journey runner supplies `ctx.gateway`, `ctx.sms.waitForOtp()`, `ctx.journal.sideEffect()`, `ctx.state`, and `ctx.event.operation()` to the required journey `run` function. Provider authors should keep `run` small: call the covered operations in step order, stop at the declared safe boundary, and let the generated health metadata carry schedule, timeout, required secret, and SMS matcher information to the health monitor.
 
 For authenticated journeys, open a fresh connection inside `run` with `ctx.gateway.connect({ input: { ... } })`, execute covered operations with the returned `connectionId`, and disconnect in a `finally` block. Do not require or store long-lived `HEALTH_MONITOR_*_CONNECTION_ID` secrets; those stale connection IDs can hide broken login ceremonies.
 
@@ -309,6 +608,287 @@ External contributors are expected to submit standalone Provider source plus:
 Maintainers own monorepo import under `providers/<id>/`, registry generation,
 deployment projection checks, and release workflows.
 
+### Error responses
+
+Provider-server failures use a stable public envelope:
+
+```json
+{
+  "error": {
+    "code": "UPSTREAM_ERROR",
+    "message": "The upstream service failed",
+    "requestId": "req_123",
+    "retryable": true,
+    "details": { "providerReason": "temporarily_unavailable" }
+  }
+}
+```
+
+`retryable` is always present on responses emitted by the current SDK. Set
+`retryable` in the `ProviderError` options when the provider knows the answer;
+an explicit `true` or `false` wins over the matching operation declaration and
+SDK derivation. When it is omitted, `operations.<id>.errorCodes[].retryable`
+is used for a matching provider-owned code, followed by SDK derivation (which
+defaults ordinary `ProviderError` values to `false`). During stateful rolling
+upgrades, the forwarding client also accepts an older owner response that omits
+`retryable` and treats it as `false` without loosening the emitted response
+contract. Existing optional `fix` guidance is also preserved when a
+`ProviderError` supplies it.
+
+`details` belongs exclusively to the provider. The server passes
+`ProviderError.options.details` through verbatim, including strings and arrays,
+and never merges, overwrites, or wraps it. Do not put SDK taxonomy fields there.
+SDK-owned validation and masked-internal-error paths retain their own diagnostic
+details.
+
+SDK observability is emitted separately in the
+`X-ApiFuse-Error-Observability` response header as compact, single-line JSON:
+
+```json
+{"category":"upstream_http","taxonomyVersion":"2026-05-26","retryable":true,"upstreamStatus":502}
+```
+
+Treat this header as telemetry, not as provider-controlled public error detail.
+It is SDK-owned even when a handler returns a raw `Response`: a caller-set
+header is dropped, and a raw status of 400 or above gets a status-derived one
+(retryable only for 408, 429, and 5xx) while the body is left untouched.
+Its category, taxonomy version, retryability, and optional upstream status match
+the structured `provider_request_failed` log event.
+
+Declare provider-owned operation failures directly on the operation. The
+server builds a lookup once at startup and applies it to failures from that
+operation:
+
+```ts
+errorCodes: [{
+  code: "ITEM_SOLD_OUT",
+  status: 409,
+  retryable: false,
+  description: "The upstream sold the item before checkout completed.",
+}],
+handler: async () => {
+  throw new ProviderError("Item sold out", { code: "ITEM_SOLD_OUT" });
+},
+```
+
+Declare only codes the SDK does not already register. `UPSTREAM_SCHEMA_ERROR`,
+`UPSTREAM_AUTH_ERROR`, and `INVALID_REQUEST` are registered below, so throwing
+them needs no declaration at all.
+
+`defineProvider` accepts only statuses the server can emit: 400, 401, 404, 429,
+500, 502, 503, and 504. Invalid declared statuses fail provider definition,
+not a live request. Status selection uses this order:
+
+1. SDK-owned errors retain SDK status semantics. Operation declarations cannot
+   override SDK-owned codes, stateful-forwarding failures, Zod/deadline errors,
+   or `TransportError` values.
+2. A matching operation `errorCodes` entry with `status` supplies the status.
+   This slot applies to `ValidationError` as well as ordinary `ProviderError`.
+3. The registered mappings below apply.
+4. Existing fallbacks apply: `TransportError` 502/504, unregistered input
+   `ValidationError` 400 (output validation 500), and other unregistered
+   `ProviderError` values 500.
+
+The registered mappings are:
+
+| Error code or fallback | HTTP status |
+| --- | ---: |
+| `AUTH_REQUIRED`, `reauth_required` | 401 |
+| `MISSING_SECRET`, `UPSTREAM_AUTH_ERROR`, `INVALID_REQUEST` | 400 |
+| `NOT_FOUND`, `not_found`, `NO_DATA` | 404 |
+| `RATE_LIMITED`, `UPSTREAM_RATE_LIMIT`, `LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR` | 429 |
+| `UPSTREAM_ERROR`, `BLOCKED`, `UPSTREAM_SCHEMA_ERROR` | 502 |
+| `STT_UNAVAILABLE`, `UNSUPPORTED_STT_BACKEND`, `STATEFUL_FORWARDING_REPLAY_CACHE_FULL` | 503 |
+| Unregistered input `ValidationError` code | 400 |
+| Other unregistered `ProviderError` code | 500 |
+
+A registered code that names an upstream outcome also carries a category. When
+a `ProviderError` (or any subclass, `ValidationError` included) with one of
+these codes sets no `category`, the server reports the code's category in
+`X-ApiFuse-Error-Observability`, and the public `source` follows from it:
+
+| Error code | Category when unset | `source` |
+| --- | --- | --- |
+| `NOT_FOUND`, `not_found`, `NO_DATA` | `upstream_http` | `upstream_failure` |
+| `RATE_LIMITED`, `UPSTREAM_RATE_LIMIT`, `LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR` | `upstream_rate_limited` | `upstream_rule` |
+| `UPSTREAM_REJECTED` | `upstream_rejected` | `upstream_rule` |
+| `UPSTREAM_ERROR` | `upstream_http` | `upstream_failure` |
+| `BLOCKED` | `anti_bot_blocked` | `upstream_failure` |
+| `UPSTREAM_AUTH_ERROR` | `upstream_auth` | `upstream_failure` |
+| `UPSTREAM_SCHEMA_ERROR` | `upstream_schema_drift` | `upstream_failure` |
+
+So `throw new ProviderError("…", { code: "UPSTREAM_SCHEMA_ERROR" })` is enough
+for the health monitor to grade a drifted upstream `down`; without the
+category it would be served as `source: "apifuse"` and graded unknown. An
+explicit `category` always wins, an operation-declared rejection status
+(409/410/422) still classifies as `upstream_rejected`, and retryability does
+not follow the category: it stays the instance option, then the declaration,
+then `false`. Every other code, including `AUTH_REQUIRED`, `INVALID_REQUEST`,
+and your own codes, is classified as before (`provider_error` unless you set a
+category).
+
+An unregistered non-validation `ProviderError` code returns HTTP 500 and emits
+the greppable `unregistered_provider_error_code` signal with the code in the
+structured failure log. A matching operation declaration, including one that
+omits `status`, makes the code registered for this signal and may independently
+supply `retryable`. The HTTP 400 `ValidationError` behavior is only the fallback
+when neither an operation status nor a registered mapping applies.
+
+Throw the domain `ProviderError` directly. Subclassing or wrapping it as a
+`TransportError` solely to preserve a 5xx response is obsolete; declare the
+domain code's `status` instead. Genuine `TransportError` values remain
+SDK-owned and keep their 502/504 mapping.
+
+#### Three fleet-consensus codes are registered
+
+`UPSTREAM_AUTH_ERROR` (400), `UPSTREAM_SCHEMA_ERROR` (502), and
+`INVALID_REQUEST` (400) are registered mappings. All three are non-retryable.
+
+- `UPSTREAM_AUTH_ERROR` is 400, not 401 or 502, because it means the upstream
+  refused a *platform-managed* service key. The caller holds no credential, so
+  401 ("re-authenticate") asks for something the caller cannot do, and 502
+  ("the upstream is sick") promises a recovery that will never arrive. It is a
+  deployment/config defect, exactly like `MISSING_SECRET`. The status is about
+  what the caller can do; the attribution is still the upstream's, since the
+  upstream is what refused the key, so the category is `upstream_auth`.
+- `UPSTREAM_SCHEMA_ERROR` is non-retryable: a retry returns the same payload
+  the provider already could not normalize.
+- `INVALID_REQUEST` is the spelling for caller-side bad input. `INVALID_INPUT`,
+  `VALIDATION_ERROR`, and `BAD_REQUEST` are not registered.
+
+Like `UPSTREAM_ERROR` and `BLOCKED`, these are thrown by provider code rather
+than by the SDK, so they are registered mappings and not SDK-owned codes: an
+existing operation declaration still wins at runtime (step 2 above). Registering
+them therefore never rewrites a status you already declared. What it does do is
+let you delete the declaration — and when your declaration disagrees with the
+registered mapping, `apifuse check` reports it rather than leaving the fleet
+answering one code two ways:
+
+- `error-code-status-conflicts-sdk` — declared `status` differs from the
+  registered status.
+- `error-code-retryable-conflicts-sdk` — declared `retryable` differs from the
+  registered retryability.
+
+Both are warnings. Drop the conflicting field so the SDK supplies the value, or,
+if your operation genuinely means something else, throw a distinct code that
+says so.
+
+### Localized error messages (`messageKey` / `fixKey`)
+
+The positional `ProviderError` message stays **English**. It is what
+`error.message`, cause frames, the `provider_request_failed` log, OTLP
+attributes and tests see. Only two fields of the response body are localized:
+`error.message` and `error.fix`. Nothing else — not `code`, not `details`, not
+`errorCodes[].description`, not the `X-ApiFuse-Error-Observability` header.
+
+Attach locale keys instead of parsing `Accept-Language` yourself:
+
+```ts
+// locales/en.json
+{ "errors": { "upstreamSchema": {
+    "message": "{provider} returned an unexpected response.",
+    "fix": "Retry in a few minutes."
+} } }
+```
+
+```ts
+throw new ProviderError("The culture data service returned an unexpected response.", {
+  code: "UPSTREAM_SCHEMA_ERROR",
+  messageKey: "errors.upstreamSchema.message",
+  fixKey: "errors.upstreamSchema.fix",
+  params: { provider: "Culture Data" },
+});
+```
+
+Keys can also live on the declaration, which localizes **every** site that
+throws that code without touching the throw sites:
+
+```ts
+errorCodes: [{
+  code: "UPSTREAM_SCHEMA_ERROR",
+  description: "The upstream response no longer matches its schema.",
+  messageKey: "errors.upstreamSchema.message",
+  fixKey: "errors.upstreamSchema.fix",
+}],
+```
+
+`status` and `retryable` are omitted because `UPSTREAM_SCHEMA_ERROR` is a
+registered code: the SDK already supplies 502 and non-retryable, and declaring
+a different value trips `error-code-status-conflicts-sdk` /
+`error-code-retryable-conflicts-sdk`. A declaration that carries only keys is
+still worth writing — it localizes every site that throws the code.
+
+Resolution order per field, evaluated at serve time:
+
+1. the throw site's `messageKey` / `fixKey`;
+2. the matching `errorCodes[]` entry's `messageKey` / `fixKey`;
+3. the derived `errors.<code>.message` / `errors.<code>.fix` (the code is used
+   verbatim as a catalog segment, so `errors.UPSTREAM_SCHEMA_ERROR.message`
+   works with no declaration at all);
+4. the English literal passed to the constructor.
+
+Each candidate is resolved in the caller's locale first and then in `en`, so a
+more specific key always beats a more specific locale. A missing key, a
+malformed key, a non-string catalog value or an absent catalog is a miss, never
+a throw: the caller always gets text. Steps 2 and 3 do not apply to SDK-owned
+failures (transport, Zod, stateful deadline, SDK runtime codes) — a provider
+catalog must not be able to relabel `Request timed out`.
+
+**Key grammar.** A locale key is dot-separated segments. Every segment is
+camelCase (`upstreamSchema`, `whenToUse`) or an array index (`0`), and the
+first segment is always a camelCase namespace. The one exception is the segment
+directly under `errors`, which may also be the error code spelled the way it is
+thrown — `errors.UPSTREAM_SCHEMA_ERROR.message`, `errors.BLOCKED.fix`,
+`errors.reauth_required.message`. Both spellings work, so
+`errors.upstreamSchema.message` and `errors.UPSTREAM_SCHEMA_ERROR.message` are
+equally legal keys; write the code form when you want the key to match the
+derived path in step 3. Nothing else loosens: a space, a dot inside a segment,
+an empty segment, a mixed-case or hyphenated code, and a leading digit are all
+still malformed.
+
+Locale negotiation reads `Accept-Language` from the request envelope's
+`headers` map first (the gateway stamps the flow's locale there) and then from
+the HTTP header, honours quality values, matches on the primary subtag, and
+supports `en`, `ko`, `ja` with `en` as the default. A request with no
+`Accept-Language` therefore keeps serving the `en` catalog value, so existing
+contract fixtures do not churn.
+
+**Interpolation.** `{name}` placeholders, `{{` and `}}` for literal braces.
+`params` accepts strings and finite numbers only. A placeholder with no usable
+param is left verbatim so the authoring gap is visible rather than silently
+deleting text.
+
+**Params are untrusted.** Upstream error text routinely ends up in `params`, so
+every string value is scrubbed before substitution: secrets and e-mail
+addresses redacted, control/bidi/newline characters encoded or collapsed,
+`<`, `>` and backticks removed, HTML-entity ampersands (`&lt;`) neutralized
+while ordinary ampersands survive, and the value capped at 200 characters.
+Substituted text is never rescanned, so a value containing `{other}` cannot
+trigger a second interpolation round. Prefer `details` when you need to relay
+an upstream body verbatim; `params` is for short, bounded values.
+
+**Catalog loading.** Catalogs are read once when the server is built (from the
+provider directory's `locales/{en,ko,ja}.json`, loading only the locales that
+exist). Pass `serve(provider, { localeCatalogs })` to bundle them instead. A
+catalog that exists but cannot be parsed logs one
+`provider_locale_catalogs_unavailable` warn at boot and every field falls back
+to its English literal.
+
+**Lint.** `apifuse check` reports:
+
+- `error-locale-key-missing` / `error-locale-key-malformed` (**error**) — a
+  literal `messageKey`/`fixKey`, on a throw site or on an `errorCodes[]` entry,
+  that `locales/en.json` does not resolve to non-empty text, or that is not a
+  legal locale dot path (see **Key grammar** above).
+- `thrown-error-message-not-localized` (**warn**) — a throw site whose declared
+  code has no key anywhere and no `errors.<code>.message` in `en`, so it is
+  served untranslated. Warning during the migration; promoted to error per
+  provider as each wave lands.
+
+`ko`/`ja` coverage needs no new rule: `en` is the baseline, so the existing
+catalog parity and placeholder checks already fail an `errors.*` key that is
+missing or untranslated in `ko`/`ja`.
+
 ### Declared secrets are SDK-enforced
 
 Environment/secret presence validation is single-sourced in the SDK. Declare
@@ -327,12 +907,12 @@ secrets: [
 The runtime validates every `required: true` declaration before any operation
 handler or auth-flow handler (except `abort`) runs. When a required secret is
 unset or whitespace-only, the invocation fails with the canonical structured
-error — code `MISSING_SECRET`, HTTP 400, `details.category:
-"credential_unavailable"`, `retryable: false`, and a `fix` naming every missing
-secret — across `/v1/{operation}`, self-test probes, `apifuse perf`, and
-`apifuse record`. The server also emits a `provider_secrets_missing` warn log
-at boot so unprovisioned deployments are visible immediately without crashing
-the pod.
+error — code `MISSING_SECRET`, HTTP 400, top-level `retryable: false`, and a
+`fix` naming every missing secret — across `/v1/{operation}`, self-test probes,
+`apifuse perf`, and `apifuse record`. Its error-observability header carries the
+`credential_unavailable` category. The server also emits a
+`provider_secrets_missing` warn log at boot so unprovisioned deployments are
+visible immediately without crashing the pod.
 
 Provider-local presence re-validation is **deprecated**: do not write
 `requireServiceKey`/`requireApiKey`-style guards that re-check `ctx.env.get()`
@@ -362,6 +942,157 @@ Note the asymmetry: the gate treats whitespace-only values as missing, but
 `ctx.env.get()` still returns the raw value to handlers — trim at the point of
 use if the upstream is whitespace-sensitive.
 
+### Runtime boundary: no `process.env`, `node:fs`, `child_process`, or raw `fetch()`
+
+Provider runtime code reaches the outside world through the context only:
+`ctx.http` / `ctx.stealth` for HTTP, `ctx.browser` for browser work,
+`ctx.env.get()` / `ctx.credential` for configuration and secrets, `ctx.files` /
+`ctx.cache` / `ctx.state` for data that must outlive a request. Ambient Node
+and Bun globals bypass `allowedHosts`, proxy policy, retries, redaction, the
+secret presence gate, and telemetry. `apifuse check` reports them at **error**
+level — a finding fails `apifuse check` and `apifuse submit-check`, in the
+official and the bounty `standalone` mode alike (the level was `warn` for one
+release as a migration window; the window closed once the fleet's request-path
+hits were fixed or acknowledged — a provider that still carries one sees
+`apifuse check` fail on its next SDK bump and fixes or acknowledges it in that
+same PR):
+
+- `process-env-direct-read` — `process.env.X`, `process.env["X"]`, a bare
+  `process.env` object use, `Bun.env`. The `APIFUSE__RUNTIME__*` bootstrap
+  family (`APIFUSE__RUNTIME__PORT`, `…POD_ID`, `…POD_ENDPOINT`) is exempt
+  everywhere; every other value is declared in `defineProvider` under
+  `secrets: [{ name, required }]` and read with `ctx.env.get(name)`. The names
+  visible to `ctx.env.get` are exactly the declared `secrets[].name` (minus
+  engine-owned names; an `oauth2_proxied` auth flow additionally sees
+  `APIFUSE__AUTH_PROXY__URL`). `env: true` (or `env: {}`) is the capability
+  declaration that turns the `ctx.env` binding on — a type *and* runtime gate,
+  since touching `ctx.env` without it throws `PROVIDER_CAPABILITY_UNDECLARED`
+  — and does not widen the readable names. Test/E2E toggles are not secrets
+  and cannot move to `ctx.env`: replace them with test doubles (inject
+  `ctx.env` / `ctx.http`) or recorded fixtures.
+- `node-runtime-module-import` — value imports of `fs`, `fs/promises`, `net`,
+  `tls`, `dgram`, `http`, `https`, `http2`, `child_process` (with or without
+  `node:`), and `Bun.spawn` / `Bun.spawnSync` / ``Bun.$` ` `` / `Bun.file` /
+  `Bun.write`. Type-only imports (`import type`, or every binding inline `type`) are ignored; `node:path`, `node:crypto`,
+  `node:url` are fine.
+- `direct-fetch-call` — the global `fetch()` (also `globalThis.fetch`).
+  `ctx.stealth.fetch()` never matches, nor does a call to a `fetch` binding
+  declared in an enclosing scope (parameter, variable, import, catch clause).
+  The check is lexical: a wrapper that takes `fetch` as a parameter does not
+  hide a global `fetch()` in another function of the same file.
+
+Scope is runtime source only: tests, recorded fixtures, `.d.ts`, the root
+`dev.ts` / `start.ts` / `deploy.ts` entrypoints, and the `scripts/`, `tools/`,
+`bin/` directories at the provider root are not scanned. Keep fixture
+recorders, smoke scripts, and other operator tooling under `scripts/`, and do
+not import from there in request-path modules. `apifuse check` also leaves out
+any directory that is itself a git checkout (a linked worktree such as
+`.worktree/<branch>/`, a nested clone, an initialised submodule): its files are
+another revision, checked in that checkout, not this provider's runtime source.
+
+Acknowledge a deliberate exception on the finding line or the comment-only
+line above it with `// @apifuse-allow <rule>: <reason>`; the finding then
+appears as an `INFO` audit line instead of an error, and the check passes.
+
+```ts
+// Before: request-path module reads the ambient environment and the disk
+import { mkdir, writeFile } from "node:fs/promises";
+const serviceKey = process.env.EXAMPLE_SERVICE_KEY;
+if (process.env.EXAMPLE_DIAG_TAP_DIR) {
+  await writeFile(`${process.env.EXAMPLE_DIAG_TAP_DIR}/booking.json`, JSON.stringify(response));
+}
+
+// After: the credential is a declared secret read through the context —
+// defineProvider({
+//   env: true, // turns the ctx.env capability on (type + runtime gate)
+//   secrets: [{ name: "APIFUSE__PROVIDER__EXAMPLE__SERVICE_KEY", required: true }], // the readable names
+// })
+// — and the ad-hoc diagnostic tap is deleted: a toggle that is not a secret has
+// no place in ctx.env; observability goes through ctx.trace instead.
+const serviceKey = ctx.env.get("APIFUSE__PROVIDER__EXAMPLE__SERVICE_KEY");
+const response = await ctx.trace.span("booking.confirm", () => confirmBooking(ctx, serviceKey));
+```
+
+### Credentials forced into query parameters
+
+Prefer an authorization header or request body whenever the upstream supports
+one. When the upstream requires a credential in the URL query (for example
+`serviceKey`, `confmKey`, or `crtfc_key`), use `sensitiveParams`:
+
+```ts
+const response = await ctx.http.get("/openapi/lookup", {
+	params: { pageNo: 1, numOfRows: 100 },
+	sensitiveParams: {
+		serviceKey: ctx.env.get("APIFUSE__PROVIDER__EXAMPLE__SERVICE_KEY")!,
+	},
+});
+```
+
+`sensitiveParams` is merged into the outgoing query like `params`, while its
+values are redacted from SDK transport errors, traces, and `apifuse record`
+fixtures. Do not put query credentials in `params`, and do not hand-build a URL
+containing a key; those paths cannot declare which query values are secret.
+
+#### Residual risks
+
+Redaction is unconditional in structural positions (declared query keys and
+exact scalar fixture/error fields) for values of every length. In unstructured
+free text, values of four or more characters are replaced as substrings; shorter
+values are replaced only at token boundaries to avoid corrupting unrelated text
+(for example, a secret `api` must not rewrite `rapid`). The residual risk is that
+a sub-four-character secret embedded directly inside a larger alphanumeric token
+can remain in free text. Prefer a higher-entropy credential, or a header/body
+credential channel, whenever the upstream permits it. An empty
+`sensitiveParams: {}` is treated exactly as if the option were omitted.
+
+For `session.redirects.run()`, returned hop URLs are diagnostic metadata and
+therefore keep declared query values and common response-only credential keys
+redacted. If a login flow must consume a rotated credential from `Location`,
+inspect it inside `stopWhen`; that callback receives the real hop while callback
+failures are sanitized before propagation.
+
+### Request-bound proof headers
+
+When an upstream requires a single-use, request-bound header (DPoP proofs,
+HTTP message signatures, HMAC nonces), pass `headers` as a factory instead of a
+record. `ctx.http` calls it once per issued attempt with the resolved URL and
+method, so a managed retry sends a fresh proof rather than replaying the first
+one, and the request keeps proxy failover and the transient retry taxonomy:
+
+```ts
+const response = await ctx.http.get(requestUrl, {
+	headers: async ({ url, method }) => {
+		// RFC 9449 §4.2: `htu` is the target URI without query and fragment.
+		const htu = new URL(url);
+		htu.search = "";
+		htu.hash = "";
+		return {
+			...commonHeaders,
+			dpop: await createDpopProof(htu.toString(), method),
+		};
+	},
+});
+```
+
+`url` is the exact URL the attempt is issued against, including `params` and
+`sensitiveParams`. Bind to it instead of a URL you rebuild, but strip the query
+and fragment for fields that are defined without them (DPoP `htu`), and never
+log it or copy it verbatim into a signed field a verifier logs.
+
+Keep the factory fast and local. It runs after proxy resolution, so an already
+allocated egress endpoint and its lease are held while it is awaited; a remote
+signing round trip there can outlive the lease TTL. Mint locally, and set
+`timeout` on the call so a hung signer cannot hold the endpoint indefinitely.
+
+The factory is not invoked for redirect hops (they reuse the attempt's
+headers), for skipped duplicate proxy offsets, or for an attempt whose proxy
+allocation failed — those build no request, so `attempt` counts only the
+requests that are actually issued. A factory that throws fails the request with
+the non-retryable `TransportError` code `http_header_factory_failed`, which is
+classified as a provider-side fault (`provider_error`), not an upstream
+failure. `ctx.stealth` has its own `headers` option and does not accept a
+factory.
+
 ### Public local debugging checklist
 
 - Operation smoke requests use the provider server envelope:
@@ -379,7 +1110,7 @@ use if the upstream is whitespace-sensitive.
   HTML, or upstream `Error` objects.
 
 ```ts
-export default defineProvider({
+const buildProvider = defineProvider({
   id: "example-provider",
   version: "1.0.0",
   runtime: "standard",
@@ -413,8 +1144,10 @@ export default defineProvider({
     },
   },
   credential: { keys: ["cookie"] },
-  // ...metadata and operations
+  // ...metadata
 });
+
+export default buildProvider({ operations });
 ```
 
 - Credentials auth providers should use `defineCredentialsAuth()` instead of
@@ -441,15 +1174,17 @@ const credentialsAuth = defineCredentialsAuth({
   },
 });
 
-export default defineProvider({
+const buildProvider = defineProvider({
   id: "example-provider",
   version: "1.0.0",
   runtime: "standard",
   auth: credentialsAuth.auth,
   credential: credentialsAuth.credential,
   context: credentialsAuth.context,
-  // ...metadata and operations
+	// ...metadata
 });
+
+export default buildProvider({ operations });
 ```
 
 For OTP, MFA, CAPTCHA handoff, or user-approved login, return a challenge from
@@ -509,14 +1244,171 @@ const credentialsAuth = defineCredentialsAuth({
   request's `context`.
 - Stealth/browser providers may require local runtime setup outside Provider code:
   keep access-sensitive operations on `ctx.stealth.fetch()` with an SDK stealth
-  `profile`; the TypeScript runtime uses `impit` behind that interface, so do
+  `profile`; the TypeScript runtime uses `wreq-js` behind that interface, so do
   not add per-operation JA3, HTTP/2 SETTINGS, or pseudo-header tuning. `ctx.stealth`
-  supports Chrome/Firefox-style profiles; use `browser.engine:
-  "playwright-stealth"` for Safari-specific or real browser Providers
-  (`nodriver` is Python-runtime only); install local browser assets with
+  supports Chrome, Firefox, and Safari profiles; use `ctx.browser` when a
+  Provider needs real browser execution. TypeScript browser Providers use
+  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only);
+  install local browser assets with
   `bunx playwright install chromium`, or set
   `APIFUSE__CDP_POOL__URL` for remote browser debugging.
 
+### Native gateway adapter migration
+
+Native proxy resolution supports both HTTP CONNECT and SOCKS5 without
+terminating origin TLS. The built-in vendor order follows `proxy.providers`
+exactly: `smartproxy` means the `api.smartproxy.org` allocation vendor (raw
+`ip:port` endpoints), while `nodemaven` is the credentialed gateway. It is not
+the company formerly called Smartproxy; that separate company is represented
+by the deprecated `decodo` name.
+
+Custom `gatewaySynthesizers` must now accept the selected `protocol` and the
+injected `credentials` resolver on `NativeGatewayProxySynthesisInput`.
+Synthesizers may be async because allocation vendors perform network I/O. They
+may return a proxy, `undefined` when they do not implement the offered vendor,
+or `{ kind: "skipped", reason }` so an exhausted required chain can explain an
+absent credential, unsupported protocol, or allocation failure. Accordingly,
+`resolveNativeGatewayProxy(...)` must now be awaited.
+
+Callers that do not supply custom synthesizers or credentials keep env-backed
+behavior. Hosts that already have an allowlisted `EnvContext` can inject it
+explicitly, and vault-backed or per-tenant hosts can supply their own resolver:
+
+```ts
+import {
+  createEnvVendorCredentialResolver,
+  createNativeNetworkClient,
+} from "@apifuse/provider-sdk";
+
+const network = createNativeNetworkClient({
+  proxyPolicy: { mode: "required", providers: ["smartproxy", "nodemaven"] },
+  credentials: createEnvVendorCredentialResolver(ctx.env),
+  // Optional advanced override; omit for each vendor's default.
+  proxyProtocol: "socks5",
+});
+```
+
+Never include credential values in adapter skip messages or thrown errors. The
+SDK redacts built-in proxy URL userinfo, CONNECT authentication, and allocator
+causes, but a custom adapter remains responsible for not publishing secrets in
+its own diagnostics.
+
+### Limiting stealth response bodies
+
+Set `maxBodyBytes` on `ctx.stealth.fetch()` or `session.redirects.run()` when an
+upstream response has a known safe maximum. The limit is opt-in and counts
+decoded bytes as `wreq-js` streams them. It applies to every redirect hop, uses a
+parseable `Content-Length` for an early rejection, and still enforces the limit
+incrementally when the header is absent or inaccurate. Exceeding the limit
+aborts the response and throws a non-retryable `TransportError` with code
+`response_too_large`.
+
+Pass the limit to the transport instead of checking `Content-Length` in provider
+code:
+
+```ts
+const response = await ctx.stealth.fetch("/api/search", {
+  params: { query: input.query },
+  maxBodyBytes: 2 * 1024 * 1024,
+})
+```
+
+### Persisting stealth session cookies
+
+Persist `session.cookies.serialize()` as JSON when an authenticated session must
+survive a restart or move to another replica. The returned
+`StealthCookieStoreV1` has an explicit version and retains every cookie together
+with its Domain, Path, Secure, expiry, host-only, and other cookie attributes.
+Restore it with `session.cookies.deserialize()`. Unsupported future versions
+fail explicitly instead of being accepted as a partial cookie jar.
+
+Credential values are strings, so stringify the store at the credential
+boundary and parse it when rebuilding the session:
+
+```ts
+// After login (including any redirects across sibling hosts):
+const result = await session.redirects.run({ url: loginUrl });
+return {
+  credential: {
+    cookieStore: JSON.stringify(result.cookieStore),
+  },
+};
+
+// In a later operation or replica:
+const persisted = ctx.credential.get("cookieStore");
+if (persisted) {
+  session.cookies.deserialize(JSON.parse(persisted));
+}
+```
+
+`snapshot()` and `restore()` remain only for backward compatibility with flat
+`Record<string, string>` credentials. `snapshot()` enumerates cookies across all
+hosts and paths, but the flat shape is inherently lossy: duplicate names
+collapse and Domain, Path, Secure, expiry, and host-only attributes cannot be
+represented. `restore()` therefore recreates host-only `Path=/` cookies on the
+session base origin. Do not use the flat form for new persistence code. Cookie
+headers remain origin-filtered: use `toHeader(url)` for a particular request and
+never build a request header from serialized or snapshotted persistence data.
+
+### Recording and replaying streaming responses
+
+`apifuse record` passes responses returned by `ctx.http.stream()` directly to the operation
+handler while incrementally capturing a bounded preview. If the handler returns or cancels its
+reader before EOF, the recorder drains the retained upstream reader before writing a JSON evidence
+record to `__fixtures__/raw.json`. The record contains the status, success
+flag, `content-type`/`content-length`/`content-disposition` headers when present, the
+full body SHA-256 and byte count, and a base64 preview up to the configured stream preview limit.
+Textual previews are decoded and passed through the fixture sanitizer before base64 encoding.
+Classification uses both the declared content type and the preview bytes, so missing or incorrect
+content-type headers do not bypass sanitization. PEM private-key blocks and long high-entropy
+tokens in otherwise unstructured text are redacted as well. If the full preview is not valid UTF-8,
+the entire lossy-decoded preview is scanned and matching decodable byte windows are sanitized. Only a
+magic-number-confirmed binary preview with no textual-secret pattern anywhere in the preview bypasses
+sanitization; other undecodable data fails closed.
+Sanitized previews carry `preview_sanitized: true`, plus a
+`preview_redaction_reason` when capture had to fail closed. The original hash and byte count always
+describe upstream bytes, not a sanitized preview.
+
+Each record includes query-free request provenance (`method`, `path`, and a one-based stream call
+ordinal). Provenance never stores the origin, URL userinfo, query, or fragment. Every retained path
+segment is scrubbed before persistence: credential-key segments, values following those keys,
+known token shapes, and long high-entropy opaque segments become `[REDACTED]`. If an operation
+opens multiple streams, the recorder finalizes every retained reader and
+writes all evidence records in stream call order. Stream invocations use a tagged capture envelope
+whose items distinguish stream evidence from ordinary JSON responses. Evidence-only snapshot replay
+consumes that exact call order and fails immediately when evidence is exhausted or a call kind is
+reordered. When request provenance is present, replay also rejects method or path changes (relative
+URLs are resolved against the recorded path prefix); ordinals remain diagnostic and are not matched.
+Appended fixtures replay a stream envelope only when it is the latest invocation. SSE
+recording remains unsupported and fails explicitly instead of retaining an unrelated earlier
+response.
+
+#### Residual risks
+
+- Credential-path sanitization decodes each URL path segment once. Double-encoded separators or
+  values such as `%252F` are not decoded recursively, so they can conceal a credential-shaped
+  segment from the recorder. This single-pass policy keeps path handling deterministic and avoids
+  interpreting ambiguous or intentionally layered encodings differently from the upstream. Never
+  place credentials in URL paths, and review recorded provenance before committing fixtures.
+- Primitive strings embedded in prose are redacted only when they match the current PEM,
+  credential-assignment, known-token, or entropy heuristics. Other secret formats can remain because
+  blanket redaction of ordinary strings would destroy useful fixture content and create broad false
+  positives. Keep secrets under credential-named structured fields where possible and manually
+  inspect sanitized fixture text before committing it.
+
+Stream fixture replay in `runStandardTests(..., { snapshot: true })` is evidence-only:
+`ctx.http.stream()` returns a usable stream containing exactly the recorded preview,
+not a fabricated full body. The replay response also carries runtime metadata
+`evidence_only: true`, `body_sha256`, `body_bytes`, and the optional preview sanitization fields
+for assertions about the original capture. Do not assert that the replay body hashes to
+`body_sha256` when `body_bytes`
+exceeds the decoded preview length or `preview_sanitized` is present; use the metadata for
+full-body integrity and limit body-content assertions to the preview.
+
+Golden snapshot suites can set `requireSnapshot: true` so a missing committed snapshot fails instead
+of being created implicitly. Regenerate intentional changes with
+`bun test --update-snapshots`; review and commit the resulting `transform.snap.json` file.
+
 ### Running the pre-submission report
 
 ```bash