@apifuse/provider-sdk 2.2.0-beta.48 → 2.2.0-beta.49

package/AUTHORING.md

@@ -73,45 +73,105 @@ 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: {}`, `choice: {}`, or
+`cache: {}`. `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.
+
 ### Factored operations
 
 `defineProvider(declaration)` returns the builder that accepts `operations`, so
 inline handlers are typed only after capability declarations are fixed. Export
-`ProviderContextOf<typeof buildProvider>` once from the provider entry point.
-Separate operation files import that provider context and call
-`defineOperation<ProviderContext>()({...})`; 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`.
+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
 
@@ -221,15 +281,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
 
@@ -248,6 +304,7 @@ export default defineProvider({
 })({
   operations: {
     verifyAudioOtp: {
+      riskClass: "read",
       input: z.object({
         audioBase64: z.string().describe("Base64-encoded short OTP audio"),
         mediaType: z.string().optional().describe("Audio MIME type"),
@@ -422,7 +479,7 @@ Provider-server failures use a stable public envelope:
 `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`
+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
@@ -447,19 +504,17 @@ 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
+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
-docs: {
-  errorCodes: [{
-    code: "UPSTREAM_SCHEMA_ERROR",
-    status: 502,
-    retryable: true,
-    description: "The upstream response no longer matches its schema.",
-  }],
-},
+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",

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.49
+
+- Release candidate for main commit 694b145f65c2c81e298c2516dde221ce19cb52da.
+
 ## 2.2.0-beta.48
 
 - Release candidate for main commit ba6636fa8dd53a35af3091ae6efd797f5ef3d836.

package/README.md

@@ -138,13 +138,14 @@ the bad request path; provider/runtime failures include `code`, `message`, and
 - **Stealth-sensitive providers**: use `ctx.http` for normal JSON/REST calls and
   `ctx.stealth.fetch()` when you need browser-like session or cookie control.
   `ctx.stealth.fetch()` uses the `wreq-js`-backed browser stealth transport and
-  accepts request controls for `params`, `sensitiveParams`, `proxy`, `timeout`, `profile`,
+  accepts request controls for `params`, `sensitiveParams`, `proxy`, `timeout`,
   `maxBodyBytes`, `redirect`, `throwOnHttpError`, and
   `stealth.insecureSkipVerify`. For login
   flows that must inspect intermediate `Location`/`Set-Cookie` headers, create
   a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
   inspect accumulated cookies through `session.cookies`. Select an SDK stealth
-  intent-based `profile` such as `chrome-desktop`; do not pin a browser version
+  identity with structured `stealth: { browser, os }` options; omitted `os`
+  explicitly defaults to `macos`. Do not pin a browser version
   or tune JA3, HTTP/2 SETTINGS, or
   pseudo-header order in provider code. Chrome, Firefox, and Safari profiles
   are supported; use `ctx.browser` when the provider needs browser execution.
@@ -219,6 +220,7 @@ const buildProvider = defineProvider({
 export type ProviderContext = ProviderContextOf<typeof buildProvider>
 
 const search = defineOperation<ProviderContext>()({
+  riskClass: "read",
   input: z.object({ q: z.string().describe("Search query") }),
   output: z.object({ count: z.number().describe("Result count") }),
   async handler(ctx, input) {
@@ -266,17 +268,17 @@ healthCheck: {
 }
 ```
 
-### Operation annotations
+### Flat operation metadata
 
-Operations declare non-functional metadata via `annotations`:
+Operations declare access, safety, and execution metadata directly on the
+operation. `riskClass` is required and is the safety source of truth:
 
 | Field | Type | Notes |
 |---|---|---|
-| `readOnly` | `boolean` | Operation has no side effects (safe to test in production). |
-| `destructive` | `boolean` | Operation modifies/deletes state. |
-| `idempotent` | `boolean` | Safe to retry without duplicate side effects. |
-| `openWorld` | `boolean` | Callable without authentication. |
-| `rateLimit` | `{ calls, window }` | Per-operation rate hint. `window` is `"minute"\|"hour"\|"day"`. |
+| `riskClass` | `"read" \| "write" \| "destructive" \| "external-send"` | Required safety classification. |
+| `approval` | `"never" \| "risk-based" \| "always"` | Optional override; omit when it matches the risk-class default. |
+| `connectionMode` | `"none" \| "optional" \| "required"` | Access requirement. Required by lint for credential-bearing providers. |
+| `connectionExternalRefParam` | `string` | Public argument used to resolve a Connection. |
 | `timeoutMs` | `number` | Per-operation upstream timeout (1–60000 ms). Omit to inherit the gateway global default. |
 
 `defineProvider()` validates `timeoutMs` is an integer in `[1, 60000]` and throws `ValidationError` otherwise. The gateway applies the value via `context.WithTimeout` on every proxied call and clamps defensively to the same bound.

package/SUBMISSION.md

@@ -28,7 +28,7 @@ The score is a triage aid, not a payout guarantee. Maintainers still review corr
 | Category | Points | Examples |
 |---|---:|---|
 | Definition & metadata | 15 | `defineProvider`, package, Dockerfile, SDK structural checks |
-| Operations & schemas | 15 | strong descriptions, annotations, input/output schemas |
+| Operations & schemas | 15 | locale-keyed descriptions, explicit risk classes, input/output schemas |
 | Fixtures & tests | 15 | bidirectional fixtures that parse against schemas |
 | Health coverage | 15 | real `healthCheck` or specific `healthCheckUnsupported.reason` |
 | Runtime/local smoke | 10 | `/health` and at least one `POST /v1/{operation}` note |

package/bin/apifuse-dev.ts

@@ -6,13 +6,17 @@ import {
 	createCredentialContext,
 	createEnvContext,
 	createHttpClient,
+	createInProcessProviderEngine,
 	createOcrClientFromEnv,
 	createProviderCache,
 	createProviderChoiceContext,
+	createProviderEnvironment,
 	createUnsupportedResolverClient,
 	createSttClientFromEnv,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	readEngineProxyCredentials,
 	type ProviderDefinition,
+	type ProviderEngineBindingCandidates,
 	ProviderError,
 	type ProviderProxyPolicy,
 } from "../src/index.js";
@@ -79,19 +83,20 @@ export async function main() {
 export function createProviderContext(provider: ProviderDefinition): {
 	ctx: ProviderContext;
 } {
-	const env = createEnvContext([
-		...(provider.secrets?.map((secret) => secret.name) ?? []),
-		PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-	]);
+	const providerEnvironment = createProviderEnvironment(
+		process.env,
+		provider.secrets?.map((secret) => secret.name) ?? [],
+	);
+	const providerEnv = { get: (key: string) => providerEnvironment[key] };
+	const engineEnv = createEnvContext([PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV]);
+	const engineCredentials = readEngineProxyCredentials();
 	const credential = createCredentialContext();
 	const state = createMemoryProviderRuntimeState();
 	const cache = createProviderCache({ providerId: provider.id });
 	const proxyPolicy = resolveNativeProxyPolicy(provider);
-	const stealthProfile = provider.stealth?.profile
-		? getStealthProfile(provider.stealth.profile)
-		: undefined;
-	const ctx: ProviderContext = {
-		env,
+	const stealthProfile = provider.stealth ? getStealthProfile(provider.stealth) : undefined;
+	const candidates: ProviderEngineBindingCandidates = {
+		env: providerEnv,
 		credential,
 		auth: createUnsupportedAuthStub(),
 		browser:
@@ -105,11 +110,13 @@ export function createProviderContext(provider: ProviderDefinition): {
 		cache,
 		state,
 		trace: createTraceContext(),
-		stealth: createStealthClient("http://localhost"),
+		stealth: createStealthClient("http://localhost", {
+			...(provider.stealth ? { stealth: provider.stealth } : {}),
+		}),
 		ocr: createOcrClientFromEnv(provider.ocr),
 		stt: createSttClientFromEnv(provider.stt),
 		resolver: provider.resolver
-			? createResolverClientFromEnv(provider.resolver, undefined, {
+			? createResolverClientFromEnv(provider.resolver, engineCredentials, {
 					allowedHosts: provider.allowedHosts,
 					cache,
 					...(proxyPolicy
@@ -125,11 +132,15 @@ export function createProviderContext(provider: ProviderDefinition): {
 			: createUnsupportedResolverClient("Provider does not declare resolver capability"),
 		choice: createProviderChoiceContext({
 			providerId: provider.id,
-			env,
+			env: engineEnv,
 			credential,
 			state,
 		}),
-	} satisfies Omit<ProviderContext, "native"> as unknown as ProviderContext;
+	};
+	const ctx = createInProcessProviderEngine().attach({
+		provider,
+		bindings: candidates,
+	}) as ProviderContext;
 
 	return { ctx };
 }

package/bin/apifuse-migrate-operation-declaration.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env bun
+
+/**
+ * `apifuse migrate-operation-declaration [path] [--check] [--json]`
+ *
+ * Rewrites ADR-0009's legacy nested operation declarations to the flat
+ * authoring contract. The run is repository-atomic: any declaration the
+ * codemod cannot prove leaves every source file untouched and exits 2.
+ */
+
+import { resolve } from "node:path";
+
+import { migrateOperationDeclarationRepository } from "../src/cli/migrate-operation-declaration.js";
+
+export async function main(): Promise<number> {
+	const args = process.argv.slice(3);
+	const check = args.includes("--check");
+	const json = args.includes("--json");
+	const positional = args.filter((argument) => !argument.startsWith("--"));
+	const providerRoot = resolve(positional[0] ?? ".");
+	const result = migrateOperationDeclarationRepository(providerRoot, { check });
+
+	if (json) {
+		console.log(
+			JSON.stringify({
+				schemaVersion: 1,
+				command: "migrate-operation-declaration",
+				...result,
+			}),
+		);
+	} else if (result.status === "refused") {
+		console.error(
+			`migrate-operation-declaration: refused ${result.refusals.length} declaration(s); no files were written.`,
+		);
+		for (const item of result.refusals) {
+			console.error(`  ${item.file} [${item.operationKey}] ${item.reason}: ${item.detail}`);
+		}
+	} else if (result.status === "unchanged") {
+		console.log("migrate-operation-declaration: already flat; nothing to do.");
+	} else {
+		const verb = result.status === "would-migrate" ? "would migrate" : "migrated";
+		const sidecar = result.sidecar === undefined ? "" : ` and ${result.sidecar}`;
+		console.log(
+			`migrate-operation-declaration: ${verb} ${result.operationCount} operation(s) across ${result.changedFiles.length} file(s)${sidecar}.`,
+		);
+	}
+
+	const exitCode = result.status === "refused" ? 2 : 0;
+	process.exitCode = exitCode;
+	return exitCode;
+}
+
+if (import.meta.main) {
+	process.exit(await main());
+}

package/bin/apifuse-pack-smoke.ts

@@ -236,7 +236,7 @@ function smokePackedStealthNative(consumerDir: string): void {
 				"const address = server.address();",
 				'if (!address || typeof address === "string") throw new Error("Local server has no TCP address");',
 				'const baseUrl = "http://127.0.0.1:" + address.port;',
-				'const session = createStealthClient(baseUrl).createSession({ profile: "safari-17" });',
+				'const session = createStealthClient(baseUrl).createSession({ stealth: { browser: "safari", os: "macos" } });',
 				"try {",
 				'  const response = await session.fetch("/native");',
 				'  if (response.body !== "packed native stealth ok") throw new Error("Unexpected stealth body: " + response.body);',

package/bin/apifuse-pack-types.ts

@@ -80,6 +80,7 @@ const NEGATIVE_CONTROLS = [
 			"})({",
 			"\toperations: {",
 			"\t\tprobe: {",
+			'\t\t\triskClass: "read",',
 			"\t\t\tinput: z.object({}),",
 			"\t\t\toutput: z.object({ ok: z.boolean() }),",
 			"\t\t\thandler: async () => ({ ok: true }),",
@@ -436,7 +437,7 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 			'export const cookieSolution: ChallengeSolution = { form: "cookies", cookies: { cf_clearance: "clearance" }, userAgent: "fixture-agent" };',
 			"export const invalidation = invalidateResolverSolution(providerContext.resolver, awsWafChallenge, cookieSolution);",
 			'export const resolverConfig: ProviderResolverConfig = { vendors: ["browser", "capsolver"], kinds: ["cloudflare_interstitial", "turnstile"] };',
-			'export const resolverProvider = defineProvider({ id: "pack-types-resolver", version: "1.0.0", runtime: "standard", resolver: resolverConfig, meta: { displayName: "Pack Types Resolver", descriptionKey: "meta.description", category: "test" } })({ operations: { probe: { input: z.object({}), output: z.object({ ok: z.boolean() }), handler: async () => ({ ok: true }), healthCheckUnsupported: { reason: "type fixture" } } } });',
+			'export const resolverProvider = defineProvider({ id: "pack-types-resolver", version: "1.0.0", runtime: "standard", resolver: resolverConfig, meta: { displayName: "Pack Types Resolver", descriptionKey: "meta.description", category: "test" } })({ operations: { probe: { riskClass: "read", input: z.object({}), output: z.object({ ok: z.boolean() }), handler: async () => ({ ok: true }), healthCheckUnsupported: { reason: "type fixture" } } } });',
 			"export const resolverContext: ResolverContext = { solve: async () => tokenSolution };",
 			'export const browserCookie: BrowserCookie = { name: "persistent-id", value: "persistent-token", domain: "example.com", path: "/", expires: 1786698176, httpOnly: true, secure: true };',
 			'const browserPage = undefined as unknown as Awaited<ReturnType<ProviderContext["browser"]["newPage"]>>;',

package/bin/apifuse-record.ts

@@ -8,8 +8,10 @@ import { pathToFileURL } from "node:url";
 import {
 	createBypassProviderCache,
 	createHttpClient,
+	createInProcessProviderEngine,
 	createOcrClientFromEnv,
 	createProviderChoiceContext,
+	createProviderEnvironment,
 	createSttClientFromEnv,
 	createUnsupportedResolverClient,
 	executeOperation,
@@ -18,7 +20,9 @@ import {
 	type HttpStreamResponse,
 	type ProviderContext,
 	type ProviderDefinition,
+	type ProviderEngineBindingCandidates,
 	ProviderError,
+	readEngineProxyCredentials,
 	type ProviderProxyPolicy,
 	type RequestOptions,
 	type StealthClient,
@@ -449,7 +453,7 @@ export function createCaptureContext(
 	let capturedSse: { order: number; method: string; path: string } | undefined;
 	const sensitiveParamNames = new Set<string>();
 	const sensitiveParamValues = new Set<string>();
-	const captureSensitiveParams = (url: string, options?: RequestOptions) => {
+	const captureSensitiveParams = (url: string, options?: SensitiveRequestOptions) => {
 		captureSensitiveRequestValues(url, options, sensitiveParamNames, sensitiveParamValues);
 	};
 	const getCapturedSensitiveParams = (): CapturedSensitiveParams => ({
@@ -503,15 +507,21 @@ export function createCaptureContext(
 		},
 	});
 	const stealth = proxyStealthClient(
-		createStealthClient(baseUrl),
+		createStealthClient(baseUrl, {
+			...(provider.stealth ? { stealth: provider.stealth } : {}),
+		}),
 		captureSensitiveParams,
 		(order, response) => retainRawCapture(order, normalizeCapturedStealthResponse(response)),
 		reserveCaptureOrder,
 	);
 
-	const env = {
-		get: (key: string) => process.env[key],
-	};
+	const providerEnvironment = createProviderEnvironment(
+		process.env,
+		provider.secrets?.map((secret) => secret.name) ?? [],
+	);
+	const env = { get: (key: string) => providerEnvironment[key] };
+	const engineEnv = { get: (key: string) => process.env[key] };
+	const engineCredentials = readEngineProxyCredentials();
 	const credential = {
 		mode: "none" as const,
 		get: () => undefined,
@@ -522,10 +532,8 @@ export function createCaptureContext(
 	const state = createMemoryProviderRuntimeState();
 	const cache = createBypassProviderCache({ providerId: provider.id });
 	const proxyPolicy = resolveNativeProxyPolicy(provider);
-	const stealthProfile = provider.stealth?.profile
-		? getStealthProfile(provider.stealth.profile)
-		: undefined;
-	const ctx: ProviderContext = {
+	const stealthProfile = provider.stealth ? getStealthProfile(provider.stealth) : undefined;
+	const candidates: ProviderEngineBindingCandidates = {
 		env,
 		credential,
 		request: { headers: {} },
@@ -560,7 +568,7 @@ export function createCaptureContext(
 		ocr: createOcrClientFromEnv(provider.ocr),
 		stt: createSttClientFromEnv(provider.stt),
 		resolver: provider.resolver
-			? createResolverClientFromEnv(provider.resolver, undefined, {
+			? createResolverClientFromEnv(provider.resolver, engineCredentials, {
 					allowedHosts: provider.allowedHosts,
 					cache,
 					...(proxyPolicy
@@ -576,12 +584,16 @@ export function createCaptureContext(
 			: createUnsupportedResolverClient("Provider does not declare resolver capability"),
 		choice: createProviderChoiceContext({
 			providerId: provider.id,
-			env,
+			env: engineEnv,
 			request: { headers: {} },
 			credential,
 			state,
 		}),
-	} satisfies Omit<ProviderContext, "native"> as unknown as ProviderContext;
+	};
+	const ctx = createInProcessProviderEngine().attach({
+		provider,
+		bindings: candidates,
+	}) as ProviderContext;
 
 	return {
 		ctx,
@@ -636,9 +648,11 @@ type CapturedSensitiveParams = {
 	values: readonly string[];
 };
 
+type SensitiveRequestOptions = Pick<RequestOptions, "params" | "sensitiveParams">;
+
 function captureSensitiveRequestValues(
 	url: string,
-	options: RequestOptions | undefined,
+	options: SensitiveRequestOptions | undefined,
 	names: Set<string>,
 	values: Set<string>,
 ): void {
@@ -683,7 +697,7 @@ function captureSensitiveRequestValues(
 	}
 }
 
-function snapshotRequestOptions<T extends RequestOptions>(options: T): T {
+function snapshotRequestOptions<T extends SensitiveRequestOptions>(options: T): T {
 	return {
 		...options,
 		...(options.params
@@ -778,7 +792,7 @@ type StealthSession = ReturnType<StealthClient["createSession"]>;
 
 function proxyStealthClient(
 	client: StealthClient,
-	onSensitiveParams: (url: string, options?: RequestOptions) => void,
+	onSensitiveParams: (url: string, options?: SensitiveRequestOptions) => void,
 	onResponse: (order: number, response: Awaited<ReturnType<StealthClient["fetch"]>>) => void,
 	reserveOrder: () => number,
 ): StealthClient {
@@ -804,7 +818,7 @@ function proxyStealthClient(
 
 function proxyStealthSession(
 	session: StealthSession,
-	onSensitiveParams: (url: string, options?: RequestOptions) => void,
+	onSensitiveParams: (url: string, options?: SensitiveRequestOptions) => void,
 	onResponse: (order: number, response: Awaited<ReturnType<StealthClient["fetch"]>>) => void,
 	reserveOrder: () => number,
 ): StealthSession {

package/bin/apifuse-submit-check.ts

@@ -2947,13 +2947,17 @@ function collectProviderRequiredLocaleKeys(provider: ProviderDefinition): string
 
 	for (const operation of Object.values(provider.operations)) {
 		addLocaleKeys(keys, [
+			operation.titleKey,
 			operation.descriptionKey,
-			operation.docs?.titleKey,
-			operation.docs?.descriptionKey,
-			operation.docs?.summaryKey,
-			operation.docs?.markdownKey,
+			operation.summaryKey,
+			operation.markdownKey,
 			...(operation.whenToUseKeys ?? []),
 			...(operation.whenNotToUseKeys ?? []),
+			...(operation.normalizationNotesKeys ?? []),
+			...(operation.examples ?? []).flatMap((example) => [
+				example.scenarioKey,
+				example.rationaleKey,
+			]),
 			...collectSchemaDescriptionKeys(operation.input),
 			...collectSchemaDescriptionKeys(operation.output),
 		]);
@@ -3020,8 +3024,8 @@ function scoreOperationMetadata(provider: ProviderDefinition): SubmitCheck {
 			return true;
 		})
 		.map(([operationId]) => operationId);
-	const missingAnnotations = operations
-		.filter(([, operation]) => !operation.annotations)
+	const missingRiskClass = operations
+		.filter(([, operation]) => !operation.riskClass)
 		.map(([operationId]) => operationId);
 
 	if (weakDescriptions.length > 0) {
@@ -3033,30 +3037,30 @@ function scoreOperationMetadata(provider: ProviderDefinition): SubmitCheck {
 			points: 0,
 			maxPoints: CATEGORY_MAX_POINTS.operations,
 			message: "One or more operations have weak descriptions.",
-			remediation: `For ${weakDescriptions.join(", ")}, add an operation \`descriptionKey\` backed by \`locales/en.json\` and \`locales/ko.json\`, or add a 150+ character \`description\` explaining when to use it, when not to use it, outputs, and caveats.`,
+			remediation: `For ${weakDescriptions.join(", ")}, add an operation \`descriptionKey\` backed by \`locales/en.json\` and \`locales/ko.json\`.`,
 			evidence: weakDescriptions,
 		};
 	}
 
-	const points = missingAnnotations.length > 0 ? 11 : CATEGORY_MAX_POINTS.operations;
+	const points = missingRiskClass.length > 0 ? 11 : CATEGORY_MAX_POINTS.operations;
 	return {
 		id: "operation-metadata",
 		category: "operations",
-		level: missingAnnotations.length > 0 ? "warn" : "info",
-		status: missingAnnotations.length > 0 ? "warn" : "pass",
+		level: missingRiskClass.length > 0 ? "warn" : "info",
+		status: missingRiskClass.length > 0 ? "warn" : "pass",
 		points,
 		maxPoints: CATEGORY_MAX_POINTS.operations,
 		message:
-			missingAnnotations.length > 0
-				? "Operations are described, but some are missing safety annotations."
+			missingRiskClass.length > 0
+				? "Operations are described, but some are missing a safety classification."
 				: "Operation descriptions and metadata are review-ready.",
 		remediation:
-			missingAnnotations.length > 0
-				? `For ${missingAnnotations.join(", ")}, add \`annotations\` with the applicable safety fields, such as \`readOnly\`, \`destructive\`, \`idempotent\`, \`openWorld\`, \`rateLimit\`, or \`timeoutMs\`.`
+			missingRiskClass.length > 0
+				? `For ${missingRiskClass.join(", ")}, declare the operation's required \`riskClass\` as \`read\`, \`write\`, \`destructive\`, or \`external-send\`.`
 				: undefined,
 		evidence:
-			missingAnnotations.length > 0
-				? missingAnnotations.map((operationId) => `${operationId}: missing annotations`)
+			missingRiskClass.length > 0
+				? missingRiskClass.map((operationId) => `${operationId}: missing riskClass`)
 				: operations.map(([operationId]) => operationId),
 	};
 }
@@ -5332,25 +5336,6 @@ function scoreAuthSafety(provider: ProviderDefinition): SubmitCheck {
 		};
 	}
 
-	if (authMode === "none") {
-		const securedOperations = Object.entries(provider.operations).filter(
-			([, operation]) => operation.annotations?.openWorld === false,
-		);
-		if (securedOperations.length > 0) {
-			return {
-				id: "auth-safety",
-				category: "auth",
-				level: "warn",
-				status: "warn",
-				points: 7,
-				maxPoints: CATEGORY_MAX_POINTS.auth,
-				message: "Provider is no-auth but at least one operation is not marked openWorld.",
-				remediation: `Either set \`auth.mode\` to the upstream auth model, or mark these public no-auth operations with \`annotations.openWorld: true\`: ${securedOperations.map(([operationId]) => operationId).join(", ")}.`,
-				evidence: securedOperations.map(([operationId]) => operationId),
-			};
-		}
-	}
-
 	return pass(
 		"auth-safety",
 		"auth",