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

package/src/cli/templates/provider/skills/normalization-standards/SKILL.md.tpl

@@ -0,0 +1,57 @@
+---
+name: normalization-standards
+description: Public output contract rules — field naming, timestamps, enums, units, nullability. Load before writing or editing any output schema or mapper.
+---
+
+# Normalization standards
+
+Public output is the product. Apply these to every schema + mapper pair.
+
+## Field naming
+- `snake_case`, English, semantic. `emergency_phone`, not `dutyTel3`.
+- Never expose vendor key vocabularies (`hv1`..`hv12`, `MKioskTy*`, `duty*`)
+  as public field names OR as dynamic record keys. A
+  `z.record(z.string(), ...)` keyed by vendor codes is still a vendor leak —
+  map codes to a stable public vocabulary (enum keys or an array of
+  `{ code, label, status }` objects with normalized status).
+
+## Timestamps and dates
+- Public: ISO 8601 (`2026-07-07T22:28:55+09:00`, dates `2026-07-07`,
+  clock times `HH:MM`). Include the upstream's timezone offset; Korean public
+  APIs are KST (+09:00) — verify, then encode it.
+- Vendor formats (`YYYYMMDDHHmmss`, `HHmm`, unpadded `900`) are parsed inside
+  the mapper. Unparseable → `null`, plus a test for that row shape.
+- Never emit a raw vendor timestamp string in public output, including
+  fixtures.
+
+## Enums
+- Vendor status values (codes, `Y`/`N`, Korean labels like `불가능`,
+  `정보미제공`) → declared `z.enum`. Unknown value → explicit `unknown` member
+  or fail closed; never pass raw text through.
+- Map from the OFFICIAL code table, not from guessing what live samples mean.
+  Add a regression test per enum member.
+
+## Numbers and units
+- Field name states the unit: `distance_meters`, `radius_meters`,
+  `price_krw`. Mapper proves the conversion (upstream km → `* 1000`).
+- Verify the upstream unit from spec or live-data sanity check (a "distance"
+  of `1.2` from a nearby search is km, not meters). Sibling endpoints of the
+  same vendor may differ — verify each one.
+- Value-domain constraints (`nonnegative`, `min`, `max`) must reflect the
+  upstream's REAL domain observed in live data, not what seems sensible.
+  A wrong `nonnegative()` turns real negative values into `null`/errors
+  silently.
+
+## Nullability
+- `null` means "upstream did not provide it" — never "parsing failed" and
+  never a placeholder for invented data.
+- Required-for-identity fields (ids, names) missing → throw
+  `UPSTREAM_SCHEMA_ERROR`; do not emit partial rows.
+
+## Checklist before submitting a schema/mapper change
+- [ ] No vendor key visible in any public field name or record key
+- [ ] All timestamps ISO 8601 with timezone; parsing tested for real vendor
+      shapes (padded/unpadded, string/number)
+- [ ] All status-like strings are declared enums with official-table mapping
+- [ ] Every numeric field's unit is in its name and conversion is tested
+- [ ] Constraints checked against live data, not intuition

package/src/cli/templates/provider/skills/pagination-and-counts/SKILL.md.tpl

@@ -0,0 +1,52 @@
+---
+name: pagination-and-counts
+description: total_count semantics, client-side filtering, and paging honesty. Load before implementing any list/search operation.
+---
+
+# Pagination and counts
+
+A caller uses `total_count`, `page`, and `limit` to plan iteration. If those
+numbers don't describe what the caller can actually page through, the
+operation is lying.
+
+## The client-side filtering trap
+If the upstream has no server-side filter for one of your inputs (e.g. no
+radius param) and you filter rows after fetching:
+
+- Upstream `totalCount` counts UNFILTERED rows. Returning it as your
+  `total_count` while returning filtered rows means: caller sees
+  `total_count: 541`, gets 1 row on page 1, and pages 2..28 return rows that
+  are outside the filter or empty. This is a contract failure, not a nuance.
+
+Acceptable resolutions, in preference order:
+1. **Don't accept the input.** If the upstream can't filter by it and you
+   can't enumerate all pages, drop the input from the schema and document the
+   upstream's real semantics (e.g. "results are distance-sorted; no radius
+   cutoff").
+2. **Expose upstream semantics honestly.** Distance-sorted paging with a
+   documented "no radius filter" contract and no fake `radius` input.
+3. **Filter AND fix the metadata.** If you must filter client-side, do not
+   return the upstream total. Return only what you can prove (`returned_count`
+   plus a `has_more` you can actually compute) and document that totals are
+   unavailable.
+
+Never combine: accepted filter input + client-side filter + upstream total.
+
+## Count integrity
+- Parse failure of `totalCount` → `UPSTREAM_SCHEMA_ERROR`, not `0`.
+  A fail-open zero disguises upstream drift as an empty dataset.
+- If `total_count > 0` but the page's row array normalizes to empty on
+  page 1, throw — that combination means broken extraction, not empty data.
+
+## Page/limit echo
+- Echo the EFFECTIVE values: if you clamp `limit` to the upstream max, return
+  the clamped value, not the requested one.
+- `page`/`limit` semantics must match the upstream's paging model
+  (1-indexed vs 0-indexed) — verify with two live pages, checking the
+  returned rows actually differ.
+
+## Checklist
+- [ ] No input is filtered client-side while `total_count` comes from upstream
+- [ ] totalCount parse failure fails closed
+- [ ] Effective (clamped) limit echoed
+- [ ] Two-page live check proves paging advances

package/src/cli/templates/provider/skills/upstream-contract-verification/SKILL.md.tpl

@@ -0,0 +1,45 @@
+---
+name: upstream-contract-verification
+description: How to establish evidence for upstream request params and response fields before coding. Load before wiring any new endpoint or mapping new fields.
+---
+
+# Upstream contract verification
+
+Most provider P0s come from guessed upstream contracts. Every param name and
+response field needs evidence BEFORE it ships.
+
+## Request parameters
+1. Start from the official spec document (data.go.kr 활용가이드, vendor API
+   docs). Copy exact names — casing and underscores matter
+   (`WGS84_LAT` ≠ `WGS84LAT`; the wrong one is often silently ignored).
+2. Confirm with ONE live call per endpoint. A param being ignored does not
+   produce an error — it produces plausible-looking wrong results, so compare:
+   - filtered vs unfiltered `totalCount` (identical → param ignored)
+   - a dense-area query returning 0 rows (→ param name/format wrong)
+3. Do NOT copy param names from a sibling endpoint or sibling API of the same
+   vendor without re-verifying. Same vendor ≠ same contract; endpoints drift.
+4. If a param only works together with another param (district requires
+   province), encode that dependency in the input schema with a clear error.
+   Test it: dependent-param-alone must be rejected, not silently national.
+
+## Response fields
+- Map exactly the field names present in your recorded live fixtures.
+- No speculative fallback chains (`row.distance ?? row.dist ?? row.Distance`).
+  If two shapes genuinely exist, you need a recorded fixture proving EACH
+  branch plus a row-level test per branch; otherwise map one name only.
+- Field presence varies by endpoint within the same vendor. Detail endpoints
+  often return more/differently-named fields than list endpoints — record
+  fixtures per endpoint, not per vendor.
+
+## When results look wrong
+- Same response body across different request payloads → the upstream is
+  ignoring your variation; stop tuning fields and re-check param names/auth.
+- Empty result for a query that must have data (city-center radius search,
+  major-district listing) → treat as a request bug. Never record it as a
+  fixture and never ship it.
+
+## Deliverables per endpoint
+- [ ] Spec reference (URL or doc name + section) noted in the PR/commit
+- [ ] One recorded live fixture proving request params take effect
+- [ ] Negative evidence checked: filtered count differs from unfiltered
+- [ ] Param dependencies enforced in the input schema with tests

package/src/cli/templates/provider/skills/upstream-notes/README.md.tpl

@@ -0,0 +1,13 @@
+# Upstream notes
+
+Per-vendor / per-API-family pitfalls proven by live evidence. These are the
+highest-value files in this workspace: general principles are knowable, but
+"this API silently ignores param X" is only discoverable by getting burned.
+
+- Read EVERY file here before your first upstream call.
+- When you discover a new upstream quirk (silently ignored param, unit
+  surprise, undocumented value domain, error-shape oddity), ADD it here in
+  the same format — evidence line included. Reviewers treat contributed
+  upstream notes as part of submission quality.
+
+Format per entry: **Symptom → Cause → Rule → Evidence**.

package/src/contract.ts

@@ -170,6 +170,7 @@ function extractHealthCheck(
 	if (!value) return undefined;
 	return compactObject({
 		interval: value.interval,
+		schedule: toJsonValue(value.schedule),
 		timeoutMs: value.timeoutMs,
 		degradedThresholdMs: value.degradedThresholdMs,
 		requiresConnection: value.requiresConnection,

package/src/define.ts

@@ -1,3 +1,5 @@
+import ms from "ms";
+
 import { ProviderError, ValidationError } from "./errors";
 import { safeParseSchemaSync } from "./schema";
 import type {
@@ -10,6 +12,7 @@ import type {
 	HealthCheckUnsupported,
 	HealthJourneyDefinition,
 	HealthJourneySchedule,
+	HealthScheduleRandomization,
 	InferSchemaOutput,
 	OperationDefinition,
 	OperationHandlerResult,
@@ -118,49 +121,25 @@ const VALID_OPERATION_TRANSPORT_KINDS = [
 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>;
@@ -285,6 +264,8 @@ export interface ProviderConfig<
 	};
 	operations: OperationMapConfig<TOperations>;
 	healthMonitor?: ProviderHealthMonitorConfig;
+	/** New name for `healthMonitor` (transitional alias); declaring both is a ValidationError. */
+	healthProbe?: ProviderHealthMonitorConfig;
 	healthJourneys?: readonly HealthJourneyDefinition[];
 }
 
@@ -374,6 +355,14 @@ function validateProviderShape(config: unknown): void {
 			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" &&
@@ -1116,6 +1105,7 @@ function validateOperationTransports(
 
 const HEALTH_CHECK_SUITE_FIELDS = new Set([
 	"interval",
+	"schedule",
 	"timeoutMs",
 	"degradedThresholdMs",
 	"cases",
@@ -1225,6 +1215,7 @@ function assertBoundedIntegerMs(
 function validateProviderHealthMonitor(
 	providerId: string,
 	healthMonitor: unknown,
+	field: "healthMonitor" | "healthProbe" = "healthMonitor",
 ): void {
 	if (healthMonitor === undefined) return;
 	if (
@@ -1233,21 +1224,21 @@ function validateProviderHealthMonitor(
 		Array.isArray(healthMonitor)
 	)
 		throw new ValidationError(
-			`Provider "${providerId}" has invalid healthMonitor: must be an object.`,
+			`Provider "${providerId}" has invalid ${field}: must be an object.`,
 			{
-				fix: `Set healthMonitor to { requiredSecrets?: string[]; serviceAccount?: string }`,
+				fix: `Set ${field} to { requiredSecrets?: string[]; serviceAccount?: string }`,
 			},
 		);
 	const healthMonitorRecord = Object.fromEntries(Object.entries(healthMonitor));
 	rejectUnknownFields(
 		healthMonitorRecord,
 		PROVIDER_HEALTH_MONITOR_FIELDS,
-		"healthMonitor",
+		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 +1249,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 +1261,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 +1278,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.`,
 				);
 			}
 		}
@@ -1317,32 +1308,32 @@ function validateProviderHealthMonitor(
 			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 +1344,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 +1360,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.`,
 		);
 }
 
@@ -1463,6 +1454,35 @@ 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,
@@ -1561,7 +1581,12 @@ 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",
@@ -1734,6 +1759,54 @@ function isoDurationMs(value: string): number {
 	);
 }
 
+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,
+	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,
@@ -1749,13 +1822,21 @@ 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.`,
 			);
 		}
-		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 +1848,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;
@@ -1993,15 +2090,29 @@ function validateHealthJourneySchedule(
 		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(
@@ -2244,7 +2355,9 @@ export function defineProvider<
 	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" },
+			{
+				fix: "Add at least one operation to the operations object",
+			},
 		);
 	validateOperationIds(config.id, config.operations);
 	validateOperationAnnotations(config.id, config.operations);
@@ -2262,7 +2375,18 @@ export function defineProvider<
 		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);
 	validateProviderProxy(config);
 	validateProviderStt(config);
@@ -2295,7 +2419,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,
 	};
 }