@mpgd/game-services 0.28.1 → 0.29.0

package/dist/server.js

@@ -4,10 +4,12 @@ import { createAnalyticsReporter } from '@mpgd/analytics';
 import { resolveAdPlacementPlatformId, resolveCatalogCurrencies, resolveProductPlatformId, } from '@mpgd/catalog';
 import { gameServicesBackendEndpoints, } from './client.js';
 import { resolveCommerceStoreId, } from './commerce-evidence-registry.js';
-import { isEntitlementGrantReversed, readPurchaseLedgerStatuses, RevocationKeyConflictError, } from './commerce-ledger.js';
+import { createPurchaseHolderEvidenceVerificationId, findEntitlementRevocationsChunked, findPurchaseWideRevocation, holderRevocationEvidenceId, isEntitlementGrantReversed, isRestoredAcrossPlayers, listPurchaseHolders, readPurchaseLedgerStatuses, readPurchaseVerificationId, RevocationKeyConflictError, revokeEntitlementGrant, } from './commerce-ledger.js';
+import { assertPlayerDataErasureInput, createRetainedLedgerEntryId, detachRetainedLedgerPayload, isRetainedPlayerId, } from './account-deletion.js';
 import { gameServicesContract } from './contract.js';
 import { createRejectingGameServicesEvidenceVerifier, } from './evidence-verification.js';
-import { assertClaimAdRewardRequest, assertClaimAdRewardResponse, assertEntitlementLedgerGrant, assertEntitlementLedgerResult, assertEntitlementLedgerRevocation, assertEntitlementRevocationTransaction, assertGameServicesDeploymentTarget, assertLeaderboardScoreTransaction, assertProductGrantTransaction, assertPurchaseGrantFinalization, assertRecordLeaderboardScoreRequest, assertRecordLeaderboardScoreResponse, assertVerifyPurchaseRequest, assertVerifyPurchaseResponse, } from './types.js';
+import { assertClaimAdRewardRequest, assertClaimAdRewardResponse, assertEntitlementLedgerGrant, assertEntitlementLedgerNote, assertEntitlementLedgerResult, assertEntitlementLedgerRevocation, assertEntitlementRevocationTransaction, assertGameServicesDeploymentTarget, assertLeaderboardScoreTransaction, assertProductGrantTransaction, assertPurchaseGrantFinalization, assertRecordLeaderboardScoreRequest, assertRecordLeaderboardScoreResponse, assertVerifyPurchaseRequest, assertVerifyPurchaseResponse, } from './types.js';
+import { resolvePurchaseRestoreSharingPolicy, } from './purchase-sharing.js';
 import { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
 export { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
 export { listActiveEntitlementTransactions, readPurchaseLedgerStatuses, revokeEntitlementGrant, RevocationKeyConflictError, } from './commerce-ledger.js';
@@ -19,6 +21,7 @@ export class InMemoryGameServicesStore {
     revocationsByKey = new Map();
     revocationsByGrant = new Map();
     revocationsByEvidence = new Map();
+    notesById = new Map();
     leaderboardTransactionsByRun = new Map();
     leaderboardTransactionsById = new Map();
     async recordEntitlementGrant(input) {
@@ -46,17 +49,8 @@ export class InMemoryGameServicesStore {
             throw new EvidenceAlreadyProcessedError();
         }
         const transaction = createEntitlementTransaction(grant);
-        this.entitlementTransactionsByKey.set(key, transaction);
-        this.entitlementTransactionsById.set(transaction.ledgerEntryId, transaction);
-        if (grant.evidenceVerificationId !== undefined) {
-            this.entitlementTransactionsByEvidence.set(createEntitlementEvidenceKey({
-                source: grant.source,
-                evidenceVerificationId: grant.evidenceVerificationId,
-            }), transaction);
-        }
-        if (platformEvidenceIdentity !== undefined) {
-            this.entitlementTransactionsByPlatformEvidence.set(createEntitlementPlatformEvidenceKey(platformEvidenceIdentity), transaction);
-        }
+        // Indexes it by idempotency key, ledger entry id, and evidence identities.
+        this.rememberEntitlementTransaction(transaction);
         return assertEntitlementLedgerResult({
             ledgerEntryId: transaction.ledgerEntryId,
             alreadyProcessed: false,
@@ -68,6 +62,19 @@ export class InMemoryGameServicesStore {
     async findEntitlementTransactionByEvidenceVerificationId(input) {
         return this.entitlementTransactionsByEvidence.get(createEntitlementEvidenceKey(input));
     }
+    async findEntitlementTransactionsByEvidencePrefix(input) {
+        const found = [];
+        for (const transaction of this.entitlementTransactionsById.values()) {
+            if (transaction.source === input.source
+                && transaction.evidenceVerificationId?.startsWith(input.prefix) === true) {
+                found.push(transaction);
+                if (found.length >= input.limit) {
+                    break;
+                }
+            }
+        }
+        return found;
+    }
     async findEntitlementTransactionByPlatformEvidence(input) {
         return this.entitlementTransactionsByPlatformEvidence.get(createEntitlementPlatformEvidenceKey(input));
     }
@@ -119,11 +126,7 @@ export class InMemoryGameServicesStore {
             ...revocation,
             ledgerEntryId: createRevocationLedgerEntryId(revocation),
         });
-        this.revocationsByKey.set(key, transaction);
-        this.revocationsByGrant.set(revocation.revokesLedgerEntryId, transaction);
-        if (revocation.evidenceVerificationId !== undefined) {
-            this.revocationsByEvidence.set(revocation.evidenceVerificationId, transaction);
-        }
+        this.rememberEntitlementRevocation(transaction);
         return assertEntitlementLedgerResult({
             ledgerEntryId: transaction.ledgerEntryId,
             alreadyProcessed: false,
@@ -135,6 +138,23 @@ export class InMemoryGameServicesStore {
             .filter((revocation) => wanted.has(revocation.revokesLedgerEntryId))
             .sort((left, right) => left.revokedAt.localeCompare(right.revokedAt));
     }
+    async recordEntitlementNote(input) {
+        const note = assertEntitlementLedgerNote(input);
+        if (this.notesById.has(note.noteId)) {
+            return { alreadyRecorded: true };
+        }
+        if (!this.entitlementTransactionsById.has(note.ledgerEntryId)) {
+            throw new Error('Entitlement note references an unknown grant.');
+        }
+        this.notesById.set(note.noteId, note);
+        return { alreadyRecorded: false };
+    }
+    async findEntitlementNotes(input) {
+        const wanted = new Set(input.ledgerEntryIds);
+        return [...this.notesById.values()]
+            .filter((note) => wanted.has(note.ledgerEntryId))
+            .sort((left, right) => left.recordedAt.localeCompare(right.recordedAt));
+    }
     async recordLeaderboardScore(input, options = {}) {
         const request = assertRecordLeaderboardScoreRequest(input);
         const runKey = createLeaderboardRunKey(request);
@@ -167,6 +187,148 @@ export class InMemoryGameServicesStore {
     async listLeaderboardTransactions() {
         return this.sortedLeaderboardTransactions();
     }
+    async erasePlayerData(input) {
+        const { playerId, retainedPlayerId } = assertPlayerDataErasureInput(input);
+        let deleted = 0;
+        let retained = 0;
+        const grants = [...this.entitlementTransactionsById.values()]
+            .filter((transaction) => transaction.playerId === playerId);
+        const grantIds = new Set(grants.map((grant) => grant.ledgerEntryId));
+        const keptGrantIds = new Map();
+        for (const grant of grants) {
+            this.forgetEntitlementTransaction(grant);
+            if (grant.source !== 'purchase') {
+                deleted += 1;
+                continue;
+            }
+            const ledgerEntryId = createRetainedLedgerEntryId();
+            keptGrantIds.set(grant.ledgerEntryId, ledgerEntryId);
+            this.rememberEntitlementTransaction(assertProductGrantTransaction({
+                ...grant,
+                ledgerEntryId,
+                playerId: retainedPlayerId,
+                idempotencyKey: ledgerEntryId,
+                payload: detachRetainedLedgerPayload(grant.payload),
+            }));
+            retained += 1;
+        }
+        const keptRevocationIds = new Map();
+        const deletedRevocationIds = new Set();
+        for (const revocation of [...this.revocationsByGrant.values()]) {
+            if (revocation.playerId !== playerId && !grantIds.has(revocation.revokesLedgerEntryId)) {
+                continue;
+            }
+            this.forgetEntitlementRevocation(revocation);
+            // A revocation is kept with the grant it reverses, whoever wrote it.
+            const keptGrantId = keptGrantIds.get(revocation.revokesLedgerEntryId)
+                ?? (this.entitlementTransactionsById.has(revocation.revokesLedgerEntryId)
+                    ? revocation.revokesLedgerEntryId
+                    : undefined);
+            if (keptGrantId === undefined) {
+                deletedRevocationIds.add(revocation.ledgerEntryId);
+                deleted += 1;
+                continue;
+            }
+            const ledgerEntryId = createRetainedLedgerEntryId();
+            keptRevocationIds.set(revocation.ledgerEntryId, ledgerEntryId);
+            const kept = assertEntitlementRevocationTransaction({
+                ...revocation,
+                ledgerEntryId,
+                playerId: retainedPlayerId,
+                revokesLedgerEntryId: keptGrantId,
+                idempotencyKey: ledgerEntryId,
+                payload: detachRetainedLedgerPayload(revocation.payload),
+            });
+            this.rememberEntitlementRevocation(kept);
+            retained += 1;
+        }
+        for (const note of [...this.notesById.values()]) {
+            // Also a note (of another player) pointing at a revocation rewritten
+            // above, as the D1 eraser selects it.
+            const aboutKeptRevocation = note.revocationLedgerEntryId !== undefined
+                && keptRevocationIds.has(note.revocationLedgerEntryId);
+            if (note.revocationLedgerEntryId !== undefined && deletedRevocationIds.has(note.revocationLedgerEntryId)) {
+                // It points at a revocation deleted with the player's other grant.
+                this.notesById.delete(note.noteId);
+                deleted += 1;
+                continue;
+            }
+            if (note.playerId !== playerId && !grantIds.has(note.ledgerEntryId) && !aboutKeptRevocation) {
+                continue;
+            }
+            const keptGrantId = keptGrantIds.get(note.ledgerEntryId)
+                ?? (this.entitlementTransactionsById.has(note.ledgerEntryId) ? note.ledgerEntryId : undefined);
+            if (keptGrantId === undefined) {
+                this.notesById.delete(note.noteId);
+                deleted += 1;
+                continue;
+            }
+            const revocationLedgerEntryId = note.revocationLedgerEntryId === undefined
+                ? undefined
+                : (keptRevocationIds.get(note.revocationLedgerEntryId) ?? note.revocationLedgerEntryId);
+            this.notesById.set(note.noteId, assertEntitlementLedgerNote({
+                noteId: note.noteId,
+                kind: note.kind,
+                playerId: retainedPlayerId,
+                ledgerEntryId: keptGrantId,
+                ...(revocationLedgerEntryId === undefined ? {} : { revocationLedgerEntryId }),
+                recordedAt: note.recordedAt,
+                payload: detachRetainedLedgerPayload(note.payload),
+            }));
+            retained += 1;
+        }
+        for (const transaction of [...this.leaderboardTransactionsById.values()]) {
+            if (transaction.playerId !== playerId) {
+                continue;
+            }
+            this.leaderboardTransactionsById.delete(transaction.ledgerEntryId);
+            this.leaderboardTransactionsByRun.delete(createLeaderboardRunKey(transaction));
+            deleted += 1;
+        }
+        return { deleted, retained };
+    }
+    rememberEntitlementRevocation(revocation) {
+        this.revocationsByKey.set(createRevocationIdempotencyKey(revocation), revocation);
+        this.revocationsByGrant.set(revocation.revokesLedgerEntryId, revocation);
+        if (revocation.evidenceVerificationId !== undefined) {
+            this.revocationsByEvidence.set(revocation.evidenceVerificationId, revocation);
+        }
+    }
+    forgetEntitlementRevocation(revocation) {
+        this.revocationsByKey.delete(createRevocationIdempotencyKey(revocation));
+        this.revocationsByGrant.delete(revocation.revokesLedgerEntryId);
+        if (revocation.evidenceVerificationId !== undefined) {
+            this.revocationsByEvidence.delete(revocation.evidenceVerificationId);
+        }
+    }
+    forgetEntitlementTransaction(transaction) {
+        this.entitlementTransactionsByKey.delete(createEntitlementIdempotencyKey(transaction));
+        this.entitlementTransactionsById.delete(transaction.ledgerEntryId);
+        if (transaction.evidenceVerificationId !== undefined) {
+            this.entitlementTransactionsByEvidence.delete(createEntitlementEvidenceKey({
+                source: transaction.source,
+                evidenceVerificationId: transaction.evidenceVerificationId,
+            }));
+        }
+        const platformEvidenceIdentity = getEntitlementPlatformEvidenceIdentity(transaction);
+        if (platformEvidenceIdentity !== undefined) {
+            this.entitlementTransactionsByPlatformEvidence.delete(createEntitlementPlatformEvidenceKey(platformEvidenceIdentity));
+        }
+    }
+    rememberEntitlementTransaction(transaction) {
+        this.entitlementTransactionsByKey.set(createEntitlementIdempotencyKey(transaction), transaction);
+        this.entitlementTransactionsById.set(transaction.ledgerEntryId, transaction);
+        if (transaction.evidenceVerificationId !== undefined) {
+            this.entitlementTransactionsByEvidence.set(createEntitlementEvidenceKey({
+                source: transaction.source,
+                evidenceVerificationId: transaction.evidenceVerificationId,
+            }), transaction);
+        }
+        const platformEvidenceIdentity = getEntitlementPlatformEvidenceIdentity(transaction);
+        if (platformEvidenceIdentity !== undefined) {
+            this.entitlementTransactionsByPlatformEvidence.set(createEntitlementPlatformEvidenceKey(platformEvidenceIdentity), transaction);
+        }
+    }
     rankFor(transaction) {
         return (this.sortedLeaderboardTransactions()
             .filter((candidate) => candidate.leaderboardId === transaction.leaderboardId)
@@ -199,6 +361,7 @@ export function createGameServicesBackend(input) {
     const evidenceVerificationTimeoutMs = resolveEvidenceVerificationTimeout(input.evidenceVerificationTimeoutMs);
     const purchaseGrantFinalizationTimeoutMs = resolvePurchaseGrantFinalizationTimeout(input.purchaseGrantFinalizationTimeoutMs);
     const deploymentTargetBindings = resolveDeploymentTargetBindings(input.deploymentTargetBindings);
+    const restoreSharing = resolvePurchaseRestoreSharingPolicy(input.restoreSharing);
     const analytics = createAnalyticsReporter({
         target: 'server',
         sessionId: input.analyticsSessionId ?? 'game-services',
@@ -236,6 +399,7 @@ export function createGameServicesBackend(input) {
                     evidenceVerificationTimeoutMs,
                     purchaseGrantFinalizationTimeoutMs,
                     deploymentTargetBindings,
+                    restoreSharing,
                     ...(purchaseGrantFinalizer === undefined
                         ? {}
                         : { purchaseGrantFinalizer }),
@@ -256,6 +420,7 @@ export function createGameServicesBackend(input) {
                             finalizationAction: verification.finalization?.action,
                             finalizationAlreadyCompleted: verification.finalization?.alreadyCompleted,
                             finalizationReason: verification.finalization?.reason,
+                            restoredAcrossPlayers: verification.restoredAcrossPlayers,
                         },
                     });
                 });
@@ -644,9 +809,12 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
             ledgerEntryId: transaction.ledgerEntryId,
             alreadyProcessed: true,
             ...(finalization === undefined ? {} : { finalization }),
+            ...(isRestoredAcrossPlayers(transaction) ? { restoredAcrossPlayers: true } : {}),
         });
     };
     const existing = await findEntitlementTransactionByIdempotency(context.store, retryIdentity);
+    // A key names one grant: a resend under the key of a reversed grant
+    // answers it as reversed, never as a new restore.
     if (existing !== undefined) {
         return completeExistingRetry(existing);
     }
@@ -681,6 +849,26 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
         // the requesting player, product, and target.
         return completeSettledPurchase(request, verification, context);
     }
+    // The store routed to, as for a grant below.
+    const routedEntry = context.registry?.route(request);
+    const verifiedStore = routedEntry?.status === 'routed'
+        ? routedEntry.entry.store
+        : resolveCommerceStoreId(request);
+    if (verification.status === 'restorable') {
+        // A verified restore of a purchase the store binds to another player.
+        return shareRestoredPurchase(request, {
+            product,
+            platformProductId,
+            verification,
+            verifiedStore,
+            refusal: assertVerifyPurchaseResponse({
+                verified: false,
+                alreadyProcessed: false,
+                disposition: 'rejected',
+                reason: verification.reason,
+            }),
+        }, context);
+    }
     if (verification.status !== 'verified') {
         // A matching grant can land while provider verification is in flight. Recheck
         // before returning a stale provider state such as an already-consumed token.
@@ -699,14 +887,31 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
     }
     const verificationPayload = createVerificationPayload(verification, 'platformTransactionId');
     const platformTransactionId = resolvePlatformEvidenceId(verification, request.platformTransactionId);
-    const evidenceSchema = request.evidence?.schema;
+    if (context.restoreSharing.mode === 'share'
+        && product.type === 'non_consumable'
+        && context.store.findEntitlementTransactionsByEvidencePrefix !== undefined) {
+        // The retention purge can delete a purchase's first grant while its
+        // shares remain: the buyer then takes a holder's place under the limit
+        // like any other player, never a replacement first grant past it.
+        const holders = await listPurchaseHolders(context.store, verification.verificationId);
+        if (holders.first === undefined && holders.shared.length > 0) {
+            return shareRestoredPurchase(request, {
+                product,
+                platformProductId,
+                verification,
+                verifiedStore,
+                bindingMatches: true,
+                refusal: assertVerifyPurchaseResponse({
+                    verified: false,
+                    alreadyProcessed: false,
+                    reason: 'EVIDENCE_ALREADY_PROCESSED',
+                }),
+            }, context);
+        }
+    }
     // The store written is the one the registry routed to (an entry's own
     // store, or a declared fallback store); a fallback serving undeclared
     // stores and the v1 path record the request's resolved store.
-    const routed = context.registry?.route(request);
-    const verifiedStore = routed?.status === 'routed'
-        ? routed.entry.store
-        : resolveCommerceStoreId(request);
     const grant = await recordEntitlementGrantWithEvidence(context.store, {
         playerId: request.playerId,
         grantId: product.id,
@@ -715,25 +920,39 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
         grantedAt: context.now(),
         grant: product.grant,
         evidenceVerificationId: verification.verificationId,
-        payload: {
-            ...verificationPayload,
-            target: request.target,
-            store: verifiedStore,
-            ...(request.deploymentTarget === undefined
-                ? {}
-                : { deploymentTarget: request.deploymentTarget }),
-            productId: request.productId,
-            productType: product.type,
+        payload: createPurchaseGrantPayload(request, {
+            product,
             platformProductId,
+            verification,
+            verifiedStore,
             ...(platformTransactionId === undefined ? {} : { platformTransactionId }),
-            purchasedAt: request.purchasedAt,
-            ...(evidenceSchema === undefined ? {} : { evidenceSchema }),
-            evidenceVerificationId: verification.verificationId,
-            evidenceVerifiedAt: verification.verifiedAt,
-        },
+        }),
     });
     if (grant.status === 'evidence_already_processed') {
         const existingEvidence = await findEntitlementTransactionByEvidenceVerificationId(context.store, { source: 'purchase', evidenceVerificationId: verification.verificationId });
+        if (existingEvidence !== undefined
+            && context.restoreSharing.mode === 'share'
+            && product.type === 'non_consumable'
+            && existingEvidence.playerId !== request.playerId
+            && (request.intent === 'restore' || existingEvidence.payload.restoredAcrossAccounts === true)) {
+            // The store binds the purchase to this player, but another player's
+            // grant names it: a restore of this player's, or (when that grant came
+            // from another guest's restore before this player's own verify reached
+            // the ledger) the buyer's checkout. The binding match is the proof, so
+            // this player gets its own share.
+            return shareRestoredPurchase(request, {
+                product,
+                platformProductId,
+                verification,
+                verifiedStore,
+                bindingMatches: true,
+                refusal: assertVerifyPurchaseResponse({
+                    verified: false,
+                    alreadyProcessed: false,
+                    reason: 'EVIDENCE_ALREADY_PROCESSED',
+                }),
+            }, context);
+        }
         if (existingEvidence !== undefined
             && matchesPurchaseEvidenceRecovery(existingEvidence, {
                 playerId: request.playerId,
@@ -847,6 +1066,278 @@ async function completeSettledPurchase(request, decision, context) {
         ...(finalization === undefined ? {} : { finalization }),
     });
 }
+/** The ledger payload of a purchase grant: the verifier's payload and the request's identity. */
+function createPurchaseGrantPayload(request, input) {
+    const evidenceSchema = request.evidence?.schema;
+    return {
+        ...createVerificationPayload(input.verification, 'platformTransactionId'),
+        target: request.target,
+        store: input.verifiedStore,
+        ...(request.deploymentTarget === undefined
+            ? {}
+            : { deploymentTarget: request.deploymentTarget }),
+        productId: request.productId,
+        productType: input.product.type,
+        platformProductId: input.platformProductId,
+        ...(input.platformTransactionId === undefined
+            ? {}
+            : { platformTransactionId: input.platformTransactionId }),
+        purchasedAt: request.purchasedAt,
+        ...(evidenceSchema === undefined ? {} : { evidenceSchema }),
+        evidenceVerificationId: input.verification.verificationId,
+        evidenceVerifiedAt: input.verification.verifiedAt,
+    };
+}
+/**
+ * A verified restore of a non-consumable the store binds to another player
+ * (RFC "Restore sharing"). Under the `share` policy, for a request with
+ * `intent: 'restore'` of a non-consumable, the restoring player gets its own
+ * grant linked to the purchase and earlier holders keep theirs; otherwise
+ * `refusal` is answered. A purchase no grant holds yet is granted to the
+ * restoring player as its first grant. A refunded or revoked purchase is
+ * refused, a purchase already held by `maxHolders` players answers
+ * `pending` (`PURCHASE_HOLDER_LIMIT_REACHED`) and evicts nobody, and a
+ * player that already holds it gets its grant back.
+ */
+async function shareRestoredPurchase(request, input, context) {
+    const { store, restoreSharing: policy } = context;
+    const { product, verification } = input;
+    if (policy.mode !== 'share'
+        || (request.intent !== 'restore' && input.bindingMatches !== true)
+        || product.type !== 'non_consumable') {
+        return input.refusal;
+    }
+    const purchaseVerificationId = verification.verificationId;
+    const notGranted = (disposition, reason) => ({
+        status: 'answer',
+        response: assertVerifyPurchaseResponse({
+            verified: false,
+            alreadyProcessed: false,
+            disposition,
+            reason,
+        }),
+    });
+    const payload = createPurchaseGrantPayload(request, input);
+    const platformTransactionId = resolvePlatformEvidenceId(verification, request.platformTransactionId);
+    const holderIdentity = {
+        source: 'purchase',
+        playerId: request.playerId,
+        grantId: request.productId,
+        target: request.target,
+        store: input.verifiedStore,
+        ...(request.deploymentTarget === undefined
+            ? {}
+            : { deploymentTarget: request.deploymentTarget }),
+    };
+    const outcome = await withEntitlementEvidenceLocks(store, [createEntitlementEvidenceKey({
+            source: 'purchase',
+            evidenceVerificationId: purchaseVerificationId,
+        })], async () => {
+        // A lost race for a slot (another isolate shared the purchase between
+        // the read and the write) reads the holders again.
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const holders = await listPurchaseHolders(store, purchaseVerificationId);
+            const first = holders.first;
+            // The holders; the first grant may be gone (the retention purge
+            // deleted a deleted player's record) while its shares remain.
+            const all = [...(first === undefined ? [] : [first]), ...holders.shared];
+            const anchor = all[0];
+            if (anchor === undefined) {
+                // No grant holds the purchase: it never reached this ledger (an app
+                // closed before verifying, or bought outside the app). The store's
+                // verification is the proof, as for a share.
+                const recorded = await recordEntitlementGrantUnchecked(store, {
+                    playerId: request.playerId,
+                    grantId: product.id,
+                    source: 'purchase',
+                    idempotencyKey: request.idempotencyKey,
+                    grantedAt: context.now(),
+                    grant: product.grant,
+                    evidenceVerificationId: purchaseVerificationId,
+                    payload: {
+                        ...payload,
+                        ...(platformTransactionId === undefined ? {} : { platformTransactionId }),
+                        restoredAcrossAccounts: true,
+                    },
+                });
+                if (recorded.status !== 'recorded') {
+                    continue;
+                }
+                if (recorded.result.alreadyProcessed) {
+                    // The key already held a grant (another isolate wrote it after the
+                    // lookup): it is this restore only if it records this purchase.
+                    const keyed = await store.getEntitlementTransaction(recorded.result.ledgerEntryId);
+                    if (keyed === undefined
+                        || !matchesEntitlementRetry(keyed, {
+                            ...holderIdentity,
+                            idempotencyKey: request.idempotencyKey,
+                        })
+                        || readPurchaseVerificationId(keyed) !== purchaseVerificationId) {
+                        return notGranted('rejected', 'IDEMPOTENCY_KEY_CONFLICT');
+                    }
+                    if (await isEntitlementGrantReversed(store, keyed.ledgerEntryId)) {
+                        return notGranted('rejected', 'LEDGER_GRANT_REVERSED');
+                    }
+                }
+                return {
+                    status: 'written',
+                    ledgerEntryId: recorded.result.ledgerEntryId,
+                    alreadyProcessed: recorded.result.alreadyProcessed,
+                };
+            }
+            if (anchor.source !== 'purchase'
+                || anchor.grantId !== request.productId
+                || anchor.payload.target !== request.target
+                || (anchor.payload.store !== undefined && anchor.payload.store !== input.verifiedStore)
+                // Two deployment targets sharing a ledger never share a grant, as
+                // for a retry (`matchesEntitlementTransactionIdentity`).
+                || (anchor.payload.deploymentTarget !== undefined
+                    && anchor.payload.deploymentTarget !== request.deploymentTarget)) {
+                return notGranted('rejected', 'LEDGER_GRANT_IDENTITY_MISMATCH');
+            }
+            const revocations = await findEntitlementRevocationsChunked(store, all.map((grant) => grant.ledgerEntryId));
+            const reversed = new Set(revocations.map((entry) => entry.revokesLedgerEntryId));
+            if (await findPurchaseWideRevocation(store, all) !== undefined
+                || all.every((grant) => reversed.has(grant.ledgerEntryId))) {
+                // Refunded, charged back, or voided: the purchase ended for every
+                // holder. An admin entry ends one holder only and frees its place,
+                // but a purchase no holder keeps is never shared again (a refund
+                // that arrives then finds no grant left to mark).
+                return notGranted('rejected', 'LEDGER_GRANT_REVERSED');
+            }
+            const own = all.find((grant) => grant.playerId === request.playerId);
+            if (own !== undefined && !matchesEntitlementTransactionIdentity(own, holderIdentity)) {
+                return notGranted('rejected', 'LEDGER_GRANT_IDENTITY_MISMATCH');
+            }
+            if (own !== undefined) {
+                return reversed.has(own.ledgerEntryId)
+                    ? notGranted('rejected', 'LEDGER_GRANT_REVERSED')
+                    : { status: 'held', grant: own };
+            }
+            const active = all.filter((grant) => !reversed.has(grant.ledgerEntryId) && !isRetainedPlayerId(grant.playerId)).length;
+            if (active >= policy.maxHolders) {
+                return notGranted('pending', 'PURCHASE_HOLDER_LIMIT_REACHED');
+            }
+            const holderSlot = holders.nextSlot;
+            const holderEvidenceVerificationId = createPurchaseHolderEvidenceVerificationId(purchaseVerificationId, holderSlot);
+            const recorded = await recordEntitlementGrantUnchecked(store, {
+                playerId: request.playerId,
+                grantId: product.id,
+                source: 'purchase',
+                // The request's key, so a retry under it answers this grant; a
+                // player that already holds the purchase was answered above.
+                idempotencyKey: request.idempotencyKey,
+                grantedAt: context.now(),
+                grant: product.grant,
+                evidenceVerificationId: holderEvidenceVerificationId,
+                // The store transaction id stays with the first grant (its platform
+                // evidence is unique); a share names the purchase by its
+                // verification id instead.
+                payload: {
+                    ...payload,
+                    evidenceVerificationId: holderEvidenceVerificationId,
+                    holderOfEvidenceVerificationId: purchaseVerificationId,
+                    // No ledger id of another holder: it embeds that player's id,
+                    // which must not outlive that player's account deletion here.
+                    holderSlot,
+                },
+            });
+            if (recorded.status !== 'recorded') {
+                // The slot went to another restore; read the holders again.
+                continue;
+            }
+            if (recorded.result.alreadyProcessed) {
+                // The key held a grant already (this request's share landed from
+                // another isolate, or the key names something else).
+                const keyed = await store.getEntitlementTransaction(recorded.result.ledgerEntryId);
+                if (keyed === undefined
+                    || !matchesEntitlementRetry(keyed, {
+                        ...holderIdentity,
+                        idempotencyKey: request.idempotencyKey,
+                    })
+                    || readPurchaseVerificationId(keyed) !== purchaseVerificationId) {
+                    return notGranted('rejected', 'IDEMPOTENCY_KEY_CONFLICT');
+                }
+                return { status: 'held', grant: keyed };
+            }
+            // A refund that landed between the read and this write may have
+            // fanned out before the share existed: it then ends the share too.
+            // A refund writes its first entry before it reads the holders, so
+            // either it sees this share or this read sees its entry.
+            // A refund that met only admin-revoked grants leaves no entry of its
+            // own; the share then ends with them, as a purchase no holder keeps
+            // is never shared again.
+            const written = await store.getEntitlementTransaction(recorded.result.ledgerEntryId);
+            const ended = await findPurchaseWideRevocation(store, written === undefined ? all : [...all, written]);
+            const priorReversed = new Set((await findEntitlementRevocationsChunked(store, all.map((grant) => grant.ledgerEntryId)))
+                .map((entry) => entry.revokesLedgerEntryId));
+            const abandoned = all.every((grant) => priorReversed.has(grant.ledgerEntryId));
+            if (ended !== undefined || abandoned) {
+                if (written !== undefined && ended?.revokesLedgerEntryId !== written.ledgerEntryId) {
+                    await revokeEntitlementGrant(store, ended === undefined
+                        ? {
+                            playerId: written.playerId,
+                            revokesLedgerEntryId: written.ledgerEntryId,
+                            idempotencyKey: `mpgd-holder-closed:${purchaseVerificationId}`,
+                            reason: 'admin',
+                            revokedAt: context.now(),
+                            payload: { holderOfEvidenceVerificationId: purchaseVerificationId },
+                        }
+                        : {
+                            playerId: written.playerId,
+                            revokesLedgerEntryId: written.ledgerEntryId,
+                            idempotencyKey: ended.idempotencyKey,
+                            reason: ended.reason,
+                            revokedAt: ended.revokedAt,
+                            payload: ended.payload,
+                            ...(ended.evidenceVerificationId === undefined
+                                ? {}
+                                : {
+                                    evidenceVerificationId: holderRevocationEvidenceId(ended.evidenceVerificationId, written),
+                                }),
+                        });
+                }
+                return notGranted('rejected', 'LEDGER_GRANT_REVERSED');
+            }
+            return {
+                status: 'written',
+                ledgerEntryId: recorded.result.ledgerEntryId,
+                alreadyProcessed: false,
+            };
+        }
+        return notGranted('pending', 'PURCHASE_HOLDER_CONFLICT');
+    });
+    if (outcome.status === 'answer') {
+        return outcome.response;
+    }
+    if (outcome.status === 'held') {
+        const finalization = await finalizeExistingPurchaseGrant(request, outcome.grant, context);
+        return assertVerifyPurchaseResponse({
+            verified: true,
+            ledgerEntryId: outcome.grant.ledgerEntryId,
+            alreadyProcessed: true,
+            ...(finalization === undefined ? {} : { finalization }),
+            ...(isRestoredAcrossPlayers(outcome.grant) ? { restoredAcrossPlayers: true } : {}),
+        });
+    }
+    const finalization = await finalizePurchaseGrant(context.purchaseGrantFinalizer, {
+        request,
+        product,
+        platformProductId: input.platformProductId,
+        evidenceVerificationId: purchaseVerificationId,
+        ...(verification.payload === undefined ? {} : { evidencePayload: verification.payload }),
+        ledgerEntryId: outcome.ledgerEntryId,
+        alreadyProcessed: outcome.alreadyProcessed,
+        timeoutMs: context.purchaseGrantFinalizationTimeoutMs,
+    });
+    return assertVerifyPurchaseResponse({
+        verified: true,
+        ledgerEntryId: outcome.ledgerEntryId,
+        alreadyProcessed: outcome.alreadyProcessed,
+        ...(finalization === undefined ? {} : { finalization }),
+        restoredAcrossPlayers: true,
+    });
+}
 async function finalizeExistingPurchaseGrant(request, transaction, context) {
     if (context.purchaseGrantFinalizer === undefined) {
         return undefined;
@@ -856,8 +1347,8 @@ async function finalizeExistingPurchaseGrant(request, transaction, context) {
     const product = createStoredPurchaseProduct(request, transaction) ?? currentProduct;
     const platformProductId = storedPlatformProductId
         ?? currentProduct?.platformProductIds[request.target];
-    const evidenceVerificationId = transaction.evidenceVerificationId
-        ?? transaction.payload.evidenceVerificationId;
+    // A shared grant is finalized as the purchase it records, not as its slot.
+    const evidenceVerificationId = readPurchaseVerificationId(transaction);
     const finalizationRequest = createStoredPurchaseRequest(request, transaction);
     if (product === undefined
         || platformProductId === undefined
@@ -1068,8 +1559,8 @@ async function claimAdRewardForRetry(request, retryIdentity, context) {
             disposition: verification.status === 'pending' ? 'pending' : 'rejected',
             reason: verification.status === 'pending'
                 ? (verification.reason ?? 'EVIDENCE_PENDING')
-                : verification.status === 'settled'
-                    // Only purchase verification reads a settled ledger entry.
+                : verification.status === 'settled' || verification.status === 'restorable'
+                    // Only purchase verification reads a settled ledger entry or a restore.
                     ? 'EVIDENCE_VERIFIER_ERROR'
                     : verification.reason,
         });
@@ -1185,7 +1676,10 @@ function createVerificationPayload(verification, platformEvidenceField) {
     return payload;
 }
 function assertEvidenceVerificationDecision(decision) {
-    if (decision.status === 'verified') {
+    if (decision.status === 'verified' || decision.status === 'restorable') {
+        if (decision.status === 'restorable') {
+            assertNonEmptyDecisionString(decision.reason, 'reason');
+        }
         assertNonEmptyDecisionString(decision.verificationId, 'verificationId');
         assertNonEmptyDecisionString(decision.verifiedAt, 'verifiedAt');
         if (!Number.isFinite(Date.parse(decision.verifiedAt))) {