@chipmobilesdk/rn-ads 0.1.0

package/src/core/adsInstance.ts

@@ -0,0 +1,1031 @@
+/**
+ * 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 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 { createRewardedSession, type RewardedSession } from './rewardedSession';
+import { createTimerSet, isStale } from './timers';
+
+export type InitResult =
+	| { readonly status: 'ready' }
+	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
+	| { readonly status: 'disabled' }
+	| { 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: 'unavailable'; readonly reason: UnavailableReason };
+
+export type LoadResult =
+	| { readonly status: 'loaded'; readonly correlationId: string }
+	| { readonly status: 'disabled' }
+	| { 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' }
+	| { readonly status: 'disabled' }
+	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
+	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
+	| { readonly status: 'timeout' }
+	| { readonly status: 'failed'; readonly error: AdsError };
+
+export interface AdsInstance {
+	initialize(privacy: PrivacyOptions): Promise<InitResult>;
+	updatePrivacy(privacy: PrivacyOptions): Promise<PrivacyUpdateResult>;
+	setEnabled(enabled: boolean): void;
+	setAppActive(active: boolean): void;
+	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[];
+	/** 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;
+}
+
+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>;
+}
+
+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();
+	const lock = createFullScreenLock();
+
+	let init: InitSnapshot = initialInit;
+	let enabled = resolved.enabled;
+	let appActive = true;
+	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(),
+		});
+	}
+
+	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));
+	}
+
+	/** Every refusal that applies before a placement is even looked up. */
+	function gateCheck():
+		| { readonly ok: true }
+		| { readonly ok: false; readonly result: Extract<LoadResult, { status: 'disabled' | 'blocked' | 'unavailable' }> } {
+		if (!enabled) {
+			return { ok: false, result: { status: 'disabled' } };
+		}
+		if (!engine.isAvailable()) {
+			return {
+				ok: false,
+				result: { status: 'unavailable', reason: 'unsupported_platform' },
+			};
+		}
+		const gate = evaluateGate(currentPrivacy);
+		if (!gate.allowed) {
+			return { ok: false, result: { status: 'blocked', reason: gate.reason } };
+		}
+		return { ok: true };
+	}
+
+	function emitRefusal(
+		operation: 'initialize' | 'load' | 'show',
+		result: { readonly status: string; readonly reason?: string },
+		placementKey?: string,
+		format?: AdFormat,
+	): void {
+		if (result.status === 'disabled') {
+			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;
+	}
+
+	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': {
+				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':
+				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 },
+					);
+				});
+		});
+	}
+
+	const instance: AdsInstance = {
+		async initialize(privacy) {
+			if (disposed) {
+				return { status: 'unavailable', reason: 'provider_missing' };
+			}
+			currentPrivacy = privacy;
+
+			if (!enabled) {
+				setInit(initReducer(init, { type: 'DISABLE' }));
+				const result = { status: 'disabled' } as const;
+				emitRefusal('initialize', result);
+				return result;
+			}
+
+			if (!engine.isAvailable()) {
+				setInit(initReducer(init, { type: 'UNAVAILABLE', reason: 'unsupported_platform' }));
+				const result = { status: 'unavailable', reason: 'unsupported_platform' } as const;
+				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 || !enabled) {
+				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) {
+			if (disposed || enabled === next) {
+				return;
+			}
+			enabled = next;
+			if (!next) {
+				// FR-037: new work is prevented and in-flight resources released
+				// deterministically. An ad already on screen is left alone — the
+				// provider offers no safe way to close it, and yanking it would be
+				// worse than letting it finish.
+				for (const [key, runtime] of placements) {
+					if (runtime.snapshot.state === 'showing') {
+						continue;
+					}
+					releasePlacementResources(key);
+					dispatchPlacement(key, { type: 'RESET' });
+				}
+				setInit(initReducer(init, { type: 'DISABLE' }));
+			} else {
+				setInit(initReducer(init, { type: 'ENABLE' }));
+			}
+		},
+
+		setAppActive(active) {
+			if (disposed) {
+				return;
+			}
+			appActive = active;
+			if (!active) {
+				return;
+			}
+			// 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) {
+				if (
+					runtime.snapshot.state === 'ready' &&
+					runtime.snapshot.loadedAtMs !== null &&
+					isStale(runtime.snapshot.loadedAtMs, current, resolved.timeouts.adValidity)
+				) {
+					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)!;
+			const promise = loadFullScreen(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' };
+			}
+
+			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(), resolved.timeouts.adValidity)
+			) {
+				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 (!enabled || !engine.isAvailable()) {
+				return 'unavailable';
+			}
+			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;
+		},
+
+		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 enabled && 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;
+			for (const key of placements.keys()) {
+				releasePlacementResources(key);
+				placements.get(key)?.listeners.clear();
+			}
+			timers.clearAll();
+			lock.reset();
+			statusListeners.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;