@chipmobilesdk/rn-ads 0.1.0 → 0.2.0

package/src/core/adsInstance.ts

@@ -20,6 +20,8 @@ import {
 	isFullScreenFormat,
 	type AdFormat,
 	type AdsConfig,
+	type ConsentSnapshot,
+	type Enablement,
 	type FullScreenFormat,
 	type InitStatus,
 	type PlacementDefinition,
@@ -48,13 +50,26 @@ import {
 	type PlacementSnapshot,
 } from './placementMachine';
 import { evaluateGate, requiresReinitialization, toEnginePrivacy } from './privacyGate';
+import { evaluateGates, type ConsentGateInput, type GateDecision } from './gates';
 import { createRewardedSession, type RewardedSession } from './rewardedSession';
-import { createTimerSet, isStale } from './timers';
+import { createTimerSet, isStale, type Scheduler } from './timers';
+import { canResume, permitsRequests, type EnablementResult } from './enablement';
+import { canRetry, delayForAttempt } from './retryPolicy';
+import { createAdOriginatedTracker } from './adOriginatedReturn';
+import {
+	buildConsentOptions,
+	INITIAL_CONSENT,
+	needsForm,
+	runConsentStep,
+	toGateInput,
+} from './consentFlow';
 
 export type InitResult =
 	| { readonly status: 'ready' }
 	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
 	| { readonly status: 'disabled' }
+	/** The app has not decided whether ads are on. Nothing was requested (FR-115). */
+	| { readonly status: 'undecided' }
 	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
 	| { readonly status: 'failed'; readonly error: AdsError };
 
@@ -63,11 +78,13 @@ export type PrivacyUpdateResult =
 	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
 	| { readonly status: 'requires_reinitialization' }
 	| { readonly status: 'disabled' }
+	| { readonly status: 'undecided' }
 	| { readonly status: 'unavailable'; readonly reason: UnavailableReason };
 
 export type LoadResult =
 	| { readonly status: 'loaded'; readonly correlationId: string }
 	| { readonly status: 'disabled' }
+	| { readonly status: 'undecided' }
 	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
 	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
 	| { readonly status: 'no_fill' }
@@ -80,17 +97,54 @@ export type ShowResult =
 	| { readonly status: 'busy' }
 	| { readonly status: 'consumed' }
 	| { readonly status: 'app_inactive' }
+	/**
+	 * The user came back to the app from an ad, or from a browser an ad opened,
+	 * so an app-open ad would be an ad immediately after an ad. Distinct from
+	 * `busy` and `not_ready` because the app cannot detect this itself and
+	 * therefore cannot infer it from either of those (FR-128).
+	 */
+	| { readonly status: 'ad_originated_return' }
 	| { readonly status: 'disabled' }
+	| { readonly status: 'undecided' }
 	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
 	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
 	| { readonly status: 'timeout' }
 	| { readonly status: 'failed'; readonly error: AdsError };
 
+/**
+ * The optional consent capability (FR-101).
+ *
+ * Grouped under its own namespace rather than flattened onto the instance so
+ * that FR-102's optionality stays legible: an app that never touches
+ * `ads.consent` never starts a flow. Five loose methods on the instance would
+ * invite the assumption that they are part of the normal path.
+ */
+export interface ConsentApi {
+	/** Refreshes consent information from the provider. */
+	requestInfoUpdate(): Promise<ConsentSnapshot>;
+	/** Presents the provider's form if one is required. Renders nothing itself. */
+	showFormIfRequired(): Promise<ConsentSnapshot>;
+	getState(): ConsentSnapshot;
+	subscribe(listener: (snapshot: ConsentSnapshot) => void): Unsubscribe;
+	/** Clears the stored decision. Inert in production (FR-113). */
+	reset(): Promise<void>;
+}
+
 export interface AdsInstance {
 	initialize(privacy: PrivacyOptions): Promise<InitResult>;
 	updatePrivacy(privacy: PrivacyOptions): Promise<PrivacyUpdateResult>;
-	setEnabled(enabled: boolean): void;
+	/**
+	 * Turns ads on or off. Returns a result rather than `void` (FR-122).
+	 *
+	 * 0.1.0 returned nothing, which meant an app re-enabling ads after a lapsed
+	 * subscription had no way to learn that it also had to re-initialize — and
+	 * every load and show after that was refused in silence.
+	 */
+	setEnabled(enabled: boolean): EnablementResult;
+	/** The same, including the third state the app has not resolved yet. */
+	setEnablement(next: Enablement): EnablementResult;
 	setAppActive(active: boolean): void;
+	readonly consent: ConsentApi;
 	getStatus(): InitStatus;
 	subscribeStatus(listener: (status: InitStatus) => void): Unsubscribe;
 
@@ -103,6 +157,8 @@ export interface AdsInstance {
 
 	/** FR-011a — substitution is observable state, not only a log line. */
 	getSubstitutedPlacements(): readonly string[];
+	/** FR-113 — the same treatment for consent tools dropped in production. */
+	getIgnoredConsentTools(): readonly string[];
 	/** Internal wiring for the banner host; not part of the documented surface. */
 	readonly internals: InstanceInternals;
 
@@ -127,6 +183,12 @@ export interface CreateAdsOptions {
 	/** Injected so the FR-012 rule is testable without touching a global. */
 	readonly isDevBuild?: boolean;
 	readonly now?: () => number;
+	/**
+	 * Injected so retry backoff, app-open expiry, and the undecided warning can
+	 * be driven by a test clock instead of by waiting. Production uses real
+	 * timers.
+	 */
+	readonly scheduler?: Scheduler;
 }
 
 interface PlacementRuntime {
@@ -150,6 +212,10 @@ interface PlacementRuntime {
 	cancelShowTimer: Unsubscribe | null;
 	rewarded: RewardedSession | null;
 	listeners: Set<(state: PlacementState) => void>;
+	/** Retries already spent in this load cycle. Reset when a new cycle starts. */
+	retryAttempts: number;
+	/** Cancels a scheduled retry. Called by disable, undecided, and dispose. */
+	cancelRetry: Unsubscribe | null;
 }
 
 function detectDevBuild(): boolean {
@@ -167,12 +233,34 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 	const engine: AdsEngine = options.engine ?? createDefaultEngine();
 	const events = createEventEmitter();
 	const correlation = createCorrelationIssuer();
-	const timers = createTimerSet();
+	const timers = createTimerSet(options.scheduler);
 	const lock = createFullScreenLock();
+	const adReturn = createAdOriginatedTracker();
 
-	let init: InitSnapshot = initialInit;
-	let enabled = resolved.enabled;
+	/**
+	 * An instance told it is `undecided` says so from the moment it exists.
+	 *
+	 * Without this it reports `not_started` until `initialize()` runs, which is
+	 * indistinguishable from a disabled instance at exactly the point an app is
+	 * deciding whether to reserve the banner's space — so FR-116 would hold only
+	 * after a call the app has no reason to make yet. Found on device, not in a
+	 * unit test, because the demo screen defers initialization the way a real
+	 * entitlement-gated app does.
+	 *
+	 * `disabled` deliberately keeps 0.1.0's `not_started` here: that behavior is
+	 * observable today and BC-004 protects it. The asymmetry is the cost of not
+	 * changing something that already shipped.
+	 */
+	let init: InitSnapshot =
+		resolved.enablement === 'undecided'
+			? initReducer(initialInit, { type: 'UNDECIDE' })
+			: initialInit;
+	let enablement: Enablement = resolved.enablement;
 	let appActive = true;
+	let consent: ConsentSnapshot = INITIAL_CONSENT;
+	let consentStarted = false;
+	let undecidedWarned = false;
+	let cancelUndecidedTimer: Unsubscribe | null = null;
 	let appliedPrivacy: PrivacyOptions | null = null;
 	let currentPrivacy: PrivacyOptions | null = null;
 	let inFlightInit: Promise<InitResult> | null = null;
@@ -194,9 +282,78 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			cancelShowTimer: null,
 			rewarded: null,
 			listeners: new Set(),
+			retryAttempts: 0,
+			cancelRetry: null,
+		});
+	}
+
+	const consentListeners = new Set<(snapshot: ConsentSnapshot) => void>();
+
+	function setConsent(next: ConsentSnapshot): void {
+		consent = next;
+		for (const listener of Array.from(consentListeners)) {
+			try {
+				listener(next);
+			} catch {
+				// Consumer code; isolated exactly as event listeners are (FR-056).
+			}
+		}
+	}
+
+	/**
+	 * The consent flow's contribution to the gate, or `null` when the app never
+	 * opted in.
+	 *
+	 * `null` is what makes FR-102 structural rather than conditional: with no
+	 * flow started, the gate sees only the app's own input and behaves exactly as
+	 * 0.1.0 did. There is no code path to skip and therefore none to forget.
+	 */
+	function consentGateInput(): ConsentGateInput {
+		return consentStarted ? toGateInput(consent) : null;
+	}
+
+	/**
+	 * Warns once if the app leaves `undecided` unresolved (FR-119).
+	 *
+	 * Once, not repeatedly: a warning that fires every ten seconds becomes noise
+	 * that gets filtered, which defeats the diagnostic. And it only warns — the
+	 * package never resolves the state itself, because doing so would mean
+	 * guessing at exactly the business decision FR-120 forbids it from knowing.
+	 */
+	function armUndecidedWarning(): void {
+		if (enablement !== 'undecided' || undecidedWarned || cancelUndecidedTimer) {
+			return;
+		}
+		const armedAt = now();
+		cancelUndecidedTimer = timers.after(resolved.timeouts.undecidedWarning, () => {
+			cancelUndecidedTimer = null;
+			if (disposed || enablement !== 'undecided' || undecidedWarned) {
+				return;
+			}
+			undecidedWarned = true;
+			events.emit({
+				type: 'config_warning',
+				timestamp: now(),
+				warning: 'enablement_undecided_timeout',
+				placementKeys: [],
+				elapsedMs: now() - armedAt,
+			});
 		});
 	}
 
+	function disarmUndecidedWarning(): void {
+		cancelUndecidedTimer?.();
+		cancelUndecidedTimer = null;
+	}
+
+	/** Cancels every pending retry, everywhere (FR-137). */
+	function cancelAllRetries(): void {
+		for (const runtime of placements.values()) {
+			runtime.cancelRetry?.();
+			runtime.cancelRetry = null;
+		}
+	}
+
 	function setInit(next: InitSnapshot): void {
 		if (next === init || next.status === init.status) {
 			init = next;
@@ -246,24 +403,67 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 		setPlacement(key, placementReducer(runtime.snapshot, event, definition.format));
 	}
 
+	/**
+	 * The single gate evaluation (FR-140).
+	 *
+	 * Assembles the three inputs and defers the precedence entirely to
+	 * `evaluateGates`. Nothing in this file compares gate state itself — the
+	 * whole point of FR-140 is that the order is a decision made once, not four
+	 * `if` chains that happen to agree today.
+	 *
+	 * Note the order differs from 0.1.0's, which checked `enabled` before
+	 * availability. That was never observable in isolation, only when two gates
+	 * were closed at once, and the case it changes — disabled on an unsupported
+	 * platform, previously decided by whichever transition arrived last — is the
+	 * incidental ordering FR-140a exists to fix.
+	 */
+	function currentGate(): GateDecision {
+		return evaluateGates({
+			available: engine.isAvailable()
+				? { ok: true }
+				: { ok: false, reason: 'unsupported_platform' },
+			enablement,
+			appGate: (() => {
+				const gate = evaluateGate(currentPrivacy);
+				return gate.allowed
+					? ({ permitted: true } as const)
+					: ({ permitted: false, reason: gate.reason } as const);
+			})(),
+			consentGate: consentGateInput(),
+		});
+	}
+
+	/** Maps a closed gate onto the refusal shape load, show, and the banner share. */
+	function refusalFor(
+		decision: Extract<GateDecision, { allowed: false }>,
+	): Extract<LoadResult, { status: 'disabled' | 'undecided' | 'blocked' | 'unavailable' }> {
+		switch (decision.kind) {
+			case 'unavailable':
+				return { status: 'unavailable', reason: decision.reason };
+			case 'disabled':
+				return { status: 'disabled' };
+			case 'undecided':
+				return { status: 'undecided' };
+			default:
+				return { status: 'blocked', reason: decision.reason };
+		}
+	}
+
 	/** Every refusal that applies before a placement is even looked up. */
 	function gateCheck():
 		| { readonly ok: true }
-		| { readonly ok: false; readonly result: Extract<LoadResult, { status: 'disabled' | 'blocked' | 'unavailable' }> } {
-		if (!enabled) {
-			return { ok: false, result: { status: 'disabled' } };
-		}
-		if (!engine.isAvailable()) {
-			return {
-				ok: false,
-				result: { status: 'unavailable', reason: 'unsupported_platform' },
-			};
-		}
-		const gate = evaluateGate(currentPrivacy);
-		if (!gate.allowed) {
-			return { ok: false, result: { status: 'blocked', reason: gate.reason } };
+		| {
+				readonly ok: false;
+				readonly result: Extract<
+					LoadResult,
+					{ status: 'disabled' | 'undecided' | 'blocked' | 'unavailable' }
+				>;
+		  } {
+		const decision = currentGate();
+		if (decision.allowed) {
+			return { ok: true };
 		}
-		return { ok: true };
+		return { ok: false, result: refusalFor(decision) };
 	}
 
 	function emitRefusal(
@@ -272,7 +472,11 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 		placementKey?: string,
 		format?: AdFormat,
 	): void {
-		if (result.status === 'disabled') {
+		if (result.status === 'disabled' || result.status === 'undecided') {
+			// `undecided` reuses the `disabled` event rather than minting a new
+			// one: for an observer of the event stream the fact is the same — no
+			// request was made — and the distinction that matters is carried by
+			// the typed result and the init status, where the app reads it.
 			events.emit({ type: 'disabled', timestamp: now(), operation, placementKey, format });
 		} else if (result.status === 'unavailable' || result.status === 'blocked') {
 			events.emit({
@@ -316,6 +520,15 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 		}
 		runtime.inFlightLoad = null;
 		runtime.rewarded = null;
+		runtime.cancelRetry?.();
+		runtime.cancelRetry = null;
+	}
+
+	/** App-open expires on its own, shorter window (FR-130). */
+	function validityFor(format: AdFormat): number {
+		return format === 'app_open'
+			? resolved.timeouts.appOpenValidity
+			: resolved.timeouts.adValidity;
 	}
 
 	async function doInitialize(privacy: PrivacyOptions): Promise<InitResult> {
@@ -356,6 +569,13 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 
 		switch (event.type) {
 			case 'opened': {
+				// The provider confirming an ad is on screen is what arms
+				// ad-originated return detection (FR-128). Taken from here rather
+				// than from the app's background report, which arrives too late to
+				// be trusted — see core/adOriginatedReturn.ts.
+				if (isFullScreenFormat(definition.format)) {
+					adReturn.noteFullScreenShown(now());
+				}
 				events.emit({ ...base, type: 'display_started' });
 				// R5: the provider exposes no impression callback for full-screen
 				// formats, so this one is derived from the ad opening. Labelled
@@ -364,6 +584,10 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				break;
 			}
 			case 'clicked':
+				// Recorded so that a background transition moments later is
+				// recognized as "the ad opened a browser" — the only signal the
+				// provider gives for that case (FR-128).
+				adReturn.noteClick(now());
 				events.emit({ ...base, type: 'click' });
 				break;
 			case 'rewarded': {
@@ -532,6 +756,118 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 		});
 	}
 
+	/**
+	 * One load, plus however many bounded retries the policy allows (FR-134).
+	 *
+	 * Off unless configured, so an upgraded 0.1.0 consumer goes through here once
+	 * and issues exactly the requests it always did. When on, only errors already
+	 * flagged `retryable` are retried — a configuration or consent failure is a
+	 * state another attempt cannot change, and retrying it would spend a billable
+	 * request on a certainty (FR-135).
+	 *
+	 * Every attempt is emitted before it is waited on, carrying the cycle's
+	 * correlation id, so the event stream can be reconciled against a bill
+	 * without inferring anything (FR-138).
+	 */
+	async function loadWithRetry(
+		key: string,
+		definition: PlacementDefinition,
+		adUnitId: string,
+		correlationId: string,
+	): Promise<LoadResult> {
+		const runtime = placements.get(key)!;
+		const policy = resolved.retryByKey.get(key) ?? null;
+
+		for (;;) {
+			const result = await loadFullScreen(key, definition, adUnitId, correlationId);
+			if (result.status === 'loaded' || disposed) {
+				return result;
+			}
+
+			const error =
+				result.status === 'failed'
+					? result.error
+					: result.status === 'no_fill'
+						? new AdsError('no_fill', { operation: 'load', placementKey: key })
+						: result.status === 'timeout'
+							? new AdsError('load_timeout', { operation: 'load', placementKey: key })
+							: null;
+
+			// A refusal — disabled, undecided, blocked, unavailable — is not a
+			// failure to retry. Nothing was requested, and nothing about asking
+			// again would change that.
+			if (!error || !error.retryable) {
+				return result;
+			}
+			if (!canRetry(policy, runtime.retryAttempts) || !permitsRequests(enablement)) {
+				return result;
+			}
+
+			runtime.retryAttempts += 1;
+			const delayMs = delayForAttempt(policy!, runtime.retryAttempts);
+			events.emit({
+				type: 'retry_scheduled',
+				timestamp: now(),
+				placementKey: key,
+				format: definition.format,
+				correlationId,
+				attempt: runtime.retryAttempts,
+				delayMs,
+				error,
+			});
+
+			const waited = await new Promise<boolean>(resolve => {
+				runtime.cancelRetry = timers.after(delayMs, () => {
+					runtime.cancelRetry = null;
+					resolve(true);
+				});
+				const cancel = runtime.cancelRetry;
+				// Cancellation replaces the handle, so a disable or dispose that
+				// clears it resolves this wait as "do not continue" rather than
+				// leaving a promise nobody will settle.
+				runtime.cancelRetry = () => {
+					cancel?.();
+					runtime.cancelRetry = null;
+					resolve(false);
+				};
+			});
+
+			if (!waited || disposed || !permitsRequests(enablement)) {
+				return result;
+			}
+
+			dispatchPlacement(key, { type: 'LOAD' });
+		}
+	}
+
+	/**
+	 * Applies a consent outcome to the gate without a second initialization.
+	 *
+	 * This is FR-105's "the app does not wire it by hand" in one function. When
+	 * consent opens the gate and the instance was blocked, it initializes — and
+	 * because `initialize` is idempotent and shares one in-flight operation, the
+	 * total native initialization count across a whole consent flow stays at one
+	 * (FR-022, SC-102). When consent closes the gate, requests stop and every
+	 * pending retry is cancelled with them (FR-137).
+	 */
+	async function reevaluateAfterConsent(): Promise<void> {
+		if (disposed || !currentPrivacy) {
+			return;
+		}
+		const decision = currentGate();
+		if (!decision.allowed) {
+			cancelAllRetries();
+			if (decision.kind === 'blocked' && init.status !== 'ready') {
+				setInit(initReducer(init, { type: 'BLOCK', reason: decision.reason }));
+			}
+			return;
+		}
+		if (init.status === 'ready' || init.status === 'initializing') {
+			return;
+		}
+		await instance.initialize(currentPrivacy);
+	}
+
 	const instance: AdsInstance = {
 		async initialize(privacy) {
 			if (disposed) {
@@ -539,16 +875,28 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			}
 			currentPrivacy = privacy;
 
-			if (!enabled) {
+			// Availability first, then enablement, then consent — the one order,
+			// evaluated in the one place (FR-140).
+			const decision = currentGate();
+			if (!decision.allowed && decision.kind === 'unavailable') {
+				setInit(initReducer(init, { type: 'UNAVAILABLE', reason: decision.reason }));
+				const result = { status: 'unavailable', reason: decision.reason } as const;
+				emitRefusal('initialize', result);
+				return result;
+			}
+			if (!decision.allowed && decision.kind === 'disabled') {
 				setInit(initReducer(init, { type: 'DISABLE' }));
 				const result = { status: 'disabled' } as const;
 				emitRefusal('initialize', result);
 				return result;
 			}
-
-			if (!engine.isAvailable()) {
-				setInit(initReducer(init, { type: 'UNAVAILABLE', reason: 'unsupported_platform' }));
-				const result = { status: 'unavailable', reason: 'unsupported_platform' } as const;
+			if (!decision.allowed && decision.kind === 'undecided') {
+				// FR-115. Nothing provider-facing happens, exactly as when
+				// disabled — but the status the app observes says `undecided`, so
+				// a banner host can hold its space instead of reclaiming it.
+				setInit(initReducer(init, { type: 'UNDECIDE' }));
+				armUndecidedWarning();
+				const result = { status: 'undecided' } as const;
 				emitRefusal('initialize', result);
 				return result;
 			}
@@ -582,7 +930,13 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 		},
 
 		async updatePrivacy(privacy) {
-			if (disposed || !enabled) {
+			if (disposed) {
+				return { status: 'disabled' };
+			}
+			if (enablement === 'undecided') {
+				return { status: 'undecided' };
+			}
+			if (enablement === 'disabled') {
 				return { status: 'disabled' };
 			}
 			if (!engine.isAvailable()) {
@@ -616,15 +970,27 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 		},
 
 		setEnabled(next) {
-			if (disposed || enabled === next) {
-				return;
+			return instance.setEnablement(next ? 'enabled' : 'disabled');
+		},
+
+		setEnablement(next) {
+			if (disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			if (enablement === next) {
+				return { status: 'unchanged' };
 			}
-			enabled = next;
-			if (!next) {
-				// FR-037: new work is prevented and in-flight resources released
-				// deterministically. An ad already on screen is left alone — the
-				// provider offers no safe way to close it, and yanking it would be
-				// worse than letting it finish.
+
+			const previous = enablement;
+			enablement = next;
+
+			if (next === 'disabled' || next === 'undecided') {
+				// FR-037 and FR-125: new work is prevented and in-flight resources
+				// released deterministically, and moving to `undecided` from
+				// `enabled` follows the same rules as disabling. An ad already on
+				// screen is left alone — the provider offers no safe way to close
+				// it, and yanking it would be worse than letting it finish.
+				cancelAllRetries();
 				for (const [key, runtime] of placements) {
 					if (runtime.snapshot.state === 'showing') {
 						continue;
@@ -632,10 +998,39 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 					releasePlacementResources(key);
 					dispatchPlacement(key, { type: 'RESET' });
 				}
-				setInit(initReducer(init, { type: 'DISABLE' }));
-			} else {
-				setInit(initReducer(init, { type: 'ENABLE' }));
+				setInit(initReducer(init, { type: next === 'disabled' ? 'DISABLE' : 'UNDECIDE' }));
+				if (next === 'undecided') {
+					armUndecidedWarning();
+					return { status: 'undecided' };
+				}
+				disarmUndecidedWarning();
+				return { status: 'disabled' };
+			}
+
+			// Turning ads on. This is the path 0.1.0 got wrong: it dropped the
+			// status to `not_started` and returned nothing, so an app whose user
+			// lost their entitlement turned ads back on and then had every load
+			// silently refused (FR-121).
+			disarmUndecidedWarning();
+			const resumable = canResume(init.resumeTo);
+			setInit(initReducer(init, { type: 'ENABLE' }));
+
+			if (init.status === 'unavailable') {
+				return { status: 'unavailable', reason: init.unavailableReason ?? 'unsupported_platform' };
+			}
+			if (resumable && init.status === 'ready') {
+				// The provider was never un-initialized, so there is genuinely
+				// nothing to redo — and FR-022 forbids initializing it twice.
+				return { status: 'resumed', initStatus: init.status };
+			}
+			if (previous === 'undecided' && init.status === 'ready') {
+				return { status: 'resumed', initStatus: init.status };
 			}
+			// Said out loud rather than left for the app to discover from a
+			// refused load. The package will not initialize implicitly: that would
+			// hide an asynchronous, billable operation behind a setter the caller
+			// may not be awaiting.
+			return { status: 'requires_initialization' };
 		},
 
 		setAppActive(active) {
@@ -644,17 +1039,25 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			}
 			appActive = active;
 			if (!active) {
+				// Arming happens when the provider reports an ad opened, not here:
+				// this event can be delivered late enough that the ad is already
+				// gone. All this adds is the browser case, where a background
+				// closely follows a click (FR-128).
+				adReturn.noteBackground(now());
 				return;
 			}
+			adReturn.noteForeground(now());
 			// FR-034: on return to the foreground, re-evaluate what was loaded.
 			// An ad that went stale while the app was away must stop reporting
 			// `ready` before the app offers a button that would fail on tap.
 			const current = now();
 			for (const [key, runtime] of placements) {
+				const definition = resolved.placements.get(key);
 				if (
 					runtime.snapshot.state === 'ready' &&
 					runtime.snapshot.loadedAtMs !== null &&
-					isStale(runtime.snapshot.loadedAtMs, current, resolved.timeouts.adValidity)
+					definition !== undefined &&
+					isStale(runtime.snapshot.loadedAtMs, current, validityFor(definition.format))
 				) {
 					releasePlacementResources(key);
 					dispatchPlacement(key, { type: 'EXPIRE' });
@@ -760,7 +1163,8 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			});
 
 			const adUnitId = resolved.catalog.byKey.get(placementKey)!;
-			const promise = loadFullScreen(placementKey, definition, adUnitId, correlationId);
+			runtime.retryAttempts = 0;
+			const promise = loadWithRetry(placementKey, definition, adUnitId, correlationId);
 			runtime.inFlightLoad = promise;
 			return promise;
 		},
@@ -805,6 +1209,16 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				return { status: 'app_inactive' };
 			}
 
+			// FR-128. Only app-open is refused: the user just came back from an ad
+			// or from a browser an ad opened, and app-open is the format that
+			// would fire on exactly that return. An interstitial at the same
+			// moment is the app's own deliberate choice, made somewhere the
+			// package cannot see, so refusing it would be policy rather than
+			// capability.
+			if (definition.format === 'app_open' && adReturn.isRefusing(now())) {
+				return { status: 'ad_originated_return' };
+			}
+
 			const runtime = placements.get(placementKey)!;
 
 			if (runtime.snapshot.state === 'consumed') {
@@ -815,7 +1229,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			if (
 				runtime.snapshot.state === 'ready' &&
 				runtime.snapshot.loadedAtMs !== null &&
-				isStale(runtime.snapshot.loadedAtMs, now(), resolved.timeouts.adValidity)
+				isStale(runtime.snapshot.loadedAtMs, now(), validityFor(definition.format))
 			) {
 				releasePlacementResources(placementKey);
 				dispatchPlacement(placementKey, { type: 'EXPIRE' });
@@ -903,9 +1317,15 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			if (!resolved.placements.has(placementKey)) {
 				return 'unavailable';
 			}
-			if (!enabled || !engine.isAvailable()) {
+			if (!engine.isAvailable() || enablement === 'disabled') {
 				return 'unavailable';
 			}
+			// Reported distinctly from `unavailable` so the app can choose to hold
+			// the banner's space rather than reclaim it. That choice is the entire
+			// reason the third state is worth having (FR-116).
+			if (enablement === 'undecided') {
+				return 'undecided';
+			}
 			return placements.get(placementKey)?.snapshot.state ?? 'idle';
 		},
 
@@ -933,6 +1353,105 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			return resolved.catalog.substitutedKeys;
 		},
 
+		getIgnoredConsentTools() {
+			return resolved.ignoredConsentTools;
+		},
+
+		consent: {
+			async requestInfoUpdate() {
+				if (disposed) {
+					return consent;
+				}
+				// Marks the flow as in use. Until this is called the gate sees no
+				// consent input at all, which is how an app that supplies its own
+				// gate keeps 0.1.0 behavior without opting out of anything
+				// (FR-102).
+				consentStarted = true;
+				if (resolved.consentTesting?.resetOnStart) {
+					try {
+						engine.consent.reset();
+					} catch {
+						// A reset that fails must not abort the update; the flow
+						// continues against whatever state is stored.
+					}
+				}
+				const next = await runConsentStep(
+					() =>
+						engine.consent.requestInfoUpdate(
+							buildConsentOptions(
+								resolved.consentTesting,
+								currentPrivacy?.underAgeOfConsent,
+								resolved.testDeviceIds,
+							),
+						),
+					'consent information update failed',
+				);
+				if (disposed) {
+					return consent;
+				}
+				setConsent(next);
+				await reevaluateAfterConsent();
+				return next;
+			},
+
+			async showFormIfRequired() {
+				if (disposed) {
+					return consent;
+				}
+				consentStarted = true;
+				if (!needsForm(consent)) {
+					// Nothing to present. Not an error: a region that does not
+					// require consent is the normal case, and showing a form there
+					// is exactly what FR-107 forbids the package from deciding.
+					return consent;
+				}
+				const next = await runConsentStep(
+					() => engine.consent.showFormIfRequired(),
+					'consent form failed',
+				);
+				if (disposed) {
+					return consent;
+				}
+				setConsent(next);
+				await reevaluateAfterConsent();
+				return next;
+			},
+
+			getState() {
+				return consent;
+			},
+
+			subscribe(listener) {
+				consentListeners.add(listener);
+				let active = true;
+				return () => {
+					if (!active) {
+						return;
+					}
+					active = false;
+					consentListeners.delete(listener);
+				};
+			},
+
+			async reset() {
+				if (disposed) {
+					return;
+				}
+				// Config validation already stripped the testing tools in
+				// production, so this is inert there without a check here (FR-113).
+				if (!resolved.consentTesting) {
+					return;
+				}
+				try {
+					engine.consent.reset();
+				} catch {
+					// Nothing to report: the stored state is the provider's, and a
+					// failed reset leaves it as it was.
+				}
+				setConsent(INITIAL_CONSENT);
+			},
+		},
+
 		internals: {
 			resolveBanner(placementKey) {
 				const definition = resolved.placements.get(placementKey);
@@ -986,7 +1505,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				}
 			},
 			isReady() {
-				return enabled && engine.isAvailable() && canRequest(init.status);
+				return permitsRequests(enablement) && engine.isAvailable() && canRequest(init.status);
 			},
 			nextCorrelationId() {
 				return correlation.next();
@@ -1002,13 +1521,17 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				return;
 			}
 			disposed = true;
+			cancelAllRetries();
+			disarmUndecidedWarning();
 			for (const key of placements.keys()) {
 				releasePlacementResources(key);
 				placements.get(key)?.listeners.clear();
 			}
 			timers.clearAll();
 			lock.reset();
+			adReturn.reset();
 			statusListeners.clear();
+			consentListeners.clear();
 			events.dispose();
 			inFlightInit = null;
 		},