@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.10

package/src/define.ts

@@ -1,5 +1,7 @@
-import { ProviderError, ValidationError } from "./errors";
-import { safeParseSchemaSync } from "./schema";
+import ms from "ms";
+
+import { ProviderError, ValidationError } from "./errors.js";
+import { safeParseSchemaSync } from "./schema.js";
 import type {
 	AuthConfig,
 	BrowserEngine,
@@ -10,6 +12,7 @@ import type {
 	HealthCheckUnsupported,
 	HealthJourneyDefinition,
 	HealthJourneySchedule,
+	HealthScheduleRandomization,
 	InferSchemaOutput,
 	OperationDefinition,
 	OperationHandlerResult,
@@ -19,8 +22,10 @@ import type {
 	OperationWebSocketTransport,
 	ProviderAccessConfig,
 	ProviderDefinition,
+	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
 	ProviderProxyConfig,
+	ProviderProxyProvider,
 	ProviderPublicProfile,
 	ProviderReviewed,
 	ProviderSecretDeclaration,
@@ -29,7 +34,7 @@ import type {
 	SchemaLike,
 	SmsOtpMatcherDefinition,
 	StealthPlatform,
-} from "./types";
+} from "./types.js";
 import {
 	HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
 	HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN,
@@ -45,7 +50,7 @@ import {
 	STREAM_IDLE_TIMEOUT_MS_MIN,
 	STREAM_MAX_DURATION_MS_MAX,
 	STREAM_MAX_DURATION_MS_MIN,
-} from "./types";
+} from "./types.js";
 
 type ProviderImplementationSourceAccess =
 	| "official_api"
@@ -71,23 +76,10 @@ interface ProviderImplementationProfile {
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
 const OPERATION_ID_REGEX = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const VALID_RUNTIMES = ["standard", "shared", "browser"] as const;
-const VALID_AUTH_MODES = [
-	"none",
-	"platform-managed",
-	"credentials",
-	"oauth2",
-] as const;
+const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"] as const;
 const VALID_PROVIDER_ACCESS_VISIBILITIES = ["public", "early_access"] as const;
-const VALID_PROVIDER_PROXY_MODES = [
-	"disabled",
-	"optional",
-	"required",
-] as const;
-const VALID_PROVIDER_PROXY_PROVIDERS = [
-	"smartproxy",
-	"decodo",
-	"custom",
-] as const;
+const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"] as const;
+const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "nodemaven", "decodo", "custom"] as const;
 const VALID_PROVIDER_PROXY_AFFINITIES = [
 	"request",
 	"operation",
@@ -96,78 +88,52 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
 ] as const;
 const VALID_PROVIDER_STT_MODES = ["optional", "required"] as const;
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
+const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+// Per-vendor provider-declared credential secrets. A required-mode chain must
+// declare every secret of every credentialed vendor it names, so a missing
+// credential fails at build/validation time rather than during a live outage: a
+// declared-but-uncredentialed fallback leg is a silently dead SPOF, which is
+// exactly the failure class the multi-vendor chain exists to remove. Vendors
+// absent from this map (e.g. `custom`/`decodo`, whose credentials come from the
+// `APIFUSE__PROXY__URL` bring-your-own escape hatch, not provider secrets) impose
+// no declaration requirement.
+const VENDOR_REQUIRED_SECRETS: Partial<Record<ProviderProxyProvider, readonly string[]>> = {
+	smartproxy: [SMARTPROXY_APP_KEY_SECRET],
+	nodemaven: [NODEMAVEN_USERNAME_SECRET, NODEMAVEN_PASSWORD_SECRET],
+};
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
 const MCP_TOOL_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
-const VALID_OPERATION_RISK_CLASSES = [
-	"read",
-	"write",
-	"destructive",
-	"external-send",
-] as const;
-const VALID_OPERATION_APPROVAL_POLICIES = [
-	"never",
-	"risk-based",
-	"always",
-] as const;
-const VALID_OPERATION_TRANSPORT_KINDS = [
-	"json",
-	"sse",
-	"http-stream",
-	"websocket",
-] as const;
+const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"] as const;
+const VALID_OPERATION_APPROVAL_POLICIES = ["never", "risk-based", "always"] as const;
+const VALID_OPERATION_TRANSPORT_KINDS = ["json", "sse", "http-stream", "websocket"] as const;
 const SSE_EVENT_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
 const WEBSOCKET_SUBPROTOCOL_REGEX = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 
-const MS_DURATION_UNITS = new Set([
-	"years",
-	"year",
-	"yrs",
-	"yr",
-	"y",
-	"weeks",
-	"week",
-	"w",
-	"days",
-	"day",
-	"d",
-	"hours",
-	"hour",
-	"hrs",
-	"hr",
-	"h",
-	"minutes",
-	"minute",
-	"mins",
-	"min",
-	"m",
-	"seconds",
-	"second",
-	"secs",
-	"sec",
-	"s",
-	"milliseconds",
-	"millisecond",
-	"msecs",
-	"msec",
-	"ms",
-]);
 const MS_DURATION_PATTERN = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))\s*([a-zA-Z]+)?$/;
 
 function isPositiveMsDurationString(value: unknown): value is string {
 	if (typeof value !== "string") return false;
-	const match = value.trim().match(MS_DURATION_PATTERN);
-	if (!match) return false;
-	const amount = Number(match[1]);
-	if (!Number.isFinite(amount) || amount <= 0) return false;
-	const unit = match[2]?.toLowerCase();
-	return unit === undefined || MS_DURATION_UNITS.has(unit);
+	return parsePositiveMsDuration(value) !== undefined;
+}
+
+function msDurationMs(value: string): number {
+	return parsePositiveMsDuration(value) ?? 0;
+}
+
+function parsePositiveMsDuration(value: string): number | undefined {
+	const trimmed = value.trim();
+	if (!MS_DURATION_PATTERN.test(trimmed)) return undefined;
+	const parsed = ms((trimmed.startsWith("+") ? trimmed.slice(1) : trimmed) as ms.StringValue);
+	if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+	return parsed;
 }
 
 type ProviderOperation = OperationDefinition<SchemaLike, SchemaLike>;
-type OperationConfig<
-	TInput extends SchemaLike,
-	TOutput extends SchemaLike,
-> = Omit<OperationDefinition<TInput, TOutput>, "handler"> & {
+type OperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
+	OperationDefinition<TInput, TOutput>,
+	"handler"
+> & {
 	handler(
 		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
 		input: InferSchemaOutput<TInput>,
@@ -175,59 +141,44 @@ type OperationConfig<
 		| OperationHandlerResult<InferSchemaOutput<TOutput>>
 		| Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
 };
-type OperationMapConfig<TOperations extends Record<string, ProviderOperation>> =
-	{
-		[K in keyof TOperations]: TOperations[K] extends OperationDefinition<
-			infer TInput,
-			infer TOutput
-		>
-			? OperationConfig<TInput, TOutput> | OperationDefinition<TInput, TOutput>
-			: never;
-	};
-type StreamOperationConfig<
-	TInput extends SchemaLike,
-	TOutput extends SchemaLike,
-> =
+type OperationMapConfig<TOperations extends Record<string, ProviderOperation>> = {
+	[K in keyof TOperations]: TOperations[K] extends OperationDefinition<infer TInput, infer TOutput>
+		? OperationConfig<TInput, TOutput> | OperationDefinition<TInput, TOutput>
+		: 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 SseOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
+	OperationConfig<TInput, TOutput>,
+	"handler" | "transport"
+> & {
 	transport: OperationSseTransport;
 	handler(
 		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
 		input: InferSchemaOutput<TInput>,
-	):
-		| AsyncIterable<ProviderStreamEvent>
-		| Promise<AsyncIterable<ProviderStreamEvent>>;
+	): 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> = Omit<
+	OperationConfig<TInput, TOutput>,
+	"handler" | "transport"
+> & {
 	transport: OperationHttpStreamTransport;
 	handler(
 		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
 		input: InferSchemaOutput<TInput>,
-	):
-		| Response
-		| ReadableStream<Uint8Array>
-		| Promise<Response | ReadableStream<Uint8Array>>;
+	): 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> = Omit<
+	OperationConfig<TInput, TOutput>,
+	"handler" | "transport"
+> & {
 	transport: OperationWebSocketTransport;
 	handler(
 		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
 		input: InferSchemaOutput<TInput>,
-	):
-		| Response
-		| ReadableStream<Uint8Array>
-		| Promise<Response | ReadableStream<Uint8Array>>;
+	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
 
 type AuthStartNoInputGuard<TConfig> = TConfig extends {
@@ -242,12 +193,17 @@ type AuthStartNoInputGuard<TConfig> = TConfig extends {
 		: unknown
 	: unknown;
 
-export interface ProviderConfig<
-	TOperations extends Record<string, ProviderOperation>,
-> {
+export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
 	id: string;
 	version: string;
 	runtime: "standard" | "shared" | "browser";
+	/**
+	 * Optional deployment overrides, passed through verbatim onto the returned
+	 * provider definition. The SDK types this field but does not deep-validate
+	 * it — the APIFuse registry builder owns deployment validation and
+	 * resolves omitted fields against the runtime deployment profiles.
+	 */
+	deployment?: ProviderDeploymentOverrides;
 	allowedHosts?: string[];
 	stealth?: {
 		profile: string;
@@ -285,39 +241,30 @@ export interface ProviderConfig<
 	};
 	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,
->(
+export function defineOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
 	operation: OperationConfig<TInput, TOutput>,
 ): OperationDefinition<TInput, TOutput> {
 	return operation;
 }
 
 /** Define a non-JSON provider operation with explicit transport metadata. */
-export function defineStreamOperation<
-	TInput extends SchemaLike,
-	TOutput extends SchemaLike,
->(
+export function defineStreamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
 	operation: StreamOperationConfig<TInput, TOutput>,
 ): OperationDefinition<TInput, TOutput> {
 	return operation;
 }
 
-function assertObjectConfig(
-	value: unknown,
-): asserts value is Record<string, unknown> {
+function assertObjectConfig(value: unknown): asserts value is Record<string, unknown> {
 	if (!value || typeof value !== "object") {
-		throw new ProviderError(
-			"defineProvider config must be an object. Offending field: config",
-			{
-				fix: "Pass defineProvider({ id, version, runtime, meta, operations })",
-			},
-		);
+		throw new ProviderError("defineProvider config must be an object. Offending field: config", {
+			fix: "Pass defineProvider({ id, version, runtime, meta, operations })",
+		});
 	}
 }
 function assertRequiredField(
@@ -355,25 +302,18 @@ function validateProviderShape(config: unknown): void {
 	assertRequiredField(config, "meta", String(config.id));
 	assertRequiredField(config, "operations", String(config.id));
 	if (typeof config.runtime === "string")
-		assertLiteralField(
-			config.runtime,
-			"runtime",
-			VALID_RUNTIMES,
-			String(config.id),
-		);
+		assertLiteralField(config.runtime, "runtime", VALID_RUNTIMES, String(config.id));
 	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),
+	if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
+		assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
+	if (auth && typeof auth === "object" && "exchange" in auth) {
+		throw new ProviderError(
+			`Provider "${String(config.id)}" auth.exchange is not part of the Provider SDK auth contract`,
+			{
+				fix: "Use the single canonical auth interface: auth.flow. Gateway calls auth.flow.start/continue/poll/abort/refresh only and persists complete turn data.credential as-is, so put login/token/session exchange inside auth.flow.continue.",
+			},
 		);
+	}
 	if (
 		auth &&
 		typeof auth === "object" &&
@@ -401,9 +341,7 @@ function validateProviderShape(config: unknown): void {
 				},
 			);
 		}
-		const accessRecord: Record<string, unknown> = Object.fromEntries(
-			Object.entries(access),
-		);
+		const accessRecord: Record<string, unknown> = Object.fromEntries(Object.entries(access));
 		for (const key of Object.keys(accessRecord)) {
 			if (key !== "visibility") {
 				throw new ValidationError(`Unknown field "${key}" on access.`, {
@@ -448,31 +386,26 @@ function validateProviderProxy(config: {
 			},
 		);
 	}
-	rejectUnknownFields(
-		proxy,
-		new Set(["mode", "provider", "geo", "session"]),
-		"proxy",
-	);
-	assertLiteralField(
-		proxy.mode,
-		"proxy.mode",
-		VALID_PROVIDER_PROXY_MODES,
-		config.id,
-	);
+	rejectUnknownFields(proxy, new Set(["mode", "provider", "providers", "geo", "session"]), "proxy");
+	assertLiteralField(proxy.mode, "proxy.mode", VALID_PROVIDER_PROXY_MODES, config.id);
 	if (proxy.provider !== undefined) {
-		assertLiteralField(
-			proxy.provider,
-			"proxy.provider",
-			VALID_PROVIDER_PROXY_PROVIDERS,
-			config.id,
-		);
+		assertLiteralField(proxy.provider, "proxy.provider", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
+	}
+	if (proxy.providers !== undefined) {
+		if (!Array.isArray(proxy.providers) || proxy.providers.length === 0) {
+			throw new ValidationError(
+				`Provider "${config.id}" has invalid proxy.providers: must be a non-empty array of proxy vendors.`,
+				{
+					fix: `Use proxy.providers: ["smartproxy", "nodemaven"] to declare an ordered fallback chain.`,
+				},
+			);
+		}
+		for (const vendor of proxy.providers) {
+			assertLiteralField(vendor, "proxy.providers[]", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
+		}
 	}
 	if (proxy.geo !== undefined) {
-		if (
-			!proxy.geo ||
-			typeof proxy.geo !== "object" ||
-			Array.isArray(proxy.geo)
-		) {
+		if (!proxy.geo || typeof proxy.geo !== "object" || Array.isArray(proxy.geo)) {
 			throw new ValidationError(
 				`Provider "${config.id}" has invalid proxy.geo: must be an object.`,
 				{
@@ -480,11 +413,7 @@ function validateProviderProxy(config: {
 				},
 			);
 		}
-		rejectUnknownFields(
-			proxy.geo,
-			new Set(["country", "subdivision", "city"]),
-			"proxy.geo",
-		);
+		rejectUnknownFields(proxy.geo, new Set(["country", "subdivision", "city"]), "proxy.geo");
 		if (proxy.geo.country !== undefined) {
 			assertIsoCountry(proxy.geo.country, "proxy.geo.country");
 		}
@@ -498,11 +427,7 @@ function validateProviderProxy(config: {
 		}
 	}
 	if (proxy.session !== undefined) {
-		if (
-			!proxy.session ||
-			typeof proxy.session !== "object" ||
-			Array.isArray(proxy.session)
-		) {
+		if (!proxy.session || typeof proxy.session !== "object" || Array.isArray(proxy.session)) {
 			throw new ValidationError(
 				`Provider "${config.id}" has invalid proxy.session: must be an object.`,
 				{
@@ -524,51 +449,75 @@ function validateProviderProxy(config: {
 			);
 		}
 		const lifetime = proxy.session.lifetimeMinutes;
-		if (
-			lifetime !== undefined &&
-			(!Number.isFinite(lifetime) || lifetime <= 0)
-		) {
+		if (lifetime !== undefined && (!Number.isFinite(lifetime) || lifetime <= 0)) {
 			throw new ValidationError(
 				`Provider "${config.id}" has invalid proxy.session.lifetimeMinutes: must be a positive number of minutes.`,
 			);
 		}
 		const poolSize = proxy.session.poolSize;
-		if (
-			poolSize !== undefined &&
-			(!Number.isInteger(poolSize) || poolSize <= 0)
-		) {
+		if (poolSize !== undefined && (!Number.isInteger(poolSize) || poolSize <= 0)) {
 			throw new ValidationError(
 				`Provider "${config.id}" has invalid proxy.session.poolSize: must be a positive integer.`,
 			);
 		}
 	}
-	if (proxy.mode === "required" && proxy.provider === "smartproxy") {
-		const hasSmartproxySecret = config.secrets?.some(
-			(secret) =>
-				secret.name === SMARTPROXY_APP_KEY_SECRET && secret.required !== false,
-		);
-		if (!hasSmartproxySecret) {
-			throw new ValidationError(
-				`Provider "${config.id}" requires Smartproxy egress but does not declare ${SMARTPROXY_APP_KEY_SECRET}.`,
-				{
-					fix: `Add secrets: [{ name: "${SMARTPROXY_APP_KEY_SECRET}", required: true }] to the provider.`,
-				},
-			);
+	// Every credentialed vendor in a required-mode chain must declare its
+	// provider secret(s) so a missing credential fails at build/validation time,
+	// not during a live outage. This covers the fallback legs too (not just the
+	// first vendor): a declared-but-uncredentialed nodemaven fallback would leave
+	// the chain silently down to a single vendor, reintroducing the SPOF the chain
+	// removes.
+	const vendorChain =
+		proxy.providers && proxy.providers.length > 0
+			? proxy.providers
+			: proxy.provider
+				? [proxy.provider]
+				: [];
+	if (proxy.mode === "required") {
+		for (const vendor of vendorChain) {
+			const requiredSecrets = VENDOR_REQUIRED_SECRETS[vendor];
+			if (!requiredSecrets) continue;
+			for (const secretName of requiredSecrets) {
+				// Match the canonical runtime gate (assertRequiredSecretsPresent /
+				// listMissingRequiredSecrets), which enforces only `required === true`
+				// declarations. A declaration that omits `required` (defaulting to
+				// optional) is skipped at runtime, so accepting it here would pass
+				// validation while leaving the credential unenforced until proxy
+				// resolution during a live request — the fail-open gap this check exists
+				// to close.
+				const declared = config.secrets?.some(
+					(secret) => secret.name === secretName && secret.required === true,
+				);
+				if (!declared) {
+					throw new ValidationError(
+						`Provider "${config.id}" requires ${vendor} egress but does not declare ${secretName}.`,
+						{
+							fix: `Add secrets: [{ name: "${secretName}", required: true }] to the provider (every vendor in a required proxy chain must declare its credential secrets).`,
+						},
+					);
+				}
+			}
 		}
 	}
+	// `decodo`/`custom` are deprecated vendor values (string-union members, so the
+	// @deprecated symbol gate can't catch them — warn at validation time instead).
+	const deprecatedVendors = vendorChain.filter(
+		(vendor) => vendor === "decodo" || vendor === "custom",
+	);
+	if (deprecatedVendors.length > 0) {
+		console.warn(
+			`[provider-sdk] Provider "${config.id}" uses deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}. Use "smartproxy"/"nodemaven", or the APIFUSE__PROXY__URL bring-your-own escape hatch.`,
+		);
+	}
 }
 
-function validateProviderStt(config: {
-	id: string;
-	stt?: ProviderSttConfig;
-}): void {
+function validateProviderStt(config: { id: string; stt?: ProviderSttConfig }): void {
 	const stt = config.stt;
 	if (stt === undefined) return;
 	if (!stt || typeof stt !== "object" || Array.isArray(stt)) {
-		throw new ValidationError(
-			`Provider "${config.id}" has invalid stt: must be an object.`,
-			{ fix: `Use stt: { mode: "required" } or stt: { mode: "optional" }.` },
-		);
+		throw new ValidationError(`Provider "${config.id}" has invalid stt: must be an object.`, {
+			fix: `Use stt: { mode: "required" } or stt: { mode: "optional" }.`,
+		});
 	}
 	rejectUnknownFields(stt, new Set(["mode"]), "stt");
 	assertLiteralField(stt.mode, "stt.mode", VALID_PROVIDER_STT_MODES, config.id);
@@ -595,16 +544,9 @@ function validateOperationIds(
 			);
 	}
 }
-const OPERATION_CONTRACT_VERSION_REGEX =
-	/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
-const OPERATION_SENSITIVE_PATH_REGEX =
-	/^(?:[A-Za-z0-9_$-]+|\*)(?:\.(?:[A-Za-z0-9_$-]+|\*))*$/;
-const VALID_OPERATION_LIFECYCLES = [
-	"stable",
-	"beta",
-	"deprecated",
-	"removed",
-] as const;
+const OPERATION_CONTRACT_VERSION_REGEX = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const OPERATION_SENSITIVE_PATH_REGEX = /^(?:[A-Za-z0-9_$-]+|\*)(?:\.(?:[A-Za-z0-9_$-]+|\*))*$/;
+const VALID_OPERATION_LIFECYCLES = ["stable", "beta", "deprecated", "removed"] as const;
 
 function assertNonEmptyString(
 	value: unknown,
@@ -635,10 +577,7 @@ function validateToolRouterMetadata(
 				},
 			);
 		}
-		if (
-			toolRouter.name !== undefined &&
-			!MCP_TOOL_NAME_REGEX.test(toolRouter.name)
-		) {
+		if (toolRouter.name !== undefined && !MCP_TOOL_NAME_REGEX.test(toolRouter.name)) {
 			throw new ValidationError(
 				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.toolRouter.name: expected an MCP-safe name.`,
 				{
@@ -710,10 +649,7 @@ function validateOperationContracts(
 				providerId,
 			);
 		}
-		if (
-			contract.lifecycle === "deprecated" ||
-			contract.lifecycle === "removed"
-		) {
+		if (contract.lifecycle === "deprecated" || contract.lifecycle === "removed") {
 			if (!contract.deprecation || typeof contract.deprecation !== "object") {
 				throw new ValidationError(
 					`Provider "${providerId}" operation "${operationName}" is ${contract.lifecycle} but lacks operations.${operationName}.contract.deprecation metadata.`,
@@ -761,10 +697,7 @@ function validateOperationAnnotations(
 					fix: `Set ${field} to an integer in [${OPERATION_TIMEOUT_MS_MIN}, ${OPERATION_TIMEOUT_MS_MAX}] (milliseconds).`,
 				},
 			);
-		if (
-			timeoutMs < OPERATION_TIMEOUT_MS_MIN ||
-			timeoutMs > OPERATION_TIMEOUT_MS_MAX
-		)
+		if (timeoutMs < OPERATION_TIMEOUT_MS_MIN || timeoutMs > OPERATION_TIMEOUT_MS_MAX)
 			throw new ValidationError(
 				`Provider "${providerId}" has invalid ${field}: ${timeoutMs} is outside [${OPERATION_TIMEOUT_MS_MIN}, ${OPERATION_TIMEOUT_MS_MAX}] ms.`,
 				{
@@ -962,12 +895,7 @@ function validateOperationTransports(
 				},
 			);
 		}
-		assertLiteralField(
-			kind,
-			`${fieldPath}.kind`,
-			VALID_OPERATION_TRANSPORT_KINDS,
-			providerId,
-		);
+		assertLiteralField(kind, `${fieldPath}.kind`, VALID_OPERATION_TRANSPORT_KINDS, providerId);
 
 		switch (kind) {
 			case "json":
@@ -999,16 +927,9 @@ function validateOperationTransports(
 					STREAM_MAX_DURATION_MS_MAX,
 					"max duration",
 				);
-				assertPositiveBytes(
-					Reflect.get(transport, "maxEventBytes"),
-					`${fieldPath}.maxEventBytes`,
-				);
+				assertPositiveBytes(Reflect.get(transport, "maxEventBytes"), `${fieldPath}.maxEventBytes`);
 				const resumable = Reflect.get(transport, "resumable");
-				if (
-					resumable !== undefined &&
-					resumable !== false &&
-					resumable !== "last-event-id"
-				) {
+				if (resumable !== undefined && resumable !== false && resumable !== "last-event-id") {
 					throw new ValidationError(
 						`Provider "${providerId}" operation "${operationName}" has invalid ${fieldPath}.resumable: expected false or "last-event-id".`,
 						{
@@ -1028,12 +949,7 @@ function validateOperationTransports(
 				rejectUnknownFields(transport, HTTP_STREAM_TRANSPORT_FIELDS, fieldPath);
 				const contentType = Reflect.get(transport, "contentType");
 				if (contentType !== undefined) {
-					assertNonEmptyString(
-						contentType,
-						`${fieldPath}.contentType`,
-						providerId,
-						operationName,
-					);
+					assertNonEmptyString(contentType, `${fieldPath}.contentType`, providerId, operationName);
 				}
 				assertStreamMs(
 					Reflect.get(transport, "idleTimeoutMs"),
@@ -1049,10 +965,7 @@ function validateOperationTransports(
 					STREAM_MAX_DURATION_MS_MAX,
 					"max duration",
 				);
-				assertPositiveBytes(
-					Reflect.get(transport, "maxChunkBytes"),
-					`${fieldPath}.maxChunkBytes`,
-				);
+				assertPositiveBytes(Reflect.get(transport, "maxChunkBytes"), `${fieldPath}.maxChunkBytes`);
 				break;
 			}
 			case "websocket": {
@@ -1077,10 +990,7 @@ function validateOperationTransports(
 						);
 					}
 					for (const subprotocol of subprotocols) {
-						if (
-							typeof subprotocol !== "string" ||
-							!WEBSOCKET_SUBPROTOCOL_REGEX.test(subprotocol)
-						) {
+						if (typeof subprotocol !== "string" || !WEBSOCKET_SUBPROTOCOL_REGEX.test(subprotocol)) {
 							throw new ValidationError(
 								`Provider "${providerId}" operation "${operationName}" has invalid ${fieldPath}.subprotocols: each subprotocol must be an RFC token string.`,
 								{
@@ -1104,10 +1014,7 @@ function validateOperationTransports(
 					STREAM_MAX_DURATION_MS_MAX,
 					"max duration",
 				);
-				assertPositiveBytes(
-					Reflect.get(transport, "maxFrameBytes"),
-					`${fieldPath}.maxFrameBytes`,
-				);
+				assertPositiveBytes(Reflect.get(transport, "maxFrameBytes"), `${fieldPath}.maxFrameBytes`);
 				break;
 			}
 		}
@@ -1116,6 +1023,7 @@ function validateOperationTransports(
 
 const HEALTH_CHECK_SUITE_FIELDS = new Set([
 	"interval",
+	"schedule",
 	"timeoutMs",
 	"degradedThresholdMs",
 	"cases",
@@ -1169,10 +1077,7 @@ function levenshtein(a: string, b: string): number {
 	return prev[n] ?? 0;
 }
 
-function suggestField(
-	unknown: string,
-	candidates: ReadonlySet<string>,
-): string | undefined {
+function suggestField(unknown: string, candidates: ReadonlySet<string>): string | undefined {
 	let best: string | undefined;
 	let bestDist = 3;
 	for (const candidate of candidates) {
@@ -1185,11 +1090,7 @@ function suggestField(
 	return best;
 }
 
-function rejectUnknownFields(
-	value: object,
-	allowed: ReadonlySet<string>,
-	fieldPath: string,
-): void {
+function rejectUnknownFields(value: object, allowed: ReadonlySet<string>, fieldPath: string): void {
 	for (const key of Object.keys(value)) {
 		if (allowed.has(key)) continue;
 		const hint = suggestField(key, allowed);
@@ -1225,29 +1126,19 @@ function assertBoundedIntegerMs(
 function validateProviderHealthMonitor(
 	providerId: string,
 	healthMonitor: unknown,
+	field: "healthMonitor" | "healthProbe" = "healthMonitor",
 ): void {
 	if (healthMonitor === undefined) return;
-	if (
-		!healthMonitor ||
-		typeof healthMonitor !== "object" ||
-		Array.isArray(healthMonitor)
-	)
-		throw new ValidationError(
-			`Provider "${providerId}" has invalid healthMonitor: must be an object.`,
-			{
-				fix: `Set healthMonitor to { requiredSecrets?: string[]; serviceAccount?: string }`,
-			},
-		);
+	if (!healthMonitor || typeof healthMonitor !== "object" || Array.isArray(healthMonitor))
+		throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an object.`, {
+			fix: `Set ${field} to { requiredSecrets?: string[]; serviceAccount?: string }`,
+		});
 	const healthMonitorRecord = Object.fromEntries(Object.entries(healthMonitor));
-	rejectUnknownFields(
-		healthMonitorRecord,
-		PROVIDER_HEALTH_MONITOR_FIELDS,
-		"healthMonitor",
-	);
+	rejectUnknownFields(healthMonitorRecord, PROVIDER_HEALTH_MONITOR_FIELDS, field);
 	if (healthMonitorRecord.defaultProbeTimeoutMs !== undefined) {
 		assertBoundedIntegerMs(
 			healthMonitorRecord.defaultProbeTimeoutMs,
-			`Provider "${providerId}" healthMonitor.defaultProbeTimeoutMs`,
+			`Provider "${providerId}" ${field}.defaultProbeTimeoutMs`,
 			{
 				min: HEALTH_CHECK_TIMEOUT_MS_MIN,
 				max: HEALTH_CHECK_TIMEOUT_MS_MAX,
@@ -1258,7 +1149,7 @@ function validateProviderHealthMonitor(
 	if (healthMonitorRecord.defaultDegradedThresholdMs !== undefined) {
 		assertBoundedIntegerMs(
 			healthMonitorRecord.defaultDegradedThresholdMs,
-			`Provider "${providerId}" healthMonitor.defaultDegradedThresholdMs`,
+			`Provider "${providerId}" ${field}.defaultDegradedThresholdMs`,
 			{
 				min: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN,
 				max: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
@@ -1270,12 +1161,12 @@ function validateProviderHealthMonitor(
 	if (requiredSecrets !== undefined) {
 		if (!Array.isArray(requiredSecrets))
 			throw new ValidationError(
-				`Provider "${providerId}" has invalid healthMonitor.requiredSecrets: must be string[].`,
+				`Provider "${providerId}" has invalid ${field}.requiredSecrets: must be string[].`,
 			);
 		for (const [index, secret] of requiredSecrets.entries()) {
 			if (typeof secret !== "string" || secret.length === 0)
 				throw new ValidationError(
-					`Provider "${providerId}" has invalid healthMonitor.requiredSecrets[${index}]: must be a non-empty string.`,
+					`Provider "${providerId}" has invalid ${field}.requiredSecrets[${index}]: must be a non-empty string.`,
 				);
 		}
 	}
@@ -1287,23 +1178,23 @@ function validateProviderHealthMonitor(
 			Array.isArray(credentialInputs)
 		) {
 			throw new ValidationError(
-				`Provider "${providerId}" has invalid healthMonitor.credentialInputs: must be an object mapping auth input fields to env var names.`,
+				`Provider "${providerId}" has invalid ${field}.credentialInputs: must be an object mapping auth input fields to env var names.`,
 			);
 		}
-		for (const [field, envVar] of Object.entries(credentialInputs)) {
-			if (field.trim().length === 0) {
+		for (const [inputField, envVar] of Object.entries(credentialInputs)) {
+			if (inputField.trim().length === 0) {
 				throw new ValidationError(
-					`Provider "${providerId}" has invalid healthMonitor.credentialInputs key: must be a non-empty auth input field.`,
+					`Provider "${providerId}" has invalid ${field}.credentialInputs key: must be a non-empty auth input field.`,
 				);
 			}
 			if (typeof envVar !== "string" || envVar.trim().length === 0) {
 				throw new ValidationError(
-					`Provider "${providerId}" has invalid healthMonitor.credentialInputs.${field}: must be a non-empty env var name.`,
+					`Provider "${providerId}" has invalid ${field}.credentialInputs.${inputField}: must be a non-empty env var name.`,
 				);
 			}
 			if (Array.isArray(requiredSecrets) && !requiredSecrets.includes(envVar)) {
 				throw new ValidationError(
-					`Provider "${providerId}" healthMonitor.credentialInputs.${field} references ${envVar}, which must also be listed in healthMonitor.requiredSecrets.`,
+					`Provider "${providerId}" ${field}.credentialInputs.${inputField} references ${envVar}, which must also be listed in ${field}.requiredSecrets.`,
 				);
 			}
 		}
@@ -1311,38 +1202,34 @@ function validateProviderHealthMonitor(
 
 	const probeOverrides = healthMonitorRecord.probeOverrides;
 	if (probeOverrides !== undefined) {
-		if (
-			!probeOverrides ||
-			typeof probeOverrides !== "object" ||
-			Array.isArray(probeOverrides)
-		)
+		if (!probeOverrides || typeof probeOverrides !== "object" || Array.isArray(probeOverrides))
 			throw new ValidationError(
-				`Provider "${providerId}" has invalid healthMonitor.probeOverrides: must be an object keyed by probe id.`,
+				`Provider "${providerId}" has invalid ${field}.probeOverrides: must be an object keyed by probe id.`,
 			);
 		for (const [probeId, override] of Object.entries(probeOverrides)) {
 			if (probeId.length === 0)
 				throw new ValidationError(
-					`Provider "${providerId}" has invalid healthMonitor.probeOverrides key: must be a non-empty probe id.`,
+					`Provider "${providerId}" has invalid ${field}.probeOverrides key: must be a non-empty probe id.`,
 				);
 			if (!override || typeof override !== "object" || Array.isArray(override))
 				throw new ValidationError(
-					`Provider "${providerId}" has invalid healthMonitor.probeOverrides["${probeId}"]: must be an object.`,
+					`Provider "${providerId}" has invalid ${field}.probeOverrides["${probeId}"]: must be an object.`,
 				);
 			const overrideRecord = Object.fromEntries(Object.entries(override));
 			rejectUnknownFields(
 				overrideRecord,
 				PROVIDER_HEALTH_MONITOR_PROBE_OVERRIDE_FIELDS,
-				`healthMonitor.probeOverrides["${probeId}"]`,
+				`${field}.probeOverrides["${probeId}"]`,
 			);
 			const interval = overrideRecord.interval;
 			if (interval !== undefined && !isPositiveMsDurationString(interval))
 				throw new ValidationError(
-					`Provider "${providerId}" has invalid healthMonitor.probeOverrides["${probeId}"].interval: must be a positive ms-style duration string such as 30s, 5m, 8h, or 1 day.`,
+					`Provider "${providerId}" has invalid ${field}.probeOverrides["${probeId}"].interval: must be a positive ms-style duration string such as 30s, 5m, 8h, or 1 day.`,
 				);
 			if (overrideRecord.timeoutMs !== undefined) {
 				assertBoundedIntegerMs(
 					overrideRecord.timeoutMs,
-					`Provider "${providerId}" healthMonitor.probeOverrides["${probeId}"].timeoutMs`,
+					`Provider "${providerId}" ${field}.probeOverrides["${probeId}"].timeoutMs`,
 					{
 						min: HEALTH_CHECK_TIMEOUT_MS_MIN,
 						max: HEALTH_CHECK_TIMEOUT_MS_MAX,
@@ -1353,7 +1240,7 @@ function validateProviderHealthMonitor(
 			if (overrideRecord.degradedThresholdMs !== undefined) {
 				assertBoundedIntegerMs(
 					overrideRecord.degradedThresholdMs,
-					`Provider "${providerId}" healthMonitor.probeOverrides["${probeId}"].degradedThresholdMs`,
+					`Provider "${providerId}" ${field}.probeOverrides["${probeId}"].degradedThresholdMs`,
 					{
 						min: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN,
 						max: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
@@ -1369,7 +1256,7 @@ function validateProviderHealthMonitor(
 		(typeof serviceAccount !== "string" || serviceAccount.length === 0)
 	)
 		throw new ValidationError(
-			`Provider "${providerId}" has invalid healthMonitor.serviceAccount: must be a non-empty string.`,
+			`Provider "${providerId}" has invalid ${field}.serviceAccount: must be a non-empty string.`,
 		);
 }
 
@@ -1381,14 +1268,8 @@ function validateHealthCheckCase(
 ): void {
 	const fieldPath = `operations.${operationName}.healthCheck.cases[${caseIndex}]`;
 	if (!caseValue || typeof caseValue !== "object" || Array.isArray(caseValue))
-		throw new ValidationError(
-			`Provider "${providerId}" ${fieldPath} must be an object.`,
-		);
-	rejectUnknownFields(
-		caseValue as Record<string, unknown>,
-		HEALTH_CHECK_CASE_FIELDS,
-		fieldPath,
-	);
+		throw new ValidationError(`Provider "${providerId}" ${fieldPath} must be an object.`);
+	rejectUnknownFields(caseValue as Record<string, unknown>, HEALTH_CHECK_CASE_FIELDS, fieldPath);
 	const c = caseValue as HealthCheckCase;
 	if (typeof c.name !== "string" || c.name.length === 0)
 		throw new ValidationError(
@@ -1416,15 +1297,11 @@ function validateHealthCheckCase(
 			`Provider "${providerId}" ${fieldPath}.degradedThresholdMs must be an integer degraded threshold in [${HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN}, ${HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX}] ms.`,
 		);
 	if (c.timeoutMs !== undefined) {
-		assertBoundedIntegerMs(
-			c.timeoutMs,
-			`Provider "${providerId}" ${fieldPath}.timeoutMs`,
-			{
-				min: HEALTH_CHECK_TIMEOUT_MS_MIN,
-				max: HEALTH_CHECK_TIMEOUT_MS_MAX,
-				label: "timeout",
-			},
-		);
+		assertBoundedIntegerMs(c.timeoutMs, `Provider "${providerId}" ${fieldPath}.timeoutMs`, {
+			min: HEALTH_CHECK_TIMEOUT_MS_MIN,
+			max: HEALTH_CHECK_TIMEOUT_MS_MAX,
+			label: "timeout",
+		});
 	}
 	if (
 		c.expectedStatus !== undefined &&
@@ -1440,21 +1317,11 @@ function validateHealthCheckCase(
 		);
 }
 
-function validateHealthCheckSuite(
-	providerId: string,
-	operationName: string,
-	suite: unknown,
-): void {
+function validateHealthCheckSuite(providerId: string, operationName: string, suite: unknown): void {
 	const fieldPath = `operations.${operationName}.healthCheck`;
 	if (!suite || typeof suite !== "object" || Array.isArray(suite))
-		throw new ValidationError(
-			`Provider "${providerId}" ${fieldPath} must be an object.`,
-		);
-	rejectUnknownFields(
-		suite as Record<string, unknown>,
-		HEALTH_CHECK_SUITE_FIELDS,
-		fieldPath,
-	);
+		throw new ValidationError(`Provider "${providerId}" ${fieldPath} must be an object.`);
+	rejectUnknownFields(suite as Record<string, unknown>, HEALTH_CHECK_SUITE_FIELDS, fieldPath);
 	const s = suite as HealthCheckSuite;
 	if (!isPositiveMsDurationString(s.interval))
 		throw new ValidationError(
@@ -1463,16 +1330,33 @@ function validateHealthCheckSuite(
 				fix: `Set ${fieldPath}.interval to a positive ms-style duration string.`,
 			},
 		);
+	if (s.schedule !== undefined) {
+		if (!s.schedule || typeof s.schedule !== "object" || Array.isArray(s.schedule)) {
+			throw new ValidationError(
+				`Provider "${providerId}" ${fieldPath}.schedule must be an object.`,
+			);
+		}
+		if (Reflect.get(s.schedule, "jitter") !== undefined) {
+			throw new ValidationError(
+				`Provider "${providerId}" ${fieldPath}.schedule.jitter is not supported for operation healthCheck schedules. Use schedule.randomize instead.`,
+			);
+		}
+		rejectUnknownFields(s.schedule, new Set(["randomize"]), `${fieldPath}.schedule`);
+		const randomize = Reflect.get(s.schedule, "randomize");
+		if (randomize !== undefined) {
+			validateScheduleRandomization(
+				randomize,
+				`Provider "${providerId}" ${fieldPath}.schedule.randomize`,
+				msDurationMs(s.interval),
+			);
+		}
+	}
 	if (s.timeoutMs !== undefined) {
-		assertBoundedIntegerMs(
-			s.timeoutMs,
-			`Provider "${providerId}" ${fieldPath}.timeoutMs`,
-			{
-				min: HEALTH_CHECK_TIMEOUT_MS_MIN,
-				max: HEALTH_CHECK_TIMEOUT_MS_MAX,
-				label: "timeout",
-			},
-		);
+		assertBoundedIntegerMs(s.timeoutMs, `Provider "${providerId}" ${fieldPath}.timeoutMs`, {
+			min: HEALTH_CHECK_TIMEOUT_MS_MIN,
+			max: HEALTH_CHECK_TIMEOUT_MS_MAX,
+			label: "timeout",
+		});
 	}
 	if (s.degradedThresholdMs !== undefined) {
 		assertBoundedIntegerMs(
@@ -1485,10 +1369,7 @@ function validateHealthCheckSuite(
 			},
 		);
 	}
-	if (
-		s.requiresConnection !== undefined &&
-		typeof s.requiresConnection !== "boolean"
-	)
+	if (s.requiresConnection !== undefined && typeof s.requiresConnection !== "boolean")
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath}.requiresConnection must be a boolean.`,
 		);
@@ -1520,14 +1401,8 @@ function validateHealthCheckUnsupported(
 	unsupported: unknown,
 ): void {
 	const fieldPath = `operations.${operationName}.healthCheckUnsupported`;
-	if (
-		!unsupported ||
-		typeof unsupported !== "object" ||
-		Array.isArray(unsupported)
-	)
-		throw new ValidationError(
-			`Provider "${providerId}" ${fieldPath} must be an object.`,
-		);
+	if (!unsupported || typeof unsupported !== "object" || Array.isArray(unsupported))
+		throw new ValidationError(`Provider "${providerId}" ${fieldPath} must be an object.`);
 	rejectUnknownFields(
 		unsupported as Record<string, unknown>,
 		HEALTH_CHECK_UNSUPPORTED_FIELDS,
@@ -1561,7 +1436,7 @@ const HEALTH_JOURNEY_FIELDS = new Set([
 	"steps",
 	"run",
 ]);
-const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set(["kind", "interval", "jitter"]);
+const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set(["kind", "interval", "jitter", "randomize"]);
 const HEALTH_JOURNEY_STEP_FIELDS = new Set([
 	"id",
 	"description",
@@ -1580,10 +1455,7 @@ const HEALTH_JOURNEY_MANUAL_TRIGGER_FIELDS = new Set([
 	"minManualInterval",
 	"publicRationale",
 ]);
-const HEALTH_JOURNEY_MANUAL_TRIGGER_DISABLED_FIELDS = new Set([
-	"enabled",
-	"reason",
-]);
+const HEALTH_JOURNEY_MANUAL_TRIGGER_DISABLED_FIELDS = new Set(["enabled", "reason"]);
 const HEALTH_JOURNEY_MANUAL_TRIGGER_ENABLED_FIELDS = new Set([
 	"enabled",
 	"requiresAcknowledgement",
@@ -1603,32 +1475,18 @@ function validateHealthJourneyManualTrigger(
 	manualTrigger: unknown,
 ): void {
 	const fieldPath = `healthJourneys.${journeyId}.manualTrigger`;
-	if (
-		!manualTrigger ||
-		typeof manualTrigger !== "object" ||
-		Array.isArray(manualTrigger)
-	) {
+	if (!manualTrigger || typeof manualTrigger !== "object" || Array.isArray(manualTrigger)) {
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath} must be an object when present.`,
 		);
 	}
-	rejectUnknownFields(
-		manualTrigger,
-		HEALTH_JOURNEY_MANUAL_TRIGGER_FIELDS,
-		fieldPath,
-	);
+	rejectUnknownFields(manualTrigger, HEALTH_JOURNEY_MANUAL_TRIGGER_FIELDS, fieldPath);
 	const enabled = Reflect.get(manualTrigger, "enabled");
 	if (typeof enabled !== "boolean") {
-		throw new ValidationError(
-			`Provider "${providerId}" ${fieldPath}.enabled must be a boolean.`,
-		);
+		throw new ValidationError(`Provider "${providerId}" ${fieldPath}.enabled must be a boolean.`);
 	}
 	if (enabled === false) {
-		rejectUnknownFields(
-			manualTrigger,
-			HEALTH_JOURNEY_MANUAL_TRIGGER_DISABLED_FIELDS,
-			fieldPath,
-		);
+		rejectUnknownFields(manualTrigger, HEALTH_JOURNEY_MANUAL_TRIGGER_DISABLED_FIELDS, fieldPath);
 		if (
 			Reflect.get(manualTrigger, "reason") !== undefined &&
 			(typeof Reflect.get(manualTrigger, "reason") !== "string" ||
@@ -1640,25 +1498,15 @@ function validateHealthJourneyManualTrigger(
 		}
 		return;
 	}
-	rejectUnknownFields(
-		manualTrigger,
-		HEALTH_JOURNEY_MANUAL_TRIGGER_ENABLED_FIELDS,
-		fieldPath,
-	);
-	const requiresAcknowledgement = Reflect.get(
-		manualTrigger,
-		"requiresAcknowledgement",
-	);
+	rejectUnknownFields(manualTrigger, HEALTH_JOURNEY_MANUAL_TRIGGER_ENABLED_FIELDS, fieldPath);
+	const requiresAcknowledgement = Reflect.get(manualTrigger, "requiresAcknowledgement");
 	if (typeof requiresAcknowledgement !== "boolean") {
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath}.requiresAcknowledgement must be a boolean.`,
 		);
 	}
 	const risk = Reflect.get(manualTrigger, "risk");
-	if (
-		typeof risk !== "string" ||
-		!HEALTH_JOURNEY_MANUAL_TRIGGER_RISKS.has(risk)
-	) {
+	if (typeof risk !== "string" || !HEALTH_JOURNEY_MANUAL_TRIGGER_RISKS.has(risk)) {
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath}.risk must be one of read_only, writes_external_state, or sms_or_payment.`,
 		);
@@ -1669,10 +1517,7 @@ function validateHealthJourneyManualTrigger(
 		);
 	}
 	const minManualInterval = Reflect.get(manualTrigger, "minManualInterval");
-	assertIsoDuration(
-		minManualInterval,
-		`Provider "${providerId}" ${fieldPath}.minManualInterval`,
-	);
+	assertIsoDuration(minManualInterval, `Provider "${providerId}" ${fieldPath}.minManualInterval`);
 	if (isoDurationMs(minManualInterval) <= 0) {
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath}.minManualInterval must be a positive duration.`,
@@ -1703,18 +1548,14 @@ const SMS_ORIGIN_FIELDS_BY_KIND: Record<string, ReadonlySet<string>> = {
 	e164: new Set(["kind", "value", "display"]),
 	nationalServiceCode: new Set(["kind", "country", "value", "display"]),
 };
-const DURATION_RE =
-	/^P(?=\d|T\d)(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$/;
+const DURATION_RE = /^P(?=\d|T\d)(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$/;
 const E164_RE = /^\+[1-9]\d{1,14}$/;
 const ISO_COUNTRY_RE = /^[A-Z]{2}$/;
 const NATIONAL_SERVICE_CODE_RE = /^[0-9]{2,15}$/;
 const BCP47_RE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
 const JOURNEY_ID_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
-function assertIsoDuration(
-	value: unknown,
-	fieldPath: string,
-): asserts value is string {
+function assertIsoDuration(value: unknown, fieldPath: string): asserts value is string {
 	if (typeof value !== "string" || !DURATION_RE.test(value)) {
 		throw new ValidationError(
 			`${fieldPath} must be an ISO 8601 duration for example PT8H or PT2M30S.`,
@@ -1729,15 +1570,49 @@ function isoDurationMs(value: string): number {
 	const hours = Number(/(\d+)H/.exec(value)?.[1] ?? 0);
 	const minutes = Number(/(\d+)M/.exec(value)?.[1] ?? 0);
 	const seconds = Number(/(\d+(?:\.\d+)?)S/.exec(value)?.[1] ?? 0);
-	return (
-		days * 86_400_000 + hours * 3_600_000 + minutes * 60_000 + seconds * 1_000
-	);
+	return days * 86_400_000 + hours * 3_600_000 + minutes * 60_000 + seconds * 1_000;
 }
 
-function assertIsoCountry(
-	value: unknown,
+function scheduleRandomizationMs(randomize: unknown, fieldPath: string): number {
+	const mode = Reflect.get(randomize as object, "mode");
+	switch (mode) {
+		case "centered": {
+			const maxOffset = Reflect.get(randomize as object, "maxOffset");
+			assertIsoDuration(maxOffset, `${fieldPath}.maxOffset`);
+			return isoDurationMs(maxOffset);
+		}
+		case "delayed": {
+			const maxDelay = Reflect.get(randomize as object, "maxDelay");
+			assertIsoDuration(maxDelay, `${fieldPath}.maxDelay`);
+			return isoDurationMs(maxDelay);
+		}
+		default:
+			throw new ValidationError(`${fieldPath}.mode must be "centered" or "delayed".`);
+	}
+}
+
+function validateScheduleRandomization(
+	randomize: unknown,
 	fieldPath: string,
-): asserts value is string {
+	intervalMs: number,
+): void {
+	if (!randomize || typeof randomize !== "object" || Array.isArray(randomize)) {
+		throw new ValidationError(`${fieldPath} must be an object.`);
+	}
+	const mode = Reflect.get(randomize, "mode");
+	const allowedFields =
+		mode === "centered" ? new Set(["mode", "maxOffset"]) : new Set(["mode", "maxDelay"]);
+	rejectUnknownFields(randomize, allowedFields, fieldPath);
+	const offsetMs = scheduleRandomizationMs(randomize, fieldPath);
+	if (offsetMs <= 0) {
+		throw new ValidationError(`${fieldPath} duration must be positive.`);
+	}
+	if (offsetMs >= intervalMs) {
+		throw new ValidationError(`${fieldPath} duration must be shorter than schedule interval.`);
+	}
+}
+
+function assertIsoCountry(value: unknown, fieldPath: string): asserts value is string {
 	if (typeof value !== "string" || !ISO_COUNTRY_RE.test(value)) {
 		throw new ValidationError(
 			`${fieldPath} must be an ISO 3166-1 alpha-2 country code for example KR.`,
@@ -1749,13 +1624,19 @@ function normalizeIntervalDuration(input: string): string {
 	const trimmed = input.trim();
 	const shorthand = /^(\d+)(s|m|h|d)$/i.exec(trimmed);
 	if (shorthand) {
-		const amount = Number(shorthand[1]);
+		const durationMs = msDurationMs(trimmed);
+		const unit = shorthand[2]?.toLowerCase();
+		const amount =
+			unit === "s"
+				? durationMs / 1_000
+				: unit === "m"
+					? durationMs / 60_000
+					: unit === "h"
+						? durationMs / 3_600_000
+						: durationMs / 86_400_000;
 		if (!Number.isInteger(amount) || amount <= 0) {
-			throw new ValidationError(
-				`Journey schedule interval must be a positive duration.`,
-			);
+			throw new ValidationError(`Journey schedule interval must be a positive duration.`);
 		}
-		const unit = shorthand[2]?.toLowerCase();
 		if (unit === "s") return `PT${amount}S`;
 		if (unit === "m") return `PT${amount}M`;
 		if (unit === "h") return `PT${amount}H`;
@@ -1767,18 +1648,34 @@ function normalizeIntervalDuration(input: string): string {
 
 export function every(
 	interval: string,
-	options: { jitter?: string } = {},
+	options: { jitter?: string; randomize?: HealthScheduleRandomization } = {},
 ): HealthJourneySchedule {
+	if (options.jitter !== undefined && options.randomize !== undefined) {
+		throw new ValidationError(
+			`Schedule cannot define both jitter and randomize. Use randomize instead.`,
+		);
+	}
 	const schedule: HealthJourneySchedule = {
 		kind: "interval",
 		interval: normalizeIntervalDuration(interval),
 	};
+	if (options.randomize !== undefined) {
+		schedule.randomize = options.randomize;
+	}
 	if (options.jitter !== undefined) {
 		schedule.jitter = normalizeIntervalDuration(options.jitter);
 	}
 	return schedule;
 }
 
+export function centered(maxOffset: string): HealthScheduleRandomization {
+	return { mode: "centered", maxOffset: normalizeIntervalDuration(maxOffset) };
+}
+
+export function delayed(maxDelay: string): HealthScheduleRandomization {
+	return { mode: "delayed", maxDelay: normalizeIntervalDuration(maxDelay) };
+}
+
 function countCapturingGroups(pattern: RegExp): number {
 	let count = 0;
 	const source = pattern.source;
@@ -1797,11 +1694,7 @@ function countCapturingGroups(pattern: RegExp): number {
 		if (inCharacterClass || char !== "(") continue;
 		const next = source[i + 1];
 		if (next === "?" && source[i + 2] !== "<") continue;
-		if (
-			next === "?" &&
-			source[i + 2] === "<" &&
-			(source[i + 3] === "=" || source[i + 3] === "!")
-		)
+		if (next === "?" && source[i + 2] === "<" && (source[i + 3] === "=" || source[i + 3] === "!"))
 			continue;
 		count += 1;
 	}
@@ -1820,9 +1713,7 @@ function validateSmsOrigin(origin: unknown, fieldPath: string): void {
 	}
 	const kind = Reflect.get(origin, "kind");
 	if (kind !== "e164" && kind !== "nationalServiceCode") {
-		throw new ValidationError(
-			`${fieldPath}.kind must be "e164" or "nationalServiceCode".`,
-		);
+		throw new ValidationError(`${fieldPath}.kind must be "e164" or "nationalServiceCode".`);
 	}
 	rejectUnknownFields(origin, SMS_ORIGIN_FIELDS_BY_KIND[kind], fieldPath);
 	if (kind === "e164") {
@@ -1849,9 +1740,7 @@ function validateSmsOrigin(origin: unknown, fieldPath: string): void {
 		Reflect.get(origin, "display") !== undefined &&
 		typeof Reflect.get(origin, "display") !== "string"
 	) {
-		throw new ValidationError(
-			`${fieldPath}.display must be a string when present.`,
-		);
+		throw new ValidationError(`${fieldPath}.display must be a string when present.`);
 	}
 }
 
@@ -1865,9 +1754,7 @@ function validateSmsOtpMatcher(
 	rejectUnknownFields(matcher, SMS_OTP_MATCHER_FIELDS, fieldPath);
 	const matcherId = Reflect.get(matcher, "id");
 	if (typeof matcherId !== "string" || !JOURNEY_ID_RE.test(matcherId)) {
-		throw new ValidationError(
-			`${fieldPath}.id must be a kebab-case identifier.`,
-		);
+		throw new ValidationError(`${fieldPath}.id must be a kebab-case identifier.`);
 	}
 	assertIsoCountry(Reflect.get(matcher, "country"), `${fieldPath}.country`);
 	if (
@@ -1875,24 +1762,18 @@ function validateSmsOtpMatcher(
 		(typeof Reflect.get(matcher, "locale") !== "string" ||
 			!BCP47_RE.test(Reflect.get(matcher, "locale")))
 	) {
-		throw new ValidationError(
-			`${fieldPath}.locale must be a BCP 47 locale for example ko-KR.`,
-		);
+		throw new ValidationError(`${fieldPath}.locale must be a BCP 47 locale for example ko-KR.`);
 	}
 	if (
 		Reflect.get(matcher, "phoneNumber") !== undefined &&
 		(typeof Reflect.get(matcher, "phoneNumber") !== "string" ||
 			!E164_RE.test(Reflect.get(matcher, "phoneNumber")))
 	) {
-		throw new ValidationError(
-			`${fieldPath}.phoneNumber must be an ITU-T E.164 number.`,
-		);
+		throw new ValidationError(`${fieldPath}.phoneNumber must be an ITU-T E.164 number.`);
 	}
 	const origins = Reflect.get(matcher, "origins");
 	if (!Array.isArray(origins) || origins.length === 0) {
-		throw new ValidationError(
-			`${fieldPath}.origins must be a non-empty array.`,
-		);
+		throw new ValidationError(`${fieldPath}.origins must be a non-empty array.`);
 	}
 	for (const [index, origin] of origins.entries()) {
 		validateSmsOrigin(origin, `${fieldPath}.origins[${index}]`);
@@ -1913,10 +1794,7 @@ function validateSmsOtpMatcher(
 		);
 	}
 	const regex = pattern instanceof RegExp ? pattern : new RegExp(pattern);
-	if (
-		countCapturingGroups(regex) !== 1 &&
-		Reflect.get(code, "capture") === undefined
-	) {
+	if (countCapturingGroups(regex) !== 1 && Reflect.get(code, "capture") === undefined) {
 		throw new ValidationError(
 			`${fieldPath}.code.pattern must contain exactly one OTP capture or declare code.capture.`,
 		);
@@ -1926,20 +1804,12 @@ function validateSmsOtpMatcher(
 		typeof Reflect.get(code, "capture") !== "string" &&
 		typeof Reflect.get(code, "capture") !== "number"
 	) {
-		throw new ValidationError(
-			`${fieldPath}.code.capture must be a string or number when present.`,
-		);
+		throw new ValidationError(`${fieldPath}.code.capture must be a string or number when present.`);
 	}
 	assertIsoDuration(Reflect.get(matcher, "maxAge"), `${fieldPath}.maxAge`);
-	assertIsoDuration(
-		Reflect.get(matcher, "waitTimeout"),
-		`${fieldPath}.waitTimeout`,
-	);
+	assertIsoDuration(Reflect.get(matcher, "waitTimeout"), `${fieldPath}.waitTimeout`);
 	if (Reflect.get(matcher, "clockSkew") !== undefined)
-		assertIsoDuration(
-			Reflect.get(matcher, "clockSkew"),
-			`${fieldPath}.clockSkew`,
-		);
+		assertIsoDuration(Reflect.get(matcher, "clockSkew"), `${fieldPath}.clockSkew`);
 }
 
 export function defineSmsOtpMatcher(
@@ -1971,9 +1841,7 @@ export function defineSmsOtpMatcher(
 	return matcher;
 }
 
-export function defineHealthJourney(
-	config: HealthJourneyDefinition,
-): HealthJourneyDefinition {
+export function defineHealthJourney(config: HealthJourneyDefinition): HealthJourneyDefinition {
 	return config;
 }
 
@@ -1984,24 +1852,31 @@ function validateHealthJourneySchedule(
 ): void {
 	const fieldPath = `healthJourneys.${journeyId}.schedule`;
 	if (!schedule || typeof schedule !== "object" || Array.isArray(schedule)) {
-		throw new ValidationError(
-			`Provider "${providerId}" ${fieldPath} must be an object.`,
-		);
+		throw new ValidationError(`Provider "${providerId}" ${fieldPath} must be an object.`);
 	}
 	rejectUnknownFields(schedule, HEALTH_JOURNEY_SCHEDULE_FIELDS, fieldPath);
 	if (Reflect.get(schedule, "kind") !== "interval")
+		throw new ValidationError(`Provider "${providerId}" ${fieldPath}.kind must be "interval".`);
+	const interval = Reflect.get(schedule, "interval");
+	assertIsoDuration(interval, `Provider "${providerId}" ${fieldPath}.interval`);
+	const randomize = Reflect.get(schedule, "randomize");
+	if (Reflect.get(schedule, "jitter") !== undefined && randomize !== undefined) {
 		throw new ValidationError(
-			`Provider "${providerId}" ${fieldPath}.kind must be "interval".`,
+			`Provider "${providerId}" ${fieldPath} cannot define both jitter and randomize.`,
 		);
-	assertIsoDuration(
-		Reflect.get(schedule, "interval"),
-		`Provider "${providerId}" ${fieldPath}.interval`,
-	);
+	}
 	if (Reflect.get(schedule, "jitter") !== undefined)
 		assertIsoDuration(
 			Reflect.get(schedule, "jitter"),
 			`Provider "${providerId}" ${fieldPath}.jitter`,
 		);
+	if (randomize !== undefined) {
+		validateScheduleRandomization(
+			randomize,
+			`Provider "${providerId}" ${fieldPath}.randomize`,
+			isoDurationMs(interval),
+		);
+	}
 }
 
 function validateHealthJourneys(
@@ -2012,17 +1887,13 @@ function validateHealthJourneys(
 	const covered = new Set<string>();
 	if (healthJourneys === undefined) return covered;
 	if (!Array.isArray(healthJourneys)) {
-		throw new ValidationError(
-			`Provider "${providerId}" healthJourneys must be an array.`,
-		);
+		throw new ValidationError(`Provider "${providerId}" healthJourneys must be an array.`);
 	}
 	const journeyIds = new Set<string>();
 	for (const [index, journey] of healthJourneys.entries()) {
 		const prefix = `healthJourneys[${index}]`;
 		if (!journey || typeof journey !== "object" || Array.isArray(journey)) {
-			throw new ValidationError(
-				`Provider "${providerId}" ${prefix} must be an object.`,
-			);
+			throw new ValidationError(`Provider "${providerId}" ${prefix} must be an object.`);
 		}
 		rejectUnknownFields(journey, HEALTH_JOURNEY_FIELDS, prefix);
 		if (typeof journey.id !== "string" || !JOURNEY_ID_RE.test(journey.id)) {
@@ -2036,10 +1907,7 @@ function validateHealthJourneys(
 			);
 		journeyIds.add(journey.id);
 		validateHealthJourneySchedule(providerId, journey.id, journey.schedule);
-		if (
-			!Array.isArray(journey.coversOperations) ||
-			journey.coversOperations.length === 0
-		) {
+		if (!Array.isArray(journey.coversOperations) || journey.coversOperations.length === 0) {
 			throw new ValidationError(
 				`Provider "${providerId}" healthJourneys.${journey.id}.coversOperations must be a non-empty array.`,
 			);
@@ -2074,10 +1942,7 @@ function validateHealthJourneys(
 					`Provider "${providerId}" healthJourneys.${journey.id}.smsMatchers must be an array.`,
 				);
 			for (const [matcherIndex, matcher] of journey.smsMatchers.entries()) {
-				validateSmsOtpMatcher(
-					matcher,
-					`healthJourneys.${journey.id}.smsMatchers[${matcherIndex}]`,
-				);
+				validateSmsOtpMatcher(matcher, `healthJourneys.${journey.id}.smsMatchers[${matcherIndex}]`);
 				if (matcherIds.has(matcher.id))
 					throw new ValidationError(
 						`Provider "${providerId}" healthJourneys.${journey.id}.smsMatchers has duplicate matcher id "${matcher.id}".`,
@@ -2088,9 +1953,7 @@ function validateHealthJourneys(
 		for (const [stepIndex, step] of journey.steps.entries()) {
 			const stepPath = `healthJourneys.${journey.id}.steps[${stepIndex}]`;
 			if (!step || typeof step !== "object" || Array.isArray(step))
-				throw new ValidationError(
-					`Provider "${providerId}" ${stepPath} must be an object.`,
-				);
+				throw new ValidationError(`Provider "${providerId}" ${stepPath} must be an object.`);
 			rejectUnknownFields(step, HEALTH_JOURNEY_STEP_FIELDS, stepPath);
 			if (typeof step.id !== "string" || !JOURNEY_ID_RE.test(step.id))
 				throw new ValidationError(
@@ -2100,20 +1963,13 @@ function validateHealthJourneys(
 				throw new ValidationError(
 					`Provider "${providerId}" ${stepPath}.operationId references unknown operation "${step.operationId}".`,
 				);
-			if (
-				step.usesSmsMatcher !== undefined &&
-				!matcherIds.has(step.usesSmsMatcher)
-			)
+			if (step.usesSmsMatcher !== undefined && !matcherIds.has(step.usesSmsMatcher))
 				throw new ValidationError(
 					`Provider "${providerId}" ${stepPath}.usesSmsMatcher references unknown matcher "${step.usesSmsMatcher}".`,
 				);
 		}
 		if (journey.manualTrigger !== undefined)
-			validateHealthJourneyManualTrigger(
-				providerId,
-				journey.id,
-				journey.manualTrigger,
-			);
+			validateHealthJourneyManualTrigger(providerId, journey.id, journey.manualTrigger);
 		if (journey.timeout !== undefined)
 			assertIsoDuration(
 				journey.timeout,
@@ -2159,23 +2015,10 @@ function validateOperationHealthChecks(
 					fix: `Remove either operations.${operationName}.healthCheck or operations.${operationName}.healthCheckUnsupported.`,
 				},
 			);
-		if (hasCheck)
-			validateHealthCheckSuite(
-				providerId,
-				operationName,
-				operation.healthCheck,
-			);
+		if (hasCheck) validateHealthCheckSuite(providerId, operationName, operation.healthCheck);
 		if (hasUnsupported)
-			validateHealthCheckUnsupported(
-				providerId,
-				operationName,
-				operation.healthCheckUnsupported,
-			);
-		if (
-			!hasCheck &&
-			!hasUnsupported &&
-			!journeyCoveredOperations.has(operationName)
-		)
+			validateHealthCheckUnsupported(providerId, operationName, operation.healthCheckUnsupported);
+		if (!hasCheck && !hasUnsupported && !journeyCoveredOperations.has(operationName))
 			throw new ValidationError(
 				`Provider "${providerId}" operation "${operationName}" declares neither healthCheck nor healthCheckUnsupported.`,
 				{
@@ -2230,6 +2073,19 @@ function validateOperationFixtures(
 	}
 }
 
+/**
+ * Shallow shape guard only: the `deployment` object is passed through
+ * verbatim and deliberately not deep-validated by the SDK — the APIFuse
+ * registry builder owns deployment validation and profile resolution.
+ */
+function validateProviderDeployment(providerId: string, deployment: unknown): void {
+	if (deployment === undefined) return;
+	if (!deployment || typeof deployment !== "object" || Array.isArray(deployment))
+		throw new ProviderError(`Provider "${providerId}" deployment must be an object when present`, {
+			fix: 'Pass deployment: { runtime: "shared" | "dedicated" | "browser", ... } or remove the field',
+		});
+}
+
 export function defineProvider<
 	TOperations extends Record<string, ProviderOperation>,
 	TConfig extends ProviderConfig<TOperations>,
@@ -2242,10 +2098,9 @@ export function defineProvider<
 			fix: 'Use lowercase alphanumeric with dashes, e.g., "korea-air-quality"',
 		});
 	if (Object.keys(config.operations).length === 0)
-		throw new ProviderError(
-			`Provider "${config.id}" must define at least one operation`,
-			{ fix: "Add at least one operation to the operations object" },
-		);
+		throw new ProviderError(`Provider "${config.id}" must define at least one operation`, {
+			fix: "Add at least one operation to the operations object",
+		});
 	validateOperationIds(config.id, config.operations);
 	validateOperationAnnotations(config.id, config.operations);
 	validateOperationObservability(config.id, config.operations);
@@ -2257,13 +2112,21 @@ export function defineProvider<
 		config.operations,
 		config.healthJourneys,
 	);
-	validateOperationHealthChecks(
+	validateOperationHealthChecks(config.id, config.operations, journeyCoveredOperations);
+	if (config.healthMonitor !== undefined && config.healthProbe !== undefined)
+		throw new ValidationError(
+			`Provider "${config.id}" declares both healthMonitor and healthProbe. They are aliases; declare exactly one.`,
+			{
+				fix: "Keep healthProbe (the new name) and delete the healthMonitor block.",
+			},
+		);
+	validateProviderHealthMonitor(
 		config.id,
-		config.operations,
-		journeyCoveredOperations,
+		config.healthProbe ?? config.healthMonitor,
+		config.healthProbe !== undefined ? "healthProbe" : "healthMonitor",
 	);
-	validateProviderHealthMonitor(config.id, config.healthMonitor);
 	validateOperationFixtures(config.id, config.operations);
+	validateProviderDeployment(config.id, config.deployment);
 	validateProviderProxy(config);
 	validateProviderStt(config);
 	if (config.runtime === "browser" && !config.browser)
@@ -2282,6 +2145,9 @@ export function defineProvider<
 		id: config.id,
 		version: config.version,
 		runtime: config.runtime,
+		// Verbatim passthrough: deployment validation and profile resolution
+		// are owned by the APIFuse registry builder, not the SDK.
+		deployment: config.deployment,
 		allowedHosts: config.allowedHosts,
 		stealth: config.stealth,
 		proxy: config.proxy,
@@ -2295,7 +2161,10 @@ export function defineProvider<
 		context: config.context,
 		meta: config.meta,
 		operations: config.operations,
-		healthMonitor: config.healthMonitor,
+		// Transitional healthMonitor → healthProbe alias: mirror whichever field
+		// was declared onto both so old and new consumers keep working.
+		healthMonitor: config.healthMonitor ?? config.healthProbe,
+		healthProbe: config.healthProbe ?? config.healthMonitor,
 		healthJourneys: config.healthJourneys,
 	};
 }