@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.30

package/dist/types.js

@@ -32,6 +32,7 @@ export const HEALTH_CHECK_TIMEOUT_MS_MIN = 1;
 export const HEALTH_CHECK_TIMEOUT_MS_MAX = 60_000;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN = 1;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX = 60_000;
+export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 409, 410, 422, 429, 500, 502, 503, 504];
 export const HttpRetryPreset = {
     Off: "off",
     TransportTransient: "transport_transient",

package/dist/user-input.d.ts

@@ -0,0 +1,30 @@
+export declare const NEEDS_INPUT_STATUS: "needs_input";
+export interface ProviderSelectionOption {
+    readonly selection_value: string;
+    readonly label: string;
+    readonly [extra: string]: unknown;
+}
+export interface ProviderRequiredSelection {
+    readonly selection_key: string;
+    readonly label: string;
+    readonly required: boolean;
+    readonly selection_type?: string;
+    readonly valid_options: readonly ProviderSelectionOption[];
+    readonly [extra: string]: unknown;
+}
+export interface ProviderSelectedOption {
+    readonly selection_key: string;
+    readonly selection_value: string;
+    /** Free-text answer for text-kind selections. */
+    readonly text?: string;
+    /** Quantity for quantity-kind selections. */
+    readonly quantity?: number;
+}
+export interface ProviderNeedsInputPayload {
+    readonly status: typeof NEEDS_INPUT_STATUS;
+    readonly required_selections: readonly ProviderRequiredSelection[];
+    readonly selected_options?: readonly ProviderSelectedOption[];
+    /** Provider-specific fresh state token(s), e.g. `reservation_state`. */
+    readonly [extra: string]: unknown;
+}
+export declare function isProviderNeedsInputPayload(value: unknown): value is ProviderNeedsInputPayload;

package/dist/user-input.js

@@ -0,0 +1,66 @@
+// Official cross-provider contract for user-input round-trips.
+//
+// Doctrine (born from the 2026-07-20 CatchTable reserve incident): an
+// operation MUST NOT dead-end on a problem the end user can resolve by
+// choosing among live options. Instead of throwing, the provider returns a
+// SUCCESSFUL payload with `status: "needs_input"` that carries everything a
+// consumer-side agent needs to relay the choice verbatim and retry:
+//
+// - `required_selections`: only the still-pending questions, each with
+//   human-readable `label`s and `valid_options` the agent shows the user
+//   as-is. The agent never chooses on the user's behalf.
+// - `selected_options`: selections already settled, echoed so the follow-up
+//   call keeps them without the agent reconstructing anything.
+// - a fresh provider-specific state token (e.g. `reservation_state`) minted
+//   at response time, so the retry never races an expired token.
+//
+// Keeping this success-shaped (instead of error `details`) is deliberate:
+// consumer error-shaping layers routinely strip error metadata, and a model
+// that only sees "error" narrates failure to the user. Complex recovery
+// logic belongs to the system, not the model.
+//
+// Deliberately ABSENT: retry templates, next-action routing, or any other
+// agent choreography. Provider payloads carry upstream-backed data only; how
+// to phrase the ask and shape the retry call is the consumer's contract
+// (apifuse#1030). The retry is fully determined by data: copy the echoed
+// selected_options, add the user's new answers, resend with the fresh state.
+export const NEEDS_INPUT_STATUS = "needs_input";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSelectionOption(value) {
+    return (isRecord(value) &&
+        typeof value.selection_value === "string" &&
+        typeof value.label === "string");
+}
+function isRequiredSelection(value) {
+    return (isRecord(value) &&
+        typeof value.selection_key === "string" &&
+        typeof value.label === "string" &&
+        typeof value.required === "boolean" &&
+        Array.isArray(value.valid_options) &&
+        value.valid_options.every(isSelectionOption));
+}
+function isSelectedOption(value) {
+    return (isRecord(value) &&
+        typeof value.selection_key === "string" &&
+        typeof value.selection_value === "string");
+}
+export function isProviderNeedsInputPayload(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (value.status !== NEEDS_INPUT_STATUS ||
+        !Array.isArray(value.required_selections) ||
+        !value.required_selections.every(isRequiredSelection)) {
+        return false;
+    }
+    // A needs_input with nothing to ask AND nothing settled to echo is a
+    // no-op dead end — reject it so providers cannot ship it accidentally.
+    if (value.required_selections.length > 0) {
+        return true;
+    }
+    return (Array.isArray(value.selected_options) &&
+        value.selected_options.length > 0 &&
+        value.selected_options.every(isSelectedOption));
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.3",
+	"version": "2.2.0-beta.30",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -61,6 +61,36 @@
 			"import": "./dist/server/index.js",
 			"default": "./dist/server/index.js"
 		},
+		"./runtime/browser": {
+			"types": "./dist/runtime/browser.d.ts",
+			"import": "./dist/runtime/browser.js",
+			"default": "./dist/runtime/browser.js"
+		},
+		"./runtime/native-network": {
+			"types": "./dist/runtime/native-network.d.ts",
+			"import": "./dist/runtime/native-network.js",
+			"default": "./dist/runtime/native-network.js"
+		},
+		"./runtime/prevalidate": {
+			"types": "./dist/runtime/prevalidate.d.ts",
+			"import": "./dist/runtime/prevalidate.js",
+			"default": "./dist/runtime/prevalidate.js"
+		},
+		"./runtime/resolver": {
+			"types": "./dist/runtime/resolver-public.d.ts",
+			"import": "./dist/runtime/resolver-public.js",
+			"default": "./dist/runtime/resolver-public.js"
+		},
+		"./runtime/stealth": {
+			"types": "./dist/runtime/stealth.d.ts",
+			"import": "./dist/runtime/stealth.js",
+			"default": "./dist/runtime/stealth.js"
+		},
+		"./stateful": {
+			"types": "./dist/stateful/index.d.ts",
+			"import": "./dist/stateful/index.js",
+			"default": "./dist/stateful/index.js"
+		},
 		"./testing": {
 			"types": "./dist/testing/index.d.ts",
 			"import": "./dist/testing/index.js",
@@ -75,30 +105,32 @@
 	"scripts": {
 		"lint": "biome lint .",
 		"lint:fix": "biome lint --write",
+		"lint:deprecated": "bun run scripts/lint-deprecated-usage.ts",
 		"format": "biome format --write",
-		"type-check": "tsgo --noEmit",
+		"type-check": "tsc --noEmit",
 		"test": "bun test",
-		"check": "bun run lint && bun run type-check && bun run build",
+		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run build",
 		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
 		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
+		"pack:types": "bun run build && bun bin/apifuse-pack-types.ts",
 		"release:guard": "bun scripts/guard-release-pr.ts",
 		"format:check": "biome format .",
-		"build": "tsgo -p tsconfig.build.json && rm -rf dist/cli/templates && cp -R src/cli/templates dist/cli/templates && rm -rf dist/auth-turn/fixtures && cp -R src/auth-turn/fixtures dist/auth-turn/fixtures && cp src/auth-turn/auth-turn.v1.schema.json dist/auth-turn/auth-turn.v1.schema.json"
+		"build": "tsc -p tsconfig.build.json && rm -rf dist/cli/templates && cp -R src/cli/templates dist/cli/templates && rm -rf dist/auth-turn/fixtures && cp -R src/auth-turn/fixtures dist/auth-turn/fixtures && cp src/auth-turn/auth-turn.v1.schema.json dist/auth-turn/auth-turn.v1.schema.json"
 	},
 	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.5",
 		"@biomejs/biome": "^2.5.0",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
-		"@typescript/native-preview": "7.0.0-dev.20260419.1"
+		"ajv": "^8.17",
+		"typescript": "6.0.3"
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
 		"@rgrove/parse-xml": "4.2.2",
 		"@types/ms": "^2.1.0",
 		"acorn": "^8.17.0",
-		"ajv": "^8.17",
 		"hono": "^4.12.25",
-		"impit": "0.14.1",
 		"ioredis": "^5.11.1",
 		"ms": "^2.1.3",
 		"playwright": "^1.55.1",
@@ -106,6 +138,9 @@
 		"puppeteer-extra-plugin-stealth": "^2.11.2",
 		"re2-wasm": "^1.0",
 		"safe-regex": "^2.1",
+		"socks": "^2.8.9",
+		"tough-cookie": "^6.0.2",
+		"wreq-js": "3.0.0",
 		"zod": "^4.4.3"
 	},
 	"repository": {

package/src/auth-turn/index.ts

@@ -1,4 +1,4 @@
-import type { AuthTurn } from "../types";
+import type { AuthTurn } from "../types.js";
 
 export type { AuthTurn };
 
@@ -24,7 +24,7 @@ export const AUTH_TURN_SCHEMA_ARTIFACT_PATH = "dist/auth-turn/auth-turn.v1.schem
  *
  * This is the exact codification of the runtime validation the SDK applies to
  * ceremony outputs (see `validateCeremonyOutput` in `src/ceremonies`), which
- * compiles this same document. `kind` is an OPEN string on the wire: the known
+ * evaluates this same document. `kind` is an OPEN string on the wire: the known
  * kinds in {@link TURN_KINDS} are tooling metadata, never a wire constraint.
  *
  * The committed artifact at `src/auth-turn/auth-turn.v1.schema.json` (shipped

package/src/auth.ts

@@ -1,4 +1,9 @@
-import { AuthError, ProviderError } from "./errors";
+import { AuthError, ProviderError } from "./errors.js";
+import {
+	declarationInvalidError,
+	DECLARATION_RULE_IDS,
+	type DeclarationViolation,
+} from "./declaration-validation.js";
 import type {
 	AuthAbortData,
 	AuthConfig,
@@ -10,7 +15,7 @@ import type {
 	CredentialDeclaration,
 	FlowContext,
 	ProviderLocaleKeyInput,
-} from "./types";
+} from "./types.js";
 
 const CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY = "__credentialsAuthChallenge";
 const DEFAULT_COMPLETE_TURN_ID = "auth.complete";
@@ -33,11 +38,7 @@ function isSensitiveAuthDataKey(key: string): boolean {
 	return SENSITIVE_ABORT_DATA_KEY_PATTERN.test(normalizedAuthDataKey(key));
 }
 
-export type CredentialsAuthFieldType =
-	| "string"
-	| "email"
-	| "password"
-	| "otp";
+export type CredentialsAuthFieldType = "string" | "email" | "password" | "otp";
 
 export interface CredentialsAuthField {
 	type?: CredentialsAuthFieldType;
@@ -138,10 +139,9 @@ function abortData(options: {
 	};
 }
 
-export function createAuthFlowHelpers(options: {
-	readonly signal?: AbortSignal;
-	readonly deadline?: string;
-} = {}): AuthFlowTerminalContext {
+export function createAuthFlowHelpers(
+	options: { readonly signal?: AbortSignal; readonly deadline?: string } = {},
+): AuthFlowTerminalContext {
 	return {
 		...(options.signal ? { signal: options.signal } : {}),
 		...(options.deadline ? { deadline: options.deadline } : {}),
@@ -156,16 +156,7 @@ export function createAuthFlowHelpers(options: {
 				},
 			};
 		},
-		abort({
-			code,
-			message,
-			retry,
-			actionHint,
-			fieldErrors,
-			data,
-			turnId,
-			expiresAt,
-		}) {
+		abort({ code, message, retry, actionHint, fieldErrors, data, turnId, expiresAt }) {
 			return {
 				kind: "abort",
 				...authTurnBase({ turnId, defaultTurnId: DEFAULT_ABORT_TURN_ID, expiresAt }),
@@ -190,8 +181,7 @@ export function createAuthFlowHelpers(options: {
 				...(options.hintKey ? { hintKey: options.hintKey } : {}),
 				...(options.timing ? { timing: options.timing } : {}),
 				...(options.data ? { data: options.data } : {}),
-				expectedInput:
-					options.expectedInput ?? expectedInputFromFields(options.fields ?? {}),
+				expectedInput: options.expectedInput ?? expectedInputFromFields(options.fields ?? {}),
 			};
 		},
 		nextPoll(options = {}) {
@@ -223,9 +213,7 @@ export class AuthAbortError extends AuthError {
 	}
 }
 
-export interface CredentialsAuthCompleteResult<
-	TCredentialKeys extends readonly string[],
-> {
+export interface CredentialsAuthCompleteResult<TCredentialKeys extends readonly string[]> {
 	credential: CredentialsAuthCredential<TCredentialKeys>;
 	/** Additional non-credential auth-flow data to return alongside credential. */
 	data?: Record<string, unknown>;
@@ -247,9 +235,7 @@ export interface CredentialsAuthChallengeRequest<TChallengeId extends string = s
 export type CredentialsAuthLoginResult<
 	TCredentialKeys extends readonly string[],
 	TChallengeId extends string = string,
-> =
-	| CredentialsAuthCompleteResult<TCredentialKeys>
-	| CredentialsAuthChallengeRequest<TChallengeId>;
+> = CredentialsAuthCompleteResult<TCredentialKeys> | CredentialsAuthChallengeRequest<TChallengeId>;
 
 export interface CredentialsAuthChallengeDefinition<
 	TFields extends CredentialsAuthFields,
@@ -310,6 +296,25 @@ export interface DefineCredentialsAuthOptions<
 	):
 		| CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>
 		| Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
+	/**
+	 * Optional re-mint of an expired session from the stored credential, wired
+	 * to `auth.flow.refresh`.
+	 *
+	 * Credential-auth upstreams routinely invalidate a session well before the
+	 * `expiresAt` the provider advertised, which leaves every operation failing
+	 * with a reauth error until a human repeats the whole interactive login.
+	 * Implement this to re-establish the session from what is already stored on
+	 * the connection; the result is resolved exactly like `login`, so it may
+	 * also raise a challenge when the upstream demands one. Omit it when the
+	 * upstream has no non-interactive path and re-authentication genuinely
+	 * requires the user.
+	 */
+	refresh?(
+		ctx: FlowContext,
+		input: Partial<CredentialsAuthInput<TFields>>,
+	):
+		| CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>
+		| Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
 }
 
 export interface DefinedCredentialsAuth {
@@ -351,12 +356,8 @@ function expectedInputFromFields(fields: CredentialsAuthFields): Record<string,
 					...(field.type === "password" ? { format: "password" } : {}),
 					...(field.type === "otp" ? { format: "otp" } : {}),
 					...(field.labelKey ? { nameKey: field.labelKey } : {}),
-					...(field.descriptionKey
-						? { descriptionKey: field.descriptionKey }
-						: {}),
-					...(field.placeholderKey
-						? { placeholderKey: field.placeholderKey }
-						: {}),
+					...(field.descriptionKey ? { descriptionKey: field.descriptionKey } : {}),
+					...(field.placeholderKey ? { placeholderKey: field.placeholderKey } : {}),
 					...(field.sensitive || field.type === "password" || field.type === "otp"
 						? { sensitive: true }
 						: {}),
@@ -394,6 +395,27 @@ function normalizeInput<TFields extends CredentialsAuthFields>(
 	return result as CredentialsAuthInput<TFields>;
 }
 
+/**
+ * Refresh variant of {@link normalizeInput}. `login` coerces every declared
+ * field to a string because the interactive turn has already enforced that they
+ * are present; refresh runs with no user present, so an absent field is omitted
+ * rather than turned into an empty string. That keeps "the user did not supply
+ * this" distinguishable from "the user supplied an empty value".
+ */
+function normalizePartialInput<TFields extends CredentialsAuthFields>(
+	fields: TFields,
+	input: Record<string, unknown> | undefined,
+): Partial<CredentialsAuthInput<TFields>> {
+	const result: Record<string, string> = {};
+	for (const name of Object.keys(fields)) {
+		const value = input?.[name];
+		if (typeof value === "string") {
+			result[name] = value;
+		}
+	}
+	return result as Partial<CredentialsAuthInput<TFields>>;
+}
+
 function assertCredentialKeys<TCredentialKeys extends readonly string[]>(
 	credentialKeys: TCredentialKeys,
 	credential: Record<string, unknown>,
@@ -437,10 +459,7 @@ function getPendingChallenge(ctx: FlowContext): PendingCredentialsAuthChallenge
 	};
 }
 
-function setPendingChallenge(
-	ctx: FlowContext,
-	challenge: PendingCredentialsAuthChallenge,
-): void {
+function setPendingChallenge(ctx: FlowContext, challenge: PendingCredentialsAuthChallenge): void {
 	ctx.context.set(CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, challenge);
 }
 
@@ -473,9 +492,7 @@ function retryTurn(
 		turnId: retryTurnId,
 		expectedInput,
 		data: {
-			fieldErrors: Object.fromEntries(
-				missing.map((name) => [name, "Required"]),
-			),
+			fieldErrors: Object.fromEntries(missing.map((name) => [name, "Required"])),
 			fieldErrorKeys: Object.fromEntries(
 				missing.map((name) => [name, "auth.credentials.fieldRequired"]),
 			),
@@ -499,18 +516,12 @@ function completeTurn<TCredentialKeys extends readonly string[]>(
 		typeof result.credential !== "object" ||
 		Array.isArray(result.credential)
 	) {
-		throw new ProviderError(
-			"Credentials auth login completed without a credential object",
-			{
-				code: "credentials_auth_missing_credential",
-				fix: "Return { credential: { ... } } from defineCredentialsAuth handlers. Gateway persists only auth.flow complete data.credential into the connection.",
-			},
-		);
+		throw new ProviderError("Credentials auth login completed without a credential object", {
+			code: "credentials_auth_missing_credential",
+			fix: "Return { credential: { ... } } from defineCredentialsAuth handlers. Gateway persists only auth.flow complete data.credential into the connection.",
+		});
 	}
-	assertCredentialKeys(
-		credentialKeys,
-		result.credential as Record<string, unknown>,
-	);
+	assertCredentialKeys(credentialKeys, result.credential as Record<string, unknown>);
 	return {
 		kind: "complete",
 		turnId: result.turnId ?? defaultTurnId,
@@ -523,24 +534,18 @@ function completeTurn<TCredentialKeys extends readonly string[]>(
 }
 
 function challengeTurn(
-	definition: CredentialsAuthChallengeDefinition<
-		CredentialsAuthFields,
-		readonly string[],
-		string
-	>,
+	definition: CredentialsAuthChallengeDefinition<CredentialsAuthFields, readonly string[], string>,
 	request: CredentialsAuthChallengeRequest<string>,
 ): AuthTurn {
-	const expectedInput = definition.fields
-		? expectedInputFromFields(definition.fields)
-		: undefined;
+	const expectedInput = definition.fields ? expectedInputFromFields(definition.fields) : undefined;
 	return {
 		kind: expectedInput ? "form" : "pending",
 		turnId: request.turnId ?? definition.turnId ?? `credentials.${request.challengeId}`,
 		...(request.expiresAt ? { expiresAt: request.expiresAt } : {}),
-		...(request.hintKey ?? definition.hintKey
+		...((request.hintKey ?? definition.hintKey)
 			? { hintKey: request.hintKey ?? definition.hintKey }
 			: {}),
-		...(request.timing ?? definition.timing
+		...((request.timing ?? definition.timing)
 			? { timing: request.timing ?? definition.timing }
 			: {}),
 		...(expectedInput ? { expectedInput } : {}),
@@ -630,13 +635,7 @@ async function continuePendingChallenge<TCredentialKeys extends readonly string[
 		normalizeInput(definition.fields, rawInput),
 		pending.state,
 	);
-	return await resolveAuthResult(
-		ctx,
-		credentialKeys,
-		challenges,
-		result,
-		completeTurnId,
-	);
+	return await resolveAuthResult(ctx, credentialKeys, challenges, result, completeTurnId);
 }
 
 async function pollPendingChallenge<TCredentialKeys extends readonly string[]>(
@@ -669,13 +668,7 @@ async function pollPendingChallenge<TCredentialKeys extends readonly string[]>(
 				`credentials.${pending.challengeId}.pending`,
 		};
 	}
-	return await resolveAuthResult(
-		ctx,
-		credentialKeys,
-		challenges,
-		result,
-		completeTurnId,
-	);
+	return await resolveAuthResult(ctx, credentialKeys, challenges, result, completeTurnId);
 }
 
 export function defineCredentialsAuth<
@@ -697,7 +690,7 @@ export function defineCredentialsAuth<
 ): DefinedCredentialsAuth {
 	if (Object.keys(options.fields).length === 0) {
 		throw new ProviderError("defineCredentialsAuth requires at least one field", {
-			fix: "Pass fields such as { email: { type: \"email\" }, password: { type: \"password\" } }.",
+			fix: 'Pass fields such as { email: { type: "email" }, password: { type: "password" } }.',
 		});
 	}
 
@@ -708,6 +701,7 @@ export function defineCredentialsAuth<
 		string,
 		CredentialsAuthChallengeDefinition<CredentialsAuthFields, TCredentialKeys, string>
 	>;
+	validateCredentialsAuthChallenges(challenges);
 
 	return {
 		auth: {
@@ -737,10 +731,7 @@ export function defineCredentialsAuth<
 						return retryTurn(expectedInput, missing, retryTurnId);
 					}
 
-					const result = await options.login(
-						ctx,
-						normalizeInput(options.fields, rawInput),
-					);
+					const result = await options.login(ctx, normalizeInput(options.fields, rawInput));
 					return await resolveAuthResult(
 						ctx,
 						options.credentialKeys,
@@ -765,6 +756,44 @@ export function defineCredentialsAuth<
 						completeTurnId,
 					);
 				},
+				// Only advertise refresh when the provider implements it: the
+				// protocol treats the hook's presence as "this connection can be
+				// re-established without the user", and exposing a stub that
+				// cannot actually re-mint would turn a recoverable expiry into a
+				// silent failure.
+				...(options.refresh
+					? {
+							refresh: async (ctx: FlowContext, rawInput?: Record<string, unknown>) => {
+								// A pending challenge belongs to the interactive flow that
+								// raised it; finish it there rather than restarting.
+								const pending = getPendingChallenge(ctx);
+								if (pending) {
+									return await continuePendingChallenge(
+										ctx,
+										options.credentialKeys,
+										challenges,
+										pending,
+										rawInput,
+										completeTurnId,
+									);
+								}
+
+								// Refresh runs without user input, so fields are optional
+								// here — unlike `continue`, missing ones are not a retry.
+								const result = await options.refresh!(
+									ctx,
+									normalizePartialInput(options.fields, rawInput),
+								);
+								return await resolveAuthResult(
+									ctx,
+									options.credentialKeys,
+									challenges,
+									result,
+									completeTurnId,
+								);
+							},
+						}
+					: {}),
 			},
 		},
 		credential: {
@@ -776,11 +805,42 @@ export function defineCredentialsAuth<
 		},
 		context: {
 			keys: Array.from(
-				new Set([
-					CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY,
-					...(options.contextKeys ?? []),
-				]),
+				new Set([CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, ...(options.contextKeys ?? [])]),
 			),
 		},
 	};
 }
+
+function validateCredentialsAuthChallenges(
+	challenges: Record<
+		string,
+		CredentialsAuthChallengeDefinition<CredentialsAuthFields, readonly string[], string>
+	>,
+): void {
+	const violations: DeclarationViolation[] = [];
+	for (const [challengeId, challenge] of Object.entries(challenges)) {
+		const fieldCount =
+			challenge.fields && typeof challenge.fields === "object"
+				? Object.keys(challenge.fields).length
+				: 0;
+		const fieldsDeclared =
+			challenge.fields !== undefined && challenge.fields !== null;
+		const hasFields = fieldCount > 0;
+		const hasVerify = typeof challenge.verify === "function";
+		const hasPoll = typeof challenge.poll === "function";
+		const isInteractive = hasFields && hasVerify && !hasPoll;
+		const isPolling = !fieldsDeclared && !hasVerify && hasPoll;
+		const isHybrid = hasFields && hasVerify && hasPoll;
+		const emptyFieldsDeclared = fieldsDeclared && !hasFields;
+		if (!emptyFieldsDeclared && (isInteractive || isPolling || isHybrid)) continue;
+
+		const path = `challenges.${challengeId}`;
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.challengeShape,
+			path,
+			message: "challenge must be interactive, polling, or an explicit hybrid.",
+			fix: `Give ${path} non-empty fields plus verify, poll alone, or all three for a hybrid.`,
+		});
+	}
+	if (violations.length > 0) throw declarationInvalidError(violations);
+}