@chipmobilesdk/rn-ads 0.1.0 → 0.2.1

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

@@ -1,33 +1,41 @@
 ---
 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."
+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."
 metadata:
   package: "@chipmobilesdk/rn-ads"
-  packageVersion: "0.1.0"
+  packageVersion: "0.2.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.
+Adaptive banner, interstitial, rewarded and app-open 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 — including for
+consent.
 
 ## Use this when
 
-- Adding a banner, interstitial or rewarded ad to a screen
+- Adding a banner, interstitial, rewarded or app-open ad to a screen
+- Running a consent flow in a region that requires one, without importing AdMob
+- Deferring ads at startup until a purchase or entitlement check answers
+- Turning ads back on after a subscription lapses or a refund lands
 - 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
+- Debugging an ad that never loads, or a `blocked` / `undecided` / `unavailable` /
+  `ad_originated_return` / `provider_error`
 - 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.
+- **Consent UI or copy** — the package *orchestrates* the provider's flow and normalizes
+  the outcome, but the form is drawn by the provider and the legal text is theirs. Timing,
+  surrounding copy and the "change your mind" path stay yours.
 - **Where or how often ads appear** — no frequency cap, no placement rule, no auto-insert.
+  The package never shows an ad on its own, app-open included.
 - **Granting the reward** — it reports `reward_earned`; entitlement is the app's.
+- **Anything about payments** — the undecided state exists *because* apps sell ad removal,
+  but the package receives a decision and never a reason, receipt or entitlement.
 - iOS — not implemented; every call returns `unavailable` / `unsupported_platform`.
 
 ## Nothing loads until consent and initialization complete
@@ -37,7 +45,14 @@ gate withheld, **zero** provider calls occur — not even configuration. `childD
 `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`.
+See `## Initialize — consent comes first` and `## Consent`.
+
+## Three gates, one reason — check this order first
+
+A refused request reports exactly one reason, and the precedence is fixed:
+**platform availability → enablement → consent**, most immovable first. So
+`unsupported_platform` on a disabled instance is reported as `unsupported_platform` —
+turning ads on would not have helped. Full table in `## Why an ad did not show`.
 
 ## Never gate `<AdsBanner>` on its own placement state
 
@@ -47,40 +62,112 @@ unconditionally. Rendering it only when the state is `loading`/`ready` deadlocks
 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"
+## `undecided` is not `disabled`, and that is the whole point
+
+`enabled` takes `true`, `false` or `'undecided'`. All three send zero requests except
+`true`. `'undecided'` reports itself distinctly — in `getStatus()` and in the banner's
+placement state — so an app that has not yet heard back from the store can **hold** the
+banner's space instead of reclaiming it, and a paying user never sees an ad flash in and
+out. `disabled` means a settled no; reclaim the space.
+
+The package never resolves it for you. Leave it unresolved past `undecidedWarningMs`
+(default 10s) and you get exactly one `config_warning`, never a stream.
+
+## `setEnabled` returns a result — read it
+
+In 0.1.0 it returned `void` and re-enabling after a disable silently dropped the init
+status, so every later `load` and `show` was refused with nothing to say so. That was a
+defect and it is fixed. The result now says which happened:
+
+- `resumed` — the provider was never un-initialized; load away, zero provider calls made.
+- `requires_initialization` — call `initialize()` yourself. The package will **not** do it
+  implicitly, because that would hide an async, billable operation behind a setter.
+
+Existing `ads.setEnabled(false);` call sites still compile untouched.
+
+## Four 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.
+  read, and the Android build fails outright. `0.2.0` needed no bump — consent and
+  app-open are both already in `16.0.3`. 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`.
+- **Consent tools going quiet in production.** `consentTesting.debugGeography` and
+  `resetOnStart` are stripped at config validation in `production` and listed by
+  `getIgnoredConsentTools()`. Working as designed.
+- **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.
+
+## Retry is off unless you ask
+
+No `retry` in config means the request count is byte-identical to 0.1.0 — a test in the
+package proves it. When enabled it is bounded (default 2 retries, 2s then 4s, no jitter),
+retries only errors already flagged `retryable`, and cancels everything on disable,
+undecided, consent loss or `dispose()`. Every attempt emits `retry_scheduled` carrying the
+load cycle's `correlationId`, because every attempt is a billable request.
+Per-placement `retry: false` turns it off for one placement.
+
+## App-open: the one rule you cannot implement yourself
+
+App-open shares the single full-screen lock with interstitial and rewarded, and expires on
+its own shorter window (30 min default, vs 60). The part worth knowing: a show requested
+on a return **from an ad** — or from a browser an ad opened — is refused with
+`ad_originated_return`, distinct from `busy` and `not_ready`. Your app cannot tell that
+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)
+
+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`,
+`useAds` · `AdsBanner` · `usePlacementState`, `useAdsStatus`, `useAdsEvents` · `AdsError`,
+`AdsConfigError`, `isAdsError`, `isFullScreenFormat` · `DEFAULT_LOAD_TIMEOUT_MS`,
+`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
+`@chipmobilesdk/rn-ads/testing` (test doubles only).
+
+Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setEnablement`, `setAppActive`,
+`consent`, `getStatus`, `subscribeStatus`, `load`, `show`, `getPlacementState`,
+`subscribePlacement`, `subscribeEvents`, `getSubstitutedPlacements`,
+`getIgnoredConsentTools`, `dispose`.
+
+Consent namespace (`ads.consent.*`, opt-in — untouched, nothing starts):
+`requestInfoUpdate`, `showFormIfRequired`, `getState`, `subscribe`, `reset`.
 
 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`.
+`FullScreenFormat`, `Environment`, `Enablement`, `EnablementResult`, `ConsentApi`,
+`ConsentState`, `ConsentSnapshot`, `ConsentTestingOptions`, `RetryPolicy`, `InitStatus`,
+`PlacementState`, `InitResult`, `LoadResult`, `ShowResult`, `PrivacyUpdateResult`,
+`Reward`, `AdEvent`, `AdEventType`, `AdEventListener`, `ConfigWarning`, `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`.
 
+## Upgrading 0.1.0 → 0.2.0
+
+One required change, compile-time only: five unions gained members, so an exhaustive
+`switch` over any of them needs the new cases or a `default`.
+
+| Union | New members |
+|---|---|
+| `AdFormat` | `'app_open'` |
+| `InitStatus` | `'undecided'` |
+| `PlacementState` | `'undecided'` |
+| `PrivacyBlockReason` | `'consent_flow_required'`, `'consent_flow_error'` |
+| `AdsErrorCode` | `'undecided'`, `'ad_originated_return'`, `'consent_flow_required'`, `'consent_flow_failed'`, `'retry_out_of_bounds'` |
+
+Everything else is opt-in: consent, `'undecided'`, app-open and retry are all off or absent
+until configured. One behavior change needs no action — on an unavailable platform with
+ads also disabled, the reason is now `unsupported_platform` where 0.1.0 said `disabled`.
+
 ## Where the detail lives
 
 Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
@@ -89,10 +176,16 @@ Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
 |---|---|
 | First integration | `## Install`, `## Configure` |
 | Consent ordering | `## Initialize — consent comes first` |
+| Running the consent flow | `## Consent` |
 | Rendering a banner | `## Banner` |
 | Full-screen formats | `## Interstitial and rewarded` |
+| 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` |
+| 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` |
 | Permissions, Data safety, families | `## Install`, `## Release checklists` |
 | Build failure after a bridge upgrade | `## Compatibility` |
+| Migration detail | `## Versioning` |
 | 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 };
+}