@chipmobilesdk/rn-ads 0.2.1 → 0.4.0

package/src/core/adsInstance.ts

@@ -1,1554 +1,1890 @@
-/**
- * The ads instance — the public contract's implementation.
- *
- * Every guarantee the specification treats as a rule rather than a convention
- * converges here, and none of it needs a device to prove:
- *
- *   FR-022  one native initialization, however many callers race
- *   FR-017  no request before the privacy gate permits one
- *   FR-011  no production ad unit outside production
- *   FR-029  one in-flight provider request per placement
- *   FR-030  exactly one full-screen ad, never a queue
- *   FR-031  a consumed ad is never reused
- *   FR-035  after dispose, a late callback updates nothing and emits nothing
- *
- * Nothing in this file imports the provider. It talks to the engine port, which
- * the caller injects — the AdMob adapter in production, the fake in tests.
- */
-
-import {
-	isFullScreenFormat,
-	type AdFormat,
-	type AdsConfig,
-	type ConsentSnapshot,
-	type Enablement,
-	type FullScreenFormat,
-	type InitStatus,
-	type PlacementDefinition,
-	type PlacementState,
-	type PrivacyBlockReason,
-	type PrivacyOptions,
-	type UnavailableReason,
-	type Unsubscribe,
-} from '../config/types';
-import { validateConfig, type ResolvedConfig } from '../config/validate';
-import { AdsError, normalizeProviderError } from '../diagnostics/errors';
-import {
-	createEventEmitter,
-	type AdEvent,
-	type AdEventListener,
-	type ImpressionSource,
-} from '../diagnostics/events';
-import { createCorrelationIssuer } from '../diagnostics/correlation';
-import type { AdsEngine, EngineAdEvent, EngineAdHandle } from '../engine/port';
-import { createFullScreenLock } from './fullScreenLock';
-import { canRequest, canStart, initialInit, initReducer, type InitSnapshot } from './initMachine';
-import {
-	canLoad,
-	initialPlacement,
-	placementReducer,
-	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, 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 };
-
-export type PrivacyUpdateResult =
-	| { readonly status: 'applied' }
-	| { 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' }
-	| { readonly status: 'timeout' }
-	| { readonly status: 'failed'; readonly error: AdsError };
-
-export type ShowResult =
-	| { readonly status: 'shown'; readonly correlationId: string }
-	| { readonly status: 'not_ready' }
-	| { 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>;
-	/**
-	 * 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;
-
-	load(placementKey: string): Promise<LoadResult>;
-	show(placementKey: string): Promise<ShowResult>;
-	getPlacementState(placementKey: string): PlacementState;
-	subscribePlacement(key: string, listener: (state: PlacementState) => void): Unsubscribe;
-
-	subscribeEvents(listener: AdEventListener): Unsubscribe;
-
-	/** 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;
-
-	dispose(): void;
-}
-
-/** What `AdsBanner` needs. Deliberately not documented as consumer API. */
-export interface InstanceInternals {
-	resolveBanner(placementKey: string):
-		| { readonly ok: true; readonly adUnitId: string; readonly correlationId: string }
-		| { readonly ok: false; readonly result: LoadResult };
-	emit(event: AdEvent): void;
-	setPlacementState(key: string, state: PlacementState): void;
-	isReady(): boolean;
-	nextCorrelationId(): string;
-	timerCount(): number;
-}
-
-export interface CreateAdsOptions {
-	/** Injected in tests; the AdMob adapter is the default in production. */
-	readonly engine?: AdsEngine;
-	/** 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 {
-	snapshot: PlacementSnapshot;
-	/**
-	 * The cycle's correlation id, held here rather than read from the snapshot:
-	 * the reducer resets the snapshot on dismissal, and events emitted around
-	 * that transition must still carry the id of the cycle they belong to.
-	 */
-	correlationId: string | null;
-	/**
-	 * Whether this cycle already reported a dismissal. Format-independent — the
-	 * rewarded session guards its own, but interstitials need the same guard and
-	 * would otherwise report a repeated provider callback twice.
-	 */
-	dismissed: boolean;
-	handle: EngineAdHandle | null;
-	unsubscribeEngine: Unsubscribe | null;
-	inFlightLoad: Promise<LoadResult> | null;
-	cancelLoadTimer: Unsubscribe | null;
-	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 {
-	return typeof __DEV__ !== 'undefined' ? Boolean(__DEV__) : false;
-}
-
-export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): AdsInstance {
-	const isDevBuild = options.isDevBuild ?? detectDevBuild();
-	const now = options.now ?? (() => Date.now());
-
-	// Throws on a structural fault or the FR-012 fail-closed case. Deliberately
-	// before anything else: a misconfigured instance should not exist at all.
-	const resolved: ResolvedConfig = validateConfig(config, { isDevBuild });
-
-	const engine: AdsEngine = options.engine ?? createDefaultEngine();
-	const events = createEventEmitter();
-	const correlation = createCorrelationIssuer();
-	const timers = createTimerSet(options.scheduler);
-	const lock = createFullScreenLock();
-	const adReturn = createAdOriginatedTracker();
-
-	/**
-	 * 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;
-	let disposed = false;
-	let warnedSubstitution = false;
-
-	const statusListeners = new Set<(status: InitStatus) => void>();
-	const placements = new Map<string, PlacementRuntime>();
-
-	for (const key of resolved.placements.keys()) {
-		placements.set(key, {
-			snapshot: initialPlacement,
-			correlationId: null,
-			dismissed: false,
-			handle: null,
-			unsubscribeEngine: null,
-			inFlightLoad: null,
-			cancelLoadTimer: null,
-			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;
-			return;
-		}
-		init = next;
-		events.emit({
-			type: 'initialization',
-			timestamp: now(),
-			status: next.status,
-			retryable: next.error?.retryable,
-		});
-		for (const listener of Array.from(statusListeners)) {
-			try {
-				listener(next.status);
-			} catch {
-				// A status listener is consumer code; its failure is isolated the
-				// same way an event listener's is (FR-056).
-			}
-		}
-	}
-
-	function setPlacement(key: string, next: PlacementSnapshot): void {
-		const runtime = placements.get(key);
-		if (!runtime || runtime.snapshot.state === next.state) {
-			if (runtime) {
-				runtime.snapshot = next;
-			}
-			return;
-		}
-		runtime.snapshot = next;
-		for (const listener of Array.from(runtime.listeners)) {
-			try {
-				listener(next.state);
-			} catch {
-				// Isolated, as above.
-			}
-		}
-	}
-
-	function dispatchPlacement(key: string, event: Parameters<typeof placementReducer>[1]): void {
-		const runtime = placements.get(key);
-		const definition = resolved.placements.get(key);
-		if (!runtime || !definition) {
-			return;
-		}
-		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' | 'undecided' | 'blocked' | 'unavailable' }
-				>;
-		  } {
-		const decision = currentGate();
-		if (decision.allowed) {
-			return { ok: true };
-		}
-		return { ok: false, result: refusalFor(decision) };
-	}
-
-	function emitRefusal(
-		operation: 'initialize' | 'load' | 'show',
-		result: { readonly status: string; readonly reason?: string },
-		placementKey?: string,
-		format?: AdFormat,
-	): void {
-		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({
-				type: 'unavailable',
-				timestamp: now(),
-				operation,
-				placementKey,
-				format,
-				reason: (result.reason ?? 'unsupported_platform') as UnavailableReason | PrivacyBlockReason,
-			});
-		}
-	}
-
-	function warnSubstitutionOnce(): void {
-		if (warnedSubstitution || resolved.catalog.substitutedKeys.length === 0) {
-			return;
-		}
-		warnedSubstitution = true;
-		events.emit({
-			type: 'config_warning',
-			timestamp: now(),
-			warning: 'test_ad_unit_substituted',
-			placementKeys: resolved.catalog.substitutedKeys,
-		});
-	}
-
-	function releasePlacementResources(key: string): void {
-		const runtime = placements.get(key);
-		if (!runtime) {
-			return;
-		}
-		runtime.cancelLoadTimer?.();
-		runtime.cancelLoadTimer = null;
-		runtime.cancelShowTimer?.();
-		runtime.cancelShowTimer = null;
-		runtime.unsubscribeEngine?.();
-		runtime.unsubscribeEngine = null;
-		if (runtime.handle) {
-			engine.dispose(runtime.handle);
-			runtime.handle = null;
-		}
-		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> {
-		const enginePrivacy = toEnginePrivacy(privacy, resolved.testDeviceIds);
-		try {
-			// The adapter applies privacy configuration before initializing the
-			// provider; that ordering is the whole reason FR-017 is enforceable.
-			await engine.initialize(enginePrivacy);
-			appliedPrivacy = privacy;
-			setInit(initReducer(init, { type: 'SUCCEED' }));
-			warnSubstitutionOnce();
-			return { status: 'ready' };
-		} catch (error) {
-			const normalized = normalizeProviderError(error, { operation: 'initialize' });
-			setInit(initReducer(init, { type: 'FAIL', error: normalized }));
-			return { status: 'failed', error: normalized };
-		} finally {
-			inFlightInit = null;
-		}
-	}
-
-	function handleEngineEvent(
-		key: string,
-		definition: PlacementDefinition,
-		event: EngineAdEvent,
-	): void {
-		// After dispose nothing is honored: a late provider callback must not
-		// update a consumer that has gone away (FR-035, SC-008).
-		if (disposed) {
-			return;
-		}
-		const runtime = placements.get(key);
-		if (!runtime) {
-			return;
-		}
-		const correlationId = runtime.correlationId ?? undefined;
-		const base = { timestamp: now(), placementKey: key, format: definition.format, correlationId };
-
-		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
-				// honestly rather than passed off as the provider's own.
-				events.emit({ ...base, type: 'impression', source: 'derived' as ImpressionSource });
-				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': {
-				const first = runtime.rewarded?.confirmReward(event.reward) ?? null;
-				if (first) {
-					events.emit({ ...base, type: 'reward_earned', reward: first });
-				}
-				break;
-			}
-			case 'dismissed': {
-				const rewardedFirst = runtime.rewarded ? runtime.rewarded.dismiss() : true;
-				if (runtime.dismissed || !rewardedFirst) {
-					break;
-				}
-				runtime.dismissed = true;
-				lock.release(key);
-				runtime.cancelShowTimer?.();
-				runtime.cancelShowTimer = null;
-				events.emit({
-					...base,
-					type: 'dismissed',
-					rewardEarned: runtime.rewarded ? runtime.rewarded.rewardEarned : undefined,
-				});
-				dispatchPlacement(key, { type: 'DISMISSED' });
-				// Deliberately NOT released here. FR-049 requires the reward and
-				// the dismissal to be handled in either order, and a provider that
-				// confirms the reward *after* closing the ad would otherwise have
-				// its confirmation dropped by a torn-down listener — silently
-				// costing the user a reward they earned.
-				//
-				// This is a retained resource, not a leak: at most one handle and
-				// one listener per placement, released deterministically by the
-				// next load of that placement or by dispose().
-				break;
-			}
-			case 'failed': {
-				const normalized = normalizeProviderError(event.cause, {
-					operation: 'show',
-					placementKey: key,
-					format: definition.format,
-				});
-				lock.release(key);
-				events.emit({ ...base, type: 'display_failed', error: normalized });
-				dispatchPlacement(key, { type: 'SHOW_FAILED', error: normalized });
-				releasePlacementResources(key);
-				break;
-			}
-			default:
-				break;
-		}
-	}
-
-	function loadFullScreen(
-		key: string,
-		definition: PlacementDefinition,
-		adUnitId: string,
-		correlationId: string,
-	): Promise<LoadResult> {
-		const runtime = placements.get(key)!;
-		const format = definition.format as FullScreenFormat;
-		const startedAt = now();
-
-		return new Promise<LoadResult>(resolve => {
-			let settled = false;
-
-			const finish = (result: LoadResult) => {
-				if (settled) {
-					return;
-				}
-				settled = true;
-				runtime.cancelLoadTimer?.();
-				runtime.cancelLoadTimer = null;
-				runtime.inFlightLoad = null;
-				resolve(result);
-			};
-
-			runtime.cancelLoadTimer = timers.after(resolved.timeouts.load, () => {
-				const error = new AdsError('load_timeout', {
-					operation: 'load',
-					placementKey: key,
-					format,
-					message: `load timed out after ${resolved.timeouts.load}ms`,
-				});
-				events.emit({
-					type: 'load_failed',
-					timestamp: now(),
-					placementKey: key,
-					format,
-					correlationId,
-					error,
-				});
-				dispatchPlacement(key, { type: 'LOAD_FAILED', error });
-				releasePlacementResources(key);
-				finish({ status: 'timeout' });
-			});
-
-			engine
-				.createFullScreen(format, adUnitId)
-				.then(handle => {
-					if (disposed || settled) {
-						engine.dispose(handle);
-						return;
-					}
-					runtime.handle = handle;
-					runtime.unsubscribeEngine = engine.subscribe(handle, event => {
-						if (event.type === 'loaded') {
-							dispatchPlacement(key, { type: 'LOADED', atMs: now() });
-							events.emit({
-								type: 'loaded',
-								timestamp: now(),
-								placementKey: key,
-								format,
-								correlationId,
-								durationMs: now() - startedAt,
-							});
-							finish({ status: 'loaded', correlationId });
-							return;
-						}
-						if (event.type === 'failed') {
-							const normalized = normalizeProviderError(event.cause, {
-								operation: 'load',
-								placementKey: key,
-								format,
-							});
-							events.emit({
-								type: 'load_failed',
-								timestamp: now(),
-								placementKey: key,
-								format,
-								correlationId,
-								error: normalized,
-							});
-							dispatchPlacement(key, { type: 'LOAD_FAILED', error: normalized });
-							releasePlacementResources(key);
-							finish(
-								normalized.code === 'no_fill'
-									? { status: 'no_fill' }
-									: { status: 'failed', error: normalized },
-							);
-							return;
-						}
-						handleEngineEvent(key, definition, event);
-					});
-				})
-				.catch(error => {
-					const normalized = normalizeProviderError(error, {
-						operation: 'load',
-						placementKey: key,
-						format,
-					});
-					events.emit({
-						type: 'load_failed',
-						timestamp: now(),
-						placementKey: key,
-						format,
-						correlationId,
-						error: normalized,
-					});
-					dispatchPlacement(key, { type: 'LOAD_FAILED', error: normalized });
-					finish(
-						normalized.code === 'no_fill'
-							? { status: 'no_fill' }
-							: { status: 'failed', error: normalized },
-					);
-				});
-		});
-	}
-
-	/**
-	 * 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) {
-				return { status: 'unavailable', reason: 'provider_missing' };
-			}
-			currentPrivacy = privacy;
-
-			// 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 (!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;
-			}
-
-			const gate = evaluateGate(privacy);
-			if (!gate.allowed) {
-				// FR-017. Nothing provider-facing happens here at all — not a
-				// configuration call, not an initialization. The engine is untouched.
-				setInit(initReducer(init, { type: 'BLOCK', reason: gate.reason }));
-				const result = { status: 'blocked', reason: gate.reason } as const;
-				emitRefusal('initialize', result);
-				return result;
-			}
-
-			if (init.status === 'ready') {
-				return { status: 'ready' };
-			}
-
-			// FR-022, SC-005. Racing callers share one operation, so the provider
-			// initializes exactly once however many arrive.
-			if (inFlightInit) {
-				return inFlightInit;
-			}
-			if (!canStart(init.status)) {
-				return { status: 'ready' };
-			}
-
-			setInit(initReducer(init, { type: 'START' }));
-			inFlightInit = doInitialize(privacy);
-			return inFlightInit;
-		},
-
-		async updatePrivacy(privacy) {
-			if (disposed) {
-				return { status: 'disabled' };
-			}
-			if (enablement === 'undecided') {
-				return { status: 'undecided' };
-			}
-			if (enablement === 'disabled') {
-				return { status: 'disabled' };
-			}
-			if (!engine.isAvailable()) {
-				return { status: 'unavailable', reason: 'unsupported_platform' };
-			}
-
-			// FR-020: a flag the provider only honors at initialization cannot be
-			// applied now. Say so, rather than accepting it and running half-old.
-			if (requiresReinitialization(appliedPrivacy, privacy)) {
-				return { status: 'requires_reinitialization' };
-			}
-
-			currentPrivacy = privacy;
-			const gate = evaluateGate(privacy);
-			if (!gate.allowed) {
-				setInit(initReducer(init, { type: 'BLOCK', reason: gate.reason }));
-				return { status: 'blocked', reason: gate.reason };
-			}
-
-			// FR-019: resolving consent after a block must not produce a second
-			// native initialization.
-			if (init.status === 'ready') {
-				return { status: 'applied' };
-			}
-			const result = await instance.initialize(privacy);
-			return result.status === 'ready'
-				? { status: 'applied' }
-				: result.status === 'blocked'
-					? { status: 'blocked', reason: result.reason }
-					: { status: 'applied' };
-		},
-
-		setEnabled(next) {
-			return instance.setEnablement(next ? 'enabled' : 'disabled');
-		},
-
-		setEnablement(next) {
-			if (disposed) {
-				return { status: 'unavailable', reason: 'provider_missing' };
-			}
-			if (enablement === next) {
-				return { status: 'unchanged' };
-			}
-
-			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;
-					}
-					releasePlacementResources(key);
-					dispatchPlacement(key, { type: 'RESET' });
-				}
-				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) {
-			if (disposed) {
-				return;
-			}
-			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 &&
-					definition !== undefined &&
-					isStale(runtime.snapshot.loadedAtMs, current, validityFor(definition.format))
-				) {
-					releasePlacementResources(key);
-					dispatchPlacement(key, { type: 'EXPIRE' });
-				}
-			}
-		},
-
-		getStatus() {
-			return init.status;
-		},
-
-		subscribeStatus(listener) {
-			statusListeners.add(listener);
-			let active = true;
-			return () => {
-				if (!active) {
-					return;
-				}
-				active = false;
-				statusListeners.delete(listener);
-			};
-		},
-
-		async load(placementKey) {
-			if (disposed) {
-				return { status: 'unavailable', reason: 'provider_missing' };
-			}
-
-			const definition = resolved.placements.get(placementKey);
-			if (!definition) {
-				return {
-					status: 'failed',
-					error: new AdsError('placement_not_found', {
-						operation: 'load',
-						placementKey,
-						message: `unknown placement "${placementKey}"; configured keys are ${[...resolved.placements.keys()].join(', ')}`,
-					}),
-				};
-			}
-
-			const gate = gateCheck();
-			if (!gate.ok) {
-				emitRefusal('load', gate.result, placementKey, definition.format);
-				return gate.result;
-			}
-
-			if (!canRequest(init.status)) {
-				return {
-					status: 'failed',
-					error: new AdsError('not_ready', {
-						operation: 'load',
-						placementKey,
-						format: definition.format,
-						message: 'initialize() must complete before loading',
-					}),
-				};
-			}
-
-			if (definition.format === 'banner') {
-				return {
-					status: 'failed',
-					error: new AdsError('format_mismatch', {
-						operation: 'load',
-						placementKey,
-						format: definition.format,
-						message: `"${placementKey}" is a banner; banners render through <AdsBanner> rather than load()`,
-					}),
-				};
-			}
-
-			const runtime = placements.get(placementKey)!;
-
-			// FR-029, SC-002's sibling guarantee: a repeat load while one is in
-			// flight joins it instead of creating a second provider request.
-			if (runtime.inFlightLoad) {
-				return runtime.inFlightLoad;
-			}
-
-			if (runtime.snapshot.state === 'showing') {
-				return { status: 'failed', error: new AdsError('busy', { operation: 'load', placementKey }) };
-			}
-
-			if (!canLoad(runtime.snapshot.state)) {
-				return {
-					status: 'failed',
-					error: new AdsError('not_ready', { operation: 'load', placementKey }),
-				};
-			}
-
-			releasePlacementResources(placementKey);
-
-			const correlationId = correlation.next();
-			runtime.correlationId = correlationId;
-			runtime.dismissed = false;
-			dispatchPlacement(placementKey, { type: 'LOAD' });
-			setPlacement(placementKey, { ...runtime.snapshot, correlationId });
-			events.emit({
-				type: 'load_started',
-				timestamp: now(),
-				placementKey,
-				format: definition.format,
-				correlationId,
-			});
-
-			const adUnitId = resolved.catalog.byKey.get(placementKey)!;
-			runtime.retryAttempts = 0;
-			const promise = loadWithRetry(placementKey, definition, adUnitId, correlationId);
-			runtime.inFlightLoad = promise;
-			return promise;
-		},
-
-		async show(placementKey) {
-			if (disposed) {
-				return { status: 'unavailable', reason: 'provider_missing' };
-			}
-
-			const definition = resolved.placements.get(placementKey);
-			if (!definition) {
-				return {
-					status: 'failed',
-					error: new AdsError('placement_not_found', {
-						operation: 'show',
-						placementKey,
-						message: `unknown placement "${placementKey}"; configured keys are ${[...resolved.placements.keys()].join(', ')}`,
-					}),
-				};
-			}
-
-			if (!isFullScreenFormat(definition.format)) {
-				return {
-					status: 'failed',
-					error: new AdsError('format_mismatch', {
-						operation: 'show',
-						placementKey,
-						format: definition.format,
-						message: `"${placementKey}" is a banner; banners are rendered, not shown`,
-					}),
-				};
-			}
-
-			const gate = gateCheck();
-			if (!gate.ok) {
-				emitRefusal('show', gate.result, placementKey, definition.format);
-				return gate.result;
-			}
-
-			// FR-028: never open an ad while the app is not in front of the user.
-			if (!appActive) {
-				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') {
-				return { status: 'consumed' };
-			}
-
-			// FR-034: a stale ad is not shown and is not reported ready.
-			if (
-				runtime.snapshot.state === 'ready' &&
-				runtime.snapshot.loadedAtMs !== null &&
-				isStale(runtime.snapshot.loadedAtMs, now(), validityFor(definition.format))
-			) {
-				releasePlacementResources(placementKey);
-				dispatchPlacement(placementKey, { type: 'EXPIRE' });
-				return { status: 'not_ready' };
-			}
-
-			if (runtime.snapshot.state !== 'ready' || !runtime.handle) {
-				return { status: 'not_ready' };
-			}
-
-			// FR-030. Acquired before anything else can open a screen, and never
-			// queued: a refused show is refused now, not deferred to a moment the
-			// app never chose.
-			if (!lock.acquire(placementKey)) {
-				return { status: 'busy' };
-			}
-
-			const correlationId = runtime.correlationId ?? correlation.next();
-			runtime.rewarded = definition.format === 'rewarded' ? createRewardedSession() : null;
-			dispatchPlacement(placementKey, { type: 'SHOW' });
-
-			let settled = false;
-			const showTimeout = new Promise<ShowResult>(resolve => {
-				runtime.cancelShowTimer = timers.after(resolved.timeouts.show, () => {
-					if (settled) {
-						return;
-					}
-					settled = true;
-					const error = new AdsError('show_timeout', {
-						operation: 'show',
-						placementKey,
-						format: definition.format,
-						message: `show timed out after ${resolved.timeouts.show}ms`,
-					});
-					lock.release(placementKey);
-					events.emit({
-						type: 'display_failed',
-						timestamp: now(),
-						placementKey,
-						format: definition.format,
-						correlationId,
-						error,
-					});
-					dispatchPlacement(placementKey, { type: 'SHOW_FAILED', error });
-					releasePlacementResources(placementKey);
-					resolve({ status: 'timeout' });
-				});
-			});
-
-			const attempt = engine
-				.show(runtime.handle)
-				.then<ShowResult>(() => {
-					settled = true;
-					runtime.cancelShowTimer?.();
-					runtime.cancelShowTimer = null;
-					return { status: 'shown', correlationId };
-				})
-				.catch<ShowResult>(error => {
-					settled = true;
-					runtime.cancelShowTimer?.();
-					runtime.cancelShowTimer = null;
-					const normalized = normalizeProviderError(error, {
-						operation: 'show',
-						placementKey,
-						format: definition.format,
-					});
-					lock.release(placementKey);
-					events.emit({
-						type: 'display_failed',
-						timestamp: now(),
-						placementKey,
-						format: definition.format,
-						correlationId,
-						error: normalized,
-					});
-					dispatchPlacement(placementKey, { type: 'SHOW_FAILED', error: normalized });
-					releasePlacementResources(placementKey);
-					return { status: 'failed', error: normalized };
-				});
-
-			return Promise.race([attempt, showTimeout]);
-		},
-
-		getPlacementState(placementKey) {
-			if (!resolved.placements.has(placementKey)) {
-				return 'unavailable';
-			}
-			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';
-		},
-
-		subscribePlacement(key, listener) {
-			const runtime = placements.get(key);
-			if (!runtime) {
-				return () => undefined;
-			}
-			runtime.listeners.add(listener);
-			let active = true;
-			return () => {
-				if (!active) {
-					return;
-				}
-				active = false;
-				runtime.listeners.delete(listener);
-			};
-		},
-
-		subscribeEvents(listener) {
-			return events.subscribe(listener);
-		},
-
-		getSubstitutedPlacements() {
-			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);
-				if (!definition) {
-					return {
-						ok: false,
-						result: {
-							status: 'failed',
-							error: new AdsError('placement_not_found', {
-								operation: 'load',
-								placementKey,
-								message: `unknown placement "${placementKey}"`,
-							}),
-						},
-					};
-				}
-				if (definition.format !== 'banner') {
-					return {
-						ok: false,
-						result: {
-							status: 'failed',
-							error: new AdsError('format_mismatch', {
-								operation: 'load',
-								placementKey,
-								format: definition.format,
-								message: `"${placementKey}" is not a banner placement`,
-							}),
-						},
-					};
-				}
-				const gate = gateCheck();
-				if (!gate.ok) {
-					return { ok: false, result: gate.result };
-				}
-				if (!canRequest(init.status)) {
-					return { ok: false, result: { status: 'blocked', reason: 'consent_required' } };
-				}
-				return {
-					ok: true,
-					adUnitId: resolved.catalog.byKey.get(placementKey)!,
-					correlationId: correlation.next(),
-				};
-			},
-			emit(event) {
-				events.emit(event);
-			},
-			setPlacementState(key, state) {
-				const runtime = placements.get(key);
-				if (runtime) {
-					setPlacement(key, { ...runtime.snapshot, state });
-				}
-			},
-			isReady() {
-				return permitsRequests(enablement) && engine.isAvailable() && canRequest(init.status);
-			},
-			nextCorrelationId() {
-				return correlation.next();
-			},
-			timerCount() {
-				return timers.size();
-			},
-		},
-
-		dispose() {
-			// FR-005: idempotent. A second call is a no-op, not an error.
-			if (disposed) {
-				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;
-		},
-	};
-
-	return instance;
-}
-
-/**
- * Resolved lazily so importing the package on a platform with no adapter — or
- * with the bridge absent — costs nothing and crashes nothing (FR-025, SC-004).
- */
-function createDefaultEngine(): AdsEngine {
-	// Deferred require keeps the provider off the import graph of every module
-	// that merely mentions `createAds`.
-	const { createAdMobEngine } = require('../engine/admobEngine') as typeof import('../engine/admobEngine');
-	return createAdMobEngine();
-}
-
-declare const __DEV__: boolean | undefined;
+/**
+ * The ads instance — the public contract's implementation.
+ *
+ * Every guarantee the specification treats as a rule rather than a convention
+ * converges here, and none of it needs a device to prove:
+ *
+ *   FR-022  one native initialization, however many callers race
+ *   FR-017  no request before the privacy gate permits one
+ *   FR-011  no production ad unit outside production
+ *   FR-029  one in-flight provider request per placement
+ *   FR-030  exactly one full-screen ad, never a queue
+ *   FR-031  a consumed ad is never reused
+ *   FR-035  after dispose, a late callback updates nothing and emits nothing
+ *
+ * Nothing in this file imports the provider. It talks to the engine port, which
+ * the caller injects — the AdMob adapter in production, the fake in tests.
+ */
+
+import {
+	isFullScreenFormat,
+	type AdFormat,
+	type AdsConfig,
+	type ConsentSnapshot,
+	type Enablement,
+	type FullScreenFormat,
+	type InitStatus,
+	type PlacementDefinition,
+	type PlacementState,
+	type PrivacyBlockReason,
+	type PrivacyOptions,
+	type UnavailableReason,
+	type Unsubscribe,
+} from '../config/types';
+import { validateConfig, type ResolvedConfig } from '../config/validate';
+import { AdsError, normalizeProviderError } from '../diagnostics/errors';
+import {
+	createEventEmitter,
+	type AdEvent,
+	type AdEventListener,
+	type ImpressionSource,
+} from '../diagnostics/events';
+import { createRequestThrottle } from './requestThrottle';
+import { createCorrelationIssuer } from '../diagnostics/correlation';
+import type { AdsEngine, EngineAdEvent, EngineAdHandle } from '../engine/port';
+import { createFullScreenLock } from './fullScreenLock';
+import { canRequest, canStart, initialInit, initReducer, type InitSnapshot } from './initMachine';
+import {
+	canLoad,
+	initialPlacement,
+	placementReducer,
+	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, 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,
+	normalizeConsent,
+	runConsentStep,
+	toConsentError,
+	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 };
+
+export type PrivacyUpdateResult =
+	| { readonly status: 'applied' }
+	| { 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' }
+	/**
+	 * Refused by the per-placement request throttle (FR-140), added in 0.3.0.
+	 *
+	 * Nothing was requested and nothing is broken — this placement asked too
+	 * recently. Distinct from `no_fill` on purpose: no-fill means the network had
+	 * nothing to give, this means we did not ask. An app that treats them the same
+	 * will misdiagnose the first time a banner goes quiet.
+	 */
+	| ThrottledResult
+	| { readonly status: 'timeout' }
+	| { readonly status: 'failed'; readonly error: AdsError };
+
+export interface ThrottledResult {
+	readonly status: 'throttled';
+	readonly retryAfterMs: number;
+}
+
+/** A gate refusal: what a load gets when it may not ask at all. */
+type LoadRefusal = Extract<
+	LoadResult,
+	{ status: 'disabled' | 'undecided' | 'blocked' | 'unavailable' }
+>;
+
+export type ShowResult =
+	| { readonly status: 'shown'; readonly correlationId: string }
+	| { readonly status: 'not_ready' }
+	| { 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 };
+
+/**
+ * What `consent.showPrivacyOptionsForm()` reports (FR-151), added in 0.4.0.
+ *
+ * Every refusal is its own member, so an app can tell "there is nothing to
+ * offer here" from "you asked too early" from "it broke" without parsing an
+ * error. None of them throws.
+ */
+export type PrivacyOptionsFormResult =
+	/**
+	 * The provider's form was presented and has closed. `consent` is the state it
+	 * left behind, already applied to the gate. A user who closed the form without
+	 * changing anything lands here too, with the state they already had.
+	 */
+	| { readonly status: 'shown'; readonly consent: ConsentSnapshot }
+	/** The provider does not require privacy options here. Nothing was presented. */
+	| { readonly status: 'not_required' }
+	/**
+	 * The requirement is not known yet: no successful `requestInfoUpdate()` since
+	 * the instance was created or reset, or the last one failed. Nothing was
+	 * presented.
+	 */
+	| { readonly status: 'info_update_required' }
+	/** A consent form is already on screen. Nothing was presented. */
+	| { readonly status: 'busy' }
+	/**
+	 * The form could not be presented or failed while open. The consent state is
+	 * whatever the provider reports it still holds, and never a new grant.
+	 */
+	| { readonly status: 'failed'; readonly error: AdsError }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason };
+
+/**
+ * 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>;
+	/**
+	 * Presents the provider's privacy options form, so a user can change an
+	 * answer already given (FR-151). Added in 0.4.0.
+	 *
+	 * Offer it when `getState().privacyOptionsRequirement` is `required`. Where
+	 * the entry point lives, and what it says, stay the app's. The outcome feeds
+	 * the privacy gate by itself, exactly as `showFormIfRequired` does.
+	 */
+	showPrivacyOptionsForm(): Promise<PrivacyOptionsFormResult>;
+	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>;
+	/**
+	 * 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;
+
+	load(placementKey: string): Promise<LoadResult>;
+	show(placementKey: string): Promise<ShowResult>;
+	getPlacementState(placementKey: string): PlacementState;
+	subscribePlacement(key: string, listener: (state: PlacementState) => void): Unsubscribe;
+
+	subscribeEvents(listener: AdEventListener): Unsubscribe;
+
+	/** 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;
+
+	dispose(): void;
+}
+
+/** What `AdsBanner` needs. Deliberately not documented as consumer API. */
+export interface InstanceInternals {
+	resolveBanner(placementKey: string):
+		| { readonly ok: true; readonly adUnitId: string; readonly correlationId: string }
+		| { readonly ok: false; readonly result: LoadResult };
+	/**
+	 * Takes the throttle slot for a banner cycle (FR-140).
+	 *
+	 * Called from the banner host's effect, after `resolveBanner` allowed it and
+	 * immediately before the provider component mounts. Idempotent for one
+	 * `correlationId`, so React running the effect twice charges one slot.
+	 *
+	 * Returns the refusal if the window closed between resolve and commit — rare,
+	 * but a second banner for the same placement mounting in the same tick would
+	 * do it.
+	 *
+	 * Emits nothing and sets no state: it is called during render, so the host
+	 * reports the refusal from its effect instead.
+	 */
+	commitBannerRequest(
+		placementKey: string,
+		correlationId: string,
+	): ThrottledResult | null;
+	/** The configured floor for a placement, so the host can report the cause. */
+	throttleFloorFor(placementKey: string): number;
+	emit(event: AdEvent): void;
+	setPlacementState(key: string, state: PlacementState): void;
+	isReady(): boolean;
+	nextCorrelationId(): string;
+	timerCount(): number;
+}
+
+export interface CreateAdsOptions {
+	/** Injected in tests; the AdMob adapter is the default in production. */
+	readonly engine?: AdsEngine;
+	/** 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 {
+	snapshot: PlacementSnapshot;
+	/**
+	 * The cycle's correlation id, held here rather than read from the snapshot:
+	 * the reducer resets the snapshot on dismissal, and events emitted around
+	 * that transition must still carry the id of the cycle they belong to.
+	 */
+	correlationId: string | null;
+	/**
+	 * Whether this cycle already reported a dismissal. Format-independent — the
+	 * rewarded session guards its own, but interstitials need the same guard and
+	 * would otherwise report a repeated provider callback twice.
+	 */
+	dismissed: boolean;
+	handle: EngineAdHandle | null;
+	unsubscribeEngine: Unsubscribe | null;
+	inFlightLoad: Promise<LoadResult> | null;
+	/**
+	 * Settles the in-flight load with a given result. Only a consent withdrawal
+	 * uses it (FR-153): the caller awaiting `load()` is told `blocked` instead of
+	 * waiting on a request that has been abandoned.
+	 */
+	abortLoad: ((result: LoadResult) => void) | null;
+	cancelLoadTimer: Unsubscribe | null;
+	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 {
+	return typeof __DEV__ !== 'undefined' ? Boolean(__DEV__) : false;
+}
+
+export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): AdsInstance {
+	const isDevBuild = options.isDevBuild ?? detectDevBuild();
+	const now = options.now ?? (() => Date.now());
+
+	// Throws on a structural fault or the FR-012 fail-closed case. Deliberately
+	// before anything else: a misconfigured instance should not exist at all.
+	const resolved: ResolvedConfig = validateConfig(config, { isDevBuild });
+
+	const engine: AdsEngine = options.engine ?? createDefaultEngine();
+	const events = createEventEmitter();
+	const correlation = createCorrelationIssuer();
+	// FR-140. Account safety, not product policy — see core/requestThrottle.ts.
+	const requestThrottle = createRequestThrottle(now);
+	const timers = createTimerSet(options.scheduler);
+	const lock = createFullScreenLock();
+	const adReturn = createAdOriginatedTracker();
+
+	/**
+	 * 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;
+	/**
+	 * Consent forms currently on screen. A count rather than a flag because
+	 * `showFormIfRequired` has never refused a concurrent call and 0.4.0 does not
+	 * start now; only the privacy options form reads it, to report `busy`.
+	 */
+	let consentFormsOpen = 0;
+	let privacyOptionsFormOpen = false;
+	/**
+	 * Whether the provider has been natively initialized, ever, by this instance.
+	 *
+	 * Tracked apart from the init status because the status can leave `ready` —
+	 * a withdrawn consent moves it to `blocked` — while the native SDK stays
+	 * initialized. Re-granting must resume, not initialize again (FR-022, FR-154).
+	 */
+	let providerInitialized = 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;
+	let disposed = false;
+	let warnedSubstitution = false;
+
+	const statusListeners = new Set<(status: InitStatus) => void>();
+	const placements = new Map<string, PlacementRuntime>();
+
+	for (const key of resolved.placements.keys()) {
+		placements.set(key, {
+			snapshot: initialPlacement,
+			correlationId: null,
+			dismissed: false,
+			handle: null,
+			unsubscribeEngine: null,
+			inFlightLoad: null,
+			abortLoad: null,
+			cancelLoadTimer: null,
+			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;
+			return;
+		}
+		init = next;
+		events.emit({
+			type: 'initialization',
+			timestamp: now(),
+			status: next.status,
+			retryable: next.error?.retryable,
+		});
+		for (const listener of Array.from(statusListeners)) {
+			try {
+				listener(next.status);
+			} catch {
+				// A status listener is consumer code; its failure is isolated the
+				// same way an event listener's is (FR-056).
+			}
+		}
+	}
+
+	function setPlacement(key: string, next: PlacementSnapshot): void {
+		const runtime = placements.get(key);
+		if (!runtime || runtime.snapshot.state === next.state) {
+			if (runtime) {
+				runtime.snapshot = next;
+			}
+			return;
+		}
+		runtime.snapshot = next;
+		for (const listener of Array.from(runtime.listeners)) {
+			try {
+				listener(next.state);
+			} catch {
+				// Isolated, as above.
+			}
+		}
+	}
+
+	function dispatchPlacement(key: string, event: Parameters<typeof placementReducer>[1]): void {
+		const runtime = placements.get(key);
+		const definition = resolved.placements.get(key);
+		if (!runtime || !definition) {
+			return;
+		}
+		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' | 'undecided' | 'blocked' | 'unavailable' }
+				>;
+		  } {
+		const decision = currentGate();
+		if (decision.allowed) {
+			return { ok: true };
+		}
+		return { ok: false, result: refusalFor(decision) };
+	}
+
+	function emitRefusal(
+		operation: 'initialize' | 'load' | 'show',
+		result: { readonly status: string; readonly reason?: string },
+		placementKey?: string,
+		format?: AdFormat,
+	): void {
+		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({
+				type: 'unavailable',
+				timestamp: now(),
+				operation,
+				placementKey,
+				format,
+				reason: (result.reason ?? 'unsupported_platform') as UnavailableReason | PrivacyBlockReason,
+			});
+		}
+	}
+
+	/**
+	 * Consumes a throttle slot for a placement, or reports the refusal (FR-140).
+	 *
+	 * Returns `null` when the request may proceed, so the two call sites read as a
+	 * guard clause. On refusal it moves the placement to `throttled` and emits,
+	 * which is what makes the refusal observable rather than a silent absence of
+	 * ads — the app would otherwise have no way to tell this from no-fill.
+	 */
+	function reportThrottled(
+		key: string,
+		format: AdFormat,
+		retryAfterMs: number,
+		minRequestIntervalMs: number,
+	): LoadResult {
+		const runtime = placements.get(key);
+		if (runtime) {
+			setPlacement(key, { ...runtime.snapshot, state: 'throttled' });
+		}
+		events.emit({
+			type: 'request_throttled',
+			timestamp: now(),
+			placementKey: key,
+			format,
+			retryAfterMs,
+			minRequestIntervalMs,
+		});
+		return { status: 'throttled', retryAfterMs };
+	}
+
+	/** Consumes a slot, or reports the refusal. `null` means proceed. */
+	function checkThrottle(key: string, format: AdFormat, token?: string): LoadResult | null {
+		const minRequestIntervalMs = resolved.minRequestIntervalByKey.get(key) ?? 0;
+		const decision = requestThrottle.tryAcquire(key, minRequestIntervalMs, token);
+		return decision.allowed
+			? null
+			: reportThrottled(key, format, decision.retryAfterMs, minRequestIntervalMs);
+	}
+
+	function warnSubstitutionOnce(): void {
+		if (warnedSubstitution || resolved.catalog.substitutedKeys.length === 0) {
+			return;
+		}
+		warnedSubstitution = true;
+		events.emit({
+			type: 'config_warning',
+			timestamp: now(),
+			warning: 'test_ad_unit_substituted',
+			placementKeys: resolved.catalog.substitutedKeys,
+		});
+	}
+
+	function releasePlacementResources(key: string): void {
+		const runtime = placements.get(key);
+		if (!runtime) {
+			return;
+		}
+		runtime.cancelLoadTimer?.();
+		runtime.cancelLoadTimer = null;
+		runtime.cancelShowTimer?.();
+		runtime.cancelShowTimer = null;
+		runtime.unsubscribeEngine?.();
+		runtime.unsubscribeEngine = null;
+		if (runtime.handle) {
+			engine.dispose(runtime.handle);
+			runtime.handle = null;
+		}
+		runtime.inFlightLoad = null;
+		runtime.abortLoad = null;
+		runtime.rewarded = null;
+		runtime.cancelRetry?.();
+		runtime.cancelRetry = null;
+	}
+
+	/**
+	 * Stops every request a gate that just closed forbids (FR-125, FR-153,
+	 * FR-159) — ads turned off, turned undecided, or consent withdrawn.
+	 *
+	 * In-flight loads are abandoned and their resources released, a loaded ad
+	 * that may no longer be shown is released with them, and an ad already on
+	 * screen is left alone — the provider offers no safe way to close it.
+	 *
+	 * An abandoned load *settles*: its caller gets `refusal`, the same answer a
+	 * load started now would get. Until 0.4.0 disabling released the resources
+	 * but never resolved the caller's promise, so an app awaiting `load()` across
+	 * a purchase of ad removal waited forever — and a handle the provider handed
+	 * back after the disable was adopted and went on loading.
+	 */
+	function haltPlacements(refusal: LoadRefusal): void {
+		for (const [key, runtime] of placements) {
+			if (runtime.snapshot.state === 'showing') {
+				continue;
+			}
+			const abort = runtime.abortLoad;
+			releasePlacementResources(key);
+			dispatchPlacement(key, { type: 'RESET' });
+			if (abort) {
+				emitRefusal('load', refusal, key, resolved.placements.get(key)?.format);
+				abort(refusal);
+			}
+		}
+	}
+
+	/** 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> {
+		const enginePrivacy = toEnginePrivacy(privacy, resolved.testDeviceIds);
+		try {
+			// The adapter applies privacy configuration before initializing the
+			// provider; that ordering is the whole reason FR-017 is enforceable.
+			await engine.initialize(enginePrivacy);
+			// Recorded before the status moves, and whether or not it moves: a gate
+			// that closed while this was in flight leaves the status `blocked`, but
+			// the provider is initialized all the same and must not be again.
+			providerInitialized = true;
+			appliedPrivacy = privacy;
+			setInit(initReducer(init, { type: 'SUCCEED' }));
+			warnSubstitutionOnce();
+			return { status: 'ready' };
+		} catch (error) {
+			const normalized = normalizeProviderError(error, { operation: 'initialize' });
+			setInit(initReducer(init, { type: 'FAIL', error: normalized }));
+			return { status: 'failed', error: normalized };
+		} finally {
+			inFlightInit = null;
+		}
+	}
+
+	function handleEngineEvent(
+		key: string,
+		definition: PlacementDefinition,
+		event: EngineAdEvent,
+	): void {
+		// After dispose nothing is honored: a late provider callback must not
+		// update a consumer that has gone away (FR-035, SC-008).
+		if (disposed) {
+			return;
+		}
+		const runtime = placements.get(key);
+		if (!runtime) {
+			return;
+		}
+		const correlationId = runtime.correlationId ?? undefined;
+		const base = { timestamp: now(), placementKey: key, format: definition.format, correlationId };
+
+		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
+				// honestly rather than passed off as the provider's own.
+				events.emit({ ...base, type: 'impression', source: 'derived' as ImpressionSource });
+				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': {
+				const first = runtime.rewarded?.confirmReward(event.reward) ?? null;
+				if (first) {
+					events.emit({ ...base, type: 'reward_earned', reward: first });
+				}
+				break;
+			}
+			case 'dismissed': {
+				const rewardedFirst = runtime.rewarded ? runtime.rewarded.dismiss() : true;
+				if (runtime.dismissed || !rewardedFirst) {
+					break;
+				}
+				runtime.dismissed = true;
+				lock.release(key);
+				runtime.cancelShowTimer?.();
+				runtime.cancelShowTimer = null;
+				events.emit({
+					...base,
+					type: 'dismissed',
+					rewardEarned: runtime.rewarded ? runtime.rewarded.rewardEarned : undefined,
+				});
+				dispatchPlacement(key, { type: 'DISMISSED' });
+				// Deliberately NOT released here. FR-049 requires the reward and
+				// the dismissal to be handled in either order, and a provider that
+				// confirms the reward *after* closing the ad would otherwise have
+				// its confirmation dropped by a torn-down listener — silently
+				// costing the user a reward they earned.
+				//
+				// This is a retained resource, not a leak: at most one handle and
+				// one listener per placement, released deterministically by the
+				// next load of that placement or by dispose().
+				break;
+			}
+			case 'failed': {
+				const normalized = normalizeProviderError(event.cause, {
+					operation: 'show',
+					placementKey: key,
+					format: definition.format,
+				});
+				lock.release(key);
+				events.emit({ ...base, type: 'display_failed', error: normalized });
+				dispatchPlacement(key, { type: 'SHOW_FAILED', error: normalized });
+				releasePlacementResources(key);
+				break;
+			}
+			default:
+				break;
+		}
+	}
+
+	function loadFullScreen(
+		key: string,
+		definition: PlacementDefinition,
+		adUnitId: string,
+		correlationId: string,
+	): Promise<LoadResult> {
+		const runtime = placements.get(key)!;
+		const format = definition.format as FullScreenFormat;
+		const startedAt = now();
+
+		return new Promise<LoadResult>(resolve => {
+			let settled = false;
+
+			const finish = (result: LoadResult) => {
+				if (settled) {
+					return;
+				}
+				settled = true;
+				runtime.cancelLoadTimer?.();
+				runtime.cancelLoadTimer = null;
+				runtime.inFlightLoad = null;
+				if (runtime.abortLoad === finish) {
+					runtime.abortLoad = null;
+				}
+				resolve(result);
+			};
+			// `settled` is what makes this safe: a handle the provider hands back
+			// after an abort is disposed by the `.then` below instead of adopted.
+			runtime.abortLoad = finish;
+
+			runtime.cancelLoadTimer = timers.after(resolved.timeouts.load, () => {
+				const error = new AdsError('load_timeout', {
+					operation: 'load',
+					placementKey: key,
+					format,
+					message: `load timed out after ${resolved.timeouts.load}ms`,
+				});
+				events.emit({
+					type: 'load_failed',
+					timestamp: now(),
+					placementKey: key,
+					format,
+					correlationId,
+					error,
+				});
+				dispatchPlacement(key, { type: 'LOAD_FAILED', error });
+				releasePlacementResources(key);
+				finish({ status: 'timeout' });
+			});
+
+			engine
+				.createFullScreen(format, adUnitId)
+				.then(handle => {
+					if (disposed || settled) {
+						engine.dispose(handle);
+						return;
+					}
+					runtime.handle = handle;
+					runtime.unsubscribeEngine = engine.subscribe(handle, event => {
+						if (event.type === 'loaded') {
+							dispatchPlacement(key, { type: 'LOADED', atMs: now() });
+							events.emit({
+								type: 'loaded',
+								timestamp: now(),
+								placementKey: key,
+								format,
+								correlationId,
+								durationMs: now() - startedAt,
+							});
+							finish({ status: 'loaded', correlationId });
+							return;
+						}
+						if (event.type === 'failed') {
+							const normalized = normalizeProviderError(event.cause, {
+								operation: 'load',
+								placementKey: key,
+								format,
+							});
+							events.emit({
+								type: 'load_failed',
+								timestamp: now(),
+								placementKey: key,
+								format,
+								correlationId,
+								error: normalized,
+							});
+							dispatchPlacement(key, { type: 'LOAD_FAILED', error: normalized });
+							releasePlacementResources(key);
+							finish(
+								normalized.code === 'no_fill'
+									? { status: 'no_fill' }
+									: { status: 'failed', error: normalized },
+							);
+							return;
+						}
+						handleEngineEvent(key, definition, event);
+					});
+				})
+				.catch(error => {
+					const normalized = normalizeProviderError(error, {
+						operation: 'load',
+						placementKey: key,
+						format,
+					});
+					events.emit({
+						type: 'load_failed',
+						timestamp: now(),
+						placementKey: key,
+						format,
+						correlationId,
+						error: normalized,
+					});
+					dispatchPlacement(key, { type: 'LOAD_FAILED', error: normalized });
+					finish(
+						normalized.code === 'no_fill'
+							? { status: 'no_fill' }
+							: { status: 'failed', error: normalized },
+					);
+				});
+		});
+	}
+
+	/**
+	 * 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).
+	 *
+	 * Since 0.4.0 a closed gate also moves a `ready` instance to `blocked` and
+	 * abandons in-flight loads (FR-153). 0.3.0 left the status at `ready`, which
+	 * was harmless while the only consent outcome that could close the gate ran
+	 * before anything was loaded. The privacy options form changes that: a user
+	 * can withdraw consent with a banner mounted, and a banner host keyed on
+	 * `ready` would otherwise keep requesting. Re-granting resumes through
+	 * `initialize`, which knows the provider is already up and does not touch it
+	 * again (FR-154).
+	 */
+	async function reevaluateAfterConsent(): Promise<void> {
+		if (disposed || !currentPrivacy) {
+			return;
+		}
+		const decision = currentGate();
+		if (!decision.allowed) {
+			cancelAllRetries();
+			if (decision.kind === 'blocked') {
+				haltPlacements({ status: 'blocked', reason: decision.reason });
+				setInit(initReducer(init, { type: 'BLOCK', reason: decision.reason }));
+			}
+			return;
+		}
+		if (init.status === 'ready' || init.status === 'initializing') {
+			return;
+		}
+		await instance.initialize(currentPrivacy);
+	}
+
+	/**
+	 * Answers `initialize` without a native call when the provider is already up
+	 * (FR-022, FR-154), or returns `null` to let a real initialization proceed.
+	 *
+	 * The status leaves `ready` when a gate closes, but nothing is torn down, so
+	 * the gate reopening resumes. Init-time-only flags that changed in the
+	 * meantime fall through to a real initialization: it is the only way they can
+	 * take effect, and it is what 0.3.0 did.
+	 *
+	 * Only reached once the caller has passed the whole gate, consent flow
+	 * included, so an app that re-runs `initialize` on a consent change cannot
+	 * reopen what the user just closed.
+	 */
+	function resumeInitialized(privacy: PrivacyOptions): InitResult | null {
+		if (
+			!providerInitialized ||
+			!canStart(init.status) ||
+			requiresReinitialization(appliedPrivacy, privacy)
+		) {
+			return null;
+		}
+		setInit(initReducer(init, { type: 'RESUME' }));
+		return { status: 'ready' };
+	}
+
+	const instance: AdsInstance = {
+		async initialize(privacy) {
+			if (disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			currentPrivacy = privacy;
+
+			// 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 (!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;
+			}
+
+			if (!decision.allowed && decision.kind === 'blocked') {
+				// FR-017, FR-158. Nothing provider-facing happens here at all — not a
+				// configuration call, not an initialization. The engine is untouched.
+				//
+				// `decision` is the full gate: the app's own input *and*, once the app
+				// has opted into it, the package's consent flow. Until 0.4.0 this
+				// checked the app's input alone, so a user who declined the consent
+				// form still got a natively initialized SDK — `load` refused, but the
+				// provider was up, which is exactly what the provider's own guidance
+				// says not to do before `canRequestAds`. The consent flow opening the
+				// gate later initializes it, through `reevaluateAfterConsent`.
+				setInit(initReducer(init, { type: 'BLOCK', reason: decision.reason }));
+				const result = { status: 'blocked', reason: decision.reason } as const;
+				emitRefusal('initialize', result);
+				return result;
+			}
+
+			if (init.status === 'ready') {
+				return { status: 'ready' };
+			}
+
+			const resumed = resumeInitialized(privacy);
+			if (resumed) {
+				return resumed;
+			}
+
+			// FR-022, SC-005. Racing callers share one operation, so the provider
+			// initializes exactly once however many arrive.
+			if (inFlightInit) {
+				return inFlightInit;
+			}
+			if (!canStart(init.status)) {
+				return { status: 'ready' };
+			}
+
+			setInit(initReducer(init, { type: 'START' }));
+			inFlightInit = doInitialize(privacy);
+			return inFlightInit;
+		},
+
+		async updatePrivacy(privacy) {
+			if (disposed) {
+				return { status: 'disabled' };
+			}
+			if (enablement === 'undecided') {
+				return { status: 'undecided' };
+			}
+			if (enablement === 'disabled') {
+				return { status: 'disabled' };
+			}
+			if (!engine.isAvailable()) {
+				return { status: 'unavailable', reason: 'unsupported_platform' };
+			}
+
+			// FR-020: a flag the provider only honors at initialization cannot be
+			// applied now. Say so, rather than accepting it and running half-old.
+			if (requiresReinitialization(appliedPrivacy, privacy)) {
+				return { status: 'requires_reinitialization' };
+			}
+
+			currentPrivacy = privacy;
+			const gate = evaluateGate(privacy);
+			if (!gate.allowed) {
+				setInit(initReducer(init, { type: 'BLOCK', reason: gate.reason }));
+				return { status: 'blocked', reason: gate.reason };
+			}
+
+			// FR-019: resolving consent after a block must not produce a second
+			// native initialization.
+			if (init.status === 'ready') {
+				return { status: 'applied' };
+			}
+			const result = await instance.initialize(privacy);
+			return result.status === 'ready'
+				? { status: 'applied' }
+				: result.status === 'blocked'
+					? { status: 'blocked', reason: result.reason }
+					: { status: 'applied' };
+		},
+
+		setEnabled(next) {
+			return instance.setEnablement(next ? 'enabled' : 'disabled');
+		},
+
+		setEnablement(next) {
+			if (disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			if (enablement === next) {
+				return { status: 'unchanged' };
+			}
+
+			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();
+				haltPlacements(next === 'disabled' ? { status: 'disabled' } : { status: 'undecided' });
+				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) {
+			if (disposed) {
+				return;
+			}
+			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 &&
+					definition !== undefined &&
+					isStale(runtime.snapshot.loadedAtMs, current, validityFor(definition.format))
+				) {
+					releasePlacementResources(key);
+					dispatchPlacement(key, { type: 'EXPIRE' });
+				}
+			}
+		},
+
+		getStatus() {
+			return init.status;
+		},
+
+		subscribeStatus(listener) {
+			statusListeners.add(listener);
+			let active = true;
+			return () => {
+				if (!active) {
+					return;
+				}
+				active = false;
+				statusListeners.delete(listener);
+			};
+		},
+
+		async load(placementKey) {
+			if (disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+
+			const definition = resolved.placements.get(placementKey);
+			if (!definition) {
+				return {
+					status: 'failed',
+					error: new AdsError('placement_not_found', {
+						operation: 'load',
+						placementKey,
+						message: `unknown placement "${placementKey}"; configured keys are ${[...resolved.placements.keys()].join(', ')}`,
+					}),
+				};
+			}
+
+			const gate = gateCheck();
+			if (!gate.ok) {
+				emitRefusal('load', gate.result, placementKey, definition.format);
+				return gate.result;
+			}
+
+			if (!canRequest(init.status)) {
+				return {
+					status: 'failed',
+					error: new AdsError('not_ready', {
+						operation: 'load',
+						placementKey,
+						format: definition.format,
+						message: 'initialize() must complete before loading',
+					}),
+				};
+			}
+
+			if (definition.format === 'banner') {
+				return {
+					status: 'failed',
+					error: new AdsError('format_mismatch', {
+						operation: 'load',
+						placementKey,
+						format: definition.format,
+						message: `"${placementKey}" is a banner; banners render through <AdsBanner> rather than load()`,
+					}),
+				};
+			}
+
+			const runtime = placements.get(placementKey)!;
+
+			// FR-029, SC-002's sibling guarantee: a repeat load while one is in
+			// flight joins it instead of creating a second provider request.
+			if (runtime.inFlightLoad) {
+				return runtime.inFlightLoad;
+			}
+
+			// FR-140. Checked after the in-flight join so a caller that merely
+			// arrived twice for one cycle is answered by the join, not charged a
+			// throttle slot — and before the correlation id and `load_started`,
+			// because a refused request is not a cycle and must not look like one
+			// in the event stream.
+			const throttled = checkThrottle(placementKey, definition.format);
+			if (throttled) {
+				return throttled;
+			}
+
+			if (runtime.snapshot.state === 'showing') {
+				return { status: 'failed', error: new AdsError('busy', { operation: 'load', placementKey }) };
+			}
+
+			if (!canLoad(runtime.snapshot.state)) {
+				return {
+					status: 'failed',
+					error: new AdsError('not_ready', { operation: 'load', placementKey }),
+				};
+			}
+
+			releasePlacementResources(placementKey);
+
+			const correlationId = correlation.next();
+			runtime.correlationId = correlationId;
+			runtime.dismissed = false;
+			dispatchPlacement(placementKey, { type: 'LOAD' });
+			setPlacement(placementKey, { ...runtime.snapshot, correlationId });
+			events.emit({
+				type: 'load_started',
+				timestamp: now(),
+				placementKey,
+				format: definition.format,
+				correlationId,
+			});
+
+			const adUnitId = resolved.catalog.byKey.get(placementKey)!;
+			runtime.retryAttempts = 0;
+			const promise = loadWithRetry(placementKey, definition, adUnitId, correlationId);
+			runtime.inFlightLoad = promise;
+			return promise;
+		},
+
+		async show(placementKey) {
+			if (disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+
+			const definition = resolved.placements.get(placementKey);
+			if (!definition) {
+				return {
+					status: 'failed',
+					error: new AdsError('placement_not_found', {
+						operation: 'show',
+						placementKey,
+						message: `unknown placement "${placementKey}"; configured keys are ${[...resolved.placements.keys()].join(', ')}`,
+					}),
+				};
+			}
+
+			if (!isFullScreenFormat(definition.format)) {
+				return {
+					status: 'failed',
+					error: new AdsError('format_mismatch', {
+						operation: 'show',
+						placementKey,
+						format: definition.format,
+						message: `"${placementKey}" is a banner; banners are rendered, not shown`,
+					}),
+				};
+			}
+
+			const gate = gateCheck();
+			if (!gate.ok) {
+				emitRefusal('show', gate.result, placementKey, definition.format);
+				return gate.result;
+			}
+
+			// FR-028: never open an ad while the app is not in front of the user.
+			if (!appActive) {
+				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') {
+				return { status: 'consumed' };
+			}
+
+			// FR-034: a stale ad is not shown and is not reported ready.
+			if (
+				runtime.snapshot.state === 'ready' &&
+				runtime.snapshot.loadedAtMs !== null &&
+				isStale(runtime.snapshot.loadedAtMs, now(), validityFor(definition.format))
+			) {
+				releasePlacementResources(placementKey);
+				dispatchPlacement(placementKey, { type: 'EXPIRE' });
+				return { status: 'not_ready' };
+			}
+
+			if (runtime.snapshot.state !== 'ready' || !runtime.handle) {
+				return { status: 'not_ready' };
+			}
+
+			// FR-030. Acquired before anything else can open a screen, and never
+			// queued: a refused show is refused now, not deferred to a moment the
+			// app never chose.
+			if (!lock.acquire(placementKey)) {
+				return { status: 'busy' };
+			}
+
+			const correlationId = runtime.correlationId ?? correlation.next();
+			runtime.rewarded = definition.format === 'rewarded' ? createRewardedSession() : null;
+			dispatchPlacement(placementKey, { type: 'SHOW' });
+
+			let settled = false;
+			const showTimeout = new Promise<ShowResult>(resolve => {
+				runtime.cancelShowTimer = timers.after(resolved.timeouts.show, () => {
+					if (settled) {
+						return;
+					}
+					settled = true;
+					const error = new AdsError('show_timeout', {
+						operation: 'show',
+						placementKey,
+						format: definition.format,
+						message: `show timed out after ${resolved.timeouts.show}ms`,
+					});
+					lock.release(placementKey);
+					events.emit({
+						type: 'display_failed',
+						timestamp: now(),
+						placementKey,
+						format: definition.format,
+						correlationId,
+						error,
+					});
+					dispatchPlacement(placementKey, { type: 'SHOW_FAILED', error });
+					releasePlacementResources(placementKey);
+					resolve({ status: 'timeout' });
+				});
+			});
+
+			const attempt = engine
+				.show(runtime.handle)
+				.then<ShowResult>(() => {
+					settled = true;
+					runtime.cancelShowTimer?.();
+					runtime.cancelShowTimer = null;
+					return { status: 'shown', correlationId };
+				})
+				.catch<ShowResult>(error => {
+					settled = true;
+					runtime.cancelShowTimer?.();
+					runtime.cancelShowTimer = null;
+					const normalized = normalizeProviderError(error, {
+						operation: 'show',
+						placementKey,
+						format: definition.format,
+					});
+					lock.release(placementKey);
+					events.emit({
+						type: 'display_failed',
+						timestamp: now(),
+						placementKey,
+						format: definition.format,
+						correlationId,
+						error: normalized,
+					});
+					dispatchPlacement(placementKey, { type: 'SHOW_FAILED', error: normalized });
+					releasePlacementResources(placementKey);
+					return { status: 'failed', error: normalized };
+				});
+
+			return Promise.race([attempt, showTimeout]);
+		},
+
+		getPlacementState(placementKey) {
+			if (!resolved.placements.has(placementKey)) {
+				return 'unavailable';
+			}
+			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';
+		},
+
+		subscribePlacement(key, listener) {
+			const runtime = placements.get(key);
+			if (!runtime) {
+				return () => undefined;
+			}
+			runtime.listeners.add(listener);
+			let active = true;
+			return () => {
+				if (!active) {
+					return;
+				}
+				active = false;
+				runtime.listeners.delete(listener);
+			};
+		},
+
+		subscribeEvents(listener) {
+			return events.subscribe(listener);
+		},
+
+		getSubstitutedPlacements() {
+			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) || privacyOptionsFormOpen) {
+					// 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.
+					// Nor is a privacy options form already on screen — one
+					// provider form at a time.
+					return consent;
+				}
+				consentFormsOpen += 1;
+				let next: ConsentSnapshot;
+				try {
+					next = await runConsentStep(
+						() => engine.consent.showFormIfRequired(),
+						'consent form failed',
+					);
+				} finally {
+					consentFormsOpen -= 1;
+				}
+				if (disposed) {
+					return consent;
+				}
+				setConsent(next);
+				await reevaluateAfterConsent();
+				return next;
+			},
+
+			async showPrivacyOptionsForm() {
+				// The refusals, most immovable first — the same reading order as
+				// the request gates, so the answer is the most useful one rather
+				// than the first one checked.
+				if (disposed) {
+					return { status: 'unavailable', reason: 'provider_missing' };
+				}
+				if (!engine.isAvailable()) {
+					return { status: 'unavailable', reason: 'unsupported_platform' };
+				}
+				if (privacyOptionsFormOpen || consentFormsOpen > 0) {
+					return { status: 'busy' };
+				}
+				if (consent.privacyOptionsRequirement === 'unknown') {
+					return { status: 'info_update_required' };
+				}
+				if (consent.privacyOptionsRequirement !== 'required') {
+					// The provider's verdict, not a region guess of ours (FR-150).
+					return { status: 'not_required' };
+				}
+
+				privacyOptionsFormOpen = true;
+				let next: ConsentSnapshot;
+				let failure: AdsError | null = null;
+				try {
+					next = normalizeConsent(await engine.consent.showPrivacyOptionsForm());
+				} catch (cause) {
+					failure = toConsentError(cause, 'privacy options form failed');
+					// The form did not complete, so the stored decision is the
+					// provider's to report — ask it rather than assume. Collapsing to
+					// `error` the way a failed first-time form does would revoke a
+					// consent the user never changed: that form runs while the gate is
+					// already closed, this one usually while it is open. If the
+					// provider cannot answer either, the gate closes; a failure is
+					// never consent (FR-106). Nothing is asked of a disposed instance.
+					next = disposed
+						? consent
+						: await runConsentStep(
+								() => engine.consent.getInfo(),
+								'consent information could not be read after the privacy options form failed',
+							);
+				} finally {
+					privacyOptionsFormOpen = false;
+				}
+				// dispose() during the form: the form is the provider's and stays
+				// until the user closes it, but its outcome reaches nobody (FR-157).
+				if (disposed) {
+					return { status: 'unavailable', reason: 'provider_missing' };
+				}
+				setConsent(next);
+				await reevaluateAfterConsent();
+				return failure
+					? { status: 'failed', error: failure }
+					: { status: 'shown', consent: 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);
+				if (!definition) {
+					return {
+						ok: false,
+						result: {
+							status: 'failed',
+							error: new AdsError('placement_not_found', {
+								operation: 'load',
+								placementKey,
+								message: `unknown placement "${placementKey}"`,
+							}),
+						},
+					};
+				}
+				if (definition.format !== 'banner') {
+					return {
+						ok: false,
+						result: {
+							status: 'failed',
+							error: new AdsError('format_mismatch', {
+								operation: 'load',
+								placementKey,
+								format: definition.format,
+								message: `"${placementKey}" is not a banner placement`,
+							}),
+						},
+					};
+				}
+				const gate = gateCheck();
+				if (!gate.ok) {
+					return { ok: false, result: gate.result };
+				}
+				if (!canRequest(init.status)) {
+					return { ok: false, result: { status: 'blocked', reason: 'consent_required' } };
+				}
+				// The throttle is deliberately **not** consulted here. It cannot be
+				// decided from configuration alone: a fresh mount must be throttled
+				// (that is the navigation burst the feature exists for) while a width
+				// re-adaptation of an already-mounted banner must not be (that is
+				// rotation, and refusing it would leave the user with no banner for a
+				// minute). Only the host knows which it is, so the host calls
+				// `commitBannerRequest` (FR-140).
+				return {
+					ok: true,
+					adUnitId: resolved.catalog.byKey.get(placementKey)!,
+					correlationId: correlation.next(),
+				};
+			},
+			commitBannerRequest(placementKey, correlationId) {
+				if (!resolved.placements.has(placementKey)) {
+					return null;
+				}
+				const minRequestIntervalMs =
+					resolved.minRequestIntervalByKey.get(placementKey) ?? 0;
+				const decision = requestThrottle.tryAcquire(
+					placementKey,
+					minRequestIntervalMs,
+					correlationId,
+				);
+				// Deliberately silent: the host calls this during render, because the
+				// provider component requests as part of that same render and an effect
+				// would be too late to stop it. Emitting an event or setting placement
+				// state here would mean mutating during another component's render, so
+				// the refusal is only returned — the host reports it from its effect.
+				return decision.allowed
+					? null
+					: { status: 'throttled', retryAfterMs: decision.retryAfterMs };
+			},
+			throttleFloorFor(placementKey) {
+				return resolved.minRequestIntervalByKey.get(placementKey) ?? 0;
+			},
+			emit(event) {
+				events.emit(event);
+			},
+			setPlacementState(key, state) {
+				const runtime = placements.get(key);
+				if (runtime) {
+					setPlacement(key, { ...runtime.snapshot, state });
+				}
+			},
+			isReady() {
+				return permitsRequests(enablement) && engine.isAvailable() && canRequest(init.status);
+			},
+			nextCorrelationId() {
+				return correlation.next();
+			},
+			timerCount() {
+				return timers.size();
+			},
+		},
+
+		dispose() {
+			// FR-005: idempotent. A second call is a no-op, not an error.
+			if (disposed) {
+				return;
+			}
+			disposed = true;
+			cancelAllRetries();
+			disarmUndecidedWarning();
+			for (const [key, runtime] of placements) {
+				const abort = runtime.abortLoad;
+				releasePlacementResources(key);
+				runtime.listeners.clear();
+				// Settled rather than left hanging, with the answer a `load` after
+				// dispose gets (FR-159). No refusal event goes with it: nothing is
+				// emitted after dispose (FR-035).
+				abort?.({ status: 'unavailable', reason: 'provider_missing' });
+			}
+			timers.clearAll();
+			requestThrottle.clear();
+			lock.reset();
+			adReturn.reset();
+			statusListeners.clear();
+			consentListeners.clear();
+			events.dispose();
+			inFlightInit = null;
+		},
+	};
+
+	return instance;
+}
+
+/**
+ * Resolved lazily so importing the package on a platform with no adapter — or
+ * with the bridge absent — costs nothing and crashes nothing (FR-025, SC-004).
+ */
+function createDefaultEngine(): AdsEngine {
+	// Deferred require keeps the provider off the import graph of every module
+	// that merely mentions `createAds`.
+	const { createAdMobEngine } = require('../engine/admobEngine') as typeof import('../engine/admobEngine');
+	return createAdMobEngine();
+}
+
+declare const __DEV__: boolean | undefined;