@mpgd/game-services 0.21.1 → 0.22.0

package/dist/runtime.js

@@ -63,16 +63,27 @@ export function createGameServicesRuntime(input) {
         ...(input.now === undefined ? {} : { now: input.now }),
         ...(input.rewardEvidenceRegistry === undefined ? {} : { rewardEvidenceRegistry: input.rewardEvidenceRegistry }),
     };
-    const client = createGameServicesClient(clientInput);
     const monetizationRecovery = input.operationStore === undefined
         ? undefined
         : createRecoverableMonetizationClient({ ...clientInput, operationStore: input.operationStore });
+    // The recovery client owns the reconciler over the durable journal; the
+    // plain client shares it instead of journaling in memory.
+    const client = createGameServicesClient({
+        ...clientInput,
+        ...(monetizationRecovery?.commerceReconciler === undefined
+            ? {}
+            : { commerceReconciler: monetizationRecovery.commerceReconciler }),
+    });
     let routedClient = client;
     if (monetizationRecovery !== undefined) {
         routedClient = {
             ...client,
             purchase: monetizationRecovery.purchase,
             claimRewardedAd: monetizationRecovery.claimRewardedAd,
+            // The recovery client owns the reconciler over the durable journal.
+            ...(monetizationRecovery.commerceReconciler === undefined
+                ? {}
+                : { commerceReconciler: monetizationRecovery.commerceReconciler }),
         };
     }
     return {

package/dist/server.d.ts

@@ -1,10 +1,12 @@
 import { type AnalyticsSink } from '@mpgd/analytics';
 import { type AdPlacements, type ProductCatalog } from '@mpgd/catalog';
 import { type GameServicesBackendApi, type GameServicesBackendTransport, type GameServicesBackendTransportRequest, type GameServicesBackendTransportResponse } from './client.js';
+import { type CommerceEvidenceRegistry } from './commerce-evidence-registry.js';
 import { type GameServicesHealthResponse } from './contract.js';
 import { type GameServicesEvidenceVerifier, type GameServicesPurchaseGrantFinalizer } from './evidence-verification.js';
-import { type ClaimAdRewardRequest, type ClaimAdRewardResponse, type EntitlementLedgerGrant, type EntitlementLedgerResult, type GameServicesAdRewardTarget, type GameServicesStoreTarget, type LeaderboardScoreTransaction, type ProductGrantTransaction, type RecordLeaderboardScoreRequest, type RecordLeaderboardScoreResponse, type VerifyPurchaseRequest, type VerifyPurchaseResponse } from './types.js';
+import { type ClaimAdRewardRequest, type ClaimAdRewardResponse, type EntitlementLedgerGrant, type EntitlementLedgerResult, type EntitlementLedgerRevocation, type EntitlementRevocationTransaction, type GameServicesAdRewardTarget, type GameServicesStoreTarget, type LeaderboardScoreTransaction, type ProductGrantTransaction, type PurchaseLedgerStatusRequest, type RecordLeaderboardScoreRequest, type RecordLeaderboardScoreResponse, type VerifyPurchaseRequest, type VerifyPurchaseResponse } from './types.js';
 export { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
+export { listActiveEntitlementTransactions, readPurchaseLedgerStatuses, revokeEntitlementGrant, RevocationKeyConflictError, type RevokeEntitlementGrantResult, } from './commerce-ledger.js';
 type CorsHeaders = Record<string, string>;
 export interface CreateGameServicesBackendInput {
   readonly catalog: ProductCatalog;
@@ -21,6 +23,16 @@ export interface CreateGameServicesBackendInput {
   readonly purchaseGrantFinalizationTimeoutMs?: number;
   readonly purchaseGrantFinalizer?: GameServicesPurchaseGrantFinalizer;
   /**
+  * The commerce v2 evidence registry (RFC "Evidence registry"). With it,
+  * purchase evidence is routed by `evidence.schema` to the registered
+  * verifier and finalizer, `purchaseGrantFinalizer` is not consulted for
+  * purchases, `evidenceVerifier` serves rewarded ads only, and the backend
+  * publishes `getCommerceCapabilities`. Without it the backend keeps the v1
+  * behaviour: one `evidenceVerifier` and one `purchaseGrantFinalizer` for
+  * every purchase, and no capabilities endpoint.
+  */
+  readonly commerceEvidenceRegistry?: CommerceEvidenceRegistry;
+  /**
   * Receives unexpected (non-validation) failures such as store errors before the
   * transport answers with the generic `INTERNAL_ERROR` code. Defaults to `console.error`.
   * The hook is diagnostics only: if it throws or returns a rejecting promise, the failure
@@ -55,6 +67,26 @@ export interface GameServicesStore {
   findEntitlementTransactionByPlatformEvidence?(input: EntitlementPlatformEvidenceIdentity): Promise<ProductGrantTransaction | undefined>;
   getEntitlementTransaction(ledgerEntryId: string): Promise<ProductGrantTransaction | undefined>;
   listEntitlementTransactions(): Promise<readonly ProductGrantTransaction[]>;
+  /** The grants with the given ids (at most `ledgerReadChunkSize` per call), any order. */
+  getEntitlementTransactions?(ledgerEntryIds: readonly string[]): Promise<readonly ProductGrantTransaction[]>;
+  /**
+  * Appends a `revoke` entry (RFC "Revocation and expiry entries"). A grant is
+  * reversed once: a second revocation of the same grant, under any key,
+  * answers the first entry with `alreadyProcessed: true`, as does a replay of
+  * the same `(playerId, idempotencyKey)`; a key reused for another grant
+  * throws `RevocationKeyConflictError`, a reused `evidenceVerificationId`
+  * throws `EvidenceAlreadyProcessedError`, and an unknown grant throws.
+  * Optional: a store without it answers every ledger status read as
+  * `active` and refuses `revokeEntitlementGrant`.
+  */
+  recordEntitlementRevocation?(input: EntitlementLedgerRevocation): Promise<EntitlementLedgerResult>;
+  /**
+  * The revocations that reverse any of the given grant entries (at most
+  * `ledgerReadChunkSize` per call), oldest first.
+  */
+  findEntitlementRevocations?(input: {
+    readonly ledgerEntryIds: readonly string[];
+  }): Promise<readonly EntitlementRevocationTransaction[]>;
   recordLeaderboardScore(input: RecordLeaderboardScoreRequest, options?: {
     readonly recordedAt?: string;
   }): Promise<RecordLeaderboardScoreResponse>;
@@ -87,6 +119,9 @@ export declare class InMemoryGameServicesStore implements GameServicesStore {
   private readonly entitlementTransactionsByEvidence;
   private readonly entitlementTransactionsByPlatformEvidence;
   private readonly entitlementTransactionsById;
+  private readonly revocationsByKey;
+  private readonly revocationsByGrant;
+  private readonly revocationsByEvidence;
   private readonly leaderboardTransactionsByRun;
   private readonly leaderboardTransactionsById;
   recordEntitlementGrant(input: EntitlementLedgerGrant): Promise<EntitlementLedgerResult>;
@@ -102,6 +137,11 @@ export declare class InMemoryGameServicesStore implements GameServicesStore {
   findEntitlementTransactionByPlatformEvidence(input: EntitlementPlatformEvidenceIdentity): Promise<ProductGrantTransaction | undefined>;
   getEntitlementTransaction(ledgerEntryId: string): Promise<ProductGrantTransaction | undefined>;
   listEntitlementTransactions(): Promise<readonly ProductGrantTransaction[]>;
+  getEntitlementTransactions(ledgerEntryIds: readonly string[]): Promise<readonly ProductGrantTransaction[]>;
+  recordEntitlementRevocation(input: EntitlementLedgerRevocation): Promise<EntitlementLedgerResult>;
+  findEntitlementRevocations(input: {
+    readonly ledgerEntryIds: readonly string[];
+  }): Promise<readonly EntitlementRevocationTransaction[]>;
   recordLeaderboardScore(input: RecordLeaderboardScoreRequest, options?: {
     readonly recordedAt?: string;
   }): Promise<RecordLeaderboardScoreResponse>;
@@ -121,6 +161,8 @@ export declare function createGameServicesRouter(backend: GameServicesBackendApi
   health: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<void, void>, import("@orpc/contract").Schema<GameServicesHealthResponse, GameServicesHealthResponse>, object>;
   commerce: {
     verifyPurchase: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<VerifyPurchaseRequest, VerifyPurchaseRequest>, import("@orpc/contract").Schema<VerifyPurchaseResponse, VerifyPurchaseResponse>, object>;
+    getPurchaseLedgerStatus: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<PurchaseLedgerStatusRequest, PurchaseLedgerStatusRequest>, import("@orpc/contract").Schema<import("./operation-results.js").PurchaseLedgerStatusResponse, import("./operation-results.js").PurchaseLedgerStatusResponse>, object>;
+    getCapabilities: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<void, void>, import("@orpc/contract").Schema<import("@mpgd/platform/commerce").CommerceServiceCapabilities, import("@mpgd/platform/commerce").CommerceServiceCapabilities>, object>;
   };
   ads: {
     claimReward: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<ClaimAdRewardRequest, ClaimAdRewardRequest>, import("@orpc/contract").Schema<ClaimAdRewardResponse, ClaimAdRewardResponse>, object>;

package/dist/server.js

@@ -3,16 +3,22 @@ import { BodyLimitHandlerPlugin, RPCHandler } from '@orpc/server/fetch';
 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 { gameServicesContract } from './contract.js';
 import { createRejectingGameServicesEvidenceVerifier, } from './evidence-verification.js';
-import { assertClaimAdRewardRequest, assertClaimAdRewardResponse, assertEntitlementLedgerGrant, assertEntitlementLedgerResult, assertGameServicesDeploymentTarget, assertLeaderboardScoreTransaction, assertProductGrantTransaction, assertPurchaseGrantFinalization, assertRecordLeaderboardScoreRequest, assertRecordLeaderboardScoreResponse, assertVerifyPurchaseRequest, assertVerifyPurchaseResponse, } from './types.js';
+import { assertClaimAdRewardRequest, assertClaimAdRewardResponse, assertEntitlementLedgerGrant, assertEntitlementLedgerResult, assertEntitlementLedgerRevocation, assertEntitlementRevocationTransaction, assertGameServicesDeploymentTarget, assertLeaderboardScoreTransaction, assertProductGrantTransaction, assertPurchaseGrantFinalization, assertRecordLeaderboardScoreRequest, assertRecordLeaderboardScoreResponse, assertVerifyPurchaseRequest, assertVerifyPurchaseResponse, } from './types.js';
 import { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
 export { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
+export { listActiveEntitlementTransactions, readPurchaseLedgerStatuses, revokeEntitlementGrant, RevocationKeyConflictError, } from './commerce-ledger.js';
 export class InMemoryGameServicesStore {
     entitlementTransactionsByKey = new Map();
     entitlementTransactionsByEvidence = new Map();
     entitlementTransactionsByPlatformEvidence = new Map();
     entitlementTransactionsById = new Map();
+    revocationsByKey = new Map();
+    revocationsByGrant = new Map();
+    revocationsByEvidence = new Map();
     leaderboardTransactionsByRun = new Map();
     leaderboardTransactionsById = new Map();
     async recordEntitlementGrant(input) {
@@ -71,6 +77,64 @@ export class InMemoryGameServicesStore {
     async listEntitlementTransactions() {
         return [...this.entitlementTransactionsById.values()];
     }
+    async getEntitlementTransactions(ledgerEntryIds) {
+        const found = [];
+        for (const ledgerEntryId of new Set(ledgerEntryIds)) {
+            const transaction = this.entitlementTransactionsById.get(ledgerEntryId);
+            if (transaction !== undefined) {
+                found.push(transaction);
+            }
+        }
+        return found;
+    }
+    async recordEntitlementRevocation(input) {
+        const revocation = assertEntitlementLedgerRevocation(input);
+        const key = createRevocationIdempotencyKey(revocation);
+        const byKey = this.revocationsByKey.get(key);
+        if (byKey !== undefined) {
+            if (byKey.revokesLedgerEntryId !== revocation.revokesLedgerEntryId) {
+                throw new RevocationKeyConflictError();
+            }
+            return assertEntitlementLedgerResult({
+                ledgerEntryId: byKey.ledgerEntryId,
+                alreadyProcessed: true,
+            });
+        }
+        const byGrant = this.revocationsByGrant.get(revocation.revokesLedgerEntryId);
+        if (byGrant !== undefined) {
+            return assertEntitlementLedgerResult({
+                ledgerEntryId: byGrant.ledgerEntryId,
+                alreadyProcessed: true,
+            });
+        }
+        if (revocation.evidenceVerificationId !== undefined
+            && this.revocationsByEvidence.has(revocation.evidenceVerificationId)) {
+            throw new EvidenceAlreadyProcessedError();
+        }
+        if (!this.entitlementTransactionsById.has(revocation.revokesLedgerEntryId)) {
+            // The D1 store's foreign key refuses the same write.
+            throw new Error('Entitlement revocation references an unknown grant.');
+        }
+        const transaction = assertEntitlementRevocationTransaction({
+            ...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);
+        }
+        return assertEntitlementLedgerResult({
+            ledgerEntryId: transaction.ledgerEntryId,
+            alreadyProcessed: false,
+        });
+    }
+    async findEntitlementRevocations(input) {
+        const wanted = new Set(input.ledgerEntryIds);
+        return [...this.revocationsByGrant.values()]
+            .filter((revocation) => wanted.has(revocation.revokesLedgerEntryId))
+            .sort((left, right) => left.revokedAt.localeCompare(right.revokedAt));
+    }
     async recordLeaderboardScore(input, options = {}) {
         const request = assertRecordLeaderboardScoreRequest(input);
         const runKey = createLeaderboardRunKey(request);
@@ -141,6 +205,25 @@ export function createGameServicesBackend(input) {
         now,
         ...(input.analytics === undefined ? {} : { sink: input.analytics }),
     });
+    const registry = input.commerceEvidenceRegistry;
+    if (registry !== undefined && input.purchaseGrantFinalizer !== undefined) {
+        throw new Error('createGameServicesBackend: pass the v1 purchaseGrantFinalizer as the registry '
+            + 'unregistered.finalizer instead of next to commerceEvidenceRegistry; with a registry '
+            + 'the entries own finalization.');
+    }
+    // With a registry, purchase evidence is routed by schema and the registry's
+    // finalizer owns post-grant finalization; the configured verifier keeps
+    // serving rewarded ads. Without one, the v1 single verifier and finalizer
+    // serve every purchase unchanged.
+    const purchaseEvidenceVerifier = registry === undefined
+        ? evidenceVerifier
+        : {
+            verifyPurchase: (verificationInput) => registry.verifyPurchase(verificationInput),
+            verifyAdReward: (verificationInput) => evidenceVerifier.verifyAdReward(verificationInput),
+        };
+    const purchaseGrantFinalizer = registry === undefined
+        ? input.purchaseGrantFinalizer
+        : registry.finalizer;
     return {
         version,
         purchases: {
@@ -149,19 +232,21 @@ export function createGameServicesBackend(input) {
                     catalog: input.catalog,
                     store,
                     now,
-                    evidenceVerifier,
+                    evidenceVerifier: purchaseEvidenceVerifier,
                     evidenceVerificationTimeoutMs,
                     purchaseGrantFinalizationTimeoutMs,
                     deploymentTargetBindings,
-                    ...(input.purchaseGrantFinalizer === undefined
+                    ...(purchaseGrantFinalizer === undefined
                         ? {}
-                        : { purchaseGrantFinalizer: input.purchaseGrantFinalizer }),
+                        : { purchaseGrantFinalizer }),
+                    ...(registry === undefined ? {} : { registry }),
                 }, async (verification) => {
                     await analytics.track({
                         name: verification.verified ? 'purchase_granted'
                             : verification.disposition === 'pending' ? 'purchase_pending' : 'purchase_rejected',
                         properties: {
                             target: request.target,
+                            store: resolveCommerceStoreId(request),
                             playerId: request.playerId,
                             productId: request.productId,
                             ledgerEntryId: verification.ledgerEntryId,
@@ -175,6 +260,16 @@ export function createGameServicesBackend(input) {
                     });
                 });
             },
+            async getPurchaseLedgerStatus(request) {
+                return readPurchaseLedgerStatuses(store, request);
+            },
+            ...(registry === undefined
+                ? {}
+                : {
+                    async getCommerceCapabilities() {
+                        return registry.getCapabilities();
+                    },
+                }),
         },
         adRewards: {
             async claimAdReward(request) {
@@ -321,6 +416,22 @@ export function createGameServicesRouter(backend, options = {}) {
             verifyPurchase: contract.commerce.verifyPurchase.handler(({ input }) => {
                 return invoke(() => backend.purchases.verifyPurchase(input));
             }),
+            getPurchaseLedgerStatus: contract.commerce.getPurchaseLedgerStatus.handler(({ input }) => {
+                const read = backend.purchases.getPurchaseLedgerStatus;
+                if (read === undefined) {
+                    throw new ORPCError('NOT_FOUND', { message: 'This backend has no ledger status read.' });
+                }
+                return invoke(() => read.call(backend.purchases, input));
+            }),
+            getCapabilities: contract.commerce.getCapabilities.handler(() => {
+                const read = backend.purchases.getCommerceCapabilities;
+                if (read === undefined) {
+                    throw new ORPCError('NOT_FOUND', {
+                        message: 'This backend publishes no commerce capabilities.',
+                    });
+                }
+                return invoke(() => read.call(backend.purchases));
+            }),
         }),
         ads: contract.ads.router({
             claimReward: contract.ads.claimReward.handler(({ input }) => {
@@ -436,7 +547,9 @@ function resolveDeploymentTargetBindings(input) {
     return bindings;
 }
 function bindRequestDeploymentTarget(request, bindings) {
-    const deploymentTarget = bindings[request.target] ?? request.target;
+    const deploymentTarget = (Object.hasOwn(bindings, request.target)
+        ? bindings[request.target]
+        : undefined) ?? request.target;
     if (request.deploymentTarget !== undefined
         && request.deploymentTarget !== deploymentTarget) {
         throw new GameServicesRequestValidationError(`deploymentTarget must match the backend binding for ${request.target}.`);
@@ -445,14 +558,58 @@ function bindRequestDeploymentTarget(request, bindings) {
         ? request
         : { ...request, deploymentTarget };
 }
+/** The ledger targets a v1 backend (no registry) accepts: the platform targets with a ledger. */
+const gameServicesLedgerTargets = new Set([
+    'browser',
+    'microsoft-store',
+    'android',
+    'ios',
+    'ait',
+    'reddit',
+    'verse8',
+    'oneplay',
+]);
+/**
+ * A target or store the backend does not serve is a 400, as an unknown v1
+ * target was: without a registry the ledger targets are the known platform
+ * targets; with one, the store must be registered (or declared for the
+ * fallback) and the target a ledger target or a served store id.
+ */
+function assertServedPurchaseRequest(request, registry) {
+    if (registry === undefined) {
+        if (!gameServicesLedgerTargets.has(request.target)) {
+            throw new GameServicesRequestValidationError(`target ${request.target} is not a ledger target this backend serves.`);
+        }
+        return;
+    }
+    const store = resolveCommerceStoreId(request);
+    if (!registry.serves(request)) {
+        throw new GameServicesRequestValidationError(`store ${store} is not a store this backend serves for target ${request.target}.`);
+    }
+    // A served store's declared targets are the contract (a custom store may
+    // name a custom ledger target); a store without declared targets keeps the
+    // ledger target set and the served store ids.
+    const allowed = registry.allowedTargets(store);
+    if (allowed !== undefined) {
+        if (!allowed.has(request.target)) {
+            throw new GameServicesRequestValidationError(`target ${request.target} is not a ledger target of store ${store}.`);
+        }
+        return;
+    }
+    if (!gameServicesLedgerTargets.has(request.target) && !registry.stores.has(request.target)) {
+        throw new GameServicesRequestValidationError(`target ${request.target} is not a ledger target this backend serves.`);
+    }
+}
 async function verifyPurchaseWithStore(input, context, onDecision) {
     const request = bindRequestDeploymentTarget(assertVerifyPurchaseRequest(input), context.deploymentTargetBindings);
+    assertServedPurchaseRequest(request, context.registry);
     const retryIdentity = {
         source: 'purchase',
         playerId: request.playerId,
         idempotencyKey: request.idempotencyKey,
         grantId: request.productId,
         target: request.target,
+        store: resolveCommerceStoreId(request),
         ...(request.deploymentTarget === undefined
             ? {}
             : { deploymentTarget: request.deploymentTarget }),
@@ -472,6 +629,15 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
                 reason: 'IDEMPOTENCY_KEY_CONFLICT',
             });
         }
+        if (await isEntitlementGrantReversed(context.store, transaction.ledgerEntryId)) {
+            // A replayed key for a refunded grant is not a grant, as the lookup path answers.
+            return assertVerifyPurchaseResponse({
+                verified: false,
+                alreadyProcessed: false,
+                disposition: 'rejected',
+                reason: 'LEDGER_GRANT_REVERSED',
+            });
+        }
         const finalization = await finalizeExistingPurchaseGrant(request, transaction, context);
         return assertVerifyPurchaseResponse({
             verified: true,
@@ -509,6 +675,12 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
             timeoutMs: context.evidenceVerificationTimeoutMs,
         });
     }, context.evidenceVerificationTimeoutMs);
+    if (verification.status === 'settled') {
+        // A server-push lookup found the grant the host's fulfillment path wrote.
+        // Nothing is written; the entry is answered once it is checked against
+        // the requesting player, product, and target.
+        return completeSettledPurchase(request, verification, 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.
@@ -527,6 +699,14 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
     }
     const verificationPayload = createVerificationPayload(verification, 'platformTransactionId');
     const platformTransactionId = resolvePlatformEvidenceId(verification, request.platformTransactionId);
+    const evidenceSchema = request.evidence?.schema;
+    // 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,
@@ -538,6 +718,7 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
         payload: {
             ...verificationPayload,
             target: request.target,
+            store: verifiedStore,
             ...(request.deploymentTarget === undefined
                 ? {}
                 : { deploymentTarget: request.deploymentTarget }),
@@ -546,6 +727,7 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
             platformProductId,
             ...(platformTransactionId === undefined ? {} : { platformTransactionId }),
             purchasedAt: request.purchasedAt,
+            ...(evidenceSchema === undefined ? {} : { evidenceSchema }),
             evidenceVerificationId: verification.verificationId,
             evidenceVerifiedAt: verification.verifiedAt,
         },
@@ -557,11 +739,21 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
                 playerId: request.playerId,
                 grantId: request.productId,
                 target: request.target,
+                store: verifiedStore,
                 ...(request.deploymentTarget === undefined
                     ? {}
                     : { deploymentTarget: request.deploymentTarget }),
                 evidenceVerificationId: verification.verificationId,
             })) {
+            if (await isEntitlementGrantReversed(context.store, existingEvidence.ledgerEntryId)) {
+                // A refunded grant's evidence replayed under another key is not a grant.
+                return assertVerifyPurchaseResponse({
+                    verified: false,
+                    alreadyProcessed: false,
+                    disposition: 'rejected',
+                    reason: 'LEDGER_GRANT_REVERSED',
+                });
+            }
             const finalization = await finalizeExistingPurchaseGrant(request, existingEvidence, context);
             // A different idempotency key is evidence replay unless a configured finalizer can resume
             // the provider operation. Keep generic stores fail-closed while allowing Store consume
@@ -614,6 +806,47 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
         ...(finalization === undefined ? {} : { finalization }),
     });
 }
+/**
+ * Answers a purchase a server-push lookup verifier found settled by an earlier
+ * ledger entry. The entry must be a purchase grant of the requesting player,
+ * product, and ledger target; a fulfillment path that bound the grant to a
+ * deployment target must agree with the request when both name one.
+ */
+async function completeSettledPurchase(request, decision, context) {
+    const settled = await context.store.getEntitlementTransaction(decision.ledgerEntryId);
+    if (settled === undefined
+        || settled.source !== 'purchase'
+        || settled.playerId !== request.playerId
+        || settled.grantId !== request.productId
+        || settled.payload.target !== (decision.ledgerTarget ?? request.target)
+        || (settled.payload.deploymentTarget !== undefined
+            && request.deploymentTarget !== undefined
+            && settled.payload.deploymentTarget !== request.deploymentTarget)) {
+        return assertVerifyPurchaseResponse({
+            verified: false,
+            alreadyProcessed: false,
+            disposition: 'rejected',
+            reason: 'LEDGER_GRANT_IDENTITY_MISMATCH',
+        });
+    }
+    if (await isEntitlementGrantReversed(context.store, settled.ledgerEntryId)) {
+        // `settled` is an open verifier contract; a reversed grant never settles
+        // a purchase, whichever verifier named it.
+        return assertVerifyPurchaseResponse({
+            verified: false,
+            alreadyProcessed: false,
+            disposition: 'rejected',
+            reason: 'LEDGER_GRANT_REVERSED',
+        });
+    }
+    const finalization = await finalizeExistingPurchaseGrant(request, settled, context);
+    return assertVerifyPurchaseResponse({
+        verified: true,
+        ledgerEntryId: settled.ledgerEntryId,
+        alreadyProcessed: true,
+        ...(finalization === undefined ? {} : { finalization }),
+    });
+}
 async function finalizeExistingPurchaseGrant(request, transaction, context) {
     if (context.purchaseGrantFinalizer === undefined) {
         return undefined;
@@ -630,6 +863,35 @@ async function finalizeExistingPurchaseGrant(request, transaction, context) {
         || platformProductId === undefined
         || typeof evidenceVerificationId !== 'string'
         || evidenceVerificationId.length === 0) {
+        // With a registry, a store nothing finalizes on the server (client,
+        // host, or none finish) has no pending finalization to report: the
+        // registry decides from the grant's recorded store and schema, never from
+        // the stand-in product. The v1 single finalizer keeps answering pending.
+        if (context.registry !== undefined) {
+            const recordedSchema = transaction.payload.evidenceSchema;
+            const supported = context.registry.finalizer.supportsPurchaseGrant?.({
+                request: typeof recordedSchema === 'string' && recordedSchema.length > 0
+                    ? { ...finalizationRequest, evidence: { schema: recordedSchema, payload: {} } }
+                    : finalizationRequest,
+                product: product ?? {
+                    id: request.productId,
+                    type: 'consumable',
+                    grant: transaction.grant ?? { type: 'entitlement', entitlement: request.productId },
+                    platformProductIds: {},
+                },
+                platformProductId: platformProductId ?? '',
+                evidenceVerificationId: typeof evidenceVerificationId === 'string'
+                    ? evidenceVerificationId
+                    : '',
+                evidencePayload: transaction.payload,
+                ledgerEntryId: transaction.ledgerEntryId,
+                alreadyProcessed: true,
+                timeoutMs: context.purchaseGrantFinalizationTimeoutMs,
+            });
+            if (supported === false) {
+                return undefined;
+            }
+        }
         return assertPurchaseGrantFinalization({
             status: 'pending',
             alreadyCompleted: false,
@@ -806,7 +1068,10 @@ async function claimAdRewardForRetry(request, retryIdentity, context) {
             disposition: verification.status === 'pending' ? 'pending' : 'rejected',
             reason: verification.status === 'pending'
                 ? (verification.reason ?? 'EVIDENCE_PENDING')
-                : verification.reason,
+                : verification.status === 'settled'
+                    // Only purchase verification reads a settled ledger entry.
+                    ? 'EVIDENCE_VERIFIER_ERROR'
+                    : verification.reason,
         });
     }
     // The client-reported impression id only becomes part of the globally unique platform
@@ -946,6 +1211,10 @@ function assertEvidenceVerificationDecision(decision) {
         }
         return decision;
     }
+    if (decision.status === 'settled') {
+        assertNonEmptyDecisionString(decision.ledgerEntryId, 'ledgerEntryId');
+        return decision;
+    }
     if (decision.status === 'pending') {
         if (decision.reason !== undefined) {
             assertNonEmptyDecisionString(decision.reason, 'reason');
@@ -1136,7 +1405,16 @@ function matchesEntitlementTransactionIdentity(transaction, identity) {
         && transaction.playerId === identity.playerId
         && transaction.grantId === identity.grantId
         && transaction.payload.target === identity.target
-        && transaction.payload.deploymentTarget === identity.deploymentTarget;
+        // Two stores sharing one ledger target never share a grant: a key reused
+        // with another store is a conflict, while a grant recorded before the
+        // store was written meets any store.
+        && (identity.store === undefined
+            || transaction.payload.store === undefined
+            || transaction.payload.store === identity.store)
+        // A grant written without a deployment target (a host fulfillment path)
+        // meets the request bound to one; two bound targets must agree.
+        && (transaction.payload.deploymentTarget === undefined
+            || transaction.payload.deploymentTarget === identity.deploymentTarget);
 }
 function resolveEvidenceVerificationTimeout(timeoutMs) {
     const resolved = timeoutMs ?? 10_000;
@@ -1166,6 +1444,16 @@ async function routeGameServicesRequest(endpoint, body, backend) {
     switch (endpoint) {
         case gameServicesBackendEndpoints.verifyPurchase:
             return okResponse(await backend.purchases.verifyPurchase(body));
+        case gameServicesBackendEndpoints.getPurchaseLedgerStatus:
+            if (backend.purchases.getPurchaseLedgerStatus === undefined) {
+                return errorResponse(404, 'UNKNOWN_ENDPOINT');
+            }
+            return okResponse(await backend.purchases.getPurchaseLedgerStatus(body));
+        case gameServicesBackendEndpoints.getCommerceCapabilities:
+            if (backend.purchases.getCommerceCapabilities === undefined) {
+                return errorResponse(404, 'UNKNOWN_ENDPOINT');
+            }
+            return okResponse(await backend.purchases.getCommerceCapabilities());
         case gameServicesBackendEndpoints.claimAdReward:
             return okResponse(await backend.adRewards.claimAdReward(body));
         case gameServicesBackendEndpoints.recordLeaderboardScore:
@@ -1219,6 +1507,16 @@ function createEntitlementEvidenceKey(grant) {
 function createEntitlementPlatformEvidenceKey(identity) {
     return createCompositeKey([identity.source, identity.target, identity.platformEvidenceId]);
 }
+function createRevocationIdempotencyKey(revocation) {
+    return createCompositeKey(['revoke', revocation.playerId, revocation.idempotencyKey]);
+}
+function createRevocationLedgerEntryId(revocation) {
+    return [
+        'revoke',
+        encodeIdSegment(revocation.playerId),
+        encodeIdSegment(revocation.idempotencyKey),
+    ].join('_');
+}
 function createEntitlementLedgerEntryId(grant) {
     return [
         'ledger',