@mpgd/game-services 0.21.0 → 0.22.0

package/dist/commerce-reconciler.js

@@ -0,0 +1,1251 @@
+import { assertCommercePurchaseTransition, assertRequestPurchaseSupported, CommerceError, commerceErrorInfoOf, createDerivedPurchaseIdempotencyKey, isTerminalCommercePurchaseState, summarizeCommercePurchaseState, } from '@mpgd/platform/commerce';
+import { compareCommerceServiceCapabilities, } from './commerce-evidence-registry.js';
+import { chunkLedgerEntryIds } from './commerce-ledger.js';
+/**
+ * Commerce v2 reconciler (RFC "Purchase lifecycle", "Reconciler", and
+ * "Idempotency keys"). One reconciler per `CommerceProvider` replaces the
+ * per-store recovery drivers: it journals every purchase the game starts or
+ * the store reports as one record moving through the RFC states, sends the
+ * saved verify request to the game backend, and finishes a purchase only after
+ * the backend's ledger grant. Nothing here grants: only the backend response
+ * moves a record to `granted`, and only the backend ledger moves it to
+ * `revoked`.
+ */
+/** Journal record kind of a commerce v2 purchase. */
+export const commercePurchaseOperationKind = 'commerce-purchase';
+/** The store key of a commerce v2 purchase record: one namespace per ledger target. */
+export function createCommercePurchaseOperationKey(target, idempotencyKey) {
+    if (typeof idempotencyKey !== 'string' || idempotencyKey.trim() === '') {
+        throw new Error('Commerce purchase operations require a nonempty idempotency key.');
+    }
+    return JSON.stringify([target, commercePurchaseOperationKind, idempotencyKey]);
+}
+export function isCommercePurchaseOperationRecord(record) {
+    return typeof record === 'object'
+        && record !== null
+        && record.kind === commercePurchaseOperationKind;
+}
+/** Summary status of a record: the RFC mapping, with `revoked` kept distinct. */
+export function summarizeCommercePurchaseOperation(record) {
+    return summarizeCommercePurchaseState(record.state);
+}
+/**
+ * Only `granted` and `finishing` records that hold the backend's ledger entry
+ * id and a store transaction may be finished. The StoreKit v2 SDK keeps no
+ * finish allow-list of its own (the v1 driver's `finishGrantedTransaction`
+ * pairing), so this is the finish gate for every `client` and `host` owner:
+ * the ledger entry id comes from the journal revision the backend grant wrote.
+ */
+export function assertCommerceFinishAllowed(record) {
+    if (record.state !== 'granted' && record.state !== 'finishing') {
+        throw new Error(`Commerce purchase ${record.idempotencyKey} is ${record.state}; only granted or finishing records are finished.`);
+    }
+    const ledgerEntryId = record.ledgerEntryId;
+    const transactionId = record.purchase?.transactionId;
+    if (typeof ledgerEntryId !== 'string' || ledgerEntryId.trim() === '') {
+        throw new Error(`Commerce purchase ${record.idempotencyKey} has no ledger entry id; the backend grant must finish it.`);
+    }
+    if (typeof transactionId !== 'string' || transactionId.trim() === '') {
+        throw new Error(`Commerce purchase ${record.idempotencyKey} has no store transaction to finish.`);
+    }
+    return { transactionId, ledgerEntryId };
+}
+/** The `GameServicesPurchaseResult` a journal record stands for; `pending` allows no client-side grant. */
+export function toGameServicesPurchaseResult(record) {
+    const status = summarizeCommercePurchaseOperation(record);
+    return {
+        status,
+        purchase: toPurchaseResult(record),
+        ...(record.response === undefined ? {} : { verification: record.response }),
+        ...(record.ledgerEntryId === undefined ? {} : { ledgerEntryId: record.ledgerEntryId }),
+    };
+}
+function toPurchaseResult(record) {
+    const purchase = record.purchase;
+    if (record.state === 'cancelled' || record.state === 'failed') {
+        return {
+            status: record.state,
+            entitlementIds: [],
+            ...(record.error === undefined ? {} : { diagnostic: toDiagnostic(record.error) }),
+        };
+    }
+    if (purchase === undefined) {
+        return { status: 'pending', entitlementIds: [] };
+    }
+    return {
+        status: purchase.state === 'purchased' ? 'completed' : 'pending',
+        transactionId: purchase.transactionId,
+        entitlementIds: [],
+        evidence: purchase.evidence,
+    };
+}
+function toDiagnostic(error) {
+    const providerCode = error.storeCode;
+    return {
+        code: error.code,
+        retryable: error.retryable,
+        ...(providerCode !== undefined && /^[A-Za-z0-9_.:-]{1,128}$/u.test(providerCode)
+            ? { providerCode }
+            : {}),
+    };
+}
+export const defaultStaleLaunchedAfterMs = 24 * 60 * 60 * 1000;
+/** How long one backend capabilities read may take before the last comparison is kept. */
+export const defaultServiceCapabilitiesTimeoutMs = 10 * 1000;
+export const defaultRetryIntervalMs = 60 * 1000;
+export const defaultInFlightTimeoutMs = 10 * 60 * 1000;
+function isOpen(state) {
+    return state === 'launched' || state === 'pending';
+}
+/** A backend answer that the capabilities read does not exist: HTTP 404 or oRPC NOT_FOUND. */
+function isNotFoundError(error) {
+    if (typeof error !== 'object' || error === null) {
+        return false;
+    }
+    const { status, code } = error;
+    return status === 404 || code === 'NOT_FOUND';
+}
+export function createCommerceReconciler(input) {
+    const { provider, backend, store: journal, playerId } = input;
+    const storeId = provider.store;
+    const target = input.target;
+    const deploymentTarget = input.deploymentTarget ?? input.target;
+    const now = input.now ?? (() => new Date().toISOString());
+    const staleLaunchedAfterMs = input.staleLaunchedAfterMs ?? defaultStaleLaunchedAfterMs;
+    const retryIntervalMs = input.retryIntervalMs ?? defaultRetryIntervalMs;
+    const inFlightTimeoutMs = input.inFlightTimeoutMs ?? defaultInFlightTimeoutMs;
+    const serviceCapabilitiesTimeoutMs = input.serviceCapabilitiesTimeoutMs
+        ?? defaultServiceCapabilitiesTimeoutMs;
+    if (!Number.isFinite(serviceCapabilitiesTimeoutMs) || serviceCapabilitiesTimeoutMs <= 0) {
+        throw new RangeError('serviceCapabilitiesTimeoutMs must be a positive finite duration.');
+    }
+    if (typeof playerId !== 'string' || playerId.trim() === '') {
+        throw new TypeError('The commerce reconciler requires an authenticated player id.');
+    }
+    if (!(staleLaunchedAfterMs > 0)) {
+        throw new RangeError('staleLaunchedAfterMs must be a positive duration.');
+    }
+    if (!(retryIntervalMs >= 0)) {
+        throw new RangeError('retryIntervalMs must be a non-negative duration.');
+    }
+    if (!(inFlightTimeoutMs > 0)) {
+        throw new RangeError('inFlightTimeoutMs must be a positive duration.');
+    }
+    const listeners = new Set();
+    if (input.onEvent !== undefined) {
+        listeners.add(input.onEvent);
+    }
+    const emit = (event) => {
+        for (const listener of [...listeners]) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Observers have no authority over the journal.
+            }
+        }
+    };
+    const fail = (stage, error, idempotencyKey) => {
+        emit({
+            type: 'failure',
+            stage,
+            ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+            error,
+        });
+    };
+    /** Records seen this session by purchase idempotency key, terminal ones included for matching. */
+    const records = new Map();
+    const inbox = [];
+    /** The start-time read of the available purchases failed; the next pass retries it. */
+    let initialScanPending = false;
+    /**
+     * Purchase calls whose store call is still running, by key and product; a
+     * `requested` record outside this map is stale, and events for these
+     * products wait until the call journals the store answer.
+     */
+    const inFlightKeys = new Map();
+    const nowMs = () => Date.parse(now());
+    const isInFlight = (idempotencyKey) => {
+        const entry = inFlightKeys.get(idempotencyKey);
+        return entry !== undefined && nowMs() - entry.since < inFlightTimeoutMs;
+    };
+    const inFlightProducts = () => new Set([...inFlightKeys.entries()]
+        .filter(([key]) => isInFlight(key))
+        .map(([, entry]) => entry.logicalId));
+    /** Events for an in-flight product, replayed by the pass after the call ends. */
+    const deferred = [];
+    const defer = (event) => {
+        // A polled provider lists the same purchase on every pass; keep one copy.
+        if (event.type === 'purchaseUpdated'
+            && deferred.some((waiting) => waiting.type === 'purchaseUpdated'
+                && waiting.purchase.transactionId === event.purchase.transactionId
+                && waiting.purchase.state === event.purchase.state)) {
+            return;
+        }
+        deferred.push(event);
+    };
+    /** Earliest time (ms) an event-triggered pass may retry a record's backend or store step. */
+    const retryAt = new Map();
+    const retryLater = (idempotencyKey) => {
+        retryAt.set(idempotencyKey, nowMs() + retryIntervalMs);
+    };
+    /**
+     * The same store purchase: the transaction id, or the token when the store
+     * renames the transaction (Play reports the token key until it assigns an
+     * order id). A store whose ids are unique among unfinished purchases only
+     * (Microsoft Store reuses the add-on id) relies on the provider deriving a
+     * transaction-unique id; until then a repurchase that the store lists under
+     * a finished record's id is journaled only when the game started it.
+     */
+    const samePurchase = (left, right) => left.transactionId === right.transactionId
+        || (left.token !== undefined && left.token === right.token);
+    const productCache = new Map();
+    let capabilities;
+    let serviceAlignment;
+    /** A backend that answered 404 / NOT_FOUND for the ledger status read: not asked again. */
+    let ledgerStatusUnpublished = false;
+    /** Serializes the backend capabilities read so overlapping triggers share one. */
+    let serviceAlignmentRead;
+    let unsubscribe;
+    let started = false;
+    /** The start in progress, so overlapping calls share one subscription. */
+    let starting;
+    let triggerPending = false;
+    let running;
+    let pendingFailure;
+    let tail = Promise.resolve();
+    /** Passes and purchase requests never interleave their journal writes. */
+    function withLock(job) {
+        const next = tail.then(job, job);
+        tail = next.catch(() => undefined);
+        return next;
+    }
+    const trigger = () => {
+        triggerPending = true;
+    };
+    const ownsRecord = (record) => record.playerId === playerId
+        && record.target === target
+        && record.deploymentTarget === deploymentTarget
+        && record.store === storeId;
+    const remember = (record) => {
+        records.set(record.idempotencyKey, record);
+        return record;
+    };
+    /**
+     * The provider's capability block. Event-triggered passes use the last read;
+     * an explicit trigger (`start`, `reconcile`, `restorePurchases`) reads it
+     * again, since availability can change at runtime. A failed read keeps the
+     * last block.
+     */
+    const withServiceAlignment = (block) => block === undefined || serviceAlignment?.status !== 'configuration-required'
+        ? block
+        : { ...block, availability: 'configuration-required' };
+    const readCapabilities = async (refresh = false) => {
+        if (capabilities !== undefined && !refresh) {
+            return withServiceAlignment(capabilities);
+        }
+        try {
+            capabilities = await provider.getCapabilities();
+        }
+        catch (error) {
+            fail('capabilities', error);
+        }
+        return withServiceAlignment(capabilities);
+    };
+    /**
+     * Compares the provider with the backend's published capabilities when the
+     * backend offers them: a store the backend does not accept, or a finish
+     * owner that disagrees, sets availability to `configuration-required`
+     * before any purchase UI opens. A failed read keeps the last comparison.
+     */
+    const readServiceAlignment = async () => {
+        const readService = backend.getCommerceCapabilities;
+        if (readService === undefined
+            || capabilities === undefined
+            || serviceAlignment?.status === 'unpublished') {
+            return;
+        }
+        if (serviceAlignmentRead !== undefined) {
+            return serviceAlignmentRead;
+        }
+        const providerBlock = capabilities;
+        serviceAlignmentRead = (async () => {
+            let timeout;
+            try {
+                const service = await Promise.race([
+                    readService.call(backend),
+                    new Promise((_resolve, reject) => {
+                        timeout = setTimeout(() => {
+                            reject(new Error('The backend commerce capabilities read timed out.'));
+                        }, serviceCapabilitiesTimeoutMs);
+                    }),
+                ]);
+                serviceAlignment = compareCommerceServiceCapabilities({
+                    store: storeId,
+                    provider: providerBlock,
+                    service,
+                });
+                if (serviceAlignment.status === 'configuration-required') {
+                    fail('capabilities', new CommerceError('CONFIGURATION_REQUIRED', {
+                        message: serviceAlignment.message,
+                        storeCode: serviceAlignment.reason,
+                    }));
+                }
+            }
+            catch (error) {
+                if (isNotFoundError(error)) {
+                    // A v1 backend behind a v2 client adapter: it publishes nothing, and
+                    // that is remembered rather than read again on every refresh.
+                    serviceAlignment = { status: 'unpublished', store: storeId };
+                    return;
+                }
+                // A failed or timed-out read keeps the last comparison.
+                fail('capabilities', error);
+            }
+            finally {
+                if (timeout !== undefined) {
+                    clearTimeout(timeout);
+                }
+                serviceAlignmentRead = undefined;
+            }
+        })();
+        return serviceAlignmentRead;
+    };
+    const resolveProduct = async (lookup) => {
+        const matches = (product) => 'logicalId' in lookup
+            ? product.logicalId === lookup.logicalId
+            : product.storeSku === lookup.storeSku;
+        const configured = input.products?.find(matches);
+        if (configured !== undefined) {
+            return configured;
+        }
+        const cached = [...productCache.values()].find(matches);
+        if (cached !== undefined) {
+            return cached;
+        }
+        try {
+            const products = await provider.fetchProducts('logicalId' in lookup
+                ? { logicalIds: [lookup.logicalId] }
+                : { type: 'all' });
+            for (const product of products) {
+                productCache.set(product.logicalId, {
+                    logicalId: product.logicalId,
+                    kind: product.kind,
+                    storeSku: product.storeSku,
+                });
+            }
+            return [...productCache.values()].find(matches);
+        }
+        catch (error) {
+            fail('catalog', error);
+            return undefined;
+        }
+    };
+    const resolveLogicalId = async (purchase) => {
+        const product = purchase.logicalId === undefined
+            ? await resolveProduct({ storeSku: purchase.storeSku })
+            : await resolveProduct({ logicalId: purchase.logicalId });
+        if (product === undefined) {
+            if (purchase.logicalId !== undefined) {
+                // The provider mapped the SKU itself. The kind stays unknown until the
+                // catalog answers: a client or host finish never guesses consumable.
+                return { logicalId: purchase.logicalId };
+            }
+            return undefined;
+        }
+        return { logicalId: product.logicalId, kind: product.kind };
+    };
+    const write = async (record, state, patch = {}) => {
+        assertCommercePurchaseTransition(record.state, state);
+        const next = {
+            ...record,
+            ...patch,
+            state,
+            revision: record.revision + 1,
+            updatedAt: now(),
+        };
+        await journal.replace(record.revision, next);
+        remember(next);
+        retryAt.delete(next.idempotencyKey);
+        emit({ type: 'transition', record: next, previous: record.state });
+        return next;
+    };
+    const reserve = async (record) => {
+        const candidate = {
+            ...record,
+            kind: commercePurchaseOperationKind,
+            key: createCommercePurchaseOperationKey(target, record.idempotencyKey),
+            playerId,
+            target,
+            deploymentTarget,
+            revision: 0,
+            updatedAt: now(),
+        };
+        const reserved = await journal.reserve(candidate);
+        if (!isCommercePurchaseOperationRecord(reserved.record)) {
+            throw new Error('Commerce purchase operation key is bound to another operation kind.');
+        }
+        if (!ownsRecord(reserved.record)) {
+            throw new Error('Commerce purchase operation key is bound to another player or store.');
+        }
+        remember(reserved.record);
+        if (reserved.created) {
+            emit({ type: 'transition', record: reserved.record, previous: undefined });
+        }
+        return { created: reserved.created, record: reserved.record };
+    };
+    const readRecord = async (idempotencyKey) => {
+        const found = await journal.read(createCommercePurchaseOperationKey(target, idempotencyKey));
+        if (found === undefined) {
+            return records.get(idempotencyKey);
+        }
+        if (!isCommercePurchaseOperationRecord(found) || !ownsRecord(found)) {
+            throw new Error('Commerce purchase operation key is bound to another player or store.');
+        }
+        return remember(found);
+    };
+    const ownedRecordsOf = (listed) => listed.filter((record) => isCommercePurchaseOperationRecord(record) && ownsRecord(record));
+    const listRecoverable = async () => ownedRecordsOf(await journal.listRecoverable(playerId))
+        .filter((record) => !isTerminalCommercePurchaseState(record.state))
+        .map(remember);
+    const listGranted = async () => {
+        const listed = journal.listGranted === undefined
+            ? []
+            : ownedRecordsOf(await journal.listGranted(playerId)).map(remember);
+        const granted = new Map();
+        for (const record of [...listed, ...records.values()]) {
+            if (record.ledgerEntryId !== undefined
+                && (record.state === 'granted' || record.state === 'finishing' || record.state === 'finished')) {
+                granted.set(record.idempotencyKey, record);
+            }
+        }
+        return [...granted.values()];
+    };
+    const loadRecords = async () => {
+        await listRecoverable();
+        if (journal.listGranted !== undefined) {
+            ownedRecordsOf(await journal.listGranted(playerId)).forEach(remember);
+        }
+    };
+    const openRecordsFor = (logicalId) => [...records.values()].filter((record) => record.store === storeId
+        && (logicalId === undefined || record.logicalId === logicalId)
+        && isOpen(record.state));
+    const listener = (event) => {
+        if (event.type === 'subscriptionUpdated') {
+            return;
+        }
+        inbox.push(event);
+        trigger();
+        scheduleRun();
+    };
+    const readAvailable = async (capabilitiesNow) => {
+        if (!capabilitiesNow.lifecycle.availablePurchases) {
+            return true;
+        }
+        try {
+            const available = await provider.getAvailablePurchases({
+                includePending: capabilitiesNow.lifecycle.pending,
+            });
+            for (const purchase of available) {
+                inbox.push({ type: 'purchaseUpdated', purchase });
+            }
+            return true;
+        }
+        catch (error) {
+            fail('available', error);
+            return false;
+        }
+    };
+    const buildRequest = (record) => {
+        const purchase = record.purchase;
+        if (purchase === undefined) {
+            throw new Error(`Commerce purchase ${record.idempotencyKey} is purchased without a purchase.`);
+        }
+        return {
+            // The ledger target names the deployment platform; `store` names the
+            // store the purchase was made in (RFC "Open store ids"). A v1 server
+            // ignores `store` and keeps mapping the target.
+            target,
+            store: storeId,
+            ...(deploymentTarget === target ? {} : { deploymentTarget }),
+            playerId,
+            productId: record.logicalId,
+            platformTransactionId: purchase.transactionId,
+            idempotencyKey: record.idempotencyKey,
+            purchasedAt: purchase.purchasedAt ?? now(),
+            evidence: purchase.evidence,
+        };
+    };
+    // Reconciler step 2: match a reported purchase to a journal record.
+    const ingestPurchase = async (purchase) => {
+        if (purchase.store !== storeId) {
+            fail('match', new Error(`Purchase ${purchase.transactionId} belongs to store ${purchase.store}, not ${storeId}.`));
+            return;
+        }
+        const product = await resolveLogicalId(purchase);
+        if (product === undefined) {
+            fail('catalog', new Error(`Purchase ${purchase.transactionId} names SKU ${purchase.storeSku}, which no catalog entry declares.`));
+            return;
+        }
+        let record = [...records.values()].find((candidate) => candidate.store === storeId
+            && candidate.purchase !== undefined
+            && samePurchase(candidate.purchase, purchase));
+        if (record === undefined && journal.findByTransaction !== undefined) {
+            // A terminal record of this transaction (finished, rejected) is not in
+            // memory after a restart; the journal index keeps it from being
+            // verified again under a derived key.
+            const stored = await journal.findByTransaction({
+                playerId,
+                target,
+                deploymentTarget,
+                store: storeId,
+                transactionId: purchase.transactionId,
+            });
+            if (stored !== undefined && isCommercePurchaseOperationRecord(stored) && ownsRecord(stored)) {
+                record = remember(stored);
+            }
+        }
+        if (record === undefined) {
+            const open = openRecordsFor(product.logicalId);
+            if (open.length > 1) {
+                fail('match', new Error(`Purchase ${purchase.transactionId} matches ${open.length} open records for ${product.logicalId}.`), open[0]?.idempotencyKey);
+                return;
+            }
+            record = open[0];
+            if (record?.purchase !== undefined && !samePurchase(record.purchase, purchase)) {
+                // The open attempt already holds another transaction (store-side or
+                // backend-side pending): this is a second purchase of the product.
+                record = undefined;
+            }
+        }
+        if (record === undefined) {
+            if (purchase.state === 'revoked') {
+                // Revoked store states never revoke on their own: only the ledger does (step 5).
+                return;
+            }
+            const idempotencyKey = await createDerivedPurchaseIdempotencyKey({
+                store: purchase.store,
+                transactionId: purchase.transactionId,
+                token: purchase.token,
+            });
+            record = await readRecord(idempotencyKey);
+            if (record !== undefined
+                && (record.logicalId !== product.logicalId
+                    || (record.purchase !== undefined && !samePurchase(record.purchase, purchase)))) {
+                // A game key that happens to equal the derived key names another
+                // attempt; the purchase is never attached to it.
+                fail('match', new Error(`Purchase ${purchase.transactionId} derives key ${idempotencyKey}, which journals another attempt.`), idempotencyKey);
+                return;
+            }
+            if (record === undefined) {
+                await reserve({
+                    idempotencyKey,
+                    store: purchase.store,
+                    logicalId: product.logicalId,
+                    ...(product.kind === undefined ? {} : { productKind: product.kind }),
+                    origin: 'discovered',
+                    state: purchase.state,
+                    purchase,
+                });
+                return;
+            }
+        }
+        if (purchase.state === 'pending' && record.state === 'launched') {
+            await write(record, 'pending', { purchase });
+            return;
+        }
+        if (purchase.state === 'purchased'
+            && (record.state === 'launched' || (record.state === 'pending' && record.request === undefined))) {
+            await write(record, 'purchased', { purchase });
+        }
+    };
+    const ingestError = async (logicalId, error) => {
+        if (error.code === 'OUTCOME_UNKNOWN' || error.code === 'ALREADY_OWNED') {
+            // Not terminal for an attempt: an unfinished purchase may exist, so the
+            // record stays open and the available purchases resolve it.
+            return;
+        }
+        if (logicalId === undefined) {
+            // An unattributed error cannot be bound to one attempt; the available
+            // purchases or the launched-attempt expiry decide it.
+            return;
+        }
+        // Only an attempt the store never answered can end on an error event: a
+        // record holding a store purchase or a saved verify request is decided by
+        // the available purchases and the backend, never by a later error.
+        const open = openRecordsFor(logicalId).filter((record) => record.purchase === undefined && record.request === undefined);
+        if (open.length > 1) {
+            fail('match', new Error(`purchaseError${logicalId === undefined ? '' : ` for ${logicalId}`} matches ${open.length} open records.`));
+            return;
+        }
+        const record = open[0];
+        if (record !== undefined) {
+            await write(record, error.code === 'USER_CANCELLED' ? 'cancelled' : 'failed', { error });
+        }
+    };
+    const staleAttemptError = (message) => ({
+        code: 'OUTCOME_UNKNOWN',
+        retryable: false,
+        message,
+    });
+    const sendVerify = async (record, request) => {
+        emit({ type: 'verify-requested', record });
+        try {
+            const response = await backend.verifyPurchase(request);
+            emit({ type: 'verify-result', record, response });
+            return response;
+        }
+        catch (error) {
+            // Transport failure: the state is kept and the next pass resends the saved request.
+            fail('verify', error, record.idempotencyKey);
+            return undefined;
+        }
+    };
+    // Reconciler steps 3 and 4: drive one record as far as the backend and the store allow.
+    const drive = async (initial, capabilitiesNow, explicit) => {
+        let record = initial;
+        /** Finalization the grant of this drive reported; a later pass re-reads it from the backend. */
+        let finalization;
+        const waitUntil = retryAt.get(record.idempotencyKey);
+        if (!explicit && waitUntil !== undefined && nowMs() < waitUntil) {
+            // An unrelated store event does not retry a backend or store step
+            // inside the interval; an explicit trigger always does.
+            return;
+        }
+        try {
+            for (;;) {
+                switch (record.state) {
+                    case 'requested':
+                        if (isInFlight(record.idempotencyKey)) {
+                            return;
+                        }
+                        // The store answer was never journaled (a crash or a lost write
+                        // after the reservation): the attempt ends so the product is not
+                        // serialized behind it; a purchase the store reports later is
+                        // journaled under its derived key.
+                        await write(record, 'failed', {
+                            error: staleAttemptError(`The store answer for ${record.idempotencyKey} was never journaled.`),
+                        });
+                        return;
+                    case 'launched': {
+                        if (record.purchase !== undefined || isInFlight(record.idempotencyKey)) {
+                            return;
+                        }
+                        const age = Date.parse(now()) - Date.parse(record.updatedAt);
+                        if (Number.isFinite(age) && age > staleLaunchedAfterMs) {
+                            await write(record, 'failed', {
+                                error: staleAttemptError(`No store purchase was reported for ${record.idempotencyKey} within ${String(staleLaunchedAfterMs)} ms.`),
+                            });
+                        }
+                        return;
+                    }
+                    case 'purchased':
+                        record = await write(record, 'verifying', {
+                            request: record.request ?? buildRequest(record),
+                        });
+                        continue;
+                    case 'pending':
+                        if (record.request === undefined) {
+                            // Store-side pending: waiting on the store, never sent.
+                            return;
+                        }
+                        record = await write(record, 'verifying');
+                        continue;
+                    case 'verifying': {
+                        const request = record.request ?? buildRequest(record);
+                        const response = await sendVerify(record, request);
+                        if (response === undefined) {
+                            retryLater(record.idempotencyKey);
+                            return;
+                        }
+                        if (!response.verified) {
+                            if (response.disposition === 'pending') {
+                                await write(record, 'pending', { request, response });
+                                retryLater(record.idempotencyKey);
+                            }
+                            else {
+                                await write(record, 'rejected', { request, response });
+                            }
+                            return;
+                        }
+                        const ledgerEntryId = response.ledgerEntryId;
+                        if (typeof ledgerEntryId !== 'string' || ledgerEntryId.trim() === '') {
+                            fail('verify', new Error(`A verified response for ${record.idempotencyKey} must carry a ledgerEntryId.`), record.idempotencyKey);
+                            return;
+                        }
+                        finalization = response.finalization?.status;
+                        record = await write(record, 'granted', { request, response, ledgerEntryId });
+                        continue;
+                    }
+                    case 'granted':
+                        if (capabilitiesNow === undefined) {
+                            return;
+                        }
+                        if (capabilitiesNow.lifecycle.finish === 'none') {
+                            await write(record, 'finished');
+                            return;
+                        }
+                        record = await write(record, 'finishing');
+                        continue;
+                    case 'finishing': {
+                        if (capabilitiesNow === undefined) {
+                            return;
+                        }
+                        const owner = capabilitiesNow.lifecycle.finish;
+                        if (owner === 'none') {
+                            await write(record, 'finished');
+                            return;
+                        }
+                        if (owner === 'server') {
+                            let reread;
+                            if (finalization === undefined) {
+                                // A pass that did not grant resends the saved request to read
+                                // finalization; the backend replays the grant, never a second one.
+                                reread = await sendVerify(record, record.request ?? buildRequest(record));
+                                finalization = reread?.verified === true
+                                    ? reread.finalization?.status
+                                    : undefined;
+                            }
+                            if (finalization === 'completed') {
+                                // The re-read is the last backend answer the record reports.
+                                await write(record, 'finished', reread === undefined ? {} : { response: reread });
+                            }
+                            else {
+                                retryLater(record.idempotencyKey);
+                            }
+                            return;
+                        }
+                        const finish = assertCommerceFinishAllowed(record);
+                        if (provider.finishTransaction === undefined) {
+                            fail('finish', new Error(`The provider declares finish '${owner}' but has no finishTransaction.`), record.idempotencyKey);
+                            return;
+                        }
+                        // A consume and an acknowledge are not interchangeable: the finish
+                        // waits until the catalog says which kind the product is.
+                        const kind = record.productKind
+                            ?? (await resolveProduct({ logicalId: record.logicalId }))?.kind;
+                        if (kind === undefined) {
+                            fail('catalog', new Error(`The kind of ${record.logicalId} is unknown; the finish waits for the catalog.`), record.idempotencyKey);
+                            retryLater(record.idempotencyKey);
+                            return;
+                        }
+                        let finished = false;
+                        try {
+                            finished = (await provider.finishTransaction({
+                                transactionId: finish.transactionId,
+                                ledgerEntryId: finish.ledgerEntryId,
+                                isConsumable: kind === 'consumable',
+                            })).finished;
+                        }
+                        catch (error) {
+                            // Transport-class failure: keep `finishing` for the next pass.
+                            fail('finish', error, record.idempotencyKey);
+                            retryLater(record.idempotencyKey);
+                            return;
+                        }
+                        if (finished) {
+                            await write(record, 'finished');
+                        }
+                        else {
+                            retryLater(record.idempotencyKey);
+                        }
+                        return;
+                    }
+                    default:
+                        return;
+                }
+            }
+        }
+        catch (error) {
+            // A journal write that lost its compare-and-swap, or a malformed record:
+            // the next pass reads the stored revision again.
+            fail('journal', error, record.idempotencyKey);
+        }
+    };
+    // Reconciler step 5: reversed grants move to revoked. Needs the backend's
+    // ledger status read (C2); without it the hook is inert.
+    const revokeReversed = async () => {
+        const ledgerStatus = backend.getPurchaseLedgerStatus;
+        if (ledgerStatus === undefined || ledgerStatusUnpublished) {
+            return;
+        }
+        const granted = await listGranted();
+        if (granted.length === 0) {
+            return;
+        }
+        const ledgerEntryIds = [...new Set(granted.flatMap((record) => (record.ledgerEntryId === undefined ? [] : [record.ledgerEntryId])))];
+        const statuses = [];
+        try {
+            // Reads are chunked to what a backend store accepts in one query.
+            for (const chunk of chunkLedgerEntryIds(ledgerEntryIds)) {
+                const response = await ledgerStatus.call(backend, { ledgerEntryIds: chunk, playerId });
+                statuses.push(...response.statuses);
+            }
+        }
+        catch (error) {
+            if (isNotFoundError(error)) {
+                // A pre-C2 backend behind a transport adapter that always exposes the
+                // read: the hook stays inert, as it is for a backend without it.
+                ledgerStatusUnpublished = true;
+                return;
+            }
+            fail('ledger-status', error);
+            return;
+        }
+        for (const record of granted) {
+            const status = statuses.find((candidate) => candidate.ledgerEntryId === record.ledgerEntryId);
+            if (status?.status !== 'reversed') {
+                continue;
+            }
+            try {
+                await write(record, 'revoked', {
+                    ...(status.reversedBy === undefined ? {} : { revokedBy: status.reversedBy }),
+                });
+            }
+            catch (error) {
+                fail('journal', error, record.idempotencyKey);
+            }
+        }
+    };
+    const eventPass = { explicit: false, refreshCapabilities: false };
+    const pass = async (options) => {
+        let capabilitiesNow = await readCapabilities(options.refreshCapabilities);
+        if (options.refreshCapabilities) {
+            await readServiceAlignment();
+            capabilitiesNow = withServiceAlignment(capabilities);
+        }
+        // A provider without lifecycle.events is polled: every pass reads its
+        // available purchases. An event provider whose start-time read failed is
+        // read again until it succeeds, so a purchase that predates the
+        // subscription is not missed for the session.
+        if (capabilitiesNow !== undefined && (!capabilitiesNow.lifecycle.events || initialScanPending)) {
+            initialScanPending = !(await readAvailable(capabilitiesNow)) && capabilitiesNow.lifecycle.events;
+        }
+        // An event for a product whose store call is still running waits for that
+        // call to journal the store answer: matched then, it is never journaled
+        // twice, and a cancel event ends the attempt the call launched.
+        const busy = inFlightProducts();
+        for (const event of [
+            ...deferred.splice(0, deferred.length),
+            ...inbox.splice(0, inbox.length),
+        ]) {
+            try {
+                if (event.type === 'purchaseUpdated') {
+                    const product = busy.size === 0 ? undefined : await resolveLogicalId(event.purchase);
+                    if (product !== undefined && busy.has(product.logicalId)) {
+                        defer(event);
+                        continue;
+                    }
+                    await ingestPurchase(event.purchase);
+                }
+                else if (event.type === 'purchaseError') {
+                    if (event.logicalId !== undefined && busy.has(event.logicalId)) {
+                        defer(event);
+                        continue;
+                    }
+                    await ingestError(event.logicalId, event.error);
+                }
+            }
+            catch (error) {
+                fail('journal', error);
+            }
+        }
+        for (const record of await listRecoverable()) {
+            await drive(records.get(record.idempotencyKey) ?? record, capabilitiesNow, options.explicit);
+        }
+        await revokeReversed();
+    };
+    const runUntilIdle = async () => {
+        if (running !== undefined) {
+            try {
+                await running;
+            }
+            catch (error) {
+                pendingFailure = undefined;
+                throw error;
+            }
+            // An event that landed between the loop's last check and its teardown.
+            if (started && triggerPending && running === undefined) {
+                await runUntilIdle();
+            }
+            return;
+        }
+        if (pendingFailure !== undefined) {
+            const failure = pendingFailure;
+            pendingFailure = undefined;
+            throw failure.error;
+        }
+        if (!started || !triggerPending) {
+            return;
+        }
+        const loop = (async () => {
+            while (started && triggerPending) {
+                triggerPending = false;
+                await withLock(() => pass(eventPass));
+            }
+        })();
+        running = loop.finally(() => {
+            running = undefined;
+        });
+        await running;
+    };
+    function scheduleRun() {
+        runUntilIdle().catch((error) => {
+            pendingFailure = { error };
+        });
+    }
+    const journaled = (record) => {
+        if ((record.state === 'cancelled' || record.state === 'failed') && record.error !== undefined) {
+            return { outcome: record.state, error: record.error };
+        }
+        if (record.purchase !== undefined && record.state !== 'requested') {
+            return { outcome: 'purchased', purchase: record.purchase };
+        }
+        return { outcome: 'launched' };
+    };
+    const failedOutcome = (error) => ({
+        outcome: 'failed',
+        error: commerceErrorInfoOf(error),
+    });
+    /**
+     * Journal work before the store call, under the lock: a journaled key is
+     * answered, a product the store does not sell or a provider that is not
+     * ready is refused without a record (the key stays usable), an open attempt
+     * for the product refuses with IN_PROGRESS without a record, and only a call
+     * that will open the store reserves its record.
+     */
+    const prepareRequest = async (request) => {
+        if (!started) {
+            await loadRecords();
+        }
+        // A key is never regenerated on retry: the journaled attempt is the answer,
+        // and the store UI opens once per key however many calls overlap.
+        const existing = await readRecord(request.idempotencyKey);
+        if (existing !== undefined) {
+            if (existing.logicalId !== request.logicalId
+                || (existing.input !== undefined && existing.input.source !== request.source)) {
+                throw new Error('Purchase idempotency key is bound to another product or source.');
+            }
+            return { kind: 'answered', result: journaled(existing) };
+        }
+        const product = await resolveProduct({ logicalId: request.logicalId });
+        if (product === undefined) {
+            return {
+                kind: 'answered',
+                result: failedOutcome(new CommerceError('ITEM_UNAVAILABLE', {
+                    message: `Store ${storeId} does not sell ${request.logicalId}.`,
+                })),
+            };
+        }
+        const capabilitiesNow = await readCapabilities();
+        if (capabilitiesNow === undefined) {
+            return {
+                kind: 'answered',
+                result: failedOutcome(new CommerceError('NOT_PREPARED', {
+                    message: `The ${storeId} provider capabilities could not be read.`,
+                })),
+            };
+        }
+        if (serviceAlignment === undefined) {
+            // A purchase before `start()` finished, or whose start could not read
+            // the backend: the comparison is attempted before any store UI opens.
+            await readServiceAlignment();
+        }
+        if (serviceAlignment?.status === 'configuration-required') {
+            // The backend does not serve this store as the provider declares it:
+            // no store UI opens until the deployment is corrected.
+            return {
+                kind: 'answered',
+                result: failedOutcome(new CommerceError('CONFIGURATION_REQUIRED', {
+                    message: serviceAlignment.message,
+                    storeCode: serviceAlignment.reason,
+                })),
+            };
+        }
+        // Purchases are serialized per player, store, and logical product: an
+        // open attempt for the same product, or one whose store call is still
+        // running, refuses this one with IN_PROGRESS, so a reported purchase
+        // matches at most one open record.
+        const open = (await listRecoverable()).filter((candidate) => candidate.logicalId === product.logicalId
+            && (isOpen(candidate.state)
+                || (candidate.state === 'requested' && isInFlight(candidate.idempotencyKey))));
+        if (open.length > 0) {
+            return {
+                kind: 'answered',
+                result: failedOutcome(new CommerceError('IN_PROGRESS', {
+                    message: `A purchase of ${product.logicalId} is already in progress (${open[0]?.idempotencyKey}).`,
+                })),
+            };
+        }
+        const { created, record } = await reserve({
+            idempotencyKey: request.idempotencyKey,
+            store: storeId,
+            logicalId: product.logicalId,
+            productKind: product.kind,
+            origin: 'game',
+            state: 'requested',
+            input: {
+                productId: product.logicalId,
+                source: request.source,
+                idempotencyKey: request.idempotencyKey,
+            },
+        });
+        if (!created) {
+            return { kind: 'answered', result: journaled(record) };
+        }
+        try {
+            assertRequestPurchaseSupported(capabilitiesNow, request, product.kind);
+        }
+        catch (error) {
+            // The store does not sell this kind: a definitive answer the journal keeps.
+            const info = commerceErrorInfoOf(error);
+            await write(record, 'failed', { error: info });
+            return { kind: 'answered', result: { outcome: 'failed', error: info } };
+        }
+        // Only a call that opens the store is in flight; the entry is released by
+        // that call's `finally`, so no refused path can leave a product deferred.
+        inFlightKeys.set(request.idempotencyKey, { logicalId: product.logicalId, since: nowMs() });
+        return { kind: 'launch', record, product };
+    };
+    /**
+     * Journals what the store answered, under the lock. A journal write that
+     * fails here (a stale attempt another pass ended after a very long sheet)
+     * is reported; the store answer is still returned to the caller.
+     */
+    const recordAnswer = async (request, record, product, result) => {
+        try {
+            return await journalAnswer(request, record, product, result);
+        }
+        catch (error) {
+            fail('journal', error, record.idempotencyKey);
+            return result;
+        }
+    };
+    const journalAnswer = async (request, reserved, product, result) => {
+        // A sheet open past inFlightTimeoutMs may have been ended by a pass as a
+        // stale attempt; the journal's answer stands, and a purchase the store
+        // reported meanwhile is journaled under its own record.
+        const record = (await readRecord(reserved.idempotencyKey)) ?? reserved;
+        if (record.state !== 'requested') {
+            return journaled(record);
+        }
+        if (result.outcome === 'launched') {
+            await write(record, 'launched');
+        }
+        else if (result.outcome === 'purchased') {
+            const purchase = result.purchase;
+            const launched = await write(record, 'launched');
+            const reported = await resolveLogicalId(purchase);
+            // A record that journals this transaction and is still open, or that
+            // ended after this attempt was reserved, holds the purchase the store
+            // just answered with (an event that arrived first). A record that ended
+            // before the attempt started is an earlier purchase whose id the store
+            // reused (Microsoft Store add-on ids), so this answer is a new purchase.
+            const reservedAt = Date.parse(record.updatedAt);
+            const holder = [...records.values()].find((candidate) => candidate.idempotencyKey !== record.idempotencyKey
+                && candidate.store === storeId
+                && candidate.purchase !== undefined
+                && samePurchase(candidate.purchase, purchase)
+                && (!isTerminalCommercePurchaseState(candidate.state)
+                    || Date.parse(candidate.updatedAt) > reservedAt));
+            if (holder !== undefined) {
+                // The transaction is verified once, under the holder's key. This
+                // attempt is superseded so the product is not serialized behind it.
+                const error = staleAttemptError(`Purchase ${purchase.transactionId} is journaled as ${holder.idempotencyKey}; this attempt is superseded.`);
+                await write(launched, 'failed', { error });
+                return { outcome: 'failed', error };
+            }
+            if (purchase.store !== storeId || reported?.logicalId !== product.logicalId) {
+                // A synchronous answer for another product is not this attempt's
+                // purchase; the attempt stays open and the available purchases decide.
+                fail('match', new Error(`The provider answered ${request.idempotencyKey} with purchase ${purchase.transactionId} for ${purchase.store}/${purchase.storeSku}.`), record.idempotencyKey);
+                return { outcome: 'launched' };
+            }
+            if (purchase.state === 'pending') {
+                await write(launched, 'pending', { purchase });
+            }
+            else if (purchase.state === 'purchased') {
+                await write(launched, 'purchased', { purchase });
+            }
+        }
+        else {
+            await write(record, result.outcome, { error: result.error });
+        }
+        return result;
+    };
+    const requestPurchase = async (request) => {
+        let result;
+        // Only the call that reserved the record owns its in-flight entry: a
+        // same-key replay must not release it while the store sheet is open.
+        let owned = false;
+        try {
+            const prepared = await withLock(() => prepareRequest(request));
+            if (prepared.kind === 'answered') {
+                result = prepared.result;
+            }
+            else {
+                owned = true;
+                // The store call runs outside the lock: the sheet may stay open for
+                // minutes, and events arriving meanwhile are reconciled right away.
+                let answer;
+                try {
+                    answer = await provider.requestPurchase(request);
+                }
+                catch (error) {
+                    answer = failedOutcome(error);
+                }
+                result = await withLock(() => recordAnswer(request, prepared.record, prepared.product, answer));
+            }
+        }
+        finally {
+            if (owned) {
+                inFlightKeys.delete(request.idempotencyKey);
+            }
+        }
+        trigger();
+        try {
+            await runUntilIdle();
+        }
+        catch (error) {
+            // The store answer is journaled; a pass that failed meanwhile is
+            // reported, not thrown at the caller of a purchase already made.
+            fail('journal', error, request.idempotencyKey);
+        }
+        return result;
+    };
+    return {
+        provider,
+        get started() {
+            return started;
+        },
+        get serviceAlignment() {
+            return serviceAlignment;
+        },
+        async getCapabilities() {
+            const block = await readCapabilities();
+            if (block === undefined) {
+                throw new CommerceError('NOT_PREPARED', {
+                    message: `The ${storeId} provider capabilities could not be read.`,
+                });
+            }
+            return block;
+        },
+        async start() {
+            if (started) {
+                return;
+            }
+            if (starting !== undefined) {
+                return starting;
+            }
+            starting = (async () => {
+                try {
+                    await withLock(async () => {
+                        await loadRecords();
+                        // Subscribe first, then read: an event delivered before the listener is found either way.
+                        unsubscribe = provider.subscribe(listener);
+                        started = true;
+                        const capabilitiesNow = await readCapabilities(true);
+                        await readServiceAlignment();
+                        // An event-less provider is polled by the first pass instead, so it
+                        // is read once; a failed read is retried by the next pass.
+                        initialScanPending = capabilitiesNow === undefined
+                            || (capabilitiesNow.lifecycle.events && !(await readAvailable(capabilitiesNow)));
+                        await pass({ explicit: true, refreshCapabilities: false });
+                    });
+                    await runUntilIdle();
+                }
+                catch (error) {
+                    // A failed start is retryable: nothing stays subscribed or started.
+                    started = false;
+                    unsubscribe?.();
+                    unsubscribe = undefined;
+                    triggerPending = false;
+                    pendingFailure = undefined;
+                    inbox.length = 0;
+                    deferred.length = 0;
+                    records.clear();
+                    retryAt.clear();
+                    throw error;
+                }
+                finally {
+                    starting = undefined;
+                }
+            })();
+            return starting;
+        },
+        async stop() {
+            // A start still waiting for the lock subscribes later; let it finish so
+            // the teardown below sees its subscription.
+            if (starting !== undefined) {
+                try {
+                    await starting;
+                }
+                catch {
+                    // The start cleaned up after itself.
+                }
+            }
+            started = false;
+            unsubscribe?.();
+            unsubscribe = undefined;
+            // Quiesce: a pass awaiting the backend or the store finishes before state is dropped.
+            if (running !== undefined) {
+                try {
+                    await running;
+                }
+                catch (error) {
+                    pendingFailure = { error };
+                }
+            }
+            await tail;
+            triggerPending = false;
+            inbox.length = 0;
+            deferred.length = 0;
+            records.clear();
+            retryAt.clear();
+        },
+        async reconcile() {
+            await withLock(async () => {
+                if (!started) {
+                    await loadRecords();
+                }
+                await pass({ explicit: true, refreshCapabilities: true });
+            });
+            await runUntilIdle();
+        },
+        runUntilIdle,
+        async restorePurchases() {
+            if (provider.restorePurchases !== undefined) {
+                try {
+                    await provider.restorePurchases();
+                }
+                catch (error) {
+                    fail('restore', error);
+                }
+            }
+            await withLock(async () => {
+                if (!started) {
+                    await loadRecords();
+                }
+                const capabilitiesNow = await readCapabilities(true);
+                // A polled provider is read by the pass itself.
+                if (capabilitiesNow !== undefined && capabilitiesNow.lifecycle.events) {
+                    await readAvailable(capabilitiesNow);
+                }
+                await pass({ explicit: true, refreshCapabilities: false });
+            });
+            await runUntilIdle();
+        },
+        requestPurchase,
+        async fetchProducts(request = {}) {
+            return provider.fetchProducts(request);
+        },
+        read: readRecord,
+        listRecoverable,
+        subscribe(listenerToAdd) {
+            listeners.add(listenerToAdd);
+            return () => {
+                listeners.delete(listenerToAdd);
+            };
+        },
+    };
+}