@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/AUTHORING.md

@@ -18,6 +18,59 @@
 
 Provider code is the declaration input to the internal platform registry. The public SDK owns provider authoring/runtime ergonomics; internal docs, deploy, and discovery projections are built downstream from those declarations. `bun run lint:providers` enforces provider authoring standards.
 
+### User-input round-trips: never dead-end (`needs_input`)
+
+A mutation MUST NOT fail for a problem the end user can resolve by choosing among live options (a required menu/course selection, a form question, a stale-but-recoverable state token). Throwing an error there strands the consuming agent: consumer error-shaping layers routinely strip error metadata, and a model that only sees "error" narrates failure to the user instead of relaying the choice.
+
+Return the official success-shaped contract from `src/user-input.ts` instead (`ProviderNeedsInputPayload`, guard `isProviderNeedsInputPayload`):
+
+- `status: "needs_input"` plus `required_selections` — only the still-pending questions, with human-readable `label`s and `valid_options` the agent relays verbatim. The agent never chooses for the user; anything with no real choice (agreement checkboxes, single-option required groups) is the provider's job to auto-answer.
+- `selected_options` — selections already settled, echoed so the retry keeps them (copy them back and add the user's new answers).
+- a freshly minted provider state token in the same response, so the retry never races an expired token.
+
+No retry templates, next-action routing, or other agent choreography: provider payloads carry upstream-backed data only, and the consumer owns how the ask is phrased and how the retry call is shaped.
+
+Declare the union in the operation `output` schema (`z.union([CreatedSchema, NeedsInputSchema])`). Reserve hard errors for genuinely unrecoverable flows (payment-gated, unsupported input kinds) and state the concrete reason in the error `message` itself, not only in `details`. Reference implementation: `providers/catchtable` `reserve` in the platform monorepo.
+
+### Attempt tokens: the server carries the decisions
+
+When a mutation needs more than one user decision (or one decision plus a
+final go/no-go), do not make the agent re-send accumulated state across
+rounds — weak models drop or corrupt it. Split the operation into a
+**prepare/confirm pair** driven by a server-held attempt record:
+
+- 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.
+- `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"`
+  with a human-readable summary — the consumer's user-facing confirmation.
+- The confirm operation is the only mutation and takes exactly
+  `{attempt_token}`. It re-validates everything live before executing and
+  returns `needs_input` (fresh token) instead of proceeding when upstream
+  drift invalidates a stored decision — never substitute a different option
+  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.
+
+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.
+Reference implementations: `providers/catchtable` `reserve`/`reserve-confirm`
+(including the consume-on-success guard) and `providers/modu-parking`
+payment state tokens in the platform monorepo.
+
 ### Description template
 
 Every operation `description` MUST be at least 150 characters and follow this structure:
@@ -53,6 +106,90 @@ description:
 
 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`.
 
+### 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.
+
+### 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. Direct global
+`fetch` or socket usage is outside this ProviderContext seam and should not be
+used by provider handlers.
+
 ### Health assertion context
 
 `healthCheck.cases[].assertions` receives a `HealthCheckAssertionContext` with
@@ -256,6 +393,200 @@ 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>.docs.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.
+Its category, taxonomy version, retryability, and optional upstream status match
+the structured `provider_request_failed` log event.
+
+Declare provider-owned operation failures next to their documentation. The
+server builds a lookup once at startup and applies it to failures from that
+operation:
+
+```ts
+docs: {
+  errorCodes: [{
+    code: "UPSTREAM_SCHEMA_ERROR",
+    status: 502,
+    retryable: true,
+    description: "The upstream response no longer matches its schema.",
+  }],
+},
+handler: async () => {
+  throw new ProviderError("Upstream schema changed", {
+    code: "UPSTREAM_SCHEMA_ERROR",
+  });
+},
+```
+
+`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` | 400 |
+| `NOT_FOUND`, `not_found`, `NO_DATA` | 404 |
+| `RATE_LIMITED`, `UPSTREAM_RATE_LIMIT`, `LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR` | 429 |
+| `UPSTREAM_ERROR`, `BLOCKED` | 502 |
+| `STT_UNAVAILABLE`, `UNSUPPORTED_STT_BACKEND`, `STATEFUL_FORWARDING_REPLAY_CACHE_FULL` | 503 |
+| Unregistered input `ValidationError` code | 400 |
+| Other unregistered `ProviderError` code | 500 |
+
+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.
+
+### Declared secrets are SDK-enforced
+
+Environment/secret presence validation is single-sourced in the SDK. Declare
+every env secret the provider needs in `defineProvider`:
+
+```ts
+secrets: [
+  {
+    name: "APIFUSE__PROVIDER__MY_PROVIDER__API_KEY",
+    required: true,
+    description: "Upstream API key from the vendor portal",
+  },
+],
+```
+
+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, 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()`
+and throw a hand-rolled `CONFIGURATION_ERROR`/`MISSING_SECRET`. Those guards
+are dead weight (the SDK gate runs first) and historically diverged into
+inconsistent error shapes. The `sdk-owned-secret-presence` submit-check rule
+flags them at warn level; acknowledge a deliberate exception with
+`// @apifuse-allow sdk-owned-secret-presence: <reason>`.
+
+```ts
+// Before (deprecated): provider-local double validation
+function requireServiceKey(ctx: ProviderContext): string {
+  const value = ctx.env.get(SERVICE_KEY_ENV);
+  if (!value?.trim()) {
+    throw new ProviderError(`Missing required provider secret: ${SERVICE_KEY_ENV}`, {
+      code: "CONFIGURATION_ERROR",
+    });
+  }
+  return value;
+}
+
+// After: declare { name: SERVICE_KEY_ENV, required: true } and read directly.
+const serviceKey = ctx.env.get(SERVICE_KEY_ENV);
+```
+
+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.
+
+### 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.
+
 ### Public local debugging checklist
 
 - Operation smoke requests use the provider server envelope:
@@ -411,6 +742,162 @@ const credentialsAuth = defineCredentialsAuth({
   `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 impit 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

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.21
+
+- Release candidate for main commit 00f61024fb18db39711dc5076c4621508baa49f5.
+
+## 2.2.0-beta.20
+
+- Release candidate for main commit 8043d2ef0047e431aace750d8abca2e1149ec1d6.
+
+## 2.2.0-beta.19
+
+- Release candidate for main commit fd93ae68d0472fae68d908312249163373ec5d22.
+
+## 2.2.0-beta.18
+
+- Release candidate for main commit cebaf4b994918d2641c0fe6681fbffd3a3284c5d.
+
+## 2.2.0-beta.17
+
+- Release candidate for main commit 5a0f9127a5861992d5c144b07ad379a085756544.
+
+## 2.2.0-beta.16
+
+- Release candidate for main commit c5deb2bc31a4a4a236d27a2ce3d214b533ed358f.
+
+## 2.2.0-beta.15
+
+- Release candidate for main commit b5ebd25e48f6502e4ddb775d4e0a25f5c8276712.
+
+## 2.2.0-beta.14
+
+- Release candidate for main commit 3491acd253ca17b517985e8a618f1c2904a664a9.
+
+## 2.2.0-beta.13
+
+- Release candidate for main commit 75e840d0614aea3b99a1e5cef4f93f8cdccf0507.
+
+## 2.2.0-beta.12
+
+- Release candidate for main commit c66789c4745c72fc94ad3c10b3e0d7e5ed83fd25.
+
+## 2.2.0-beta.11
+
+- Release candidate for main commit f6f739bd5265afe714bbace9900edc2695fcf826.
+
+## 2.2.0-beta.10
+
+- Release candidate for main commit c41bd919739e0293ae8fa4d72a8a32f034cef4b8.
+
+## 2.2.0-beta.9
+
+- Release candidate for main commit 5c78c8b (bundles #67 nodemaven required-secret + #68 transport vendor-advance).
+
+## 2.2.0-beta.8
+
+- Release candidate for main commit 9e8a3f028ee78b9cab29d4aa3f5494ac9cffa65f.
+
+## 2.2.0-beta.7
+
+- Release candidate for main commit 2ce4ea4bd36ce333eba8b3b474bf6e82b5e9216c.
+
+## 2.2.0-beta.6
+
+- Release candidate for main commit 17f4e41d44efe7c148ef875b950be4f2c7df1294.
+
+## 2.2.0-beta.5
+
+- Release candidate for main commit 82fa14e99a9af7edd44e3196aa3f4e87b4699edf.
+
+## 2.2.0-beta.4
+
+- Release candidate for main commit 73f2c6ec429c2fbce8ac458a67111e4844b99178.
+
+## 2.2.0-beta.3
+
+- Release candidate for main commit 74e8e18b502dd9b02dbf0d3e702f917570312fc0.
+
 ## 2.2.0-beta.2
 
 - Release candidate for main commit ceefad020a1038eade542fd3b128667b39625f6f.
@@ -38,8 +114,22 @@
 
 ## Unreleased
 
+- Upstream the platform monorepo's beta.16 dist patch: OAuth2-proxied auth ceremony (`createOAuth2ProxiedStart`, `OAUTH2_PROXIED_PKCE_VERIFIER_KEY`, `APIFUSE__AUTH_PROXY__URL` origin key, proxied redirect/callback turns) and the provider runtime state upgrades it depends on (in-memory compareAndSet with quota-aware write policy, Redis CAS/set Lua scripts with entry quotas and legacy index migration). The monorepo drops `patchedDependencies` once it pins this release.
+- **honest-provider-error-contract (phase 2):** `UPSTREAM_REJECTED` is a registered code family serving HTTP 409 with `retryable: false` — deterministic upstream business refusals are no longer 502s. Operation-declared `docs.errorCodes` may now use 409/410/422. Public error envelopes carry a `source` field (`client` | `upstream_rule` | `upstream_failure` | `apifuse`) derived from the observability category. Taxonomy version bumps to `2026-08-07` with the `upstream_rejected`, `dependency_unavailable`, `unsupported_transport`, and `client_cancelled` categories (409/410/422 map to `upstream_rejected`), matching the platform monorepo SoT. The `unregistered_provider_error_code` signal now carries a `signalFix` pointing at `docs.errorCodes` declaration.
+- **Breaking for custom native gateway adapters:** `NativeGatewayProxySynthesisInput` now includes an injected `credentials` resolver and selected `protocol`; synthesizers may return promises and structured skip reasons, and `resolveNativeGatewayProxy` is async. Default callers retain env-backed behavior. Native transport now supports both HTTP CONNECT and SOCKS5, defaults per vendor with an explicit runtime override, registers smartproxy allocation ahead of nodemaven when declared in that order, and reports every exhausted vendor reason without exposing proxy credentials.
+- Honor operation `docs.errorCodes` at runtime: declared provider-owned statuses and retryability now drive the HTTP envelope, observability header, and structured log; invalid statuses fail `defineProvider`, declared codes no longer emit the unregistered-code signal, and `TransportError` status-preservation workarounds are obsolete.
+- Add an opt-in same-origin redirect hop policy to `ctx.http`, with bounded manual following and typed failures before a refused target is requested.
+- Enforce provider-declared native TCP/TLS egress before proxy or socket setup, with revocable and expiring dynamic grants plus typed authorization failures; providers without a native egress declaration retain legacy behavior.
+- **Breaking:** Provider error `details` is now passed through verbatim; SDK observability fields (`category`, `taxonomyVersion`, `upstreamStatus`, and derived `retryable`) are no longer merged into the public body. Emitted error envelopes now require top-level `retryable`, while inbound stateful forwarding tolerates an older owner response that omits it and defaults it to `false`. The removed observability metadata is available in the new `X-ApiFuse-Error-Observability` response header.
+- Unregistered `ProviderError` codes now default to HTTP 500 instead of 400 and emit an `unregistered_provider_error_code` structured-log signal; registered mappings remain unchanged and take precedence over the HTTP 400 fallback for unregistered input `ValidationError` codes.
+- Add an opt-in native connection idle read timeout with a typed error, independently from TCP/SOCKS/TLS establishment deadlines.
+- Add opt-in `maxBodyBytes` enforcement to stealth fetches and redirect hops, aborting oversized decoded response streams with `response_too_large`.
+- Resolve relative date tokens in fixture requests before input-schema validation, add KST capture-date `fixtures.recordedAt` metadata, and support explicit KST/UTC calendars in the shared health-input resolver.
+- Add opt-in `runStandardTests(provider, { upstreamStub })` real-handler E2E coverage with strict offline transport stubs, output-schema validation, and per-operation warnings when handler E2E is not enabled.
+- Export native-network and request-file TypeScript contracts from the package root and `./provider`, including typed native provider declarations and optional runtime capabilities on provider/auth contexts.
 - Add `arrayBuffer()` and `bytes()` to `HttpResponse` so `ctx.http` consumers can read binary-safe upstream bodies; internal response handling is now byte-first.
 - Preserve identity-only operation `connectionId` values in `ProviderContext` without requiring credential material.
+- Accept and validate `proxy.session.drainLeadSeconds` in `defineProvider`, so providers can actually declare the native sticky-expiry drain lead time the type surface already exposed; a non-positive value, or one that meets or exceeds the sticky lifetime, is rejected at define time.
 
 ## 2.1.0-beta.15