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

package/dist/define.js

@@ -1,26 +1,14 @@
-import { ProviderError, ValidationError } from "./errors";
-import { safeParseSchemaSync } from "./schema";
-import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types";
+import ms from "ms";
+import { ProviderError, ValidationError } from "./errors.js";
+import { safeParseSchemaSync } from "./schema.js";
+import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 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"];
-const VALID_AUTH_MODES = [
-    "none",
-    "platform-managed",
-    "credentials",
-    "oauth2",
-];
+const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"];
 const VALID_PROVIDER_ACCESS_VISIBILITIES = ["public", "early_access"];
-const VALID_PROVIDER_PROXY_MODES = [
-    "disabled",
-    "optional",
-    "required",
-];
-const VALID_PROVIDER_PROXY_PROVIDERS = [
-    "smartproxy",
-    "decodo",
-    "custom",
-];
+const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"];
+const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "nodemaven", "decodo", "custom"];
 const VALID_PROVIDER_PROXY_AFFINITIES = [
     "request",
     "operation",
@@ -29,72 +17,44 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
 ];
 const VALID_PROVIDER_STT_MODES = ["optional", "required"];
 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 = {
+    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",
-];
-const VALID_OPERATION_APPROVAL_POLICIES = [
-    "never",
-    "risk-based",
-    "always",
-];
-const VALID_OPERATION_TRANSPORT_KINDS = [
-    "json",
-    "sse",
-    "http-stream",
-    "websocket",
-];
+const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"];
+const VALID_OPERATION_APPROVAL_POLICIES = ["never", "risk-based", "always"];
+const VALID_OPERATION_TRANSPORT_KINDS = ["json", "sse", "http-stream", "websocket"];
 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) {
     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) {
+    return parsePositiveMsDuration(value) ?? 0;
+}
+function parsePositiveMsDuration(value) {
+    const trimmed = value.trim();
+    if (!MS_DURATION_PATTERN.test(trimmed))
+        return undefined;
+    const parsed = ms((trimmed.startsWith("+") ? trimmed.slice(1) : trimmed));
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return undefined;
+    return parsed;
 }
 /** Define one provider operation with schema-driven handler inference. */
 export function defineOperation(operation) {
@@ -136,11 +96,13 @@ function validateProviderShape(config) {
     if (typeof config.runtime === "string")
         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")
+    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" &&
         "flow" in auth &&
@@ -189,15 +151,23 @@ function validateProviderProxy(config) {
             fix: `Use proxy: { mode: "required", provider: "smartproxy", geo: { country: "KR" }, session: { affinity: "connection", lifetimeMinutes: 30 } }`,
         });
     }
-    rejectUnknownFields(proxy, new Set(["mode", "provider", "geo", "session"]), "proxy");
+    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);
     }
+    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.`, {
                 fix: `Use proxy.geo: { country: "KR" } with ISO alpha-2 country codes.`,
             });
@@ -214,9 +184,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.`, {
                 fix: `Use proxy.session: { affinity: "connection", lifetimeMinutes: 30 }.`,
             });
@@ -226,31 +194,62 @@ function validateProviderProxy(config) {
             assertLiteralField(proxy.session.affinity, "proxy.session.affinity", VALID_PROVIDER_PROXY_AFFINITIES, config.id);
         }
         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) {
     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);
@@ -269,12 +268,7 @@ function validateOperationIds(providerId, operations) {
 }
 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",
-];
+const VALID_OPERATION_LIFECYCLES = ["stable", "beta", "deprecated", "removed"];
 function assertNonEmptyString(value, field, providerId, operationName) {
     if (typeof value !== "string" || value.trim().length === 0) {
         throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid ${field}: must be a non-empty string.`, { fix: `Set ${field} to a non-empty customer-facing value.` });
@@ -290,8 +284,7 @@ function validateToolRouterMetadata(providerId, operations) {
                 fix: `Remove operations.${operationName}.toolRouter or provide MCP-safe metadata.`,
             });
         }
-        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.`, {
                 fix: `Use letters, numbers, and underscores only, starting with a letter, for example "${providerId.replace(/[^A-Za-z0-9]+/g, "_")}__${operationName.replace(/[^A-Za-z0-9]+/g, "_")}".`,
             });
@@ -329,8 +322,7 @@ function validateOperationContracts(providerId, operations) {
         if (contract.lifecycle !== undefined) {
             assertLiteralField(contract.lifecycle, `operations.${operationName}.contract.lifecycle`, VALID_OPERATION_LIFECYCLES, 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.`, {
                     fix: `Add announcedAt, removalAfter, and migrationGuide to operations.${operationName}.contract.deprecation.`,
@@ -355,8 +347,7 @@ function validateOperationAnnotations(providerId, operations) {
             throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an integer number of milliseconds.`, {
                 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.`, {
                 fix: `Set ${field} to an integer in [${OPERATION_TIMEOUT_MS_MIN}, ${OPERATION_TIMEOUT_MS_MAX}] ms (the upper bound stays below the gateway/ALB ceiling).`,
             });
@@ -500,9 +491,7 @@ function validateOperationTransports(providerId, operations) {
                 assertStreamMs(maxDurationMs, `${fieldPath}.maxDurationMs`, STREAM_MAX_DURATION_MS_MIN, STREAM_MAX_DURATION_MS_MAX, "max duration");
                 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".`, {
                         fix: `Use ${fieldPath}.resumable: "last-event-id" for SSE Last-Event-ID resume support, or false to disable resume.`,
                     });
@@ -537,8 +526,7 @@ function validateOperationTransports(providerId, operations) {
                         });
                     }
                     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.`, {
                                 fix: `Use values such as "apifuse.v1" without spaces or separators that are invalid for Sec-WebSocket-Protocol.`,
                             });
@@ -555,6 +543,7 @@ function validateOperationTransports(providerId, operations) {
 }
 const HEALTH_CHECK_SUITE_FIELDS = new Set([
     "interval",
+    "schedule",
     "timeoutMs",
     "degradedThresholdMs",
     "cases",
@@ -642,26 +631,24 @@ function assertBoundedIntegerMs(value, fieldPath, options) {
         });
     }
 }
-function validateProviderHealthMonitor(providerId, healthMonitor) {
+function validateProviderHealthMonitor(providerId, healthMonitor, field = "healthMonitor") {
     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`, {
+        assertBoundedIntegerMs(healthMonitorRecord.defaultProbeTimeoutMs, `Provider "${providerId}" ${field}.defaultProbeTimeoutMs`, {
             min: HEALTH_CHECK_TIMEOUT_MS_MIN,
             max: HEALTH_CHECK_TIMEOUT_MS_MAX,
             label: "timeout",
         });
     }
     if (healthMonitorRecord.defaultDegradedThresholdMs !== undefined) {
-        assertBoundedIntegerMs(healthMonitorRecord.defaultDegradedThresholdMs, `Provider "${providerId}" healthMonitor.defaultDegradedThresholdMs`, {
+        assertBoundedIntegerMs(healthMonitorRecord.defaultDegradedThresholdMs, `Provider "${providerId}" ${field}.defaultDegradedThresholdMs`, {
             min: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN,
             max: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
             label: "degraded threshold",
@@ -670,10 +657,10 @@ function validateProviderHealthMonitor(providerId, healthMonitor) {
     const requiredSecrets = healthMonitorRecord.requiredSecrets;
     if (requiredSecrets !== undefined) {
         if (!Array.isArray(requiredSecrets))
-            throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.requiredSecrets: must be string[].`);
+            throw new ValidationError(`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.`);
+                throw new ValidationError(`Provider "${providerId}" has invalid ${field}.requiredSecrets[${index}]: must be a non-empty string.`);
         }
     }
     const credentialInputs = healthMonitorRecord.credentialInputs;
@@ -681,45 +668,43 @@ function validateProviderHealthMonitor(providerId, healthMonitor) {
         if (!credentialInputs ||
             typeof credentialInputs !== "object" ||
             Array.isArray(credentialInputs)) {
-            throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.credentialInputs: must be an object mapping auth input fields to env var names.`);
+            throw new ValidationError(`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) {
-                throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.credentialInputs key: must be a non-empty auth input field.`);
+        for (const [inputField, envVar] of Object.entries(credentialInputs)) {
+            if (inputField.trim().length === 0) {
+                throw new ValidationError(`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.`);
+                throw new ValidationError(`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.`);
+                throw new ValidationError(`Provider "${providerId}" ${field}.credentialInputs.${inputField} references ${envVar}, which must also be listed in ${field}.requiredSecrets.`);
             }
         }
     }
     const probeOverrides = healthMonitorRecord.probeOverrides;
     if (probeOverrides !== undefined) {
-        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.`);
+        if (!probeOverrides || typeof probeOverrides !== "object" || Array.isArray(probeOverrides))
+            throw new ValidationError(`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.`);
+                throw new ValidationError(`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.`);
+                throw new ValidationError(`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}"]`);
+            rejectUnknownFields(overrideRecord, PROVIDER_HEALTH_MONITOR_PROBE_OVERRIDE_FIELDS, `${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.`);
+                throw new ValidationError(`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`, {
+                assertBoundedIntegerMs(overrideRecord.timeoutMs, `Provider "${providerId}" ${field}.probeOverrides["${probeId}"].timeoutMs`, {
                     min: HEALTH_CHECK_TIMEOUT_MS_MIN,
                     max: HEALTH_CHECK_TIMEOUT_MS_MAX,
                     label: "timeout",
                 });
             }
             if (overrideRecord.degradedThresholdMs !== undefined) {
-                assertBoundedIntegerMs(overrideRecord.degradedThresholdMs, `Provider "${providerId}" healthMonitor.probeOverrides["${probeId}"].degradedThresholdMs`, {
+                assertBoundedIntegerMs(overrideRecord.degradedThresholdMs, `Provider "${providerId}" ${field}.probeOverrides["${probeId}"].degradedThresholdMs`, {
                     min: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN,
                     max: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
                     label: "degraded threshold",
@@ -730,7 +715,7 @@ function validateProviderHealthMonitor(providerId, healthMonitor) {
     const serviceAccount = healthMonitorRecord.serviceAccount;
     if (serviceAccount !== undefined &&
         (typeof serviceAccount !== "string" || serviceAccount.length === 0))
-        throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.serviceAccount: must be a non-empty string.`);
+        throw new ValidationError(`Provider "${providerId}" has invalid ${field}.serviceAccount: must be a non-empty string.`);
 }
 function validateHealthCheckCase(providerId, operationName, caseValue, caseIndex) {
     const fieldPath = `operations.${operationName}.healthCheck.cases[${caseIndex}]`;
@@ -776,6 +761,19 @@ function validateHealthCheckSuite(providerId, operationName, suite) {
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.interval must be a positive ms-style duration string such as 30s, 5m, 8h, or 1 day.`, {
             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,
@@ -790,8 +788,7 @@ function validateHealthCheckSuite(providerId, operationName, suite) {
             label: "degraded threshold",
         });
     }
-    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.`);
     if (!Array.isArray(s.cases) || s.cases.length === 0)
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.cases must be a non-empty array.`, {
@@ -810,9 +807,7 @@ function validateHealthCheckSuite(providerId, operationName, suite) {
 }
 function validateHealthCheckUnsupported(providerId, operationName, unsupported) {
     const fieldPath = `operations.${operationName}.healthCheckUnsupported`;
-    if (!unsupported ||
-        typeof unsupported !== "object" ||
-        Array.isArray(unsupported))
+    if (!unsupported || typeof unsupported !== "object" || Array.isArray(unsupported))
         throw new ValidationError(`Provider "${providerId}" ${fieldPath} must be an object.`);
     rejectUnknownFields(unsupported, HEALTH_CHECK_UNSUPPORTED_FIELDS, fieldPath);
     const u = unsupported;
@@ -837,7 +832,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",
@@ -855,10 +850,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",
@@ -873,9 +865,7 @@ const HEALTH_JOURNEY_MANUAL_TRIGGER_RISKS = new Set([
 ]);
 function validateHealthJourneyManualTrigger(providerId, journeyId, manualTrigger) {
     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);
@@ -898,8 +888,7 @@ function validateHealthJourneyManualTrigger(providerId, journeyId, manualTrigger
         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.`);
     }
     if (risk !== "read_only" && requiresAcknowledgement !== true) {
@@ -951,7 +940,39 @@ function isoDurationMs(value) {
     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 scheduleRandomizationMs(randomize, fieldPath) {
+    const mode = Reflect.get(randomize, "mode");
+    switch (mode) {
+        case "centered": {
+            const maxOffset = Reflect.get(randomize, "maxOffset");
+            assertIsoDuration(maxOffset, `${fieldPath}.maxOffset`);
+            return isoDurationMs(maxOffset);
+        }
+        case "delayed": {
+            const maxDelay = Reflect.get(randomize, "maxDelay");
+            assertIsoDuration(maxDelay, `${fieldPath}.maxDelay`);
+            return isoDurationMs(maxDelay);
+        }
+        default:
+            throw new ValidationError(`${fieldPath}.mode must be "centered" or "delayed".`);
+    }
+}
+function validateScheduleRandomization(randomize, fieldPath, intervalMs) {
+    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, fieldPath) {
     if (typeof value !== "string" || !ISO_COUNTRY_RE.test(value)) {
@@ -962,11 +983,18 @@ function normalizeIntervalDuration(input) {
     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.`);
         }
-        const unit = shorthand[2]?.toLowerCase();
         if (unit === "s")
             return `PT${amount}S`;
         if (unit === "m")
@@ -980,15 +1008,27 @@ function normalizeIntervalDuration(input) {
     return trimmed;
 }
 export function every(interval, options = {}) {
+    if (options.jitter !== undefined && options.randomize !== undefined) {
+        throw new ValidationError(`Schedule cannot define both jitter and randomize. Use randomize instead.`);
+    }
     const schedule = {
         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) {
+    return { mode: "centered", maxOffset: normalizeIntervalDuration(maxOffset) };
+}
+export function delayed(maxDelay) {
+    return { mode: "delayed", maxDelay: normalizeIntervalDuration(maxDelay) };
+}
 function countCapturingGroups(pattern) {
     let count = 0;
     const source = pattern.source;
@@ -1010,9 +1050,7 @@ function countCapturingGroups(pattern) {
         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;
     }
@@ -1090,8 +1128,7 @@ function validateSmsOtpMatcher(matcher, fieldPath) {
         throw new ValidationError(`${fieldPath}.code.pattern must be a RegExp or pattern source string.`);
     }
     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.`);
     }
     if (Reflect.get(code, "capture") !== undefined &&
@@ -1140,9 +1177,17 @@ function validateHealthJourneySchedule(providerId, journeyId, schedule) {
     rejectUnknownFields(schedule, HEALTH_JOURNEY_SCHEDULE_FIELDS, fieldPath);
     if (Reflect.get(schedule, "kind") !== "interval")
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.kind must be "interval".`);
-    assertIsoDuration(Reflect.get(schedule, "interval"), `Provider "${providerId}" ${fieldPath}.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} cannot define both jitter and randomize.`);
+    }
     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(providerId, operations, healthJourneys) {
     const covered = new Set();
@@ -1165,8 +1210,7 @@ function validateHealthJourneys(providerId, operations, healthJourneys) {
             throw new ValidationError(`Provider "${providerId}" has duplicate health journey id "${journey.id}".`);
         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.`);
         }
         for (const operationId of journey.coversOperations) {
@@ -1204,8 +1248,7 @@ function validateHealthJourneys(providerId, operations, healthJourneys) {
                 throw new ValidationError(`Provider "${providerId}" ${stepPath}.id must be a kebab-case identifier.`);
             if (step.operationId !== undefined && !operations[step.operationId])
                 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)
@@ -1239,9 +1282,7 @@ function validateOperationHealthChecks(providerId, operations, journeyCoveredOpe
             validateHealthCheckSuite(providerId, operationName, operation.healthCheck);
         if (hasUnsupported)
             validateHealthCheckUnsupported(providerId, operationName, operation.healthCheckUnsupported);
-        if (!hasCheck &&
-            !hasUnsupported &&
-            !journeyCoveredOperations.has(operationName))
+        if (!hasCheck && !hasUnsupported && !journeyCoveredOperations.has(operationName))
             throw new ValidationError(`Provider "${providerId}" operation "${operationName}" declares neither healthCheck nor healthCheckUnsupported.`, {
                 fix: `Add \`healthCheck: { interval, cases: [...] }\` or \`healthCheckUnsupported: { reason: "..." }\` to operations.${operationName}.`,
             });
@@ -1271,6 +1312,19 @@ function validateOperationFixtures(providerId, operations) {
         }
     }
 }
+/**
+ * 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, deployment) {
+    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(config) {
     validateProviderShape(config);
     if (!CONNECTOR_ID_REGEX.test(config.id))
@@ -1278,7 +1332,9 @@ export function defineProvider(config) {
             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);
@@ -1287,8 +1343,13 @@ export function defineProvider(config) {
     validateToolRouterMetadata(config.id, config.operations);
     const journeyCoveredOperations = validateHealthJourneys(config.id, config.operations, config.healthJourneys);
     validateOperationHealthChecks(config.id, config.operations, journeyCoveredOperations);
-    validateProviderHealthMonitor(config.id, config.healthMonitor);
+    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.healthProbe ?? config.healthMonitor, config.healthProbe !== undefined ? "healthProbe" : "healthMonitor");
     validateOperationFixtures(config.id, config.operations);
+    validateProviderDeployment(config.id, config.deployment);
     validateProviderProxy(config);
     validateProviderStt(config);
     if (config.runtime === "browser" && !config.browser)
@@ -1301,6 +1362,9 @@ export function defineProvider(config) {
         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,
@@ -1314,7 +1378,10 @@ export function defineProvider(config) {
         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,
     };
 }