@apifuse/provider-sdk 2.2.0-beta.35 → 2.2.0-beta.37

package/src/cli/templates/provider/index.ts.tpl

@@ -1,9 +1,9 @@
-import { defineProvider } from "@apifuse/provider-sdk/provider";
+import { defineProvider, type ProviderContextOf } from "@apifuse/provider-sdk/provider";
 
 import { providerMeta } from "./meta";
 import { operations } from "./operations";
 
-export default defineProvider({
+const buildProvider = defineProvider({
   id: "{{PROVIDER_ID}}",
   version: "1.0.0",
   runtime: "{{RUNTIME}}"{{BROWSER_BLOCK}},
@@ -11,5 +11,8 @@ export default defineProvider({
   reviewed: "community",
   {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
   meta: providerMeta,
-  operations: operations,
 });
+
+export type ProviderContext = ProviderContextOf<typeof buildProvider>;
+
+export default buildProvider({ operations });

package/src/cli/templates/provider/operations/ping.ts.tpl

@@ -1,8 +1,9 @@
 import { defineOperation } from "@apifuse/provider-sdk/provider";
+import type { ProviderContext } from "../index";
 
 import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
 
-export const pingOperation = defineOperation({
+export const pingOperation = defineOperation<ProviderContext>()({
   descriptionKey: "operations.ping.description",
   input: pingInputSchema,
   output: pingOutputSchema,

package/src/define.ts

@@ -31,6 +31,8 @@ import type {
 	ProviderAccessConfig,
 	ProviderChallengeKind,
 	ProviderDefinition,
+	ProviderContext,
+	ProviderContextFor,
 	ProviderOcrConfig,
 	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
@@ -197,71 +199,383 @@ function parsePositiveMsDuration(value: string): number | undefined {
 	return parsed;
 }
 
-type ProviderOperation = OperationDefinition<SchemaLike, SchemaLike>;
-type OperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationDefinition<TInput, TOutput>,
-	"handler"
-> & {
+type ProviderOperation = OperationDefinition<any, any, any>;
+type OperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationDefinition<TInput, TOutput, TContext>, "handler"> & {
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	):
 		| OperationHandlerResult<InferSchemaOutput<TOutput>>
 		| Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
 };
-type OperationMapConfig<TOperations extends Record<string, ProviderOperation>> = {
+type OperationMapConfig<
+	TOperations extends Record<string, ProviderOperation>,
+	TContext = ProviderContext,
+> = {
 	[K in keyof TOperations]: TOperations[K] extends OperationDefinition<infer TInput, infer TOutput>
-		? OperationConfig<TInput, TOutput> | OperationDefinition<TInput, TOutput>
+		? OperationConfig<TInput, TOutput, TContext> | OperationDefinition<TInput, TOutput, TContext>
 		: never;
 };
-type StreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> =
-	| SseOperationConfig<TInput, TOutput>
-	| HttpStreamOperationConfig<TInput, TOutput>
-	| WebSocketOperationConfig<TInput, TOutput>;
-type SseOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type StreamOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> =
+	| SseOperationConfig<TInput, TOutput, TContext>
+	| HttpStreamOperationConfig<TInput, TOutput, TContext>
+	| WebSocketOperationConfig<TInput, TOutput, TContext>;
+type SseOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationSseTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): AsyncIterable<ProviderStreamEvent> | Promise<AsyncIterable<ProviderStreamEvent>>;
 };
-type HttpStreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type HttpStreamOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationHttpStreamTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
-type WebSocketOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type WebSocketOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationWebSocketTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
 
-type AuthStartNoInputGuard<TConfig> = TConfig extends {
+type AuthStartHandlerNoInputGuard<TStart> = TStart extends (...args: infer TArgs) => unknown
+	? TArgs["length"] extends 0 | 1
+		? unknown
+		: {
+				"auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+			}
+	: unknown;
+
+export type AuthStartNoInputGuard<TConfig> = TConfig extends {
 	auth?: { flow?: { start: infer TStart } };
 }
-	? TStart extends (...args: infer TArgs) => unknown
-		? TArgs extends [unknown]
-			? unknown
-			: {
-					"auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+	? AuthStartHandlerNoInputGuard<TStart>
+	: TConfig extends { start: infer TStart }
+		? AuthStartHandlerNoInputGuard<TStart>
+		: unknown;
+
+function splitAuthStartParameters(parameters: string): string[] | undefined {
+	const parts: string[] = [];
+	let start = 0;
+	let round = 0;
+	let square = 0;
+	let curly = 0;
+	let quote: "'" | '"' | "`" | undefined;
+	let escaped = false;
+	let lineComment = false;
+	let blockComment = false;
+	const templateDepths = [0];
+	templateDepths.length = 0;
+
+	for (let index = 0; index < parameters.length; index++) {
+		const character = parameters[index];
+		const nextCharacter = parameters[index + 1];
+		if (lineComment) {
+			if (character === "\n" || character === "\r") lineComment = false;
+			else continue;
+		}
+		if (blockComment) {
+			if (character === "*" && nextCharacter === "/") {
+				blockComment = false;
+				index++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (escaped) {
+				escaped = false;
+			} else if (character === "\\") {
+				escaped = true;
+			} else if (quote === "`" && character === "$" && nextCharacter === "{") {
+				curly++;
+				templateDepths.push(curly);
+				quote = undefined;
+				index++;
+			} else if (character === quote) {
+				quote = undefined;
+			}
+			continue;
+		}
+		if (character === "'" || character === '"' || character === "`") {
+			quote = character;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "/") {
+			lineComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "*") {
+			blockComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/") return undefined;
+		// Annex B HTML-like comments are not lexed here; give up rather than
+		// risk misreading the parameter list.
+		if (character === "<" && parameters.startsWith("!--", index + 1)) return undefined;
+		if (character === "-" && parameters.startsWith("->", index + 1)) return undefined;
+		if (character === "(") round++;
+		else if (character === ")") round--;
+		else if (character === "[") square++;
+		else if (character === "]") square--;
+		else if (character === "{") curly++;
+		else if (character === "}") {
+			if (templateDepths.at(-1) === curly) {
+				templateDepths.pop();
+				curly--;
+				quote = "`";
+			} else curly--;
+		} else if (character === "," && round === 0 && square === 0 && curly === 0) {
+			parts.push(parameters.slice(start, index));
+			start = index + 1;
+		}
+		if (round < 0 || square < 0 || curly < 0) return undefined;
+	}
+
+	if (
+		quote ||
+		blockComment ||
+		templateDepths.length > 0 ||
+		round !== 0 ||
+		square !== 0 ||
+		curly !== 0
+	)
+		return undefined;
+	parts.push(parameters.slice(start));
+	return parts;
+}
+
+function authStartParameterList(source: string): string | undefined {
+	let index = 0;
+	while (index < source.length && /\s/.test(source[index] ?? "")) index++;
+	if (index >= source.length) return undefined;
+
+	let openIndex = -1;
+	let parenthesizedArrow = false;
+	let asyncMethodOrArrow = false;
+	const skipTrivia = () => {
+		while (index < source.length) {
+			if (/\s/.test(source[index] ?? "")) {
+				index++;
+				continue;
+			}
+			if (source[index] === "/" && source[index + 1] === "/") {
+				index += 2;
+				while (index < source.length && source[index] !== "\n" && source[index] !== "\r") index++;
+				continue;
+			}
+			if (source[index] === "/" && source[index + 1] === "*") {
+				const end = source.indexOf("*/", index + 2);
+				if (end < 0) {
+					index = source.length;
+					return;
 				}
-		: unknown
-	: unknown;
+				index = end + 2;
+				continue;
+			}
+			return;
+		}
+	};
+
+	const initial = source.slice(index);
+	const isAsync = initial.startsWith("async") && !/[\w$]/.test(initial[5] ?? "");
+	if (isAsync) {
+		index += 5;
+		skipTrivia();
+	}
+
+	const afterAsync = source.slice(index);
+	const isFunction = afterAsync.startsWith("function") && !/[\w$]/.test(afterAsync[8] ?? "");
+	if (isFunction) {
+		index += 8;
+		skipTrivia();
+		if (source[index] === "*") {
+			index++;
+			skipTrivia();
+		}
+	} else if (source[index] === "*") {
+		index++;
+		skipTrivia();
+	}
+
+	if (source[index] === "(") {
+		openIndex = index;
+		parenthesizedArrow = !isFunction;
+		asyncMethodOrArrow = isAsync && !isFunction;
+	} else if (isFunction) {
+		if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+		index++;
+		while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+		skipTrivia();
+		if (source[index] !== "(") return undefined;
+		openIndex = index;
+	} else {
+		const identifierStart = index;
+		if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+		index++;
+		while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+		const firstIdentifier = source.slice(identifierStart, index);
+		skipTrivia();
+		if (source[index] === "=" && source[index + 1] === ">") return undefined;
+		if (source[index] !== "(") {
+			if (firstIdentifier !== "get" && firstIdentifier !== "set") return undefined;
+			if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+			index++;
+			while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+			skipTrivia();
+		}
+		if (source[index] !== "(") return undefined;
+		openIndex = index;
+	}
+	if (openIndex < 0) return undefined;
+
+	let depth = 1;
+	let square = 0;
+	let curly = 0;
+	let quote: "'" | '"' | "`" | undefined;
+	let escaped = false;
+	let lineComment = false;
+	let blockComment = false;
+	const templateDepths = [0];
+	templateDepths.length = 0;
+	for (index = openIndex + 1; index < source.length; index++) {
+		const character = source[index];
+		const nextCharacter = source[index + 1];
+		if (lineComment) {
+			if (character === "\n" || character === "\r") lineComment = false;
+			else continue;
+		}
+		if (blockComment) {
+			if (character === "*" && nextCharacter === "/") {
+				blockComment = false;
+				index++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (escaped) escaped = false;
+			else if (character === "\\") escaped = true;
+			else if (quote === "`" && character === "$" && nextCharacter === "{") {
+				curly++;
+				templateDepths.push(curly);
+				quote = undefined;
+				index++;
+			} else if (character === quote) quote = undefined;
+			continue;
+		}
+		if (character === "'" || character === '"' || character === "`") {
+			quote = character;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "/") {
+			lineComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "*") {
+			blockComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/") return undefined;
+		// Annex B HTML-like comments are not lexed here; give up rather than
+		// risk misreading the parameter list.
+		if (character === "<" && source.startsWith("!--", index + 1)) return undefined;
+		if (character === "-" && source.startsWith("->", index + 1)) return undefined;
+		if (character === "(") depth++;
+		else if (character === ")") {
+			depth--;
+			if (depth === 0 && square === 0 && curly === 0) {
+				const closeIndex = index;
+				if (parenthesizedArrow) {
+					index++;
+					skipTrivia();
+					const hasArrow = source[index] === "=" && source[index + 1] === ">";
+					if (!hasArrow && (!asyncMethodOrArrow || source[index] !== "{")) return undefined;
+				}
+				return source.slice(openIndex + 1, closeIndex);
+			}
+			if (depth < 0) return undefined;
+		} else if (character === "[") square++;
+		else if (character === "]") {
+			square--;
+			if (square < 0) return undefined;
+		} else if (character === "{") curly++;
+		else if (character === "}") {
+			if (templateDepths.at(-1) === curly) {
+				templateDepths.pop();
+				curly--;
+				quote = "`";
+			} else curly--;
+			if (curly < 0) return undefined;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Conservative defense in depth for defaulted second parameters, which
+ * JavaScript intentionally omits from Function.length. Ambiguous source is
+ * ignored so this check can never reject a valid provider on weak evidence.
+ */
+function authStartHasHiddenInput(start: unknown): boolean {
+	let source: string;
+	try {
+		source = Function.prototype.toString.call(start);
+	} catch {
+		return false;
+	}
+	if (
+		!source ||
+		source.includes("[native code]") ||
+		/^\s*(?:async\s+)?function\s+bound\b/.test(source)
+	)
+		return false;
+
+	const parameters = authStartParameterList(source);
+	if (!parameters) return false;
+	const parts = splitAuthStartParameters(parameters);
+	if (!parts || parts.length < 2) return false;
+
+	// Require ordinary, readable source formatting. This intentionally fails
+	// open for minified output and for transpilers that rewrite defaults.
+	const commaIndex = parameters.indexOf(",");
+	if (commaIndex < 0 || !/\s/.test(parameters[commaIndex + 1] ?? "")) return false;
+	const first = parts[0].trim();
+	const second = parts[1].trim();
+	const identifier = /^[_$A-Za-z][_$A-Za-z0-9]*/;
+	const firstName = first.match(identifier)?.[0];
+	const secondName = second.match(identifier)?.[0];
+	if (!firstName || !secondName || firstName.length < 3 || secondName.length < 3) return false;
+	return /\s=\s/.test(second);
+}
 
-export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
+export interface ProviderDeclaration {
 	id: string;
 	version: string;
 	runtime: "standard" | "shared" | "browser";
@@ -272,6 +586,8 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 	 * resolves omitted fields against the runtime deployment profiles.
 	 */
 	deployment?: ProviderDeploymentOverrides;
+	/** Declares that provider operations use the SDK HTTP client. */
+	http?: true;
 	allowedHosts?: string[];
 	native?: NativeProviderConfig;
 	stealth?: {
@@ -284,11 +600,21 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 	resolver?: ProviderResolverConfig;
 	browser?: { engine: BrowserEngine };
 	auth?: AuthConfig;
+	/** Declares that provider operations issue and consume SDK choice tokens. */
+	choice?: true;
 	reviewed?: ProviderReviewed;
 	access?: ProviderAccessConfig;
 	secrets?: ProviderSecretDeclaration[];
+	/** Declares that provider operations read SDK-managed environment values. */
+	env?: true;
 	credential?: CredentialDeclaration;
 	context?: ContextDeclaration;
+	/** Declares that provider operations use SDK-managed persistent state. */
+	state?: true;
+	/** Declares that provider operations use the SDK provider cache. */
+	cache?: true;
+	/** Declares that provider operations access runtime-resolvable files. */
+	files?: true;
 	meta: {
 		displayName: string;
 		displayNameKey?: string;
@@ -310,25 +636,35 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 			publicSchemaFieldNames?: "normalized";
 		};
 	};
-	operations: OperationMapConfig<TOperations>;
 	healthMonitor?: ProviderHealthMonitorConfig;
 	/** New name for `healthMonitor` (transitional alias); declaring both is a ValidationError. */
 	healthProbe?: ProviderHealthMonitorConfig;
 	healthJourneys?: readonly HealthJourneyDefinition[];
 }
 
-/** Define one provider operation with schema-driven handler inference. */
-export function defineOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
-	operation: OperationConfig<TInput, TOutput>,
-): OperationDefinition<TInput, TOutput> {
-	return operation;
+interface ProviderConfig<
+	TOperations extends Record<string, ProviderOperation>,
+	TContext = ProviderContext,
+> extends ProviderDeclaration {
+	operations: OperationMapConfig<TOperations, TContext>;
+}
+
+/** Define one factored provider operation with schema-driven handler inference. */
+export function defineOperation<TContext>() {
+	return function operation<TInput extends SchemaLike, TOutput extends SchemaLike>(
+		config: OperationConfig<TInput, TOutput, TContext>,
+	): OperationDefinition<TInput, TOutput, TContext> {
+		return config;
+	};
 }
 
-/** Define a non-JSON provider operation with explicit transport metadata. */
-export function defineStreamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
-	operation: StreamOperationConfig<TInput, TOutput>,
-): OperationDefinition<TInput, TOutput> {
-	return operation;
+/** Define a factored non-JSON operation with explicit transport metadata. */
+export function defineStreamOperation<TContext>() {
+	return function streamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
+		config: StreamOperationConfig<TInput, TOutput, TContext>,
+	): OperationDefinition<TInput, TOutput, TContext> {
+		return config;
+	};
 }
 
 function assertObjectConfig(value: unknown): asserts value is Record<string, unknown> {
@@ -479,6 +815,14 @@ function validateProviderShape(config: unknown): void {
 	assertRequiredField(config, "operations", String(config.id));
 	if (typeof config.runtime === "string")
 		assertLiteralField(config.runtime, "runtime", VALID_RUNTIMES, String(config.id));
+	if (config.native !== undefined && config.runtime === "browser") {
+		throw new ValidationError(
+			`Provider "${String(config.id)}" cannot declare capability "native" with runtime "browser"`,
+			{
+				fix: 'Use runtime: "standard" or runtime: "shared", or remove the native declaration.',
+			},
+		);
+	}
 	const auth = config.auth;
 	if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
 		assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
@@ -510,6 +854,24 @@ function validateProviderShape(config: unknown): void {
 			},
 		);
 	}
+	if (
+		auth &&
+		typeof auth === "object" &&
+		"flow" in auth &&
+		auth.flow &&
+		typeof auth.flow === "object" &&
+		"start" in auth.flow &&
+		typeof auth.flow.start === "function" &&
+		auth.flow.start.length <= 1 &&
+		authStartHasHiddenInput(auth.flow.start)
+	) {
+		throw new ProviderError(
+			`Provider "${String(config.id)}" auth.flow.start must not declare an input parameter`,
+			{
+				fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
+			},
+		);
+	}
 	const access = config.access;
 	if (access !== undefined) {
 		if (!access || typeof access !== "object" || Array.isArray(access)) {
@@ -768,12 +1130,14 @@ function validateProviderResolver(config: { id: string; resolver?: ProviderResol
 		"resolver",
 		config.id,
 	);
-	validateResolverLiteralArray(
-		resolver.vendors,
-		"resolver.vendors",
-		VALID_PROVIDER_RESOLVER_VENDORS,
-		config.id,
-	);
+	if (resolver.vendors !== undefined) {
+		validateResolverLiteralArray(
+			resolver.vendors,
+			"resolver.vendors",
+			VALID_PROVIDER_RESOLVER_VENDORS,
+			config.id,
+		);
+	}
 	validateResolverLiteralArray(
 		resolver.kinds,
 		"resolver.kinds",
@@ -2464,12 +2828,48 @@ function validateProviderDeployment(providerId: string, deployment: unknown): vo
 		});
 }
 
-export function defineProvider<
+/** The second authoring phase for a declaration established by defineProvider. */
+export type ProviderBuilder<TDeclaration extends ProviderDeclaration> = <
+	TOperations extends Record<string, ProviderOperation>,
+>(
+	implementation: {
+		operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+	},
+) => ProviderDefinition & {
+	operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+};
+
+/** Extract the declaration-derived operation context from a provider builder. */
+export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer TDeclaration>
+	? ProviderContextFor<TDeclaration>
+	: never;
+
+/** Establish a provider declaration before its operations are contextually typed. */
+export function defineProvider<const TDeclaration extends ProviderDeclaration>(
+	declaration: TDeclaration &
+		Record<Exclude<keyof TDeclaration, keyof ProviderDeclaration>, never> &
+		AuthStartNoInputGuard<TDeclaration>,
+): ProviderBuilder<TDeclaration> {
+	const buildProvider = <TOperations extends Record<string, ProviderOperation>>(
+		implementation: {
+			operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+		},
+	) =>
+		finalizeProvider({
+			...declaration,
+			...implementation,
+		} as ProviderConfig<TOperations, ProviderContextFor<TDeclaration>>);
+	return buildProvider as ProviderBuilder<TDeclaration>;
+}
+
+function finalizeProvider<
 	TOperations extends Record<string, ProviderOperation>,
-	TConfig extends ProviderConfig<TOperations>,
+	TContext,
 >(
-	config: TConfig & AuthStartNoInputGuard<TConfig>,
-): ProviderDefinition & { operations: OperationMapConfig<TOperations> } {
+	config: ProviderConfig<TOperations, TContext>,
+): ProviderDefinition & {
+	operations: OperationMapConfig<TOperations, TContext>;
+} {
 	validateProviderShape(config);
 	const operations = resolveOperationFixtureRequests(config.operations);
 	if (!CONNECTOR_ID_REGEX.test(config.id))
@@ -2530,7 +2930,9 @@ export function defineProvider<
 			`Provider "${config.id}" cannot define browser config unless runtime is "browser"`,
 			{ fix: 'Set runtime: "browser" or remove the browser config' },
 		);
-	const provider: ProviderDefinition & { operations: OperationMapConfig<TOperations> } = {
+	const provider: ProviderDefinition & {
+		operations: OperationMapConfig<TOperations, TContext>;
+	} = {
 		id: config.id,
 		version: config.version,
 		runtime: config.runtime,
@@ -2552,7 +2954,8 @@ export function defineProvider<
 		credential: config.credential,
 		context: config.context,
 		meta: config.meta,
-		operations,
+		operations: operations as ProviderDefinition["operations"] &
+			OperationMapConfig<TOperations, TContext>,
 		// Transitional healthMonitor → healthProbe alias: mirror whichever field
 		// was declared onto both so old and new consumers keep working.
 		healthMonitor: config.healthMonitor ?? config.healthProbe,