@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/engine/engine.ts

@@ -1,999 +1,921 @@
-/**
- * The engine: status, initialization, entitlement reads, and sync.
- *
- * Owns the concurrency guarantees that make three requirements structurally true
- * rather than hoped for — one connection under concurrent init (FR-018), one
- * store request under concurrent sync (FR-063), and a rate-limited foreground
- * sync (PERF-002).
- *
- * It never imports a store type. The only thing it talks to is `ProviderPort`,
- * which is what keeps the binding replaceable and iOS additive (FR-002, FR-007).
- */
-
-import {
-	assertEnvironmentSafe,
-	mayCreateRealTransaction,
-	validateConfig,
-	type ResolvedConfig,
-	type TargetPlatform,
-} from '../config/validate';
-import type {
-	BlockedOperation,
-	EntitlementKey,
-	FinalizeResult,
-	PaymentConfig,
-	PaymentStatus,
-	PendingPurchasesState,
-	ProductKey,
-	PurchaseOptions,
-	PurchaseResult,
-	TransactionRef,
-	UnfinalizedSummary,
-	Unsubscribe,
-} from '../config/types';
-import { PaymentError, redact } from '../diagnostics/errors';
-import {
-	createCorrelationId,
-	createEmitter,
-	type PaymentEmitter,
-	type PaymentEvent,
-	type PaymentEventInput,
-	type PaymentEventListener,
-	type SyncTrigger,
-} from '../diagnostics/events';
-import {
-	createExclusive,
-	createRateLimiter,
-	createSingleFlight,
-	withTimeout,
-} from '../core/mutex';
-import { createFinalizer } from './finalize';
-import { createProducts, type ProductQueryResult } from './products';
-import { createPurchaseFlow } from './purchase';
-import {
-	createSubscriptions,
-	type PriceChangeResult,
-	type ProrationMode,
-} from './subscriptions';
-import { backoffDelayMs } from '../core/retry';
-import {
-	createSnapshotStore,
-	type SnapshotStore,
-} from '../persistence/mmkv-store';
-import {
-	emptySnapshot,
-	resolveFinalizeState,
-	type PersistedPurchase,
-	type PersistedSnapshot,
-} from '../persistence/snapshot';
-import {
-	aggregate,
-	diffEntitlements,
-	initialEntitlements,
-	type EntitlementMap,
-	type EntitlementState,
-} from '../entitlements/aggregate';
-import { productKeyForStoreId } from '../entitlements/mapping';
-import {
-	derivePending,
-	pendingTransitions,
-	samePending,
-	UNKNOWN_PENDING,
-} from './pending';
-import type { ProviderPort, ProviderPurchase } from '../adapter/port';
-
-export type SyncOutcome =
-	| { ok: true; restoredCount: number; revokedCount: number }
-	| { ok: false; error: PaymentError };
-
-export type RestoreOutcome =
-	| { ok: true; restored: true; entitlements: EntitlementKey[] }
-	/** Distinct from a failure so an app never shows a false success (FR-061). */
-	| { ok: true; restored: false }
-	| { ok: false; error: PaymentError };
-
-export type InitOutcome =
-	| { ok: true }
-	| { ok: false; error: PaymentError };
-
-export interface EngineDeps {
-	/** Injected so the fake store is a drop-in replacement (NFR-007). */
-	provider: ProviderPort;
-	snapshotStore?: SnapshotStore;
-	platform?: TargetPlatform;
-	now?: () => number;
-}
-
-export interface PaymentEngine {
-	initialize(): Promise<InitOutcome>;
-	cleanup(): void;
-
-	getStatus(): PaymentStatus;
-	subscribeStatus(listener: (status: PaymentStatus) => void): Unsubscribe;
-
-	getEntitlement(key: EntitlementKey): EntitlementState;
-	getAllEntitlements(): EntitlementMap;
-	subscribeEntitlements(
-		listener: (entitlements: EntitlementMap) => void,
-	): Unsubscribe;
-
-	/**
-	 * Purchases whose money has not arrived, in this session or an earlier one
-	 * (FR-101). Synchronous and in-memory, like `getEntitlement`. Added in 0.2.0.
-	 */
-	getPendingPurchases(): PendingPurchasesState;
-	/** Pushed only when the set, its status, or its staleness changes (FR-101). */
-	subscribePendingPurchases(
-		listener: (pending: PendingPurchasesState) => void,
-	): Unsubscribe;
-
-	sync(trigger?: SyncTrigger): Promise<SyncOutcome>;
-	restore(): Promise<RestoreOutcome>;
-	getLastSyncedAt(): number | undefined;
-	clearLocalData(): Promise<void>;
-
-	subscribeEvents(listener: PaymentEventListener): Unsubscribe;
-	/** Exposed for diagnostics and tests; not part of the public package surface. */
-	resolvedConfig(): ResolvedConfig;
-	nextCorrelationId(): string;
-	emitter(): PaymentEmitter;
-	snapshot(): PersistedSnapshot;
-	commitSnapshot(next: PersistedSnapshot): void;
-	mayCreateRealTransaction(): boolean;
-	recordBlockedOperation(productKey: ProductKey): void;
-
-	// --- Purchase and finalization (US2, US3, US5) ---------------------------
-	purchase(
-		productKey: ProductKey,
-		options?: PurchaseOptions,
-	): Promise<PurchaseResult>;
-	/** App-triggered consumption of a consumable (FR-043). */
-	consume(ref: TransactionRef): Promise<FinalizeResult>;
-	/** Paid-but-unsettled transactions, so the condition is observable (FR-045). */
-	getUnfinalized(): UnfinalizedSummary[];
-
-	// --- Products and pricing (US11) -----------------------------------------
-	getProducts(productKeys: ProductKey[]): Promise<ProductQueryResult>;
-	refreshProducts(productKeys: ProductKey[]): Promise<ProductQueryResult>;
-
-	// --- Subscriptions (US12) ------------------------------------------------
-	changePlan(
-		fromProductKey: ProductKey,
-		toProductKey: ProductKey,
-		mode: ProrationMode,
-		options?: PurchaseOptions,
-	): Promise<PurchaseResult>;
-	/** Opens the **store's** management screen; never a self-built one (FR-066). */
-	openSubscriptionManagement(productKey?: ProductKey): Promise<void>;
-	confirmPriceChange(productKey: ProductKey): Promise<PriceChangeResult>;
-
-	// --- Lifecycle -----------------------------------------------------------
-	/**
-	 * Call when the app returns to the foreground (FR-059).
-	 *
-	 * Left to the app rather than subscribing to `AppState` internally: the package
-	 * must not decide what "foreground" means for a host that may be backgrounded
-	 * by its own modal, a biometric prompt, or the store's purchase sheet. The
-	 * engine rate-limits it regardless (PERF-002).
-	 */
-	handleForeground(): Promise<void>;
-}
-
-export function createEngine(
-	config: PaymentConfig,
-	deps: EngineDeps,
-): PaymentEngine {
-	// Both run before anything connects: a bad catalog or an unsafe environment
-	// must fail at configuration time, not when a user taps Buy.
-	assertEnvironmentSafe(config);
-	const platform = deps.platform ?? 'android';
-	const resolved = validateConfig(config, platform);
-
-	const now = deps.now ?? (() => Date.now());
-	const provider = deps.provider;
-	const store = deps.snapshotStore ?? createSnapshotStore();
-	// A listener that throws is a consumer bug, so it is routed to the app's own
-	// logger rather than back into the event stream (FR-080, FR-081). Swallowing it
-	// entirely would hide a broken analytics adapter indefinitely.
-	const emitter = createEmitter((error, event) => {
-		config.logger?.error?.('payment event listener threw', {
-			eventType: event.type,
-			reason: redact(error),
-		});
-	});
-	const correlationCounter = { next: 1 };
-
-	const initFlight = createSingleFlight<InitOutcome>();
-	const syncFlight = createSingleFlight<SyncOutcome>();
-	/** Finalize drain and revalidation, joined the same way but outside the sync flight. */
-	const settleFlight = createSingleFlight<void>();
-	const foregroundLimiter = createRateLimiter(
-		resolved.foregroundSyncMinIntervalMs,
-		now,
-	);
-
-	let disposed = false;
-	let hasSynced = false;
-	let currentSnapshot: PersistedSnapshot = emptySnapshot(config.scopeToken);
-	let entitlements: EntitlementMap = initialEntitlements(resolved);
-	let status: PaymentStatus = {
-		kind: resolved.enabled ? 'not_started' : 'disabled',
-		blockedOperations: [],
-	};
-
-	let pending: PendingPurchasesState = UNKNOWN_PENDING;
-
-	const statusListeners = new Set<(status: PaymentStatus) => void>();
-	const entitlementListeners = new Set<(map: EntitlementMap) => void>();
-	const pendingListeners = new Set<(pending: PendingPurchasesState) => void>();
-	let connectionSub: Unsubscribe | undefined;
-	let purchaseSub: Unsubscribe | undefined;
-	let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
-	let reconnectAttempts = 0;
-	/**
-	 * Set once a connection has succeeded and the watchers are attached. Recovery
-	 * after an exhausted reconnect budget is only meaningful from there; a first
-	 * connection that failed is the app's to retry through `initialize`.
-	 */
-	let everConnected = false;
-	// Exclusive rather than single-flight: a second purchase must be refused, not
-	// joined onto the first, and never queued (FR-031).
-	const purchaseLock = createExclusive();
-
-	const emit = (event: PaymentEventInput) => {
-		emitter.emit({ ...event, timestamp: event.timestamp ?? now() } as PaymentEvent);
-	};
-
-	const setStatus = (next: Partial<PaymentStatus>): void => {
-		if (disposed) {
-			return;
-		}
-		status = { ...status, ...next };
-		emit({
-			type: 'initialization',
-			status: status.kind,
-			unavailableReason: status.unavailableReason,
-			retryable: status.retryable,
-		});
-		for (const listener of [...statusListeners]) {
-			// A throwing status listener must not break the state machine (FR-081).
-			try {
-				listener(status);
-			} catch {
-				/* reported through the emitter's own guard */
-			}
-		}
-	};
-
-	/**
-	 * Recomputes entitlements and emits only genuine transitions.
-	 *
-	 * Diff-based emission is what gives the exactly-once guarantees: a renewal
-	 * that changes nothing produces no event (FR-068), and an entitlement with
-	 * several sources fires once, not once per source (FR-079).
-	 */
-	const recompute = (): void => {
-		if (disposed) {
-			return;
-		}
-		const previous = entitlements;
-		entitlements = aggregate({
-			config: resolved,
-			snapshot: currentSnapshot,
-			hasSynced,
-			reportsGraceAndHoldDistinctly:
-				provider.capabilities().reportsGraceAndHoldDistinctly,
-			now: now(),
-		});
-
-		for (const change of diffEntitlements(previous, entitlements)) {
-			if (change.next === 'entitled') {
-				emit({
-					type: 'entitlement_granted',
-					entitlementKey: change.key,
-					sources: change.sources,
-				});
-			} else if (change.previous === 'entitled') {
-				emit({
-					type: 'entitlement_revoked',
-					entitlementKey: change.key,
-					reason: 'revoked_by_store',
-				});
-			}
-		}
-
-		for (const listener of [...entitlementListeners]) {
-			try {
-				listener(entitlements);
-			} catch {
-				/* a broken consumer callback must not stop the others (FR-081) */
-			}
-		}
-
-		publishPending(
-			derivePending({
-				config: resolved,
-				snapshot: currentSnapshot,
-				hasSynced,
-				now: now(),
-			}),
-		);
-	};
-
-	/**
-	 * Hands listeners the pending set, but only when it changed (FR-101).
-	 *
-	 * Unlike entitlements this is diffed, because a sync that changes nothing is
-	 * the common case and an app rendering "payment pending" has no use for a
-	 * re-render that says the same thing.
-	 */
-	const publishPending = (next: PendingPurchasesState): void => {
-		if (samePending(pending, next)) {
-			return;
-		}
-		pending = next;
-		for (const listener of [...pendingListeners]) {
-			try {
-				listener(pending);
-			} catch {
-				/* a broken consumer callback must not stop the others (FR-081) */
-			}
-		}
-	};
-
-	const commit = (next: PersistedSnapshot): void => {
-		// Read before the swap: a transition is "pending before, not pending now",
-		// and only the commit sees both sides (FR-104).
-		const ended = pendingTransitions(currentSnapshot, next, resolved, transactionId =>
-			provider.pendingEndReason?.(transactionId),
-		);
-		currentSnapshot = next;
-		store.save(next);
-		// Before `recompute`, so `settled` precedes the `entitlement_granted` it
-		// causes — an app that hides "payment pending" on the first event never
-		// shows the grant and the pending row at once (FR-102).
-		for (const transition of ended) {
-			emit({
-				type: 'purchase_pending_resolved',
-				productKey: transition.productKey,
-				outcome: transition.outcome,
-			});
-		}
-		recompute();
-	};
-
-	/**
-	 * Loads the persisted snapshot and makes it trustworthy.
-	 *
-	 * Shared by both initialization paths so they cannot drift. `hasSynced` is the
-	 * subtle part: a record carrying a `lastSyncedAt` was written by a sync that
-	 * genuinely succeeded, so it is a basis for asserting entitlement. Without
-	 * setting it, a build with selling disabled would report `unknown` forever,
-	 * because no sync will ever run to mark the snapshot good (FR-012, FR-053).
-	 */
-	const hydrate = (): void => {
-		currentSnapshot = store.load(config.scopeToken);
-		if (currentSnapshot.lastSyncedAt !== undefined) {
-			hasSynced = true;
-		}
-		if (!store.isDurable()) {
-			emit({
-				type: 'config_warning',
-				detail:
-					'Local storage unavailable; entitlements will not survive restart',
-			});
-		}
-		recompute();
-	};
-
-	/** Translates store purchases into persisted records, dropping unknown products. */
-	const toPersisted = (purchases: ProviderPurchase[]): PersistedPurchase[] => {
-		const records: PersistedPurchase[] = [];
-		for (const purchase of purchases) {
-			const productKey = productKeyForStoreId(resolved, purchase.storeProductId);
-			if (!productKey) {
-				// Legitimately possible: a user owns something from a build whose
-				// catalog has since changed. Ignored rather than treated as impossible.
-				continue;
-			}
-			const entry = resolved.entries.get(productKey);
-			if (!entry) {
-				continue;
-			}
-			const existing = currentSnapshot.purchases.find(
-				p => p.transactionId === purchase.transactionId,
-			);
-			if (purchase.state === 'unspecified') {
-				// The store reported a state it could not name. That is no basis for
-				// granting, finalizing, or ending anything: a new transaction is left
-				// out until the store says what it is, and a known one keeps what we
-				// already knew. 0.1.0 recorded it as `purchased` — a grant, and an
-				// acknowledgement of a purchase nobody confirmed.
-				if (existing) {
-					records.push(existing);
-				}
-				continue;
-			}
-			records.push({
-				transactionId: purchase.transactionId,
-				productKey,
-				productType: entry.productType,
-				token: purchase.token,
-				state: purchase.state === 'pending' ? 'pending' : 'purchased',
-				purchasedAt: purchase.purchasedAt,
-				// Preserve finalize progress across syncs: a sync must never reset a
-				// queued acknowledgement and lose the paid transaction.
-				finalizeState: resolveFinalizeState(purchase, existing),
-				attempts: existing?.attempts ?? 0,
-				validationState: existing?.validationState ?? 'not_required',
-				expiresAt: purchase.expiresAt,
-				willAutoRenew: purchase.willAutoRenew,
-			});
-		}
-		return records;
-	};
-
-	const scheduleReconnect = (): void => {
-		if (disposed) {
-			return;
-		}
-		if (reconnectAttempts >= resolved.retry.reconnect.maxAttempts) {
-			// Out of budget for now, not for good. Reported as a retryable failure
-			// rather than left at `connecting`, which promised a reconnect nobody
-			// was going to make; `handleForeground` starts a fresh budget.
-			setStatus({ kind: 'failed', retryable: true, reconnectAttempts });
-			return;
-		}
-		const attempt = reconnectAttempts + 1;
-		const delay = backoffDelayMs(attempt, resolved.retry.reconnect);
-		reconnectTimer = setTimeout(() => {
-			reconnectTimer = undefined;
-			if (disposed) {
-				return;
-			}
-			reconnectAttempts = attempt;
-			setStatus({ kind: 'connecting', reconnectAttempts });
-			reconnectOnce().catch(() => undefined);
-		}, delay);
-	};
-
-	/**
-	 * One reconnect attempt: a full teardown-then-connect cycle, deliberately.
-	 *
-	 * The upstream binding's own `reconnect()` has reported success without
-	 * rebuilding anything (openiap#408), so we never trust a shortcut here.
-	 */
-	const reconnectOnce = async (): Promise<void> => {
-		try {
-			await provider.disconnect();
-		} catch {
-			/* already down; nothing to tear down */
-		}
-		const outcome = await provider.connect();
-		if (disposed) {
-			return;
-		}
-		if (outcome.ok) {
-			reconnectAttempts = 0;
-			setStatus({ kind: 'ready', reconnectAttempts: 0 });
-		} else {
-			scheduleReconnect();
-		}
-	};
-
-	const finalizer = createFinalizer({
-		provider,
-		retry: resolved.retry,
-		attemptTimeoutMs: resolved.timeouts.finalizeAttemptMs,
-		snapshot: () => currentSnapshot,
-		commit,
-		emit,
-		now,
-		disposed: () => disposed,
-	});
-
-	const products = createProducts({
-		resolved,
-		provider,
-		emit,
-		now,
-	});
-
-	const purchaseFlow = createPurchaseFlow({
-		config,
-		resolved,
-		provider,
-		platform,
-		finalizer,
-		snapshot: () => currentSnapshot,
-		commit,
-		emit,
-		now,
-		nextCorrelationId: () => createCorrelationId(correlationCounter),
-		statusKind: () => status.kind,
-		mayCreateRealTransaction: () => mayCreateRealTransaction(config),
-		recordBlockedOperation: productKey =>
-			engine.recordBlockedOperation(productKey),
-		// `already_owned` triggers a re-sync rather than surfacing an error, which is
-		// how a reinstall repairs itself (FR-033). Fire-and-forget: the caller gets
-		// its typed result now and the entitlement arrives via the change signal.
-		requestSync: trigger => {
-			engine.sync(trigger).catch(() => undefined);
-		},
-		runExclusive: operation => purchaseLock.run(operation),
-	});
-
-	const subscriptions = createSubscriptions({
-		resolved,
-		provider,
-		snapshot: () => currentSnapshot,
-		purchase: (productKey, options) =>
-			purchaseFlow.purchase(productKey, options),
-	});
-
-	/**
-	 * Watches for store-pushed purchase updates.
-	 *
-	 * This is the channel a pending purchase settling between sessions arrives on
-	 * (FR-039), so it must stay subscribed for the whole session, not only while a
-	 * purchase is open.
-	 */
-	const watchPurchases = (): void => {
-		// Replaced, never stacked: a second subscription would ingest every update twice.
-		purchaseSub?.();
-		purchaseSub = provider.observePurchases(purchase => {
-			if (disposed) {
-				return;
-			}
-			purchaseFlow.ingest(purchase).catch(() => undefined);
-		});
-	};
-
-	const watchConnection = (): void => {
-		connectionSub?.();
-		connectionSub = provider.observeConnection((connected, reason) => {
-			if (disposed) {
-				return;
-			}
-			emit({
-				type: 'connection_changed',
-				connected,
-				reason,
-				attempt: reconnectAttempts,
-			});
-			if (!connected && status.kind === 'ready') {
-				setStatus({ kind: 'connecting' });
-				scheduleReconnect();
-			}
-		});
-	};
-
-	const engine: PaymentEngine = {
-		async initialize(): Promise<InitOutcome> {
-			if (!resolved.enabled) {
-				// Selling is off, but entitlements already held stay readable — turning
-				// off sales is not the same as taking away what someone bought (FR-012).
-				// Hydration runs here too: without it a previously granted entitlement
-				// would read `unknown` forever in a build with selling disabled, because
-				// no sync will ever run to mark the snapshot trustworthy.
-				setStatus({ kind: 'disabled' });
-				hydrate();
-				return {
-					ok: false,
-					error: new PaymentError({
-						code: 'PAYMENT_DISABLED',
-						message: 'Payments are disabled by configuration',
-						operation: 'initialize',
-					}),
-				};
-			}
-
-			// Already up: answered without reconnecting. `initFlight` only joins
-			// concurrent callers, so a later sequential call used to run the whole
-			// connection again and leave a second set of native listeners behind.
-			if (status.kind === 'ready') {
-				return { ok: true };
-			}
-
-			return initFlight.run(async () => {
-				if (disposed) {
-					return {
-						ok: false as const,
-						error: new PaymentError({
-							code: 'PAYMENT_NOT_CONFIGURED',
-							message: 'Engine has been cleaned up',
-							operation: 'initialize',
-						}),
-					};
-				}
-
-				setStatus({ kind: 'connecting' });
-
-				// Hydrate before connecting so a warm start can answer entitlement
-				// questions from the last good sync while the network is still in
-				// flight (FR-053).
-				hydrate();
-
-				const outcome = await withTimeout(
-					provider.connect(),
-					resolved.timeouts.connectMs,
-					() =>
-						new PaymentError({
-							code: 'PAYMENT_TIMEOUT',
-							message: 'Connecting to the billing service timed out',
-							operation: 'initialize',
-							retryable: true,
-						}),
-				).catch((error: PaymentError) => ({
-					ok: false as const,
-					reason: 'store_error' as const,
-					retryable: error.retryable,
-				}));
-
-				if (!outcome.ok) {
-					if (outcome.reason === 'store_error') {
-						setStatus({ kind: 'failed', retryable: outcome.retryable });
-						return {
-							ok: false as const,
-							error: new PaymentError({
-								code: 'PAYMENT_STORE_ERROR',
-								message: 'Could not connect to the billing service',
-								operation: 'initialize',
-								retryable: outcome.retryable,
-							}),
-						};
-					}
-					// No billing service, an outdated one, or an unsupported platform:
-					// each distinguishable, and none of them may break the host app
-					// (FR-021, FR-023).
-					setStatus({
-						kind: 'unavailable',
-						unavailableReason: outcome.reason,
-						retryable: outcome.retryable,
-					});
-					return {
-						ok: false as const,
-						error: new PaymentError({
-							code:
-								outcome.reason === 'platform_unsupported'
-									? 'PAYMENT_UNSUPPORTED_PLATFORM'
-									: 'PAYMENT_UNAVAILABLE',
-							message: `Billing unavailable: ${outcome.reason}`,
-							operation: 'initialize',
-							retryable: outcome.retryable,
-						}),
-					};
-				}
-
-				watchConnection();
-				watchPurchases();
-				everConnected = true;
-				setStatus({ kind: 'ready', reconnectAttempts: 0 });
-				await engine.sync('initialize');
-				// Drain after syncing, so a transaction the store still reports as owned
-				// has been re-queued first. This is the step that catches a purchase
-				// the previous session paid for but was killed before acknowledging
-				// (FR-042).
-				await finalizer.drain();
-				return { ok: true as const };
-			});
-		},
-
-		cleanup(): void {
-			disposed = true;
-			connectionSub?.();
-			connectionSub = undefined;
-			purchaseSub?.();
-			purchaseSub = undefined;
-			finalizer.dispose();
-			if (reconnectTimer !== undefined) {
-				clearTimeout(reconnectTimer);
-				reconnectTimer = undefined;
-			}
-			statusListeners.clear();
-			entitlementListeners.clear();
-			pendingListeners.clear();
-			// Disarmed last: after this nothing is emitted, and a late store callback
-			// is dropped safely (FR-082).
-			emitter.dispose();
-			provider.disconnect().catch(() => undefined);
-		},
-
-		getStatus: () => status,
-
-		subscribeStatus(listener): Unsubscribe {
-			if (disposed) {
-				return () => undefined;
-			}
-			statusListeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				statusListeners.delete(listener);
-			};
-		},
-
-		/** Synchronous, in-memory, zero I/O — it is read on render paths (PERF-001). */
-		getEntitlement(key): EntitlementState {
-			return (
-				entitlements[key] ?? {
-					key,
-					status: 'unknown',
-					sources: [],
-					isStale: false,
-				}
-			);
-		},
-
-		getAllEntitlements: () => entitlements,
-
-		getPendingPurchases: () => pending,
-
-		subscribePendingPurchases(listener): Unsubscribe {
-			if (disposed) {
-				return () => undefined;
-			}
-			pendingListeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				pendingListeners.delete(listener);
-			};
-		},
-
-		subscribeEntitlements(listener): Unsubscribe {
-			if (disposed) {
-				return () => undefined;
-			}
-			entitlementListeners.add(listener);
-			let removed = false;
-			return () => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				entitlementListeners.delete(listener);
-			};
-		},
-
-		async sync(trigger: SyncTrigger = 'manual'): Promise<SyncOutcome> {
-			if (disposed || !resolved.enabled) {
-				return {
-					ok: false,
-					error: new PaymentError({
-						code: 'PAYMENT_DISABLED',
-						message: 'Payments are disabled',
-						operation: 'sync',
-					}),
-				};
-			}
-
-			if (trigger === 'foreground' && !foregroundLimiter.tryAcquire()) {
-				// Rejected rather than deferred: the next foreground event will try
-				// again, whereas queueing would fire a burst once the interval elapsed.
-				return { ok: true, restoredCount: 0, revokedCount: 0 };
-			}
-
-			// Concurrent callers join one flight, so repeated syncs make exactly one
-			// store request (FR-063).
-			const outcome = await syncFlight.run(async () => {
-				try {
-					const owned = await withTimeout(
-						provider.queryOwned(),
-						resolved.timeouts.syncMs,
-						() =>
-							new PaymentError({
-								code: 'PAYMENT_TIMEOUT',
-								message: 'Syncing entitlements timed out',
-								operation: 'sync',
-								retryable: true,
-							}),
-					);
-
-					const before = new Set(
-						currentSnapshot.purchases
-							.filter(p => p.state === 'purchased')
-							.map(p => p.transactionId),
-					);
-					const records = toPersisted(owned);
-					const after = new Set(
-						records.filter(p => p.state === 'purchased').map(p => p.transactionId),
-					);
-
-					// A transaction the store no longer reports is revoked — a refund.
-					// The cache must not resurrect it (FR-064, FR-055).
-					let revokedCount = 0;
-					for (const id of before) {
-						if (!after.has(id)) {
-							revokedCount += 1;
-						}
-					}
-					let restoredCount = 0;
-					for (const id of after) {
-						if (!before.has(id)) {
-							restoredCount += 1;
-						}
-					}
-
-					hasSynced = true;
-					commit({
-						...currentSnapshot,
-						purchases: records,
-						lastSyncedAt: now(),
-					});
-
-					emit({
-						type: 'sync_completed',
-						restoredCount,
-						revokedCount,
-						trigger,
-					});
-
-					return { ok: true as const, restoredCount, revokedCount };
-				} catch (error) {
-					const paymentError =
-						error instanceof PaymentError
-							? error
-							: new PaymentError({
-									code: 'PAYMENT_STORE_ERROR',
-									message: 'Sync failed',
-									operation: 'sync',
-									retryable: true,
-								});
-					// A failed sync leaves the previous snapshot in place, so offline
-					// entitlements survive rather than being wiped (FR-053).
-					emit({
-						type: 'internal_error',
-						code: paymentError.code,
-						operation: 'sync',
-					});
-					return { ok: false as const, error: paymentError };
-				}
-			});
-
-			if (outcome.ok) {
-				// Every sync is also a chance to settle what a previous session left
-				// owed — a pending purchase that completed while the app was closed, a
-				// transaction whose acknowledgement failed last time (FR-039, FR-042) —
-				// and a backend decision we had to defer, on the app's own rhythm
-				// rather than a timer of ours (FR-072a).
-				//
-				// Outside the sync flight on purpose. Inside it, one store call or hook
-				// that never answered held the flight, and every later sync joined that
-				// same stuck promise for the rest of the session.
-				await settleFlight.run(async () => {
-					await finalizer.drain();
-					await purchaseFlow.revalidate();
-				});
-			}
-			return outcome;
-		},
-
-		async restore(): Promise<RestoreOutcome> {
-			const outcome = await engine.sync('manual');
-			if (!outcome.ok) {
-				return { ok: false, error: outcome.error };
-			}
-			const held = Object.values(entitlements)
-				.filter(e => e.status === 'entitled')
-				.map(e => e.key);
-			// "Nothing found" is a distinct success, so an app never claims to have
-			// restored purchases that do not exist (FR-061).
-			return held.length > 0
-				? { ok: true, restored: true, entitlements: held }
-				: { ok: true, restored: false };
-		},
-
-		getLastSyncedAt: () => currentSnapshot.lastSyncedAt,
-
-		async clearLocalData(): Promise<void> {
-			store.clearAll();
-			currentSnapshot = emptySnapshot(config.scopeToken);
-			hasSynced = false;
-			// Back to `unknown`, not `not_entitled`: after a logout the package has no
-			// basis for either claim until the next sync.
-			entitlements = initialEntitlements(resolved);
-			for (const listener of [...entitlementListeners]) {
-				try {
-					listener(entitlements);
-				} catch {
-					/* ignore */
-				}
-			}
-			// Same reasoning, and no `purchase_pending_resolved`: the records were
-			// discarded locally, not ended at the store.
-			publishPending(UNKNOWN_PENDING);
-		},
-
-		subscribeEvents: listener => emitter.subscribe(listener),
-		resolvedConfig: () => resolved,
-		nextCorrelationId: () => createCorrelationId(correlationCounter),
-		emitter: () => emitter,
-		snapshot: () => currentSnapshot,
-		commitSnapshot: commit,
-		mayCreateRealTransaction: () => mayCreateRealTransaction(config),
-
-		purchase(productKey, options) {
-			return purchaseFlow.purchase(productKey, options);
-		},
-
-		consume(ref) {
-			return finalizer.consume(ref);
-		},
-
-		getUnfinalized() {
-			return finalizer.unfinalized();
-		},
-
-		getProducts(productKeys) {
-			return products.get(productKeys);
-		},
-
-		refreshProducts(productKeys) {
-			return products.refresh(productKeys);
-		},
-
-		changePlan(fromProductKey, toProductKey, mode, options) {
-			return subscriptions.changePlan(
-				fromProductKey,
-				toProductKey,
-				mode,
-				options,
-			);
-		},
-
-		openSubscriptionManagement(productKey) {
-			return subscriptions.openManagement(productKey);
-		},
-
-		confirmPriceChange(productKey) {
-			return subscriptions.confirmPriceChange(productKey);
-		},
-
-		async handleForeground(): Promise<void> {
-			// A foreground return is the natural moment to try again after the
-			// reconnect budget ran out: the network the app lost while backgrounded
-			// is usually back. A fresh budget, and one immediate attempt.
-			if (
-				everConnected &&
-				!disposed &&
-				status.kind === 'failed' &&
-				reconnectTimer === undefined
-			) {
-				reconnectAttempts = 0;
-				setStatus({ kind: 'connecting', reconnectAttempts: 0 });
-				await reconnectOnce().catch(() => undefined);
-			}
-			// Rate-limited inside sync, so an app that calls this on every incidental
-			// foreground transition still produces at most one request per interval.
-			await engine.sync('foreground');
-		},
-
-		/**
-		 * Records a purchase refused because this environment may not move real
-		 * money (FR-014). Written into status, not just logged, so a test can
-		 * assert the block happened.
-		 */
-		recordBlockedOperation(productKey: ProductKey): void {
-			const blocked: BlockedOperation = {
-				productKey,
-				environment: config.environment,
-				at: now(),
-			};
-			setStatus({ blockedOperations: [...status.blockedOperations, blocked] });
-			emit({
-				type: 'environment_blocked',
-				productKey,
-				environment: config.environment,
-			});
-		},
-	};
-
-	return engine;
-}
+/**
+ * The engine: status, initialization, entitlement reads, and sync.
+ *
+ * Owns the concurrency guarantees that make three requirements structurally true
+ * rather than hoped for — one connection under concurrent init (FR-018), one
+ * store request under concurrent sync (FR-063), and a rate-limited foreground
+ * sync (PERF-002).
+ *
+ * It never imports a store type. The only thing it talks to is `ProviderPort`,
+ * which is what keeps the binding replaceable and iOS additive (FR-002, FR-007).
+ */
+
+import { createListenerSet, currentPlatform } from '@chipmobilesdk/rn-core';
+
+import {
+	assertEnvironmentSafe,
+	mayCreateRealTransaction,
+	validateConfig,
+	type ResolvedConfig,
+	type TargetPlatform,
+} from '../config/validate';
+import type {
+	BlockedOperation,
+	EntitlementKey,
+	FinalizeResult,
+	PaymentConfig,
+	PaymentStatus,
+	PendingPurchasesState,
+	ProductKey,
+	PurchaseOptions,
+	PurchaseResult,
+	TransactionRef,
+	UnfinalizedSummary,
+	Unsubscribe,
+} from '../config/types';
+import { PaymentError, redact } from '../diagnostics/errors';
+import {
+	createCorrelationId,
+	createEmitter,
+	type PaymentEmitter,
+	type PaymentEvent,
+	type PaymentEventInput,
+	type PaymentEventListener,
+	type SyncTrigger,
+} from '../diagnostics/events';
+import { createExclusive, createRateLimiter, createSingleFlight, withTimeout } from '../core/mutex';
+import { createFinalizer } from './finalize';
+import { createProducts, type ProductQueryResult } from './products';
+import { createPurchaseFlow } from './purchase';
+import { createSubscriptions, type PriceChangeResult, type ProrationMode } from './subscriptions';
+import { backoffDelayMs } from '../core/retry';
+import { createSnapshotStore, type SnapshotStore } from '../persistence/mmkv-store';
+import {
+	emptySnapshot,
+	resolveFinalizeState,
+	type PersistedPurchase,
+	type PersistedSnapshot,
+} from '../persistence/snapshot';
+import {
+	aggregate,
+	diffEntitlements,
+	initialEntitlements,
+	type EntitlementMap,
+	type EntitlementState,
+	shareUnchanged,
+} from '../entitlements/aggregate';
+import { productKeyForStoreId } from '../entitlements/mapping';
+import { derivePending, pendingTransitions, samePending, UNKNOWN_PENDING } from './pending';
+import type { ProviderPort, ProviderPurchase } from '../adapter/port';
+
+export type SyncOutcome =
+	{ ok: true; restoredCount: number; revokedCount: number } | { ok: false; error: PaymentError };
+
+export type RestoreOutcome =
+	| { ok: true; restored: true; entitlements: EntitlementKey[] }
+	/** Distinct from a failure so an app never shows a false success (FR-061). */
+	| { ok: true; restored: false }
+	| { ok: false; error: PaymentError };
+
+export type InitOutcome = { ok: true } | { ok: false; error: PaymentError };
+
+export interface EngineDeps {
+	/** Injected so the fake store is a drop-in replacement (NFR-007). */
+	provider: ProviderPort;
+	snapshotStore?: SnapshotStore;
+	platform?: TargetPlatform;
+	now?: () => number;
+}
+
+export interface PaymentEngine {
+	initialize(): Promise<InitOutcome>;
+	cleanup(): void;
+
+	getStatus(): PaymentStatus;
+	subscribeStatus(listener: (status: PaymentStatus) => void): Unsubscribe;
+
+	getEntitlement(key: EntitlementKey): EntitlementState;
+	getAllEntitlements(): EntitlementMap;
+	subscribeEntitlements(listener: (entitlements: EntitlementMap) => void): Unsubscribe;
+
+	/**
+	 * Purchases whose money has not arrived, in this session or an earlier one
+	 * (FR-101). Synchronous and in-memory, like `getEntitlement`. Added in 0.2.0.
+	 */
+	getPendingPurchases(): PendingPurchasesState;
+	/** Pushed only when the set, its status, or its staleness changes (FR-101). */
+	subscribePendingPurchases(listener: (pending: PendingPurchasesState) => void): Unsubscribe;
+
+	sync(trigger?: SyncTrigger): Promise<SyncOutcome>;
+	restore(): Promise<RestoreOutcome>;
+	getLastSyncedAt(): number | undefined;
+	clearLocalData(): Promise<void>;
+
+	subscribeEvents(listener: PaymentEventListener): Unsubscribe;
+	/** Exposed for diagnostics and tests; not part of the public package surface. */
+	resolvedConfig(): ResolvedConfig;
+	nextCorrelationId(): string;
+	emitter(): PaymentEmitter;
+	snapshot(): PersistedSnapshot;
+	commitSnapshot(next: PersistedSnapshot): void;
+	mayCreateRealTransaction(): boolean;
+	recordBlockedOperation(productKey: ProductKey): void;
+
+	// --- Purchase and finalization (US2, US3, US5) ---------------------------
+	purchase(productKey: ProductKey, options?: PurchaseOptions): Promise<PurchaseResult>;
+	/** App-triggered consumption of a consumable (FR-043). */
+	consume(ref: TransactionRef): Promise<FinalizeResult>;
+	/** Paid-but-unsettled transactions, so the condition is observable (FR-045). */
+	getUnfinalized(): UnfinalizedSummary[];
+
+	// --- Products and pricing (US11) -----------------------------------------
+	getProducts(productKeys: ProductKey[]): Promise<ProductQueryResult>;
+	refreshProducts(productKeys: ProductKey[]): Promise<ProductQueryResult>;
+
+	// --- Subscriptions (US12) ------------------------------------------------
+	changePlan(
+		fromProductKey: ProductKey,
+		toProductKey: ProductKey,
+		mode: ProrationMode,
+		options?: PurchaseOptions,
+	): Promise<PurchaseResult>;
+	/** Opens the **store's** management screen; never a self-built one (FR-066). */
+	openSubscriptionManagement(productKey?: ProductKey): Promise<void>;
+	confirmPriceChange(productKey: ProductKey): Promise<PriceChangeResult>;
+
+	// --- Lifecycle -----------------------------------------------------------
+	/**
+	 * Call when the app returns to the foreground (FR-059).
+	 *
+	 * Left to the app rather than subscribing to `AppState` internally: the package
+	 * must not decide what "foreground" means for a host that may be backgrounded
+	 * by its own modal, a biometric prompt, or the store's purchase sheet. The
+	 * engine rate-limits it regardless (PERF-002).
+	 */
+	handleForeground(): Promise<void>;
+}
+
+export function createEngine(config: PaymentConfig, deps: EngineDeps): PaymentEngine {
+	// Both run before anything connects: a bad catalog or an unsafe environment
+	// must fail at configuration time, not when a user taps Buy.
+	assertEnvironmentSafe(config);
+	// rn-core's one platform source (CORE-09): this used to assume Android, so an
+	// iOS app validated its catalog against the Android product ids. Where neither
+	// OS applies, the store provider refuses everything as unsupported anyway.
+	const platform = deps.platform ?? (currentPlatform() === 'ios' ? 'ios' : 'android');
+	const resolved = validateConfig(config, platform);
+
+	const now = deps.now ?? (() => Date.now());
+	const provider = deps.provider;
+	const store = deps.snapshotStore ?? createSnapshotStore();
+	// A listener that throws is a consumer bug, so it is routed to the app's own
+	// logger rather than back into the event stream (FR-080, FR-081). Swallowing it
+	// entirely would hide a broken analytics adapter indefinitely.
+	const emitter = createEmitter((error, event) => {
+		config.logger?.error?.('payment event listener threw', {
+			eventType: event.type,
+			reason: redact(error),
+		});
+	});
+	const correlationCounter = { next: 1 };
+
+	const initFlight = createSingleFlight<InitOutcome>();
+	const syncFlight = createSingleFlight<SyncOutcome>();
+	/** Finalize drain and revalidation, joined the same way but outside the sync flight. */
+	const settleFlight = createSingleFlight<void>();
+	const foregroundLimiter = createRateLimiter(resolved.foregroundSyncMinIntervalMs, now);
+
+	let disposed = false;
+	let hasSynced = false;
+	let currentSnapshot: PersistedSnapshot = emptySnapshot(config.scopeToken);
+	let entitlements: EntitlementMap = initialEntitlements(resolved);
+	let status: PaymentStatus = {
+		kind: resolved.enabled ? 'not_started' : 'disabled',
+		blockedOperations: [],
+	};
+
+	let pending: PendingPurchasesState = UNKNOWN_PENDING;
+
+	// A broken consumer callback must not stop the others nor the state machine
+	// (FR-081); rn-core isolates each one and the failure goes to the logger.
+	const listenerOptions = {
+		onListenerError: (error: unknown) =>
+			config.logger?.error?.('payment listener threw', { reason: redact(error) }),
+	};
+	const statusListeners = createListenerSet<[PaymentStatus]>(listenerOptions);
+	const entitlementListeners = createListenerSet<[EntitlementMap]>(listenerOptions);
+	const pendingListeners = createListenerSet<[PendingPurchasesState]>(listenerOptions);
+	let connectionSub: Unsubscribe | undefined;
+	let purchaseSub: Unsubscribe | undefined;
+	let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+	let reconnectAttempts = 0;
+	/**
+	 * Set once a connection has succeeded and the watchers are attached. Recovery
+	 * after an exhausted reconnect budget is only meaningful from there; a first
+	 * connection that failed is the app's to retry through `initialize`.
+	 */
+	let everConnected = false;
+	// Exclusive rather than single-flight: a second purchase must be refused, not
+	// joined onto the first, and never queued (FR-031).
+	const purchaseLock = createExclusive();
+
+	const emit = (event: PaymentEventInput) => {
+		emitter.emit({ ...event, timestamp: event.timestamp ?? now() } as PaymentEvent);
+	};
+
+	const setStatus = (next: Partial<PaymentStatus>): void => {
+		if (disposed) {
+			return;
+		}
+		status = { ...status, ...next };
+		emit({
+			type: 'initialization',
+			status: status.kind,
+			unavailableReason: status.unavailableReason,
+			retryable: status.retryable,
+		});
+		statusListeners.notify(status);
+	};
+
+	/**
+	 * Recomputes entitlements and emits only genuine transitions.
+	 *
+	 * Diff-based emission is what gives the exactly-once guarantees: a renewal
+	 * that changes nothing produces no event (FR-068), and an entitlement with
+	 * several sources fires once, not once per source (FR-079).
+	 */
+	const recompute = (): void => {
+		if (disposed) {
+			return;
+		}
+		const previous = entitlements;
+		entitlements = shareUnchanged(
+			previous,
+			aggregate({
+				config: resolved,
+				snapshot: currentSnapshot,
+				hasSynced,
+				reportsGraceAndHoldDistinctly: provider.capabilities().reportsGraceAndHoldDistinctly,
+				now: now(),
+			}),
+		);
+
+		for (const change of diffEntitlements(previous, entitlements)) {
+			if (change.next === 'entitled') {
+				emit({
+					type: 'entitlement_granted',
+					entitlementKey: change.key,
+					sources: change.sources,
+				});
+			} else if (change.previous === 'entitled') {
+				emit({
+					type: 'entitlement_revoked',
+					entitlementKey: change.key,
+					reason: 'revoked_by_store',
+				});
+			}
+		}
+
+		// Unchanged map, same object: nothing to tell a subscriber (PERF-03).
+		if (entitlements !== previous) {
+			entitlementListeners.notify(entitlements);
+		}
+
+		publishPending(
+			derivePending({
+				config: resolved,
+				snapshot: currentSnapshot,
+				hasSynced,
+				now: now(),
+			}),
+		);
+	};
+
+	/**
+	 * Hands listeners the pending set, but only when it changed (FR-101).
+	 *
+	 * Unlike entitlements this is diffed, because a sync that changes nothing is
+	 * the common case and an app rendering "payment pending" has no use for a
+	 * re-render that says the same thing.
+	 */
+	const publishPending = (next: PendingPurchasesState): void => {
+		if (samePending(pending, next)) {
+			return;
+		}
+		pending = next;
+		pendingListeners.notify(pending);
+	};
+
+	const commit = (next: PersistedSnapshot): void => {
+		// Read before the swap: a transition is "pending before, not pending now",
+		// and only the commit sees both sides (FR-104).
+		const ended = pendingTransitions(currentSnapshot, next, resolved, transactionId =>
+			provider.pendingEndReason?.(transactionId),
+		);
+		currentSnapshot = next;
+		store.save(next);
+		// Before `recompute`, so `settled` precedes the `entitlement_granted` it
+		// causes — an app that hides "payment pending" on the first event never
+		// shows the grant and the pending row at once (FR-102).
+		for (const transition of ended) {
+			emit({
+				type: 'purchase_pending_resolved',
+				productKey: transition.productKey,
+				outcome: transition.outcome,
+			});
+		}
+		recompute();
+	};
+
+	/**
+	 * Loads the persisted snapshot and makes it trustworthy.
+	 *
+	 * Shared by both initialization paths so they cannot drift. `hasSynced` is the
+	 * subtle part: a record carrying a `lastSyncedAt` was written by a sync that
+	 * genuinely succeeded, so it is a basis for asserting entitlement. Without
+	 * setting it, a build with selling disabled would report `unknown` forever,
+	 * because no sync will ever run to mark the snapshot good (FR-012, FR-053).
+	 */
+	const hydrate = (): void => {
+		currentSnapshot = store.load(config.scopeToken);
+		if (currentSnapshot.lastSyncedAt !== undefined) {
+			hasSynced = true;
+		}
+		if (!store.isDurable()) {
+			emit({
+				type: 'config_warning',
+				detail: 'Local storage unavailable; entitlements will not survive restart',
+			});
+		}
+		recompute();
+	};
+
+	/** Translates store purchases into persisted records, dropping unknown products. */
+	const toPersisted = (purchases: ProviderPurchase[]): PersistedPurchase[] => {
+		const records: PersistedPurchase[] = [];
+		for (const purchase of purchases) {
+			const productKey = productKeyForStoreId(resolved, purchase.storeProductId);
+			if (!productKey) {
+				// Legitimately possible: a user owns something from a build whose
+				// catalog has since changed. Ignored rather than treated as impossible.
+				continue;
+			}
+			const entry = resolved.entries.get(productKey);
+			if (!entry) {
+				continue;
+			}
+			const existing = currentSnapshot.purchases.find(
+				p => p.transactionId === purchase.transactionId,
+			);
+			if (purchase.state === 'unspecified') {
+				// The store reported a state it could not name. That is no basis for
+				// granting, finalizing, or ending anything: a new transaction is left
+				// out until the store says what it is, and a known one keeps what we
+				// already knew. 0.1.0 recorded it as `purchased` — a grant, and an
+				// acknowledgement of a purchase nobody confirmed.
+				if (existing) {
+					records.push(existing);
+				}
+				continue;
+			}
+			records.push({
+				transactionId: purchase.transactionId,
+				productKey,
+				productType: entry.productType,
+				token: purchase.token,
+				state: purchase.state === 'pending' ? 'pending' : 'purchased',
+				purchasedAt: purchase.purchasedAt,
+				// Preserve finalize progress across syncs: a sync must never reset a
+				// queued acknowledgement and lose the paid transaction.
+				finalizeState: resolveFinalizeState(purchase, existing),
+				attempts: existing?.attempts ?? 0,
+				validationState: existing?.validationState ?? 'not_required',
+				expiresAt: purchase.expiresAt,
+				willAutoRenew: purchase.willAutoRenew,
+			});
+		}
+		return records;
+	};
+
+	const scheduleReconnect = (): void => {
+		if (disposed) {
+			return;
+		}
+		if (reconnectAttempts >= resolved.retry.reconnect.maxAttempts) {
+			// Out of budget for now, not for good. Reported as a retryable failure
+			// rather than left at `connecting`, which promised a reconnect nobody
+			// was going to make; `handleForeground` starts a fresh budget.
+			setStatus({ kind: 'failed', retryable: true, reconnectAttempts });
+			return;
+		}
+		const attempt = reconnectAttempts + 1;
+		const delay = backoffDelayMs(attempt, resolved.retry.reconnect);
+		reconnectTimer = setTimeout(() => {
+			reconnectTimer = undefined;
+			if (disposed) {
+				return;
+			}
+			reconnectAttempts = attempt;
+			setStatus({ kind: 'connecting', reconnectAttempts });
+			reconnectOnce().catch(() => undefined);
+		}, delay);
+	};
+
+	/**
+	 * One reconnect attempt: a full teardown-then-connect cycle, deliberately.
+	 *
+	 * The upstream binding's own `reconnect()` has reported success without
+	 * rebuilding anything (openiap#408), so we never trust a shortcut here.
+	 */
+	const reconnectOnce = async (): Promise<void> => {
+		try {
+			await provider.disconnect();
+		} catch {
+			/* already down; nothing to tear down */
+		}
+		const outcome = await provider.connect();
+		if (disposed) {
+			return;
+		}
+		if (outcome.ok) {
+			reconnectAttempts = 0;
+			setStatus({ kind: 'ready', reconnectAttempts: 0 });
+		} else {
+			scheduleReconnect();
+		}
+	};
+
+	const finalizer = createFinalizer({
+		provider,
+		retry: resolved.retry,
+		attemptTimeoutMs: resolved.timeouts.finalizeAttemptMs,
+		snapshot: () => currentSnapshot,
+		commit,
+		emit,
+		now,
+		disposed: () => disposed,
+	});
+
+	const products = createProducts({
+		resolved,
+		provider,
+		emit,
+		now,
+	});
+
+	const purchaseFlow = createPurchaseFlow({
+		config,
+		resolved,
+		provider,
+		platform,
+		finalizer,
+		snapshot: () => currentSnapshot,
+		commit,
+		emit,
+		now,
+		nextCorrelationId: () => createCorrelationId(correlationCounter),
+		statusKind: () => status.kind,
+		mayCreateRealTransaction: () => mayCreateRealTransaction(config),
+		recordBlockedOperation: productKey => engine.recordBlockedOperation(productKey),
+		// `already_owned` triggers a re-sync rather than surfacing an error, which is
+		// how a reinstall repairs itself (FR-033). Fire-and-forget: the caller gets
+		// its typed result now and the entitlement arrives via the change signal.
+		requestSync: trigger => {
+			engine.sync(trigger).catch(() => undefined);
+		},
+		runExclusive: operation => purchaseLock.run(operation),
+	});
+
+	const subscriptions = createSubscriptions({
+		resolved,
+		provider,
+		snapshot: () => currentSnapshot,
+		purchase: (productKey, options) => purchaseFlow.purchase(productKey, options),
+	});
+
+	/**
+	 * Watches for store-pushed purchase updates.
+	 *
+	 * This is the channel a pending purchase settling between sessions arrives on
+	 * (FR-039), so it must stay subscribed for the whole session, not only while a
+	 * purchase is open.
+	 */
+	const watchPurchases = (): void => {
+		// Replaced, never stacked: a second subscription would ingest every update twice.
+		purchaseSub?.();
+		purchaseSub = provider.observePurchases(purchase => {
+			if (disposed) {
+				return;
+			}
+			purchaseFlow.ingest(purchase).catch(() => undefined);
+		});
+	};
+
+	const watchConnection = (): void => {
+		connectionSub?.();
+		connectionSub = provider.observeConnection((connected, reason) => {
+			if (disposed) {
+				return;
+			}
+			emit({
+				type: 'connection_changed',
+				connected,
+				reason,
+				attempt: reconnectAttempts,
+			});
+			if (!connected && status.kind === 'ready') {
+				setStatus({ kind: 'connecting' });
+				scheduleReconnect();
+			}
+		});
+	};
+
+	const engine: PaymentEngine = {
+		async initialize(): Promise<InitOutcome> {
+			if (!resolved.enabled) {
+				// Selling is off, but entitlements already held stay readable — turning
+				// off sales is not the same as taking away what someone bought (FR-012).
+				// Hydration runs here too: without it a previously granted entitlement
+				// would read `unknown` forever in a build with selling disabled, because
+				// no sync will ever run to mark the snapshot trustworthy.
+				setStatus({ kind: 'disabled' });
+				hydrate();
+				return {
+					ok: false,
+					error: new PaymentError({
+						code: 'PAYMENT_DISABLED',
+						message: 'Payments are disabled by configuration',
+						operation: 'initialize',
+					}),
+				};
+			}
+
+			// Already up: answered without reconnecting. `initFlight` only joins
+			// concurrent callers, so a later sequential call used to run the whole
+			// connection again and leave a second set of native listeners behind.
+			if (status.kind === 'ready') {
+				return { ok: true };
+			}
+
+			return initFlight.run(async () => {
+				if (disposed) {
+					return {
+						ok: false as const,
+						error: new PaymentError({
+							code: 'PAYMENT_NOT_CONFIGURED',
+							message: 'Engine has been cleaned up',
+							operation: 'initialize',
+						}),
+					};
+				}
+
+				setStatus({ kind: 'connecting' });
+
+				// Hydrate before connecting so a warm start can answer entitlement
+				// questions from the last good sync while the network is still in
+				// flight (FR-053).
+				hydrate();
+
+				const outcome = await withTimeout(
+					provider.connect(),
+					resolved.timeouts.connectMs,
+					() =>
+						new PaymentError({
+							code: 'PAYMENT_TIMEOUT',
+							message: 'Connecting to the billing service timed out',
+							operation: 'initialize',
+							retryable: true,
+						}),
+				).catch((error: PaymentError) => ({
+					ok: false as const,
+					reason: 'store_error' as const,
+					retryable: error.retryable,
+				}));
+
+				if (!outcome.ok) {
+					if (outcome.reason === 'store_error') {
+						setStatus({ kind: 'failed', retryable: outcome.retryable });
+						return {
+							ok: false as const,
+							error: new PaymentError({
+								code: 'PAYMENT_STORE_ERROR',
+								message: 'Could not connect to the billing service',
+								operation: 'initialize',
+								retryable: outcome.retryable,
+							}),
+						};
+					}
+					// No billing service, an outdated one, or an unsupported platform:
+					// each distinguishable, and none of them may break the host app
+					// (FR-021, FR-023).
+					setStatus({
+						kind: 'unavailable',
+						unavailableReason: outcome.reason,
+						retryable: outcome.retryable,
+					});
+					return {
+						ok: false as const,
+						error: new PaymentError({
+							code:
+								outcome.reason === 'platform_unsupported'
+									? 'PAYMENT_UNSUPPORTED_PLATFORM'
+									: 'PAYMENT_UNAVAILABLE',
+							message: `Billing unavailable: ${outcome.reason}`,
+							operation: 'initialize',
+							retryable: outcome.retryable,
+						}),
+					};
+				}
+
+				watchConnection();
+				watchPurchases();
+				everConnected = true;
+				setStatus({ kind: 'ready', reconnectAttempts: 0 });
+				await engine.sync('initialize');
+				// Drain after syncing, so a transaction the store still reports as owned
+				// has been re-queued first. This is the step that catches a purchase
+				// the previous session paid for but was killed before acknowledging
+				// (FR-042).
+				await finalizer.drain();
+				return { ok: true as const };
+			});
+		},
+
+		cleanup(): void {
+			disposed = true;
+			connectionSub?.();
+			connectionSub = undefined;
+			purchaseSub?.();
+			purchaseSub = undefined;
+			finalizer.dispose();
+			if (reconnectTimer !== undefined) {
+				clearTimeout(reconnectTimer);
+				reconnectTimer = undefined;
+			}
+			statusListeners.clear();
+			entitlementListeners.clear();
+			pendingListeners.clear();
+			// Disarmed last: after this nothing is emitted, and a late store callback
+			// is dropped safely (FR-082).
+			emitter.dispose();
+			provider.disconnect().catch(() => undefined);
+		},
+
+		getStatus: () => status,
+
+		subscribeStatus(listener): Unsubscribe {
+			if (disposed) {
+				return () => undefined;
+			}
+			return statusListeners.add(listener);
+		},
+
+		/** Synchronous, in-memory, zero I/O — it is read on render paths (PERF-001). */
+		getEntitlement(key): EntitlementState {
+			return (
+				entitlements[key] ?? {
+					key,
+					status: 'unknown',
+					sources: [],
+					isStale: false,
+				}
+			);
+		},
+
+		getAllEntitlements: () => entitlements,
+
+		getPendingPurchases: () => pending,
+
+		subscribePendingPurchases(listener): Unsubscribe {
+			if (disposed) {
+				return () => undefined;
+			}
+			return pendingListeners.add(listener);
+		},
+
+		subscribeEntitlements(listener): Unsubscribe {
+			if (disposed) {
+				return () => undefined;
+			}
+			return entitlementListeners.add(listener);
+		},
+
+		async sync(trigger: SyncTrigger = 'manual'): Promise<SyncOutcome> {
+			if (disposed || !resolved.enabled) {
+				return {
+					ok: false,
+					error: new PaymentError({
+						code: 'PAYMENT_DISABLED',
+						message: 'Payments are disabled',
+						operation: 'sync',
+					}),
+				};
+			}
+
+			if (trigger === 'foreground' && !foregroundLimiter.tryAcquire()) {
+				// Rejected rather than deferred: the next foreground event will try
+				// again, whereas queueing would fire a burst once the interval elapsed.
+				return { ok: true, restoredCount: 0, revokedCount: 0 };
+			}
+
+			// Concurrent callers join one flight, so repeated syncs make exactly one
+			// store request (FR-063).
+			const outcome = await syncFlight.run(async () => {
+				try {
+					const owned = await withTimeout(
+						provider.queryOwned(),
+						resolved.timeouts.syncMs,
+						() =>
+							new PaymentError({
+								code: 'PAYMENT_TIMEOUT',
+								message: 'Syncing entitlements timed out',
+								operation: 'sync',
+								retryable: true,
+							}),
+					);
+
+					const before = new Set(
+						currentSnapshot.purchases
+							.filter(p => p.state === 'purchased')
+							.map(p => p.transactionId),
+					);
+					const records = toPersisted(owned);
+					const after = new Set(
+						records.filter(p => p.state === 'purchased').map(p => p.transactionId),
+					);
+
+					// A transaction the store no longer reports is revoked — a refund.
+					// The cache must not resurrect it (FR-064, FR-055).
+					let revokedCount = 0;
+					for (const id of before) {
+						if (!after.has(id)) {
+							revokedCount += 1;
+						}
+					}
+					let restoredCount = 0;
+					for (const id of after) {
+						if (!before.has(id)) {
+							restoredCount += 1;
+						}
+					}
+
+					hasSynced = true;
+					commit({
+						...currentSnapshot,
+						purchases: records,
+						lastSyncedAt: now(),
+					});
+
+					emit({
+						type: 'sync_completed',
+						restoredCount,
+						revokedCount,
+						trigger,
+					});
+
+					return { ok: true as const, restoredCount, revokedCount };
+				} catch (error) {
+					const paymentError =
+						error instanceof PaymentError
+							? error
+							: new PaymentError({
+									code: 'PAYMENT_STORE_ERROR',
+									message: 'Sync failed',
+									operation: 'sync',
+									retryable: true,
+								});
+					// A failed sync leaves the previous snapshot in place, so offline
+					// entitlements survive rather than being wiped (FR-053).
+					emit({
+						type: 'internal_error',
+						code: paymentError.code,
+						operation: 'sync',
+					});
+					return { ok: false as const, error: paymentError };
+				}
+			});
+
+			if (outcome.ok) {
+				// Every sync is also a chance to settle what a previous session left
+				// owed — a pending purchase that completed while the app was closed, a
+				// transaction whose acknowledgement failed last time (FR-039, FR-042) —
+				// and a backend decision we had to defer, on the app's own rhythm
+				// rather than a timer of ours (FR-072a).
+				//
+				// Outside the sync flight on purpose. Inside it, one store call or hook
+				// that never answered held the flight, and every later sync joined that
+				// same stuck promise for the rest of the session.
+				await settleFlight.run(async () => {
+					await finalizer.drain();
+					await purchaseFlow.revalidate();
+				});
+			}
+			return outcome;
+		},
+
+		async restore(): Promise<RestoreOutcome> {
+			const outcome = await engine.sync('manual');
+			if (!outcome.ok) {
+				return { ok: false, error: outcome.error };
+			}
+			const held = Object.values(entitlements)
+				.filter(e => e.status === 'entitled')
+				.map(e => e.key);
+			// "Nothing found" is a distinct success, so an app never claims to have
+			// restored purchases that do not exist (FR-061).
+			return held.length > 0
+				? { ok: true, restored: true, entitlements: held }
+				: { ok: true, restored: false };
+		},
+
+		getLastSyncedAt: () => currentSnapshot.lastSyncedAt,
+
+		async clearLocalData(): Promise<void> {
+			store.clearAll();
+			currentSnapshot = emptySnapshot(config.scopeToken);
+			hasSynced = false;
+			// Back to `unknown`, not `not_entitled`: after a logout the package has no
+			// basis for either claim until the next sync.
+			entitlements = initialEntitlements(resolved);
+			entitlementListeners.notify(entitlements);
+			// Same reasoning, and no `purchase_pending_resolved`: the records were
+			// discarded locally, not ended at the store.
+			publishPending(UNKNOWN_PENDING);
+		},
+
+		subscribeEvents: listener => emitter.subscribe(listener),
+		resolvedConfig: () => resolved,
+		nextCorrelationId: () => createCorrelationId(correlationCounter),
+		emitter: () => emitter,
+		snapshot: () => currentSnapshot,
+		commitSnapshot: commit,
+		mayCreateRealTransaction: () => mayCreateRealTransaction(config),
+
+		purchase(productKey, options) {
+			return purchaseFlow.purchase(productKey, options);
+		},
+
+		consume(ref) {
+			return finalizer.consume(ref);
+		},
+
+		getUnfinalized() {
+			return finalizer.unfinalized();
+		},
+
+		getProducts(productKeys) {
+			return products.get(productKeys);
+		},
+
+		refreshProducts(productKeys) {
+			return products.refresh(productKeys);
+		},
+
+		changePlan(fromProductKey, toProductKey, mode, options) {
+			return subscriptions.changePlan(fromProductKey, toProductKey, mode, options);
+		},
+
+		openSubscriptionManagement(productKey) {
+			return subscriptions.openManagement(productKey);
+		},
+
+		confirmPriceChange(productKey) {
+			return subscriptions.confirmPriceChange(productKey);
+		},
+
+		async handleForeground(): Promise<void> {
+			// A foreground return is the natural moment to try again after the
+			// reconnect budget ran out: the network the app lost while backgrounded
+			// is usually back. A fresh budget, and one immediate attempt.
+			if (everConnected && !disposed && status.kind === 'failed' && reconnectTimer === undefined) {
+				reconnectAttempts = 0;
+				setStatus({ kind: 'connecting', reconnectAttempts: 0 });
+				await reconnectOnce().catch(() => undefined);
+			}
+			// Rate-limited inside sync, so an app that calls this on every incidental
+			// foreground transition still produces at most one request per interval.
+			await engine.sync('foreground');
+		},
+
+		/**
+		 * Records a purchase refused because this environment may not move real
+		 * money (FR-014). Written into status, not just logged, so a test can
+		 * assert the block happened.
+		 */
+		recordBlockedOperation(productKey: ProductKey): void {
+			const blocked: BlockedOperation = {
+				productKey,
+				environment: config.environment,
+				at: now(),
+			};
+			setStatus({ blockedOperations: [...status.blockedOperations, blocked] });
+			emit({
+				type: 'environment_blocked',
+				productKey,
+				environment: config.environment,
+			});
+		},
+	};
+
+	return engine;
+}