@chipmobilesdk/rn-payment 0.5.0 → 0.6.0

package/src/engine/engine.ts

@@ -8,15 +8,19 @@
  *
  * 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).
+ *
+ * This file composes (PAY-10): state and its publication live in `state.ts`, the
+ * connection in `connection.ts`, sync in `sync.ts`, and the internals tests reach
+ * for in `internals.ts`, off the public type (PAY-11).
  */
 
-import { createListenerSet, currentPlatform } from '@chipmobilesdk/rn-core';
+import { currentPlatform } from '@chipmobilesdk/rn-core';
 
+import type { ProviderPort } from '../adapter/port';
 import {
 	assertEnvironmentSafe,
 	mayCreateRealTransaction,
 	validateConfig,
-	type ResolvedConfig,
 	type TargetPlatform,
 } from '../config/validate';
 import type {
@@ -33,43 +37,26 @@ import type {
 	UnfinalizedSummary,
 	Unsubscribe,
 } from '../config/types';
-import { PaymentError, redact } from '../diagnostics/errors';
+import { createExclusive, createSingleFlight } from '../core/mutex';
+import { PaymentError } 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 type { EntitlementMap, EntitlementState } from '../entitlements/aggregate';
+import { createSnapshotStore, type SnapshotStore } from '../persistence/mmkv-store';
+import { createConnection, type InitOutcome } from './connection';
 import { createFinalizer } from './finalize';
+import { attachEngineInternals } from './internals';
 import { createProducts, type ProductQueryResult } from './products';
 import { createPurchaseFlow } from './purchase';
+import { createEngineState } from './state';
 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 };
+import { createSync, type SyncOutcome } from './sync';
+
+export type { SyncOutcome } from './sync';
+export type { InitOutcome } from './connection';
 
 export type RestoreOutcome =
 	| { ok: true; restored: true; entitlements: EntitlementKey[] }
@@ -77,8 +64,6 @@ export type RestoreOutcome =
 	| { 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;
@@ -112,14 +97,6 @@ export interface PaymentEngine {
 	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>;
@@ -155,391 +132,109 @@ export interface PaymentEngine {
 	handleForeground(): Promise<void>;
 }
 
+/** How many refused operations `status.blockedOperations` keeps. */
+export const MAX_BLOCKED_OPERATIONS = 20;
+
 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.
+	// rn-core's one platform source (CORE-09). 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 state = createEngineState(
+		config,
+		resolved,
+		provider,
+		deps.snapshotStore ?? createSnapshotStore(),
+		now,
+	);
+	const { emit, commit } = state;
 	const correlationCounter = { next: 1 };
-
+	const nextCorrelationId = () => createCorrelationId(correlationCounter);
 	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).
+	// Exclusive rather than single-flight: a second purchase is 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,
+	/** Written into status, not just logged, so a test can assert the block (FR-014). */
+	const recordBlockedOperation = (productKey: ProductKey): void => {
+		const blocked: BlockedOperation = { productKey, environment: config.environment, at: now() };
+		// The most recent ones only: an app retrying a blocked purchase in a loop
+		// must not grow status without bound (PAY-20).
+		state.setStatus({
+			blockedOperations: [...state.status.blockedOperations, blocked].slice(
+				-MAX_BLOCKED_OPERATIONS,
+			),
 		});
-		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();
-		}
+		emit({ type: 'environment_blocked', productKey, environment: config.environment });
 	};
 
 	const finalizer = createFinalizer({
 		provider,
 		retry: resolved.retry,
 		attemptTimeoutMs: resolved.timeouts.finalizeAttemptMs,
-		snapshot: () => currentSnapshot,
+		snapshot: () => state.snapshot,
 		commit,
 		emit,
 		now,
-		disposed: () => disposed,
+		disposed: () => state.disposed,
 	});
-
-	const products = createProducts({
-		resolved,
-		provider,
-		emit,
-		now,
+	const products = createProducts({ resolved, provider, emit, now });
+	// Every sync also settles what an earlier session left owed, and re-asks the
+	// backend about grants it deferred (FR-039, FR-042, FR-072a).
+	const syncer = createSync(state, async () => {
+		await finalizer.drain();
+		await purchaseFlow.revalidate();
 	});
-
 	const purchaseFlow = createPurchaseFlow({
 		config,
 		resolved,
 		provider,
 		platform,
 		finalizer,
-		snapshot: () => currentSnapshot,
+		snapshot: () => state.snapshot,
 		commit,
 		emit,
 		now,
-		nextCorrelationId: () => createCorrelationId(correlationCounter),
-		statusKind: () => status.kind,
+		nextCorrelationId,
+		statusKind: () => state.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.
+		recordBlockedOperation,
+		// `already_owned` re-syncs rather than surfacing an error, which is how a
+		// reinstall repairs itself (FR-033); the entitlement arrives via the change
+		// signal.
 		requestSync: trigger => {
-			engine.sync(trigger).catch(() => undefined);
+			syncer.sync(trigger).catch(() => undefined);
 		},
 		runExclusive: operation => purchaseLock.run(operation),
 	});
-
 	const subscriptions = createSubscriptions({
 		resolved,
 		provider,
-		snapshot: () => currentSnapshot,
+		snapshot: () => state.snapshot,
 		purchase: (productKey, options) => purchaseFlow.purchase(productKey, options),
 	});
+	const connection = createConnection(state, purchase => {
+		purchaseFlow.ingest(purchase).catch(() => undefined);
+	});
 
-	/**
-	 * 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();
-			}
-		});
-	};
+	/** A subscription that is a no-op once the engine is cleaned up. */
+	function subscriber<T>(listeners: { add(listener: (value: T) => void): Unsubscribe }) {
+		return (listener: (value: T) => void): Unsubscribe =>
+			state.disposed ? () => undefined : listeners.add(listener);
+	}
 
 	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();
+				// Selling is off, but entitlements already held stay readable (FR-012):
+				// hydration runs here too, or they would read `unknown` forever.
+				state.setStatus({ kind: 'disabled' });
+				state.hydrate();
 				return {
 					ok: false,
 					error: new PaymentError({
@@ -549,276 +244,74 @@ export function createEngine(config: PaymentConfig, deps: EngineDeps): PaymentEn
 					}),
 				};
 			}
-
-			// 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') {
+			// Checked before the shortcut below: a cleaned-up engine that had been
+			// ready used to answer `ok` while nothing behind it worked any more.
+			if (state.disposed) {
+				return {
+					ok: false,
+					error: new PaymentError({
+						code: 'PAYMENT_NOT_CONFIGURED',
+						message: 'Engine has been cleaned up',
+						operation: 'initialize',
+					}),
+				};
+			}
+			// Already up: answered without reconnecting, or a later sequential call
+			// would leave a second set of native listeners behind.
+			if (state.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',
-						}),
-					};
+				state.setStatus({ kind: 'connecting' });
+				// Before connecting, so a warm start answers from the last good sync
+				// while the network is still in flight (FR-053).
+				state.hydrate();
+				const connected = await connection.connect();
+				if (!connected.ok) {
+					return connected;
 				}
-
-				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 syncer.sync('initialize');
+				// After syncing, so a transaction the store still reports owned has been
+				// re-queued first: this 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;
+			state.disposed = true;
+			connection.dispose();
 			finalizer.dispose();
-			if (reconnectTimer !== undefined) {
-				clearTimeout(reconnectTimer);
-				reconnectTimer = undefined;
-			}
-			statusListeners.clear();
-			entitlementListeners.clear();
-			pendingListeners.clear();
+			state.statusListeners.clear();
+			state.entitlementListeners.clear();
+			state.pendingListeners.clear();
 			// Disarmed last: after this nothing is emitted, and a late store callback
 			// is dropped safely (FR-082).
-			emitter.dispose();
+			state.emitter.dispose();
 			provider.disconnect().catch(() => undefined);
 		},
 
-		getStatus: () => status,
-
-		subscribeStatus(listener): Unsubscribe {
-			if (disposed) {
-				return () => undefined;
-			}
-			return statusListeners.add(listener);
-		},
+		getStatus: () => state.status,
+		subscribeStatus: subscriber<PaymentStatus>(state.statusListeners),
 
 		/** 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);
+			return state.entitlements[key] ?? { key, status: 'unknown', sources: [], isStale: false };
 		},
+		getAllEntitlements: () => state.entitlements,
+		subscribeEntitlements: subscriber<EntitlementMap>(state.entitlementListeners),
+		getPendingPurchases: () => state.pending,
+		subscribePendingPurchases: subscriber<PendingPurchasesState>(state.pendingListeners),
 
-		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;
-		},
+		sync: trigger => syncer.sync(trigger),
 
 		async restore(): Promise<RestoreOutcome> {
-			const outcome = await engine.sync('manual');
+			const outcome = await syncer.sync('manual');
 			if (!outcome.ok) {
 				return { ok: false, error: outcome.error };
 			}
-			const held = Object.values(entitlements)
+			const held = Object.values(state.entitlements)
 				.filter(e => e.status === 'entitled')
 				.map(e => e.key);
 			// "Nothing found" is a distinct success, so an app never claims to have
@@ -828,94 +321,41 @@ export function createEngine(config: PaymentConfig, deps: EngineDeps): PaymentEn
 				: { ok: true, restored: false };
 		},
 
-		getLastSyncedAt: () => currentSnapshot.lastSyncedAt,
+		getLastSyncedAt: () => state.snapshot.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();
+			state.forget();
+			// Prices are per account and storefront; a logout drops them too (PAY-12).
+			products.invalidate();
 		},
 
-		getProducts(productKeys) {
-			return products.get(productKeys);
-		},
+		subscribeEvents: listener => state.emitter.subscribe(listener),
 
-		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);
-		},
+		purchase: (productKey, options) => purchaseFlow.purchase(productKey, options),
+		consume: ref => finalizer.consume(ref),
+		getUnfinalized: () => finalizer.unfinalized(),
+		getProducts: productKeys => products.get(productKeys),
+		refreshProducts: productKeys => products.refresh(productKeys),
+		changePlan: (from, to, mode, options) => subscriptions.changePlan(from, to, mode, options),
+		openSubscriptionManagement: productKey => subscriptions.openManagement(productKey),
+		confirmPriceChange: productKey => 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,
-			});
+			await connection.recover();
+			// Rate-limited inside sync: at most one request per interval however often
+			// the app calls this.
+			await syncer.sync('foreground');
 		},
 	};
 
+	attachEngineInternals(engine, {
+		resolvedConfig: () => resolved,
+		nextCorrelationId,
+		emitter: () => state.emitter,
+		snapshot: () => state.snapshot,
+		commitSnapshot: commit,
+		mayCreateRealTransaction: () => mayCreateRealTransaction(config),
+		recordBlockedOperation,
+	});
 	return engine;
 }