@chipmobilesdk/rn-ads 0.1.0 → 0.2.0

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

@@ -1,98 +1,98 @@
----
-name: sdk-rn-ads
-description: "Advertising via @chipmobilesdk/rn-ads: AdMob banner/interstitial/rewarded behind a provider-neutral contract, placement keys, consent gating, per-environment test-ad substitution. Use when adding ads to a screen, debugging an ad that never loads, mapping ad units per environment, or answering a Data safety question about advertising."
-metadata:
-  package: "@chipmobilesdk/rn-ads"
-  packageVersion: "0.1.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-ads
-
-Adaptive banner, interstitial and rewarded ads on Android via Google AdMob, behind a
-contract that names no provider. The app names a placement key; the package owns the
-request. Consuming code never imports the Google Mobile Ads SDK.
-
-## Use this when
-
-- Adding a banner, interstitial or rewarded ad to a screen
-- Mapping AdMob ad units to placement keys per environment
-- Debugging an ad that never loads, or a `blocked` / `unavailable` / `provider_error`
-- Wiring consent so requests cannot precede it
-- Answering a Data safety / App Privacy question about advertising
-
-## Do not use this for
-
-- **Consent UI or copy** — the package consumes a gate outcome and enforces ordering; it
-  renders no dialog and ships no legal text.
-- **Where or how often ads appear** — no frequency cap, no placement rule, no auto-insert.
-- **Granting the reward** — it reports `reward_earned`; entitlement is the app's.
-- iOS — not implemented; every call returns `unavailable` / `unsupported_platform`.
-
-## Nothing loads until consent and initialization complete
-
-This is enforced, and it is the answer to almost every "the ad never appears". With the
-gate withheld, **zero** provider calls occur — not even configuration. `childDirected`,
-`underAgeOfConsent` and `maxAdContentRating` take effect only if they reach
-`initialize()` *before* the provider starts; changing one later returns
-`requires_reinitialization` rather than silently not applying.
-See `## Initialize — consent comes first`.
-
-## Never gate `<AdsBanner>` on its own placement state
-
-`AdsBanner` is what measures the container and starts the load, so it must be mounted
-unconditionally. Rendering it only when the state is `loading`/`ready` deadlocks at
-`idle` and no ad ever appears. Use the state for the *surrounding* placeholder and to
-decide whether to hold or reclaim space — never to decide whether to mount the host. It
-renders `null` on its own when there is nothing to show.
-
-## Two 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
-  read, and the Android build fails outright. Read `## Compatibility` before widening it.
-- **Test ads in dev.** Outside `production`, non-official ad units are replaced with
-  Google's test units and reported via `config_warning` / `getSubstitutedPlacements()`.
-  That is the safety guarantee working, not a misconfiguration. Never click a production
-  ad to verify anything.
-
-## Public API (v0.1.0)
-
-Runtime: `createAds` (throws `AdsConfigError` on a bad catalog; everything else returns a
-typed result rather than throwing) · `AdsProvider`, `useAds` · `AdsBanner` ·
-`usePlacementState`, `useAdsStatus`, `useAdsEvents` · `AdsError`, `AdsConfigError`,
-`isAdsError`, `isFullScreenFormat` · `DEFAULT_LOAD_TIMEOUT_MS`, `DEFAULT_SHOW_TIMEOUT_MS`,
-`DEFAULT_AD_VALIDITY_MS`, `LOAD_TIMEOUT_BOUNDS`, `SHOW_TIMEOUT_BOUNDS`,
-`AD_VALIDITY_BOUNDS` · `createFakeAdsEngine` from `@chipmobilesdk/rn-ads/testing`
-(test doubles only).
-
-Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setAppActive`, `getStatus`,
-`subscribeStatus`, `load`, `show`, `getPlacementState`, `subscribePlacement`,
-`subscribeEvents`, `getSubstitutedPlacements`, `dispose`.
-
-Types: `AdsInstance`, `AdsConfig`, `PlacementDefinition`, `PrivacyOptions`, `AdFormat`,
-`FullScreenFormat`, `Environment`, `InitStatus`, `PlacementState`, `InitResult`,
-`LoadResult`, `ShowResult`, `PrivacyUpdateResult`, `Reward`, `AdEvent`, `AdEventType`,
-`AdEventListener`, `ImpressionSource`, `AdsErrorCode`, `AdsOperation`, `TimeoutConfig`,
-`AdContentRating`, `PrivacyBlockReason`, `UnavailableReason`, `Unsubscribe`,
-`AdsBannerProps`, `AdsProviderProps`.
-
-Call `dispose()` when the owning screen unmounts; it is idempotent, and so is every
-`Unsubscribe`.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
-
-| Need | Section |
-|---|---|
-| First integration | `## Install`, `## Configure` |
-| Consent ordering | `## Initialize — consent comes first` |
-| Rendering a banner | `## Banner` |
-| Full-screen formats | `## Interstitial and rewarded` |
-| Results, events, errors, timeouts, cleanup | `## State, events, and errors` |
-| Tests without a device | `## Testing` |
-| Permissions, Data safety, families | `## Install`, `## Release checklists` |
-| Build failure after a bridge upgrade | `## Compatibility` |
-| What is deferred | `## Known limitations`, `## Extending to iOS` |
+---
+name: sdk-rn-ads
+description: "Advertising via @chipmobilesdk/rn-ads: AdMob banner/interstitial/rewarded behind a provider-neutral contract, placement keys, consent gating, per-environment test-ad substitution. Use when adding ads to a screen, debugging an ad that never loads, mapping ad units per environment, or answering a Data safety question about advertising."
+metadata:
+  package: "@chipmobilesdk/rn-ads"
+  packageVersion: "0.1.0"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-ads
+
+Adaptive banner, interstitial and rewarded ads on Android via Google AdMob, behind a
+contract that names no provider. The app names a placement key; the package owns the
+request. Consuming code never imports the Google Mobile Ads SDK.
+
+## Use this when
+
+- Adding a banner, interstitial or rewarded ad to a screen
+- Mapping AdMob ad units to placement keys per environment
+- Debugging an ad that never loads, or a `blocked` / `unavailable` / `provider_error`
+- Wiring consent so requests cannot precede it
+- Answering a Data safety / App Privacy question about advertising
+
+## Do not use this for
+
+- **Consent UI or copy** — the package consumes a gate outcome and enforces ordering; it
+  renders no dialog and ships no legal text.
+- **Where or how often ads appear** — no frequency cap, no placement rule, no auto-insert.
+- **Granting the reward** — it reports `reward_earned`; entitlement is the app's.
+- iOS — not implemented; every call returns `unavailable` / `unsupported_platform`.
+
+## Nothing loads until consent and initialization complete
+
+This is enforced, and it is the answer to almost every "the ad never appears". With the
+gate withheld, **zero** provider calls occur — not even configuration. `childDirected`,
+`underAgeOfConsent` and `maxAdContentRating` take effect only if they reach
+`initialize()` *before* the provider starts; changing one later returns
+`requires_reinitialization` rather than silently not applying.
+See `## Initialize — consent comes first`.
+
+## Never gate `<AdsBanner>` on its own placement state
+
+`AdsBanner` is what measures the container and starts the load, so it must be mounted
+unconditionally. Rendering it only when the state is `loading`/`ready` deadlocks at
+`idle` and no ad ever appears. Use the state for the *surrounding* placeholder and to
+decide whether to hold or reclaim space — never to decide whether to mount the host. It
+renders `null` on its own when there is nothing to show.
+
+## Two 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
+  read, and the Android build fails outright. Read `## Compatibility` before widening it.
+- **Test ads in dev.** Outside `production`, non-official ad units are replaced with
+  Google's test units and reported via `config_warning` / `getSubstitutedPlacements()`.
+  That is the safety guarantee working, not a misconfiguration. Never click a production
+  ad to verify anything.
+
+## Public API (v0.1.0)
+
+Runtime: `createAds` (throws `AdsConfigError` on a bad catalog; everything else returns a
+typed result rather than throwing) · `AdsProvider`, `useAds` · `AdsBanner` ·
+`usePlacementState`, `useAdsStatus`, `useAdsEvents` · `AdsError`, `AdsConfigError`,
+`isAdsError`, `isFullScreenFormat` · `DEFAULT_LOAD_TIMEOUT_MS`, `DEFAULT_SHOW_TIMEOUT_MS`,
+`DEFAULT_AD_VALIDITY_MS`, `LOAD_TIMEOUT_BOUNDS`, `SHOW_TIMEOUT_BOUNDS`,
+`AD_VALIDITY_BOUNDS` · `createFakeAdsEngine` from `@chipmobilesdk/rn-ads/testing`
+(test doubles only).
+
+Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setAppActive`, `getStatus`,
+`subscribeStatus`, `load`, `show`, `getPlacementState`, `subscribePlacement`,
+`subscribeEvents`, `getSubstitutedPlacements`, `dispose`.
+
+Types: `AdsInstance`, `AdsConfig`, `PlacementDefinition`, `PrivacyOptions`, `AdFormat`,
+`FullScreenFormat`, `Environment`, `InitStatus`, `PlacementState`, `InitResult`,
+`LoadResult`, `ShowResult`, `PrivacyUpdateResult`, `Reward`, `AdEvent`, `AdEventType`,
+`AdEventListener`, `ImpressionSource`, `AdsErrorCode`, `AdsOperation`, `TimeoutConfig`,
+`AdContentRating`, `PrivacyBlockReason`, `UnavailableReason`, `Unsubscribe`,
+`AdsBannerProps`, `AdsProviderProps`.
+
+Call `dispose()` when the owning screen unmounts; it is idempotent, and so is every
+`Unsubscribe`.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Install`, `## Configure` |
+| Consent ordering | `## Initialize — consent comes first` |
+| Rendering a banner | `## Banner` |
+| Full-screen formats | `## Interstitial and rewarded` |
+| Results, events, errors, timeouts, cleanup | `## State, events, and errors` |
+| Tests without a device | `## Testing` |
+| Permissions, Data safety, families | `## Install`, `## Release checklists` |
+| Build failure after a bridge upgrade | `## Compatibility` |
+| What is deferred | `## Known limitations`, `## Extending to iOS` |

package/src/config/types.ts

@@ -1,3 +1,5 @@
+import type { AdsError } from '../diagnostics/errors';
+
 /**
  * Public configuration and state types (FR-001, FR-003, FR-004).
  *
@@ -9,14 +11,26 @@
  * one instance and is released by `dispose()`.
  */
 
-/** Formats supported in v1. App-open, native, and rewarded-interstitial are deferred. */
-export type AdFormat = 'banner' | 'interstitial' | 'rewarded';
+/**
+ * Supported formats. Native and rewarded-interstitial remain deferred.
+ *
+ * `app_open` joined in 0.2.0. It is a member of this union rather than a
+ * separate concept because FR-132 forbids a parallel vocabulary: app-open uses
+ * the same placement states, events, and error codes as everything else. The
+ * cost is that a consumer's exhaustive `switch` over this union stops compiling
+ * — the one required migration step, documented in the 0.2.0 release notes.
+ */
+export type AdFormat = 'banner' | 'interstitial' | 'rewarded' | 'app_open';
 
-/** Formats that take over the screen, and so contend for the single-show lock. */
-export type FullScreenFormat = Extract<AdFormat, 'interstitial' | 'rewarded'>;
+/**
+ * Formats that take over the screen, and so contend for the single-show lock.
+ * App-open is included deliberately: two full-screen ads at once is a broken
+ * app regardless of which formats produced them (FR-129).
+ */
+export type FullScreenFormat = Extract<AdFormat, 'interstitial' | 'rewarded' | 'app_open'>;
 
 export function isFullScreenFormat(format: AdFormat): format is FullScreenFormat {
-	return format === 'interstitial' || format === 'rewarded';
+	return format === 'interstitial' || format === 'rewarded' || format === 'app_open';
 }
 
 /**
@@ -41,6 +55,96 @@ export interface PlacementDefinition {
 	 * type change for every existing consumer.
 	 */
 	readonly iosAdUnitId?: string;
+	/**
+	 * Per-placement retry, overriding `AdsConfig.retry` for this placement only.
+	 * Absent inherits; `false` turns retry off here while leaving it on elsewhere.
+	 *
+	 * An override *replaces* the instance-wide policy rather than merging into
+	 * it, so the effective policy for a placement is readable from configuration
+	 * without simulating a merge. Both are held to the same bounds, so an
+	 * override can narrow behavior but never exceed a ceiling (FR-136a).
+	 */
+	readonly retry?: RetryPolicy | false;
+}
+
+/**
+ * Bounded retry for failed loads. Off unless `AdsConfig.retry` is supplied —
+ * upgrading from 0.1.0 without configuring this issues not one extra request
+ * (FR-134).
+ *
+ * Only errors already flagged `retryable` are retried. Configuration errors,
+ * consent errors, an unsupported platform, and a disabled or undecided instance
+ * never are (FR-135).
+ *
+ * Backoff is exponential with a fixed x2 multiplier and no jitter. Jitter exists
+ * to desynchronize a fleet hitting one server; a single device retrying its own
+ * load has no herd to avoid, and omitting it keeps the attempt count an exact
+ * assertion rather than a statistical one.
+ */
+export interface RetryPolicy {
+	/** Attempts *after* the first. Default 2, bounds 1-5. */
+	readonly maxRetries?: number;
+	/** Delay before the first retry. Default 2000ms, bounds 500-30000. */
+	readonly initialDelayMs?: number;
+	/** Ceiling the doubling cannot pass. Default 30000ms, bounds 1000-60000. */
+	readonly maxDelayMs?: number;
+}
+
+/**
+ * Whether the app wants ads, including the case where it does not know yet.
+ *
+ * The package never resolves `undecided` on the app's behalf and never learns
+ * why the app chose what it chose — no entitlement, no receipt, no reason
+ * (FR-119, FR-120).
+ */
+export type Enablement = 'enabled' | 'disabled' | 'undecided';
+
+/**
+ * Tools for exercising the consent flow from a device outside a
+ * consent-required region.
+ *
+ * **Stripped entirely when `environment` is `production`.** That is enforced at
+ * configuration validation rather than at each call site, so no path through the
+ * consent module can forget it, and the fact that they were ignored is
+ * observable through a `config_warning` event and `getIgnoredConsentTools()` —
+ * not merely documented (FR-113).
+ */
+export interface ConsentTestingOptions {
+	/** Makes the flow behave as though the device were in this region. */
+	readonly debugGeography?: 'disabled' | 'eea' | 'not_eea' | 'regulated_us_state' | 'other';
+	/** Clears any stored decision so the flow runs from the beginning. */
+	readonly resetOnStart?: boolean;
+}
+
+/**
+ * Consent status, normalized. Carries no provider type and no payload (FR-104).
+ *
+ * Shaped so an iOS adapter can later express both a consent flow and the
+ * platform's tracking-permission mechanism, plus the ordering between them,
+ * without changing shape.
+ */
+export type ConsentState =
+	/** Not yet asked. The initial value, and the value after a reset. */
+	| 'undetermined'
+	/** The provider reports this region does not require consent. */
+	| 'not_required'
+	/** Required and not yet obtained. */
+	| 'required'
+	/** Obtained. */
+	| 'obtained'
+	/**
+	 * The flow failed — a provider error, a network failure, a cancellation, or
+	 * a form dismissed without an answer. Never, under any circumstance, read as
+	 * consent granted (FR-106).
+	 */
+	| 'error';
+
+export interface ConsentSnapshot {
+	readonly state: ConsentState;
+	/** Always false when `state` is `error`. */
+	readonly canRequestAds: boolean;
+	readonly isFormAvailable: boolean;
+	readonly error: AdsError | null;
 }
 
 /** Bounds exist because an unbounded timeout is the same defect as no timeout. */
@@ -50,8 +154,16 @@ export interface TimeoutConfig {
 }
 
 export interface AdsConfig {
-	/** FR-009. When false, every operation is a safe no-op reporting `disabled`. */
-	readonly enabled: boolean;
+	/**
+	 * FR-009. When `false`, every operation is a safe no-op reporting `disabled`.
+	 *
+	 * `'undecided'` was added in 0.2.0 for an app that cannot answer this at
+	 * construction time — one selling an ad-removal tier has to ask a store
+	 * first. Both boolean spellings keep their exact 0.1.0 meaning; widening an
+	 * *input* union cannot break a consumer, because consumers write this value
+	 * rather than switching on it (FR-114, BC-003).
+	 */
+	readonly enabled: boolean | 'undecided';
 	readonly environment: Environment;
 	readonly placements: readonly PlacementDefinition[];
 	readonly timeouts?: TimeoutConfig;
@@ -59,6 +171,30 @@ export interface AdsConfig {
 	readonly adValidityMs?: number;
 	/** Ignored entirely in `production` (FR-014). */
 	readonly testDeviceIds?: readonly string[];
+	/**
+	 * How long a loaded app-open ad stays presentable. Separate from
+	 * `adValidityMs`, which continues to govern interstitial and rewarded.
+	 *
+	 * Default 30 minutes, half the other formats' window. Note this is *our*
+	 * constraint, not the provider's — Google expires app-open ads after four
+	 * hours, which is longer than this package's general full-screen window. The
+	 * shorter window trades some fill for a fresher creative at the most
+	 * prominent moment in the app (FR-130).
+	 */
+	readonly appOpenValidityMs?: number;
+	/**
+	 * How long `enabled: 'undecided'` may go unresolved before the package emits
+	 * one diagnostic warning. Default 10 seconds.
+	 *
+	 * It warns and does nothing else. Resolving on the app's behalf would mean
+	 * guessing at exactly the business decision FR-120 forbids the package from
+	 * knowing.
+	 */
+	readonly undecidedWarningMs?: number;
+	/** Instance-wide retry. Absent means retry is entirely off (FR-134). */
+	readonly retry?: RetryPolicy;
+	/** Consent testing tools. Stripped in `production` (FR-113). */
+	readonly consentTesting?: ConsentTestingOptions;
 }
 
 /** Content ratings, normalized. Maps onto the provider's own rating scale. */
@@ -82,7 +218,20 @@ export interface PrivacyOptions {
 	readonly personalizedAds?: boolean;
 }
 
-export type PrivacyBlockReason = 'consent_required' | 'consent_undetermined';
+/**
+ * Why the consent gate is closed.
+ *
+ * The two original members keep their exact v1 meaning — the app's own gate —
+ * so no existing consumer's interpretation changes. The two added in 0.2.0 name
+ * the package's consent flow instead. The split exists because the gate has two
+ * independent inputs that combine as most-restrictive-wins, and a refusal has to
+ * say *which* of them is blocking or the app cannot act on it (FR-105a).
+ */
+export type PrivacyBlockReason =
+	| 'consent_required'
+	| 'consent_undetermined'
+	| 'consent_flow_required'
+	| 'consent_flow_error';
 
 export type UnavailableReason = 'unsupported_platform' | 'provider_missing';
 
@@ -93,6 +242,17 @@ export type InitStatus =
 	| 'initializing'
 	| 'ready'
 	| 'disabled'
+	/**
+	 * The app has not decided whether ads are on yet — it is still waiting on
+	 * whatever answers that question, typically a store entitlement sync.
+	 *
+	 * Behaves exactly like `disabled` for requests (zero reach the provider) but
+	 * is deliberately a separate value. That distinction is the entire point:
+	 * `disabled` means a settled no, and a banner host can reclaim its space;
+	 * `undecided` means not yet, and the app may want to hold the space so a
+	 * paying user never sees an ad flash in and out (FR-116).
+	 */
+	| 'undecided'
 	| 'unavailable'
 	| 'failed';
 
@@ -107,6 +267,8 @@ export type PlacementState =
 	| 'showing'
 	| 'consumed'
 	| 'failed'
+	/** Mirrors `InitStatus.undecided` so the banner host can report it directly. */
+	| 'undecided'
 	| 'unavailable';
 
 /** FR-047. The provider's reward descriptor, normalized. */

package/src/config/validate.ts

@@ -13,9 +13,23 @@
 import { AdsConfigError } from '../diagnostics/errors';
 import { resolvePlacementAdUnits, type ResolvedCatalog } from './resolveAdUnit';
 import { resolveTimeouts, type ResolvedTimeouts } from '../core/timers';
-import type { AdFormat, AdsConfig, Environment, PlacementDefinition } from './types';
+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']);
+const FORMATS: ReadonlySet<string> = new Set<AdFormat>([
+	'banner',
+	'interstitial',
+	'rewarded',
+	'app_open',
+]);
 
 export interface ValidateOptions {
 	/**
@@ -27,13 +41,23 @@ export interface ValidateOptions {
 }
 
 export interface ResolvedConfig {
-	readonly enabled: boolean;
+	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 {
@@ -79,7 +103,7 @@ export function validateConfig(config: AdsConfig, options: ValidateOptions): Res
 
 		if (!FORMATS.has(placement.format)) {
 			throw new AdsConfigError('invalid_config', {
-				message: `placement "${key}" has unsupported format "${String(placement.format)}"; v1 supports banner, interstitial, and rewarded`,
+				message: `placement "${key}" has unsupported format "${String(placement.format)}"; supported formats are banner, interstitial, rewarded, and app_open`,
 				placementKey: key,
 			});
 		}
@@ -95,11 +119,30 @@ export function validateConfig(config: AdsConfig, options: ValidateOptions): Res
 		byKey.set(key, { ...placement, key });
 	}
 
-	const timeouts = resolveTimeouts(config.timeouts, config.adValidityMs);
+	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 {
-		enabled: config.enabled !== false,
+		enablement: toEnablement(config.enabled),
 		environment: config.environment,
 		placements: byKey,
 		catalog,
@@ -107,6 +150,39 @@ export function validateConfig(config: AdsConfig, options: ValidateOptions): Res
 		// 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: config.environment === 'production' ? [] : [...(config.testDeviceIds ?? [])],
+		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 };
+}