@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/engine/purchase.ts

@@ -1,614 +1,589 @@
-/**
- * The purchase flow.
- *
- * Ordering here is deliberate and load-bearing:
- *
- * 1. Refuse early and cheaply — disabled, not ready, already busy, environment
- *    blocked, unknown product — so nothing reaches the store that should not.
- * 2. Launch, and map every store outcome onto a typed result (FR-005).
- * 3. Pending stops here: it is persisted and signalled, but **never granted**
- *    (FR-037).
- * 4. Validate with the app's backend, if one is configured, and only for a
- *    **newly completed** purchase (FR-069a).
- * 5. Grant the entitlement, then finalize. In that order — the user gets what
- *    they paid for before the bookkeeping completes, so a finalize failure never
- *    withholds a paid entitlement. Finalization is still guaranteed, by the
- *    persisted queue.
- */
-
-import type {
-	PaymentConfig,
-	ProductKey,
-	PurchaseOptions,
-	PurchaseResult,
-	TransactionRef,
-} from '../config/types';
-import type { ResolvedConfig, TargetPlatform } from '../config/validate';
-import type {
-	ProviderFailureReason,
-	ProviderPort,
-	ProviderPurchase,
-	ProviderPurchaseOutcome,
-	ProviderPurchaseRequest,
-	StoreProductId,
-} from '../adapter/port';
-import type { ExclusiveOutcome } from '../core/mutex';
-import { withTimeout } from '../core/mutex';
-import { PURCHASE_FLOW_CEILING_MS } from '../core/timers';
-import { PaymentError } from '../diagnostics/errors';
-import type { PaymentEventInput } from '../diagnostics/events';
-import {
-	resolveFinalizeState,
-	type PersistedPurchase,
-	type PersistedSnapshot,
-} from '../persistence/snapshot';
-import { storeIdForProductKey } from '../entitlements/mapping';
-import type { Finalizer } from './finalize';
-
-export interface PurchaseFlowDeps {
-	config: PaymentConfig;
-	resolved: ResolvedConfig;
-	provider: ProviderPort;
-	platform: TargetPlatform;
-	finalizer: Finalizer;
-	snapshot: () => PersistedSnapshot;
-	commit: (next: PersistedSnapshot) => void;
-	emit: (event: PaymentEventInput) => void;
-	now: () => number;
-	nextCorrelationId: () => string;
-	statusKind: () => PaymentStatusKindLike;
-	mayCreateRealTransaction: () => boolean;
-	recordBlockedOperation: (productKey: ProductKey) => void;
-	requestSync: (trigger: 'already_owned') => void;
-	runExclusive: <T>(operation: () => Promise<T>) => Promise<ExclusiveOutcome<T>>;
-}
-
-type PaymentStatusKindLike =
-	| 'not_started'
-	| 'connecting'
-	| 'ready'
-	| 'disabled'
-	| 'unavailable'
-	| 'failed';
-
-/** Maps a provider failure onto the public vocabulary, so no store code leaks out. */
-function mapFailure(
-	reason: ProviderFailureReason,
-	productKey: ProductKey,
-): PurchaseResult {
-	switch (reason) {
-		case 'user_cancelled':
-			return { kind: 'user_cancelled', productKey };
-		case 'already_owned':
-			return { kind: 'already_owned', productKey };
-		case 'ineligible':
-			return { kind: 'ineligible', productKey };
-		case 'unknown_product':
-			return { kind: 'unknown_product', productKey };
-		case 'product_unavailable_in_region':
-			return { kind: 'product_unavailable_in_region', productKey };
-		case 'not_ready':
-			return { kind: 'not_ready', status: 'connecting' };
-		case 'network_error':
-			return { kind: 'network_error', productKey };
-		case 'timeout':
-			return { kind: 'timeout', productKey };
-		case 'store_error':
-			return { kind: 'store_error', productKey, code: 'PAYMENT_STORE_ERROR' };
-	}
-}
-
-/** Plan-change parameters, which only `subscriptions.ts` supplies. */
-export interface InternalPurchaseOptions extends PurchaseOptions {
-	replaceProductKey?: ProductKey;
-	prorationMode?: string;
-}
-
-export interface PurchaseFlow {
-	purchase(
-		productKey: ProductKey,
-		options?: InternalPurchaseOptions,
-	): Promise<PurchaseResult>;
-	/** Handles a store-pushed update, e.g. a pending purchase settling (FR-039). */
-	ingest(purchase: ProviderPurchase): Promise<void>;
-	/**
-	 * Re-runs the backend check for transactions granted under the
-	 * failure-fallback (FR-072a).
-	 *
-	 * Called on sync, so recovery happens on the app's own rhythm rather than on a
-	 * timer of ours. A rejection here revokes, which is what bounds the exposure
-	 * that `grant_and_queue` accepts.
-	 */
-	revalidate(): Promise<void>;
-}
-
-export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
-	const { resolved } = deps;
-
-	const toRef = (record: PersistedPurchase): TransactionRef => ({
-		transactionId: record.transactionId,
-		productKey: record.productKey,
-	});
-
-	/** Writes or replaces the record for one transaction. */
-	const upsert = (record: PersistedPurchase): void => {
-		const snapshot = deps.snapshot();
-		const others = snapshot.purchases.filter(
-			p => p.transactionId !== record.transactionId,
-		);
-		deps.commit({ ...snapshot, purchases: [...others, record] });
-	};
-
-	const recordFor = (
-		purchase: ProviderPurchase,
-		productKey: ProductKey,
-	): PersistedPurchase => {
-		const entry = resolved.entries.get(productKey);
-		const existing = deps
-			.snapshot()
-			.purchases.find(p => p.transactionId === purchase.transactionId);
-		return {
-			transactionId: purchase.transactionId,
-			productKey,
-			productType: entry?.productType ?? 'one_time_permanent',
-			token: purchase.token,
-			state: purchase.state === 'pending' ? 'pending' : 'purchased',
-			purchasedAt: purchase.purchasedAt,
-			// Shared with the sync path so the two cannot disagree about what is still
-			// owed a finalize call.
-			finalizeState: resolveFinalizeState(purchase, existing),
-			attempts: existing?.attempts ?? 0,
-			validationState: existing?.validationState ?? 'not_required',
-			expiresAt: purchase.expiresAt,
-			willAutoRenew: purchase.willAutoRenew,
-		};
-	};
-
-	/**
-	 * Calls the app's hook under `timeouts.validateMs`.
-	 *
-	 * Unbounded, a hook that never answers held the purchase lock and, through
-	 * revalidation, the sync flight for the rest of the session. A timeout rejects,
-	 * so callers treat it exactly like a hook that throws: unavailable (FR-072b).
-	 */
-	const askHook = (
-		hook: NonNullable<PaymentConfig['validateTransaction']>,
-		candidate: Parameters<NonNullable<PaymentConfig['validateTransaction']>>[0],
-	) =>
-		withTimeout(
-			hook(candidate),
-			resolved.timeouts.validateMs,
-			() =>
-				new PaymentError({
-					code: 'PAYMENT_VALIDATION_UNAVAILABLE',
-					message: 'The validation hook did not answer in time',
-					operation: 'validate',
-					retryable: true,
-				}),
-		);
-
-	/**
-	 * Runs the app's backend check, if configured.
-	 *
-	 * Called for newly completed purchases only (FR-069a) — sync and restore trust
-	 * a decision already made, which is what keeps restore working while the
-	 * backend is unreachable.
-	 */
-	const validate = async (
-		purchase: ProviderPurchase,
-		productKey: ProductKey,
-		correlationId: string,
-	): Promise<
-		| { outcome: 'approved' }
-		| { outcome: 'rejected'; reason?: string }
-		| { outcome: 'granted_pending_revalidation' }
-	> => {
-		const hook = deps.config.validateTransaction;
-		if (!hook) {
-			return { outcome: 'approved' };
-		}
-
-		const entry = resolved.entries.get(productKey);
-		try {
-			const decision = await askHook(hook, {
-				productKey,
-				productType: entry?.productType ?? 'one_time_permanent',
-				verificationPayload: purchase.verificationPayload ?? '',
-				correlationId,
-				transactionId: purchase.transactionId,
-				platform: deps.platform,
-			});
-			deps.emit({
-				type: 'validation_decided',
-				productKey,
-				decision: decision.approved ? 'approved' : 'rejected',
-			});
-			return decision.approved
-				? { outcome: 'approved' }
-				: { outcome: 'rejected', reason: decision.reason };
-		} catch {
-			// A hook that throws is unavailable, never an implicit approval (FR-072b).
-			const fallback = resolved.onValidationUnavailable;
-			deps.emit({ type: 'validation_unavailable', productKey, fallback });
-			return fallback === 'grant_and_queue'
-				? { outcome: 'granted_pending_revalidation' }
-				: { outcome: 'rejected', reason: 'validation_unavailable' };
-		}
-	};
-
-	/**
-	 * Settlements in progress, by transaction.
-	 *
-	 * The Play binding delivers a launched purchase twice: to the launch and, at
-	 * the same moment, to the session-long update listener. Both paths reach
-	 * `settle`, and without this the hook ran twice and the purchase was settled
-	 * twice. The second caller joins the first and gets the same result.
-	 */
-	const inFlightSettle = new Map<string, Promise<PurchaseResult>>();
-
-	const settleOnce = (
-		purchase: ProviderPurchase,
-		productKey: ProductKey,
-		correlationId: string,
-	): Promise<PurchaseResult> => {
-		const running = inFlightSettle.get(purchase.transactionId);
-		if (running) {
-			return running;
-		}
-		const flight = settle(purchase, productKey, correlationId).finally(() => {
-			inFlightSettle.delete(purchase.transactionId);
-		});
-		inFlightSettle.set(purchase.transactionId, flight);
-		return flight;
-	};
-
-	/** Persists a completed purchase, grants it, then finalizes. */
-	const settle = async (
-		purchase: ProviderPurchase,
-		productKey: ProductKey,
-		correlationId: string,
-	): Promise<PurchaseResult> => {
-		const decision = await validate(purchase, productKey, correlationId);
-
-		if (decision.outcome === 'rejected') {
-			upsert({
-				...recordFor(purchase, productKey),
-				validationState: 'rejected',
-				finalizeState: 'queued',
-			});
-			// Still finalized with the store: the money moved, so leaving it
-			// unacknowledged would have Google refund it while our backend has
-			// already decided the user is not entitled. Refunding is the app owner's
-			// call, not a side effect of a bookkeeping omission.
-			await deps.finalizer.enqueue(purchase.transactionId);
-			return {
-				kind: 'validation_rejected',
-				productKey,
-				reason: decision.reason,
-			};
-		}
-
-		upsert({
-			...recordFor(purchase, productKey),
-			validationState:
-				decision.outcome === 'granted_pending_revalidation'
-					? 'queued_for_revalidation'
-					: 'approved',
-			finalizeState: 'queued',
-		});
-
-		// Grant is already live at this point: `commit` recomputed entitlements.
-		// Finalize second, so a store hiccup cannot withhold what was paid for.
-		await deps.finalizer.enqueue(purchase.transactionId);
-
-		const record = deps
-			.snapshot()
-			.purchases.find(p => p.transactionId === purchase.transactionId);
-		return {
-			kind: 'success',
-			productKey,
-			transaction: record
-				? toRef(record)
-				: { transactionId: purchase.transactionId, productKey },
-		};
-	};
-
-	const handlePending = (
-		purchase: ProviderPurchase,
-		productKey: ProductKey,
-	): PurchaseResult => {
-		// The same pending transaction arrives from the launch and from the update
-		// listener (see `inFlightSettle`). The signal is about a purchase becoming
-		// pending, so it fires once per transaction, not once per delivery.
-		const alreadyPending = deps
-			.snapshot()
-			.purchases.some(p => p.transactionId === purchase.transactionId && p.state === 'pending');
-		upsert(recordFor(purchase, productKey));
-		if (!alreadyPending) {
-			deps.emit({ type: 'purchase_pending', productKey });
-		}
-		return {
-			kind: 'pending',
-			productKey,
-			transaction: { transactionId: purchase.transactionId, productKey },
-		};
-	};
-
-	/**
-	 * The store returned a purchase in a state it could not name — neither paid
-	 * nor pending. Nothing is granted, persisted or acknowledged on it.
-	 *
-	 * Retrying is the repair path: if the money did move, the store answers
-	 * `already_owned`, which re-syncs and grants (FR-033).
-	 */
-	const handleUnspecified = (
-		productKey: ProductKey,
-		correlationId: string,
-	): PurchaseResult => {
-		deps.emit({
-			type: 'purchase_failed',
-			productKey,
-			code: 'PAYMENT_STORE_ERROR',
-			retryable: true,
-			correlationId,
-		});
-		return { kind: 'store_error', productKey, code: 'PAYMENT_STORE_ERROR' };
-	};
-
-	/** What the store is asked for: the product and, for a plan change, what it replaces. */
-	const launchRequest = (
-		productKey: ProductKey,
-		storeProductId: StoreProductId,
-		options?: InternalPurchaseOptions,
-	): ProviderPurchaseRequest => {
-		const replaceKey = options?.replaceProductKey;
-		return {
-			storeProductId,
-			productType: resolved.entries.get(productKey)?.productType ?? 'one_time_permanent',
-			offerKey: options?.offerKey,
-			obfuscatedAccountId: options?.obfuscatedAccountId,
-			// Present only for a plan change. The store needs the token of the
-			// subscription being replaced so it migrates the existing purchase instead
-			// of creating a second one (FR-065), and its product id to apply the
-			// replacement mode.
-			replacePurchaseToken: replaceKey
-				? deps
-						.snapshot()
-						.purchases.find(p => p.productKey === replaceKey && p.state === 'purchased')
-						?.token
-				: undefined,
-			replaceStoreProductId: replaceKey
-				? storeIdForProductKey(resolved, replaceKey)
-				: undefined,
-			prorationMode: options?.prorationMode,
-		};
-	};
-
-	/**
-	 * The launch timeout covers opening the store surface only; time the user
-	 * spends inside it is the store's, not ours (FR-035). A provider that reports
-	 * nothing until the flow ends gives no "opened" moment to time, so it gets only
-	 * `PURCHASE_FLOW_CEILING_MS`: far beyond any real purchase, there so a binding
-	 * that never answers cannot hold the purchase lock for the whole session.
-	 */
-	const launch = (request: ProviderPurchaseRequest): Promise<ProviderPurchaseOutcome> => {
-		const launched = deps.provider.launchPurchase(request);
-		const includesStoreTime = deps.provider.capabilities().purchaseOutcomeIncludesStoreTime;
-		return withTimeout(
-			launched,
-			includesStoreTime ? PURCHASE_FLOW_CEILING_MS : resolved.timeouts.purchaseLaunchMs,
-			() =>
-				new PaymentError({
-					code: 'PAYMENT_TIMEOUT',
-					message: 'Opening the purchase surface timed out',
-					operation: 'purchase',
-					retryable: true,
-				}),
-		);
-	};
-
-	return {
-		async purchase(
-			productKey: ProductKey,
-			options?: InternalPurchaseOptions,
-		): Promise<PurchaseResult> {
-			if (!resolved.enabled) {
-				return { kind: 'disabled' };
-			}
-
-			const status = deps.statusKind();
-			if (status !== 'ready') {
-				return { kind: 'not_ready', status };
-			}
-
-			const storeProductId = storeIdForProductKey(resolved, productKey);
-			if (!storeProductId) {
-				return { kind: 'unknown_product', productKey };
-			}
-
-			// The block that makes a developer mistake unable to move real money.
-			// Gated on the provider actually being one that would: the fake store
-			// must still be able to complete a purchase in a test (FR-014).
-			if (
-				deps.provider.capabilities().createsRealTransactions &&
-				!deps.mayCreateRealTransaction()
-			) {
-				deps.recordBlockedOperation(productKey);
-				return {
-					kind: 'environment_blocked',
-					productKey,
-					environment: deps.config.environment,
-				};
-			}
-
-			const correlationId = deps.nextCorrelationId();
-
-			// Exclusive, not single-flight: a second purchase is refused rather than
-			// joined or queued, so no second store surface opens (FR-031).
-			const attempt = await deps.runExclusive(async () => {
-				deps.emit({ type: 'purchase_started', productKey, correlationId });
-
-				let outcome;
-				try {
-					outcome = await launch(launchRequest(productKey, storeProductId, options));
-				} catch {
-					deps.emit({
-						type: 'purchase_failed',
-						productKey,
-						code: 'PAYMENT_TIMEOUT',
-						retryable: true,
-						correlationId,
-					});
-					return { kind: 'timeout', productKey } as PurchaseResult;
-				}
-
-				if (!outcome.ok) {
-					const mapped = mapFailure(outcome.reason, productKey);
-
-					if (mapped.kind === 'user_cancelled') {
-						// A normal outcome. Reported on its own channel so it is never
-						// counted as a technical failure (FR-032).
-						deps.emit({ type: 'purchase_cancelled', productKey, correlationId });
-						return mapped;
-					}
-
-					if (mapped.kind === 'already_owned') {
-						// How a reinstall or a new device repairs itself (FR-033).
-						deps.requestSync('already_owned');
-						return mapped;
-					}
-
-					deps.emit({
-						type: 'purchase_failed',
-						productKey,
-						code:
-							mapped.kind === 'network_error'
-								? 'PAYMENT_NETWORK_ERROR'
-								: mapped.kind === 'unknown_product'
-									? 'PAYMENT_UNKNOWN_PRODUCT'
-									: mapped.kind === 'ineligible'
-										? 'PAYMENT_INELIGIBLE'
-										: mapped.kind === 'product_unavailable_in_region'
-											? 'PAYMENT_PRODUCT_UNAVAILABLE_IN_REGION'
-											: 'PAYMENT_STORE_ERROR',
-						retryable: mapped.kind === 'network_error',
-						correlationId,
-					});
-					return mapped;
-				}
-
-				if (outcome.purchase.state === 'pending') {
-					return handlePending(outcome.purchase, productKey);
-				}
-
-				if (outcome.purchase.state === 'unspecified') {
-					return handleUnspecified(productKey, correlationId);
-				}
-
-				deps.emit({ type: 'purchase_succeeded', productKey, correlationId });
-				return settleOnce(outcome.purchase, productKey, correlationId);
-			});
-
-			if (!attempt.acquired) {
-				return { kind: 'purchase_in_progress' };
-			}
-			return attempt.value;
-		},
-
-		/**
-		 * A store-pushed update.
-		 *
-		 * This is how a pending purchase that settled between sessions is granted
-		 * without the user buying again (FR-039). It runs outside the exclusive lock
-		 * because it is not a user-initiated purchase and must not be refused just
-		 * because one is open.
-		 */
-		async ingest(purchase: ProviderPurchase): Promise<void> {
-			const productKey = resolved.byStoreId.get(purchase.storeProductId);
-			if (!productKey) {
-				return;
-			}
-
-			if (purchase.state === 'pending') {
-				handlePending(purchase, productKey);
-				return;
-			}
-
-			if (purchase.state === 'unspecified') {
-				// No basis to grant or to end anything. The next sync reports what
-				// the store actually holds.
-				return;
-			}
-
-			const existing = deps
-				.snapshot()
-				.purchases.find(p => p.transactionId === purchase.transactionId);
-
-			// Already settled and validated: nothing to redo, and re-running the hook
-			// here would break FR-069a's "new purchases only" rule.
-			if (existing && existing.state === 'purchased' && existing.validationState !== 'not_required') {
-				await deps.finalizer.enqueue(purchase.transactionId);
-				return;
-			}
-
-			await settleOnce(purchase, productKey, deps.nextCorrelationId());
-		},
-
-		async revalidate(): Promise<void> {
-			const hook = deps.config.validateTransaction;
-			if (!hook) {
-				return;
-			}
-
-			const queued = deps
-				.snapshot()
-				.purchases.filter(p => p.validationState === 'queued_for_revalidation');
-
-			for (const record of queued) {
-				const entry = resolved.entries.get(record.productKey);
-				let approved: boolean;
-				try {
-					const decision = await askHook(hook, {
-						productKey: record.productKey,
-						productType: entry?.productType ?? 'one_time_permanent',
-						// Re-validation deliberately carries no payload: the original
-						// verification material is not persisted (FR-056), so the backend
-						// re-checks by transaction against its own record of the purchase —
-						// which is why the transaction id has to travel with it.
-						verificationPayload: '',
-						correlationId: deps.nextCorrelationId(),
-						transactionId: record.transactionId,
-						platform: deps.platform,
-					});
-					approved = decision.approved;
-				} catch {
-					// Still unreachable. Leave it queued and try again next sync rather
-					// than revoking from a paying user because our backend is down.
-					continue;
-				}
-
-				const snapshot = deps.snapshot();
-				deps.commit({
-					...snapshot,
-					purchases: snapshot.purchases.map(p =>
-						p.transactionId === record.transactionId
-							? {
-									...p,
-									validationState: approved ? 'approved' : 'rejected',
-									// A rejection on recovery revokes, which is the bound on the
-									// exposure `grant_and_queue` accepts (FR-072a).
-									state: approved ? p.state : 'revoked',
-								}
-							: p,
-					),
-				});
-
-				deps.emit({
-					type: 'validation_decided',
-					productKey: record.productKey,
-					decision: approved ? 'approved' : 'rejected',
-				});
-			}
-		},
-	};
-}
+/**
+ * The purchase flow.
+ *
+ * Ordering here is deliberate and load-bearing:
+ *
+ * 1. Refuse early and cheaply — disabled, not ready, already busy, environment
+ *    blocked, unknown product — so nothing reaches the store that should not.
+ * 2. Launch, and map every store outcome onto a typed result (FR-005).
+ * 3. Pending stops here: it is persisted and signalled, but **never granted**
+ *    (FR-037).
+ * 4. Validate with the app's backend, if one is configured, and only for a
+ *    **newly completed** purchase (FR-069a).
+ * 5. Grant the entitlement, then finalize. In that order — the user gets what
+ *    they paid for before the bookkeeping completes, so a finalize failure never
+ *    withholds a paid entitlement. Finalization is still guaranteed, by the
+ *    persisted queue.
+ */
+
+import type {
+	PaymentConfig,
+	ProductKey,
+	PurchaseOptions,
+	PurchaseResult,
+	TransactionRef,
+} from '../config/types';
+import type { ResolvedConfig, TargetPlatform } from '../config/validate';
+import type {
+	ProviderFailureReason,
+	ProviderPort,
+	ProviderPurchase,
+	ProviderPurchaseOutcome,
+	ProviderPurchaseRequest,
+	StoreProductId,
+} from '../adapter/port';
+import type { ExclusiveOutcome } from '../core/mutex';
+import { withTimeout } from '../core/mutex';
+import { PURCHASE_FLOW_CEILING_MS } from '../core/timers';
+import { PaymentError } from '../diagnostics/errors';
+import type { PaymentEventInput } from '../diagnostics/events';
+import {
+	resolveFinalizeState,
+	type PersistedPurchase,
+	type PersistedSnapshot,
+} from '../persistence/snapshot';
+import { storeIdForProductKey } from '../entitlements/mapping';
+import type { Finalizer } from './finalize';
+
+export interface PurchaseFlowDeps {
+	config: PaymentConfig;
+	resolved: ResolvedConfig;
+	provider: ProviderPort;
+	platform: TargetPlatform;
+	finalizer: Finalizer;
+	snapshot: () => PersistedSnapshot;
+	commit: (next: PersistedSnapshot) => void;
+	emit: (event: PaymentEventInput) => void;
+	now: () => number;
+	nextCorrelationId: () => string;
+	statusKind: () => PaymentStatusKindLike;
+	mayCreateRealTransaction: () => boolean;
+	recordBlockedOperation: (productKey: ProductKey) => void;
+	requestSync: (trigger: 'already_owned') => void;
+	runExclusive: <T>(operation: () => Promise<T>) => Promise<ExclusiveOutcome<T>>;
+}
+
+type PaymentStatusKindLike =
+	'not_started' | 'connecting' | 'ready' | 'disabled' | 'unavailable' | 'failed';
+
+/** Maps a provider failure onto the public vocabulary, so no store code leaks out. */
+function mapFailure(reason: ProviderFailureReason, productKey: ProductKey): PurchaseResult {
+	switch (reason) {
+		case 'user_cancelled':
+			return { kind: 'user_cancelled', productKey };
+		case 'already_owned':
+			return { kind: 'already_owned', productKey };
+		case 'ineligible':
+			return { kind: 'ineligible', productKey };
+		case 'unknown_product':
+			return { kind: 'unknown_product', productKey };
+		case 'product_unavailable_in_region':
+			return { kind: 'product_unavailable_in_region', productKey };
+		case 'not_ready':
+			return { kind: 'not_ready', status: 'connecting' };
+		case 'network_error':
+			return { kind: 'network_error', productKey };
+		case 'timeout':
+			return { kind: 'timeout', productKey };
+		case 'store_error':
+			return { kind: 'store_error', productKey, code: 'PAYMENT_STORE_ERROR' };
+	}
+}
+
+/** Plan-change parameters, which only `subscriptions.ts` supplies. */
+export interface InternalPurchaseOptions extends PurchaseOptions {
+	replaceProductKey?: ProductKey;
+	prorationMode?: string;
+}
+
+export interface PurchaseFlow {
+	purchase(productKey: ProductKey, options?: InternalPurchaseOptions): Promise<PurchaseResult>;
+	/** Handles a store-pushed update, e.g. a pending purchase settling (FR-039). */
+	ingest(purchase: ProviderPurchase): Promise<void>;
+	/**
+	 * Re-runs the backend check for transactions granted under the
+	 * failure-fallback (FR-072a).
+	 *
+	 * Called on sync, so recovery happens on the app's own rhythm rather than on a
+	 * timer of ours. A rejection here revokes, which is what bounds the exposure
+	 * that `grant_and_queue` accepts.
+	 */
+	revalidate(): Promise<void>;
+}
+
+export function createPurchaseFlow(deps: PurchaseFlowDeps): PurchaseFlow {
+	const { resolved } = deps;
+
+	const toRef = (record: PersistedPurchase): TransactionRef => ({
+		transactionId: record.transactionId,
+		productKey: record.productKey,
+	});
+
+	/** Writes or replaces the record for one transaction. */
+	const upsert = (record: PersistedPurchase): void => {
+		const snapshot = deps.snapshot();
+		const others = snapshot.purchases.filter(p => p.transactionId !== record.transactionId);
+		deps.commit({ ...snapshot, purchases: [...others, record] });
+	};
+
+	const recordFor = (purchase: ProviderPurchase, productKey: ProductKey): PersistedPurchase => {
+		const entry = resolved.entries.get(productKey);
+		const existing = deps
+			.snapshot()
+			.purchases.find(p => p.transactionId === purchase.transactionId);
+		return {
+			transactionId: purchase.transactionId,
+			productKey,
+			productType: entry?.productType ?? 'one_time_permanent',
+			token: purchase.token,
+			state: purchase.state === 'pending' ? 'pending' : 'purchased',
+			purchasedAt: purchase.purchasedAt,
+			// Shared with the sync path so the two cannot disagree about what is still
+			// owed a finalize call.
+			finalizeState: resolveFinalizeState(purchase, existing),
+			attempts: existing?.attempts ?? 0,
+			validationState: existing?.validationState ?? 'not_required',
+			expiresAt: purchase.expiresAt,
+			willAutoRenew: purchase.willAutoRenew,
+		};
+	};
+
+	/**
+	 * Calls the app's hook under `timeouts.validateMs`.
+	 *
+	 * Unbounded, a hook that never answers held the purchase lock and, through
+	 * revalidation, the sync flight for the rest of the session. A timeout rejects,
+	 * so callers treat it exactly like a hook that throws: unavailable (FR-072b).
+	 */
+	const askHook = (
+		hook: NonNullable<PaymentConfig['validateTransaction']>,
+		candidate: Parameters<NonNullable<PaymentConfig['validateTransaction']>>[0],
+	) =>
+		withTimeout(
+			hook(candidate),
+			resolved.timeouts.validateMs,
+			() =>
+				new PaymentError({
+					code: 'PAYMENT_VALIDATION_UNAVAILABLE',
+					message: 'The validation hook did not answer in time',
+					operation: 'validate',
+					retryable: true,
+				}),
+		);
+
+	/**
+	 * Runs the app's backend check, if configured.
+	 *
+	 * Called for newly completed purchases only (FR-069a) — sync and restore trust
+	 * a decision already made, which is what keeps restore working while the
+	 * backend is unreachable.
+	 */
+	const validate = async (
+		purchase: ProviderPurchase,
+		productKey: ProductKey,
+		correlationId: string,
+	): Promise<
+		| { outcome: 'approved' }
+		| { outcome: 'rejected'; reason?: string }
+		| { outcome: 'granted_pending_revalidation' }
+	> => {
+		const hook = deps.config.validateTransaction;
+		if (!hook) {
+			return { outcome: 'approved' };
+		}
+
+		const entry = resolved.entries.get(productKey);
+		try {
+			const decision = await askHook(hook, {
+				productKey,
+				productType: entry?.productType ?? 'one_time_permanent',
+				verificationPayload: purchase.verificationPayload ?? '',
+				correlationId,
+				transactionId: purchase.transactionId,
+				platform: deps.platform,
+			});
+			deps.emit({
+				type: 'validation_decided',
+				productKey,
+				decision: decision.approved ? 'approved' : 'rejected',
+			});
+			return decision.approved
+				? { outcome: 'approved' }
+				: { outcome: 'rejected', reason: decision.reason };
+		} catch {
+			// A hook that throws is unavailable, never an implicit approval (FR-072b).
+			const fallback = resolved.onValidationUnavailable;
+			deps.emit({ type: 'validation_unavailable', productKey, fallback });
+			return fallback === 'grant_and_queue'
+				? { outcome: 'granted_pending_revalidation' }
+				: { outcome: 'rejected', reason: 'validation_unavailable' };
+		}
+	};
+
+	/**
+	 * Settlements in progress, by transaction.
+	 *
+	 * The Play binding delivers a launched purchase twice: to the launch and, at
+	 * the same moment, to the session-long update listener. Both paths reach
+	 * `settle`, and without this the hook ran twice and the purchase was settled
+	 * twice. The second caller joins the first and gets the same result.
+	 */
+	const inFlightSettle = new Map<string, Promise<PurchaseResult>>();
+
+	const settleOnce = (
+		purchase: ProviderPurchase,
+		productKey: ProductKey,
+		correlationId: string,
+	): Promise<PurchaseResult> => {
+		const running = inFlightSettle.get(purchase.transactionId);
+		if (running) {
+			return running;
+		}
+		const flight = settle(purchase, productKey, correlationId).finally(() => {
+			inFlightSettle.delete(purchase.transactionId);
+		});
+		inFlightSettle.set(purchase.transactionId, flight);
+		return flight;
+	};
+
+	/** Persists a completed purchase, grants it, then finalizes. */
+	const settle = async (
+		purchase: ProviderPurchase,
+		productKey: ProductKey,
+		correlationId: string,
+	): Promise<PurchaseResult> => {
+		const decision = await validate(purchase, productKey, correlationId);
+
+		if (decision.outcome === 'rejected') {
+			upsert({
+				...recordFor(purchase, productKey),
+				validationState: 'rejected',
+				finalizeState: 'queued',
+			});
+			// Still finalized with the store: the money moved, so leaving it
+			// unacknowledged would have Google refund it while our backend has
+			// already decided the user is not entitled. Refunding is the app owner's
+			// call, not a side effect of a bookkeeping omission.
+			await deps.finalizer.enqueue(purchase.transactionId);
+			return {
+				kind: 'validation_rejected',
+				productKey,
+				reason: decision.reason,
+			};
+		}
+
+		upsert({
+			...recordFor(purchase, productKey),
+			validationState:
+				decision.outcome === 'granted_pending_revalidation'
+					? 'queued_for_revalidation'
+					: 'approved',
+			finalizeState: 'queued',
+		});
+
+		// Grant is already live at this point: `commit` recomputed entitlements.
+		// Finalize second, so a store hiccup cannot withhold what was paid for.
+		await deps.finalizer.enqueue(purchase.transactionId);
+
+		const record = deps.snapshot().purchases.find(p => p.transactionId === purchase.transactionId);
+		return {
+			kind: 'success',
+			productKey,
+			transaction: record ? toRef(record) : { transactionId: purchase.transactionId, productKey },
+		};
+	};
+
+	const handlePending = (purchase: ProviderPurchase, productKey: ProductKey): PurchaseResult => {
+		// The same pending transaction arrives from the launch and from the update
+		// listener (see `inFlightSettle`). The signal is about a purchase becoming
+		// pending, so it fires once per transaction, not once per delivery.
+		const alreadyPending = deps
+			.snapshot()
+			.purchases.some(p => p.transactionId === purchase.transactionId && p.state === 'pending');
+		upsert(recordFor(purchase, productKey));
+		if (!alreadyPending) {
+			deps.emit({ type: 'purchase_pending', productKey });
+		}
+		return {
+			kind: 'pending',
+			productKey,
+			transaction: { transactionId: purchase.transactionId, productKey },
+		};
+	};
+
+	/**
+	 * The store returned a purchase in a state it could not name — neither paid
+	 * nor pending. Nothing is granted, persisted or acknowledged on it.
+	 *
+	 * Retrying is the repair path: if the money did move, the store answers
+	 * `already_owned`, which re-syncs and grants (FR-033).
+	 */
+	const handleUnspecified = (productKey: ProductKey, correlationId: string): PurchaseResult => {
+		deps.emit({
+			type: 'purchase_failed',
+			productKey,
+			code: 'PAYMENT_STORE_ERROR',
+			retryable: true,
+			correlationId,
+		});
+		return { kind: 'store_error', productKey, code: 'PAYMENT_STORE_ERROR' };
+	};
+
+	/** What the store is asked for: the product and, for a plan change, what it replaces. */
+	const launchRequest = (
+		productKey: ProductKey,
+		storeProductId: StoreProductId,
+		options?: InternalPurchaseOptions,
+	): ProviderPurchaseRequest => {
+		const replaceKey = options?.replaceProductKey;
+		return {
+			storeProductId,
+			productType: resolved.entries.get(productKey)?.productType ?? 'one_time_permanent',
+			offerKey: options?.offerKey,
+			obfuscatedAccountId: options?.obfuscatedAccountId,
+			// Present only for a plan change. The store needs the token of the
+			// subscription being replaced so it migrates the existing purchase instead
+			// of creating a second one (FR-065), and its product id to apply the
+			// replacement mode.
+			replacePurchaseToken: replaceKey
+				? deps
+						.snapshot()
+						.purchases.find(p => p.productKey === replaceKey && p.state === 'purchased')?.token
+				: undefined,
+			replaceStoreProductId: replaceKey ? storeIdForProductKey(resolved, replaceKey) : undefined,
+			prorationMode: options?.prorationMode,
+		};
+	};
+
+	/**
+	 * The launch timeout covers opening the store surface only; time the user
+	 * spends inside it is the store's, not ours (FR-035). A provider that reports
+	 * nothing until the flow ends gives no "opened" moment to time, so it gets only
+	 * `PURCHASE_FLOW_CEILING_MS`: far beyond any real purchase, there so a binding
+	 * that never answers cannot hold the purchase lock for the whole session.
+	 */
+	const launch = (request: ProviderPurchaseRequest): Promise<ProviderPurchaseOutcome> => {
+		const launched = deps.provider.launchPurchase(request);
+		const includesStoreTime = deps.provider.capabilities().purchaseOutcomeIncludesStoreTime;
+		return withTimeout(
+			launched,
+			includesStoreTime ? PURCHASE_FLOW_CEILING_MS : resolved.timeouts.purchaseLaunchMs,
+			() =>
+				new PaymentError({
+					code: 'PAYMENT_TIMEOUT',
+					message: 'Opening the purchase surface timed out',
+					operation: 'purchase',
+					retryable: true,
+				}),
+		);
+	};
+
+	return {
+		async purchase(
+			productKey: ProductKey,
+			options?: InternalPurchaseOptions,
+		): Promise<PurchaseResult> {
+			if (!resolved.enabled) {
+				return { kind: 'disabled' };
+			}
+
+			const status = deps.statusKind();
+			if (status !== 'ready') {
+				return { kind: 'not_ready', status };
+			}
+
+			const storeProductId = storeIdForProductKey(resolved, productKey);
+			if (!storeProductId) {
+				return { kind: 'unknown_product', productKey };
+			}
+
+			// The block that makes a developer mistake unable to move real money.
+			// Gated on the provider actually being one that would: the fake store
+			// must still be able to complete a purchase in a test (FR-014).
+			if (
+				deps.provider.capabilities().createsRealTransactions &&
+				!deps.mayCreateRealTransaction()
+			) {
+				deps.recordBlockedOperation(productKey);
+				return {
+					kind: 'environment_blocked',
+					productKey,
+					environment: deps.config.environment,
+				};
+			}
+
+			const correlationId = deps.nextCorrelationId();
+
+			// Exclusive, not single-flight: a second purchase is refused rather than
+			// joined or queued, so no second store surface opens (FR-031).
+			const attempt = await deps.runExclusive(async () => {
+				deps.emit({ type: 'purchase_started', productKey, correlationId });
+
+				let outcome;
+				try {
+					outcome = await launch(launchRequest(productKey, storeProductId, options));
+				} catch {
+					deps.emit({
+						type: 'purchase_failed',
+						productKey,
+						code: 'PAYMENT_TIMEOUT',
+						retryable: true,
+						correlationId,
+					});
+					return { kind: 'timeout', productKey } as PurchaseResult;
+				}
+
+				if (!outcome.ok) {
+					const mapped = mapFailure(outcome.reason, productKey);
+
+					if (mapped.kind === 'user_cancelled') {
+						// A normal outcome. Reported on its own channel so it is never
+						// counted as a technical failure (FR-032).
+						deps.emit({ type: 'purchase_cancelled', productKey, correlationId });
+						return mapped;
+					}
+
+					if (mapped.kind === 'already_owned') {
+						// How a reinstall or a new device repairs itself (FR-033).
+						deps.requestSync('already_owned');
+						return mapped;
+					}
+
+					deps.emit({
+						type: 'purchase_failed',
+						productKey,
+						code:
+							mapped.kind === 'network_error'
+								? 'PAYMENT_NETWORK_ERROR'
+								: mapped.kind === 'unknown_product'
+									? 'PAYMENT_UNKNOWN_PRODUCT'
+									: mapped.kind === 'ineligible'
+										? 'PAYMENT_INELIGIBLE'
+										: mapped.kind === 'product_unavailable_in_region'
+											? 'PAYMENT_PRODUCT_UNAVAILABLE_IN_REGION'
+											: 'PAYMENT_STORE_ERROR',
+						retryable: mapped.kind === 'network_error',
+						correlationId,
+					});
+					return mapped;
+				}
+
+				if (outcome.purchase.state === 'pending') {
+					return handlePending(outcome.purchase, productKey);
+				}
+
+				if (outcome.purchase.state === 'unspecified') {
+					return handleUnspecified(productKey, correlationId);
+				}
+
+				deps.emit({ type: 'purchase_succeeded', productKey, correlationId });
+				return settleOnce(outcome.purchase, productKey, correlationId);
+			});
+
+			if (!attempt.acquired) {
+				return { kind: 'purchase_in_progress' };
+			}
+			return attempt.value;
+		},
+
+		/**
+		 * A store-pushed update.
+		 *
+		 * This is how a pending purchase that settled between sessions is granted
+		 * without the user buying again (FR-039). It runs outside the exclusive lock
+		 * because it is not a user-initiated purchase and must not be refused just
+		 * because one is open.
+		 */
+		async ingest(purchase: ProviderPurchase): Promise<void> {
+			const productKey = resolved.byStoreId.get(purchase.storeProductId);
+			if (!productKey) {
+				return;
+			}
+
+			if (purchase.state === 'pending') {
+				handlePending(purchase, productKey);
+				return;
+			}
+
+			if (purchase.state === 'unspecified') {
+				// No basis to grant or to end anything. The next sync reports what
+				// the store actually holds.
+				return;
+			}
+
+			const existing = deps
+				.snapshot()
+				.purchases.find(p => p.transactionId === purchase.transactionId);
+
+			// Already settled and validated: nothing to redo, and re-running the hook
+			// here would break FR-069a's "new purchases only" rule.
+			if (
+				existing &&
+				existing.state === 'purchased' &&
+				existing.validationState !== 'not_required'
+			) {
+				await deps.finalizer.enqueue(purchase.transactionId);
+				return;
+			}
+
+			await settleOnce(purchase, productKey, deps.nextCorrelationId());
+		},
+
+		async revalidate(): Promise<void> {
+			const hook = deps.config.validateTransaction;
+			if (!hook) {
+				return;
+			}
+
+			const queued = deps
+				.snapshot()
+				.purchases.filter(p => p.validationState === 'queued_for_revalidation');
+
+			for (const record of queued) {
+				const entry = resolved.entries.get(record.productKey);
+				let approved: boolean;
+				try {
+					const decision = await askHook(hook, {
+						productKey: record.productKey,
+						productType: entry?.productType ?? 'one_time_permanent',
+						// Re-validation deliberately carries no payload: the original
+						// verification material is not persisted (FR-056), so the backend
+						// re-checks by transaction against its own record of the purchase —
+						// which is why the transaction id has to travel with it.
+						verificationPayload: '',
+						correlationId: deps.nextCorrelationId(),
+						transactionId: record.transactionId,
+						platform: deps.platform,
+					});
+					approved = decision.approved;
+				} catch {
+					// Still unreachable. Leave it queued and try again next sync rather
+					// than revoking from a paying user because our backend is down.
+					continue;
+				}
+
+				const snapshot = deps.snapshot();
+				deps.commit({
+					...snapshot,
+					purchases: snapshot.purchases.map(p =>
+						p.transactionId === record.transactionId
+							? {
+									...p,
+									validationState: approved ? 'approved' : 'rejected',
+									// A rejection on recovery revokes, which is the bound on the
+									// exposure `grant_and_queue` accepts (FR-072a).
+									state: approved ? p.state : 'revoked',
+								}
+							: p,
+					),
+				});
+
+				deps.emit({
+					type: 'validation_decided',
+					productKey: record.productKey,
+					decision: approved ? 'approved' : 'rejected',
+				});
+			}
+		},
+	};
+}