@chipmobilesdk/rn-ads 0.2.1 → 0.3.0

package/package.json

@@ -1,49 +1,49 @@
-{
-	"name": "@chipmobilesdk/rn-ads",
-	"version": "0.2.1",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
-		},
-		"./testing": {
-			"types": "./src/testing/index.ts",
-			"react-native": "./src/testing/index.ts",
-			"default": "./src/testing/index.ts"
-		}
-	},
-	"files": [
-		"src/index.ts",
-		"src/config",
-		"src/core",
-		"src/diagnostics",
-		"src/engine",
-		"src/react",
-		"src/testing",
-		"skills",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"react": ">=19",
-		"react-native": ">=0.85",
-		"react-native-google-mobile-ads": ">=16.0.3 <16.1.0"
-	},
-	"engines": {
-		"node": ">=22.11.0"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+{
+	"name": "@chipmobilesdk/rn-ads",
+	"version": "0.3.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/config",
+		"src/core",
+		"src/diagnostics",
+		"src/engine",
+		"src/react",
+		"src/testing",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-google-mobile-ads": ">=16.0.3 <16.1.0"
+	},
+	"engines": {
+		"node": ">=22.11.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/skills/sdk-rn-ads/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: sdk-rn-ads
-description: "Advertising via @chipmobilesdk/rn-ads: AdMob banner/interstitial/rewarded/app-open behind a provider-neutral contract, placement keys, optional consent orchestration, three-state enablement, bounded retry, per-environment test-ad substitution. Use when adding ads to a screen, running a consent flow without importing AdMob, deferring ads until a purchase check resolves, debugging an ad that never loads, mapping ad units per environment, or answering a Data safety question about advertising."
+description: "Advertising via @chipmobilesdk/rn-ads: AdMob banner/interstitial/rewarded/app-open behind a provider-neutral contract, placement keys, optional consent orchestration, three-state enablement, bounded retry, per-environment test-ad substitution, per-placement request throttling. Use when adding ads to a screen, running a consent flow without importing AdMob, deferring ads until a purchase check resolves, debugging an ad that never loads or reports throttled, placing a banner inside a list or a view the user swipes between, mapping ad units per environment, or answering a Data safety question about advertising."
 metadata:
   package: "@chipmobilesdk/rn-ads"
-  packageVersion: "0.2.0"
+  packageVersion: "0.3.0"
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -85,7 +85,32 @@ defect and it is fixed. The result now says which happened:
 
 Existing `ads.setEnabled(false);` call sites still compile untouched.
 
-## Four things not to "fix"
+## A banner in a list or a swipeable view gets throttled — by design
+
+New in 0.3.0. A banner mounted inside a view the user navigates between — a day in a
+calendar, a tab, a row that scrolls in and out — is unmounted and remounted by React on
+every navigation, and **each remount is a billable request**. Ten quick swipes used to be
+ten requests in a few seconds, which ad networks read as invalid traffic. The penalty is
+account-level and no shipped fix recovers it.
+
+So each placement now has a minimum interval between *requests*: **60s for a banner**
+(AdMob's own refresh floor), **off for full-screen formats** — those are loaded by an
+explicit call, not mounted by a renderer, so they never had the problem. A refusal reports
+`throttled` on the placement and emits `request_throttled` with `retryAfterMs`.
+
+Three things to know before you reach for `minRequestIntervalMs: 0`:
+
+- **`throttled` is not `failed` and not a no-fill.** Nothing is wrong and nothing was
+  requested. Collapse the space if you like, but do not log it as an error.
+- **Rotation is exempt.** A width re-adaptation inside one mount is not charged, so a
+  rotated screen keeps its banner.
+- **The better fix is architectural.** Keep the banner outside the subtree that remounts
+  and the throttle never fires. It is a safety net, not a licence to ignore the problem.
+
+This is **not** a frequency cap. It limits how often a placement may *ask*; how often you
+*show* is yours, and the package deliberately ships no pacing (see `## Do not use this for`).
+
+## Five things not to "fix"
 
 - **The bridge pin.** `react-native-google-mobile-ads` is peered at `>=16.0.3 <16.1.0`;
   16.1.0+ carries Kotlin 2.3 metadata that React Native 0.85's pinned compiler cannot
@@ -101,6 +126,9 @@ Existing `ads.setEnabled(false);` call sites still compile untouched.
 - **A declined consent still reporting `obtained` / `canRequestAds: true`.** That is UMP's
   meaning, not a bug: `OBTAINED` means *an answer was recorded*, and non-personalized ads
   stay servable. The package forwards the provider's verdict rather than inventing one.
+- **A banner reporting `throttled` right after a navigation.** That is 0.3.0's request
+  floor working — see the section above. Lower it knowingly or move the banner out of the
+  remounting subtree; do not set `0` to make the symptom go away.
 
 ## Retry is off unless you ask
 
@@ -120,7 +148,7 @@ on a return **from an ad** — or from a browser an ad opened — is refused wit
 return apart from any other; the package can. It cannot survive process death, and a
 browser opened without a preceding click is undetectable. See `## App open`.
 
-## Public API (v0.2.0)
+## Public API (v0.3.0)
 
 Runtime: `createAds` (throws `AdsConfigError` on a bad catalog or an out-of-range retry
 policy; everything else returns a typed result rather than throwing) · `AdsProvider`,
@@ -129,7 +157,9 @@ policy; everything else returns a typed result rather than throwing) · `AdsProv
 `DEFAULT_SHOW_TIMEOUT_MS`, `DEFAULT_AD_VALIDITY_MS`, `DEFAULT_APP_OPEN_VALIDITY_MS`,
 `DEFAULT_RETRY_POLICY`, `DEFAULT_UNDECIDED_WARNING_MS`, `LOAD_TIMEOUT_BOUNDS`,
 `SHOW_TIMEOUT_BOUNDS`, `AD_VALIDITY_BOUNDS`, `APP_OPEN_VALIDITY_BOUNDS`, `RETRY_BOUNDS`,
-`UNDECIDED_WARNING_BOUNDS` · `createFakeAdsEngine`, `createTestClock` from
+`UNDECIDED_WARNING_BOUNDS`, `DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS`,
+`DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS`, `MIN_REQUEST_INTERVAL_BOUNDS`,
+`defaultMinRequestIntervalMs` · `createFakeAdsEngine`, `createTestClock` from
 `@chipmobilesdk/rn-ads/testing` (test doubles only).
 
 Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setEnablement`, `setAppActive`,
@@ -151,6 +181,24 @@ Types: `AdsInstance`, `AdsConfig`, `PlacementDefinition`, `PrivacyOptions`, `AdF
 Call `dispose()` when the owning screen unmounts; it is idempotent, and so is every
 `Unsubscribe`.
 
+## Upgrading 0.2.x → 0.3.0
+
+One compile-time change and one behaviour change.
+
+| Union | New member |
+|---|---|
+| `PlacementState` | `'throttled'` |
+| `LoadResult` | `{ status: 'throttled', retryAfterMs }` |
+| `AdEventType` | `'request_throttled'` |
+
+**The behaviour change:** banner placements now have a 60s floor between requests. If your
+banner lives inside a list row, a tab, or a view the user swipes between, it will report
+`throttled` after a quick navigation where 0.2.x silently issued another request. That was
+the bug; this is the fix. Read the throttle section above before setting
+`minRequestIntervalMs: 0`.
+
+Full-screen formats are unchanged — their default floor is `0`.
+
 ## Upgrading 0.1.0 → 0.2.0
 
 One required change, compile-time only: five unions gained members, so an exhaustive
@@ -182,6 +230,7 @@ Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
 | App-open and ad-originated return | `## App open` |
 | Turning ads off, undecided, re-enabling | `## Turning ads off — three states` |
 | Retry and reconciling it against a bill | `## Retry` |
+| Request throttling, banners in lists | `## Request throttling` |
 | Why a request was refused | `## Why an ad did not show` |
 | Results, events, errors, timeouts, cleanup | `## State, events, and errors` |
 | Tests without a device | `## Testing` |

package/src/config/types.ts

@@ -65,6 +65,18 @@ export interface PlacementDefinition {
 	 * override can narrow behavior but never exceed a ceiling (FR-136a).
 	 */
 	readonly retry?: RetryPolicy | false;
+	/**
+	 * Minimum milliseconds between two provider requests for this placement
+	 * (FR-140), added in 0.3.0.
+	 *
+	 * Absent takes the format-aware default: 60s for a banner, off for full-screen
+	 * formats. `0` turns it off here while leaving it on elsewhere.
+	 *
+	 * This is an **account-safety** floor, not a frequency cap: it limits how often
+	 * a placement may *ask* for an ad, never how often the app may *show* one. If
+	 * you are reaching for this to pace interstitials, that belongs in the app.
+	 */
+	readonly minRequestIntervalMs?: number;
 }
 
 /**
@@ -269,6 +281,16 @@ export type PlacementState =
 	| 'failed'
 	/** Mirrors `InitStatus.undecided` so the banner host can report it directly. */
 	| 'undecided'
+	/**
+	 * Refused by the per-placement request throttle (FR-140), added in 0.3.0.
+	 *
+	 * Deliberately distinct from `failed` and from a no-fill: nothing is wrong,
+	 * nothing was requested, and the same placement will work again shortly. An
+	 * app that collapses its ad slot on `failed` will usually want to collapse on
+	 * this too, but it must be able to tell the two apart when diagnosing why a
+	 * banner is absent.
+	 */
+	| 'throttled'
 	| 'unavailable';
 
 /** FR-047. The provider's reward descriptor, normalized. */

package/src/config/validate.ts

@@ -1,188 +1,211 @@
-/**
- * Catalog and configuration validation (FR-008), plus the fail-closed check
- * that substitution cannot cover (FR-012).
- *
- * Configuration faults throw rather than returning a result. They mean the app
- * is wired wrong, and no runtime status could describe a usable outcome — every
- * other failure in this package is a typed result instead.
- *
- * Every message names the offending placement key. An error that says only
- * "invalid configuration" makes the integrator hunt through a catalog by hand.
- */
-
-import { AdsConfigError } from '../diagnostics/errors';
-import { resolvePlacementAdUnits, type ResolvedCatalog } from './resolveAdUnit';
-import { resolveTimeouts, type ResolvedTimeouts } from '../core/timers';
-import { toEnablement } from '../core/enablement';
-import { resolveEffectiveRetry, type ResolvedRetryPolicy } from '../core/retryPolicy';
-import type {
-	AdFormat,
-	AdsConfig,
-	ConsentTestingOptions,
-	Enablement,
-	Environment,
-	PlacementDefinition,
-} from './types';
-
-const FORMATS: ReadonlySet<string> = new Set<AdFormat>([
-	'banner',
-	'interstitial',
-	'rewarded',
-	'app_open',
-]);
-
-export interface ValidateOptions {
-	/**
-	 * Whether this is a debug build. Injected rather than read from `__DEV__`
-	 * directly so the fail-closed rule is testable without manipulating a global
-	 * the test runner also depends on.
-	 */
-	readonly isDevBuild: boolean;
-}
-
-export interface ResolvedConfig {
-	readonly enablement: Enablement;
-	readonly environment: Environment;
-	readonly placements: ReadonlyMap<string, PlacementDefinition>;
-	readonly catalog: ResolvedCatalog;
-	readonly timeouts: ResolvedTimeouts;
-	/** Empty in production regardless of what was configured (FR-014). */
-	readonly testDeviceIds: readonly string[];
-	/** Effective retry per placement. `null` means retry is off there (FR-134). */
-	readonly retryByKey: ReadonlyMap<string, ResolvedRetryPolicy | null>;
-	/** Stripped entirely in production (FR-113). */
-	readonly consentTesting: ConsentTestingOptions | undefined;
-	/**
-	 * Which consent tools were dropped because the environment is production.
-	 * Surfaced so the inertness is observable rather than merely documented —
-	 * the same treatment FR-011a gives substituted ad units.
-	 */
-	readonly ignoredConsentTools: readonly string[];
-}
-
-export function validateConfig(config: AdsConfig, options: ValidateOptions): ResolvedConfig {
-	// FR-012. Substitution deliberately does not apply in production, so a debug
-	// build declaring `production` is the one case it cannot make safe: it would
-	// send real requests from a build that should never generate traffic. Fail
-	// closed rather than continue.
-	if (config.environment === 'production' && options.isDevBuild) {
-		throw new AdsConfigError('production_in_dev_build', {
-			message:
-				'environment is "production" but this is a development build. ' +
-				'Non-production builds must declare "development" or "test" so the package can ' +
-				'substitute official Google test ad units and keep production traffic impossible.',
-		});
-	}
-
-	if (!Array.isArray(config.placements) || config.placements.length === 0) {
-		throw new AdsConfigError('invalid_config', {
-			message: 'placements must be a non-empty array; the package can show nothing without one',
-		});
-	}
-
-	const byKey = new Map<string, PlacementDefinition>();
-
-	for (const placement of config.placements) {
-		const key = typeof placement?.key === 'string' ? placement.key.trim() : '';
-
-		if (!key) {
-			throw new AdsConfigError('invalid_config', {
-				message: 'every placement needs a non-empty key',
-			});
-		}
-
-		if (byKey.has(key)) {
-			// Rejecting the whole catalog rather than picking a winner: a repeated
-			// key means the app's own naming produced two placements for one slot,
-			// and the package has no basis to guess which was meant.
-			throw new AdsConfigError('duplicate_placement_key', {
-				message: `duplicate placement key "${key}"`,
-				placementKey: key,
-			});
-		}
-
-		if (!FORMATS.has(placement.format)) {
-			throw new AdsConfigError('invalid_config', {
-				message: `placement "${key}" has unsupported format "${String(placement.format)}"; supported formats are banner, interstitial, rewarded, and app_open`,
-				placementKey: key,
-			});
-		}
-
-		if (!placement.androidAdUnitId || !placement.androidAdUnitId.trim()) {
-			throw new AdsConfigError('missing_ad_unit_id', {
-				message: `placement "${key}" is missing androidAdUnitId`,
-				placementKey: key,
-				format: placement.format,
-			});
-		}
-
-		byKey.set(key, { ...placement, key });
-	}
-
-	const timeouts = resolveTimeouts({
-		timeouts: config.timeouts,
-		adValidityMs: config.adValidityMs,
-		appOpenValidityMs: config.appOpenValidityMs,
-		undecidedWarningMs: config.undecidedWarningMs,
-	});
-	const catalog = resolvePlacementAdUnits(Array.from(byKey.values()), config.environment);
-
-	// Resolved eagerly, for every placement, so an out-of-bounds override fails
-	// at construction rather than on the first failed load in production — which
-	// is the one moment nobody is watching for a configuration error.
-	const retryByKey = new Map<string, ResolvedRetryPolicy | null>();
-	for (const [key, placement] of byKey) {
-		retryByKey.set(key, resolveEffectiveRetry(config.retry, placement.retry, key));
-	}
-
-	const isProduction = config.environment === 'production';
-	const { consentTesting, ignoredConsentTools } = resolveConsentTesting(
-		config.consentTesting,
-		isProduction,
-	);
-
-	return {
-		enablement: toEnablement(config.enabled),
-		environment: config.environment,
-		placements: byKey,
-		catalog,
-		timeouts,
-		// FR-014: debug and test-device settings must not be able to alter
-		// production behavior, so they are dropped rather than carried and
-		// conditionally ignored somewhere further down.
-		testDeviceIds: isProduction ? [] : [...(config.testDeviceIds ?? [])],
-		retryByKey,
-		consentTesting,
-		ignoredConsentTools,
-	};
-}
-
-/**
- * Neutralizes the consent testing tools in production (FR-113).
- *
- * Dropped here, at the single validation point, rather than checked wherever
- * they are used. That is what makes the guarantee provable: a rule enforced in
- * one place can be asserted by a test, while one spread across the consent
- * module's call sites is a hope. It is the same reasoning that makes the ad-unit
- * substitution guarantee hold, and it is why both are enforced identically.
- *
- * The names of what was dropped are returned rather than only logged, so an
- * automated test — and the demo app's diagnostics screen — can see it.
- */
-function resolveConsentTesting(
-	testing: ConsentTestingOptions | undefined,
-	isProduction: boolean,
-): { consentTesting: ConsentTestingOptions | undefined; ignoredConsentTools: readonly string[] } {
-	if (!testing || !isProduction) {
-		return { consentTesting: testing, ignoredConsentTools: [] };
-	}
-
-	const ignored: string[] = [];
-	if (testing.debugGeography !== undefined && testing.debugGeography !== 'disabled') {
-		ignored.push('debugGeography');
-	}
-	if (testing.resetOnStart === true) {
-		ignored.push('resetOnStart');
-	}
-	return { consentTesting: undefined, ignoredConsentTools: ignored };
-}
+/**
+ * Catalog and configuration validation (FR-008), plus the fail-closed check
+ * that substitution cannot cover (FR-012).
+ *
+ * Configuration faults throw rather than returning a result. They mean the app
+ * is wired wrong, and no runtime status could describe a usable outcome — every
+ * other failure in this package is a typed result instead.
+ *
+ * Every message names the offending placement key. An error that says only
+ * "invalid configuration" makes the integrator hunt through a catalog by hand.
+ */
+
+import { AdsConfigError } from '../diagnostics/errors';
+import { resolvePlacementAdUnits, type ResolvedCatalog } from './resolveAdUnit';
+import { checkBand, resolveTimeouts, type ResolvedTimeouts } from '../core/timers';
+import {
+	defaultMinRequestIntervalMs,
+	MIN_REQUEST_INTERVAL_BOUNDS,
+} from '../core/requestThrottle';
+import { toEnablement } from '../core/enablement';
+import { resolveEffectiveRetry, type ResolvedRetryPolicy } from '../core/retryPolicy';
+import type {
+	AdFormat,
+	AdsConfig,
+	ConsentTestingOptions,
+	Enablement,
+	Environment,
+	PlacementDefinition,
+} from './types';
+
+const FORMATS: ReadonlySet<string> = new Set<AdFormat>([
+	'banner',
+	'interstitial',
+	'rewarded',
+	'app_open',
+]);
+
+export interface ValidateOptions {
+	/**
+	 * Whether this is a debug build. Injected rather than read from `__DEV__`
+	 * directly so the fail-closed rule is testable without manipulating a global
+	 * the test runner also depends on.
+	 */
+	readonly isDevBuild: boolean;
+}
+
+export interface ResolvedConfig {
+	readonly enablement: Enablement;
+	readonly environment: Environment;
+	readonly placements: ReadonlyMap<string, PlacementDefinition>;
+	readonly catalog: ResolvedCatalog;
+	readonly timeouts: ResolvedTimeouts;
+	/** Empty in production regardless of what was configured (FR-014). */
+	readonly testDeviceIds: readonly string[];
+	/** Effective retry per placement. `null` means retry is off there (FR-134). */
+	readonly retryByKey: ReadonlyMap<string, ResolvedRetryPolicy | null>;
+	/**
+	 * Effective minimum interval between provider requests, per placement
+	 * (FR-140). Zero means the throttle is off for that placement.
+	 */
+	readonly minRequestIntervalByKey: ReadonlyMap<string, number>;
+	/** Stripped entirely in production (FR-113). */
+	readonly consentTesting: ConsentTestingOptions | undefined;
+	/**
+	 * Which consent tools were dropped because the environment is production.
+	 * Surfaced so the inertness is observable rather than merely documented —
+	 * the same treatment FR-011a gives substituted ad units.
+	 */
+	readonly ignoredConsentTools: readonly string[];
+}
+
+export function validateConfig(config: AdsConfig, options: ValidateOptions): ResolvedConfig {
+	// FR-012. Substitution deliberately does not apply in production, so a debug
+	// build declaring `production` is the one case it cannot make safe: it would
+	// send real requests from a build that should never generate traffic. Fail
+	// closed rather than continue.
+	if (config.environment === 'production' && options.isDevBuild) {
+		throw new AdsConfigError('production_in_dev_build', {
+			message:
+				'environment is "production" but this is a development build. ' +
+				'Non-production builds must declare "development" or "test" so the package can ' +
+				'substitute official Google test ad units and keep production traffic impossible.',
+		});
+	}
+
+	if (!Array.isArray(config.placements) || config.placements.length === 0) {
+		throw new AdsConfigError('invalid_config', {
+			message: 'placements must be a non-empty array; the package can show nothing without one',
+		});
+	}
+
+	const byKey = new Map<string, PlacementDefinition>();
+
+	for (const placement of config.placements) {
+		const key = typeof placement?.key === 'string' ? placement.key.trim() : '';
+
+		if (!key) {
+			throw new AdsConfigError('invalid_config', {
+				message: 'every placement needs a non-empty key',
+			});
+		}
+
+		if (byKey.has(key)) {
+			// Rejecting the whole catalog rather than picking a winner: a repeated
+			// key means the app's own naming produced two placements for one slot,
+			// and the package has no basis to guess which was meant.
+			throw new AdsConfigError('duplicate_placement_key', {
+				message: `duplicate placement key "${key}"`,
+				placementKey: key,
+			});
+		}
+
+		if (!FORMATS.has(placement.format)) {
+			throw new AdsConfigError('invalid_config', {
+				message: `placement "${key}" has unsupported format "${String(placement.format)}"; supported formats are banner, interstitial, rewarded, and app_open`,
+				placementKey: key,
+			});
+		}
+
+		if (!placement.androidAdUnitId || !placement.androidAdUnitId.trim()) {
+			throw new AdsConfigError('missing_ad_unit_id', {
+				message: `placement "${key}" is missing androidAdUnitId`,
+				placementKey: key,
+				format: placement.format,
+			});
+		}
+
+		byKey.set(key, { ...placement, key });
+	}
+
+	const timeouts = resolveTimeouts({
+		timeouts: config.timeouts,
+		adValidityMs: config.adValidityMs,
+		appOpenValidityMs: config.appOpenValidityMs,
+		undecidedWarningMs: config.undecidedWarningMs,
+	});
+	const catalog = resolvePlacementAdUnits(Array.from(byKey.values()), config.environment);
+
+	// Resolved eagerly, for every placement, so an out-of-bounds override fails
+	// at construction rather than on the first failed load in production — which
+	// is the one moment nobody is watching for a configuration error.
+	const retryByKey = new Map<string, ResolvedRetryPolicy | null>();
+	// Resolved in the same loop and for the same reason: an out-of-bounds floor
+	// must fail at construction, not silently refuse every request in production.
+	const minRequestIntervalByKey = new Map<string, number>();
+	for (const [key, placement] of byKey) {
+		retryByKey.set(key, resolveEffectiveRetry(config.retry, placement.retry, key));
+		minRequestIntervalByKey.set(
+			key,
+			placement.minRequestIntervalMs === undefined
+				? defaultMinRequestIntervalMs(placement.format)
+				: checkBand(
+						`placements["${key}"].minRequestIntervalMs`,
+						placement.minRequestIntervalMs,
+						MIN_REQUEST_INTERVAL_BOUNDS,
+					),
+		);
+	}
+
+	const isProduction = config.environment === 'production';
+	const { consentTesting, ignoredConsentTools } = resolveConsentTesting(
+		config.consentTesting,
+		isProduction,
+	);
+
+	return {
+		enablement: toEnablement(config.enabled),
+		environment: config.environment,
+		placements: byKey,
+		catalog,
+		timeouts,
+		// FR-014: debug and test-device settings must not be able to alter
+		// production behavior, so they are dropped rather than carried and
+		// conditionally ignored somewhere further down.
+		testDeviceIds: isProduction ? [] : [...(config.testDeviceIds ?? [])],
+		retryByKey,
+		minRequestIntervalByKey,
+		consentTesting,
+		ignoredConsentTools,
+	};
+}
+
+/**
+ * Neutralizes the consent testing tools in production (FR-113).
+ *
+ * Dropped here, at the single validation point, rather than checked wherever
+ * they are used. That is what makes the guarantee provable: a rule enforced in
+ * one place can be asserted by a test, while one spread across the consent
+ * module's call sites is a hope. It is the same reasoning that makes the ad-unit
+ * substitution guarantee hold, and it is why both are enforced identically.
+ *
+ * The names of what was dropped are returned rather than only logged, so an
+ * automated test — and the demo app's diagnostics screen — can see it.
+ */
+function resolveConsentTesting(
+	testing: ConsentTestingOptions | undefined,
+	isProduction: boolean,
+): { consentTesting: ConsentTestingOptions | undefined; ignoredConsentTools: readonly string[] } {
+	if (!testing || !isProduction) {
+		return { consentTesting: testing, ignoredConsentTools: [] };
+	}
+
+	const ignored: string[] = [];
+	if (testing.debugGeography !== undefined && testing.debugGeography !== 'disabled') {
+		ignored.push('debugGeography');
+	}
+	if (testing.resetOnStart === true) {
+		ignored.push('resetOnStart');
+	}
+	return { consentTesting: undefined, ignoredConsentTools: ignored };
+}