@chipmobilesdk/rn-payment 0.0.0-stage → 0.2.0

package/src/engine/engine.ts

@@ -0,0 +1,951 @@
+/**
+ * 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 resolved = validateConfig(config, deps.platform ?? 'android');
+
+	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>();
+	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;
+	// 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 || reconnectAttempts >= resolved.retry.reconnect.maxAttempts) {
+			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,
+		snapshot: () => currentSnapshot,
+		commit,
+		emit,
+		now,
+		disposed: () => disposed,
+	});
+
+	const products = createProducts({
+		resolved,
+		provider,
+		emit,
+		now,
+	});
+
+	const purchaseFlow = createPurchaseFlow({
+		config,
+		resolved,
+		provider,
+		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 => {
+		purchaseSub = provider.observePurchases(purchase => {
+			if (disposed) {
+				return;
+			}
+			purchaseFlow.ingest(purchase).catch(() => undefined);
+		});
+	};
+
+	const watchConnection = (): void => {
+		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',
+					}),
+				};
+			}
+
+			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();
+				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).
+			return 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,
+					});
+
+					// Every sync is also a chance to settle what a previous session left
+					// owed. A pending purchase that completed while the app was closed
+					// arrives here, and so does a transaction whose acknowledgement failed
+					// last time (FR-039, FR-042).
+					await finalizer.drain();
+
+					// And a chance to settle a backend decision we had to defer. Done on
+					// sync rather than on a timer of ours, so recovery follows the app's
+					// own rhythm (FR-072a).
+					await purchaseFlow.revalidate();
+
+					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 };
+				}
+			});
+		},
+
+		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> {
+			// 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;
+}