@mpgd/game-services 0.17.2 → 0.18.0

package/README.md

@@ -4,6 +4,52 @@ Client, contract, backend, and store helpers for authoritative game services.
 See [backend integration](../../docs/GAME_SERVICES_BACKEND.md) for the existing
 verification and ledger boundaries.
 
+## Registered rewarded-ad evidence
+
+`createGameServicesClient`, `createRecoverableMonetizationClient`, and
+`createGameServicesRuntime` accept `rewardEvidenceRegistry`. Create one with
+`createClientRewardEvidenceRegistry` from
+`@mpgd/game-services/client-reward-evidence`, or extend the default AdMob,
+Verse8, and Apps in Toss decoders with
+`createDefaultClientRewardEvidenceRegistry` from
+`@mpgd/game-services/default-client-reward-evidence`.
+
+Each explicit registration has a unique `schema` and a `normalize(reward)`
+function returning `{ platformImpressionId? }` or `undefined`. The registry
+passes a bounded, frozen copy of the evidence to the decoder. Decoder errors,
+unknown schemas, and malformed candidates produce no claim. A decoder only
+recognizes a claim candidate: the backend must independently verify proof
+before a ledger grant. An SDK earned event may have `rewardGranted: false`
+and still produce a pending or verified backend claim.
+
+```ts
+import { createDefaultClientRewardEvidenceRegistry } from
+  '@mpgd/game-services/default-client-reward-evidence';
+
+const rewardEvidenceRegistry = createDefaultClientRewardEvidenceRegistry([{
+  schema: 'game-provider.reward.v1',
+  normalize(reward) {
+    const id = reward.evidence?.payload.impressionId;
+    return typeof id === 'string' && id.trim() !== ''
+      ? { platformImpressionId: id } : undefined;
+  },
+}]);
+// Pass this registry to the client/runtime, and configure server verification separately.
+```
+
+Recovery uses the same registered decoder and checks the journaled claim
+against the original evidence and impression identity. Missing registrations
+or altered evidence leave reconciliation `action-required`; they cannot
+reopen the SDK display. Supply the same registrations after a restart.
+
+For existing v1 consumers that supply neither a registry nor `ads.provider`,
+the completed SDK reward flag still forwards a legacy candidate to the
+backend. A registered schema that fails decoding cannot take this fallback.
+Explicit registries and versioned providers reject unknown schemas even if
+an SDK reports a reward. Existing `admob-client-reward` exports remain
+available for compatibility. Target routing and server verifier registration
+are separate integration boundaries.
+
 ## Optional operation progress
 
 `purchase(input, options?)` and `claimRewardedAd(input, options?)` accept optional

package/dist/ad-reward-verifier-registry.d.ts

@@ -0,0 +1,23 @@
+import type { EvidenceVerificationDecision, VerifyAdRewardEvidenceInput } from './evidence-verification.js';
+import { type GameServicesAdRewardTarget } from './types.js';
+export interface AdRewardVerifierBinding {
+  readonly target: GameServicesAdRewardTarget;
+  /** Omit only for the deployment whose key equals its platform target. */
+  readonly deploymentTarget?: string;
+}
+export interface AdRewardVerifierDescriptor {
+  readonly providerId: string;
+  readonly schema: string;
+  readonly bindings: readonly AdRewardVerifierBinding[];
+}
+export interface AdRewardVerifierRegistration extends AdRewardVerifierDescriptor {
+  /** Explicit server proof lookup without a client envelope (for example signed SSV recovery). */
+  readonly acceptsMissingEvidence?: boolean;
+  /** Authenticate proof and all request bindings; registration itself proves no reward. */
+  verify(input: VerifyAdRewardEvidenceInput): Promise<EvidenceVerificationDecision>;
+}
+export interface AdRewardEvidenceVerifierRegistry {
+  verifyAdReward(input: VerifyAdRewardEvidenceInput): Promise<EvidenceVerificationDecision>;
+}
+/** A deployment-owned allow-list. Client decoder registration never reaches this registry. */
+export declare function createAdRewardEvidenceVerifierRegistry(entries: readonly AdRewardVerifierRegistration[]): AdRewardEvidenceVerifierRegistry;

package/dist/ad-reward-verifier-registry.js

@@ -0,0 +1,83 @@
+import { assertGameServicesDeploymentTarget } from './types.js';
+/** A deployment-owned allow-list. Client decoder registration never reaches this registry. */
+export function createAdRewardEvidenceVerifierRegistry(entries) {
+    const registered = new Map();
+    const providerSchemas = new Map();
+    for (const entry of entries) {
+        assertIdentity(entry.providerId);
+        assertIdentity(entry.schema);
+        if (!Array.isArray(entry.bindings) || entry.bindings.length === 0 || typeof entry.verify !== 'function'
+            || entry.acceptsMissingEvidence !== undefined && typeof entry.acceptsMissingEvidence !== 'boolean') {
+            throw new TypeError('Invalid advertising verifier registration.');
+        }
+        const owner = providerSchemas.get(entry.schema);
+        if (owner !== undefined && owner !== entry.providerId) {
+            throw new TypeError('Advertising evidence schema belongs to another provider.');
+        }
+        providerSchemas.set(entry.schema, entry.providerId);
+        for (const binding of entry.bindings) {
+            if (!rewardTargets.has(binding.target)) {
+                throw new TypeError('Invalid advertising verifier target.');
+            }
+            const deploymentTarget = binding.deploymentTarget ?? binding.target;
+            assertGameServicesDeploymentTarget(deploymentTarget);
+            const key = bindingKey(entry.schema, binding.target, deploymentTarget);
+            if (registered.has(key)) {
+                throw new TypeError('Duplicate advertising verifier binding.');
+            }
+            const verifier = Object.freeze({ providerId: entry.providerId, verify: entry.verify });
+            registered.set(key, verifier);
+            if (entry.acceptsMissingEvidence === true) {
+                const missingKey = bindingKey(null, binding.target, deploymentTarget);
+                if (registered.has(missingKey)) {
+                    throw new TypeError('Duplicate missing-evidence advertising verifier binding.');
+                }
+                registered.set(missingKey, verifier);
+            }
+        }
+    }
+    return Object.freeze({
+        async verifyAdReward(input) {
+            const request = input.request;
+            const schema = request.evidence === undefined ? null : request.evidence?.schema;
+            const selected = schema === undefined || schema === '' ? undefined : registered.get(bindingKey(schema, request.target, request.deploymentTarget ?? request.target));
+            if (selected === undefined) {
+                return { status: 'rejected', reason: 'AD_REWARD_VERIFIER_UNREGISTERED' };
+            }
+            const { providerId, verify } = selected;
+            if (request.providerId !== undefined && request.providerId !== providerId) {
+                return { status: 'rejected', reason: 'AD_REWARD_PROVIDER_MISMATCH' };
+            }
+            // Proof verification stays abortable and server-owned. Preserve its authoritative
+            // identity so ledger replay checks remain stable across registry migration.
+            const decision = await verify(input);
+            if (decision?.status !== 'verified') {
+                return decision;
+            }
+            const payload = decision.payload;
+            if (payload !== undefined && (typeof payload !== 'object' || payload === null
+                || Array.isArray(payload) || Object.values(payload).some((value) => typeof value !== 'string' && typeof value !== 'boolean'
+                && (typeof value !== 'number' || !Number.isFinite(value))))) {
+                return { status: 'rejected', reason: 'EVIDENCE_VERIFIER_ERROR' };
+            }
+            return { ...decision, payload: { ...payload, adProviderId: providerId } };
+        },
+    });
+}
+const rewardTargets = new Set([
+    'browser',
+    'microsoft-store',
+    'android',
+    'ios',
+    'ait',
+    'reddit',
+    'verse8',
+]);
+function bindingKey(schema, target, deploymentTarget) {
+    return JSON.stringify([schema, target, deploymentTarget]);
+}
+function assertIdentity(value) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > 512) {
+        throw new TypeError('Invalid advertising verifier identity.');
+    }
+}

package/dist/admob-client-reward.d.ts

@@ -16,7 +16,7 @@ export declare const verse8ClientRewardEvidenceSchema = "verse8.ads.reward.v1";
 */
 export declare const clientRewardEvidenceSchemas: readonly ["mpgd.admob.client-reward.v1", "verse8.ads.reward.v1"];
 export type ClientRewardEvidenceSchema = (typeof clientRewardEvidenceSchemas)[number];
-/** True when a rewarded-ad result carries ungranted evidence from an allow-listed schema. */
+/** @deprecated Built-in v1 compatibility helper. Claim/recovery flows use the injected reward evidence registry. */
 export declare function isClientRewardEvidence(value: unknown): boolean;
 export declare function isVerse8ClientRewardEvidence(value: unknown): boolean;
 /**

package/dist/admob-client-reward.js

@@ -35,7 +35,7 @@ export const clientRewardEvidenceSchemas = Object.freeze([
     admobClientRewardEvidenceSchema,
     verse8ClientRewardEvidenceSchema,
 ]);
-/** True when a rewarded-ad result carries ungranted evidence from an allow-listed schema. */
+/** @deprecated Built-in v1 compatibility helper. Claim/recovery flows use the injected reward evidence registry. */
 export function isClientRewardEvidence(value) {
     return isAdMobClientRewardEvidence(value) || isVerse8ClientRewardEvidence(value);
 }

package/dist/client-reward-evidence.d.ts

@@ -0,0 +1,22 @@
+import type { PlatformEvidenceEnvelope, RewardedAdResult } from '@mpgd/platform';
+export interface ClientRewardClaimCandidate {
+  readonly evidence?: PlatformEvidenceEnvelope;
+  readonly platformImpressionId?: string;
+}
+export interface ClientRewardEvidenceNormalizer {
+  readonly schema: string;
+  /** Decode a claim candidate only. This cannot authorize a server grant. */
+  normalize(reward: RewardedAdResult): {
+    readonly platformImpressionId?: string;
+  } | undefined;
+}
+export interface ClientRewardEvidenceRegistry {
+  resolve(reward: RewardedAdResult): ClientRewardClaimCandidate | undefined;
+  recognizes(schema: string): boolean;
+}
+/** An immutable, explicitly registered client decoder set, independent of server verification. */
+export declare function createClientRewardEvidenceRegistry(entries: readonly ClientRewardEvidenceNormalizer[]): ClientRewardEvidenceRegistry;
+/** Preserve the old SDK-flag claim path only for consumers without a versioned/registered provider. */
+export declare function resolveClientRewardClaim(reward: RewardedAdResult, registry: ClientRewardEvidenceRegistry, options: {
+  readonly allowLegacyCompletion: boolean;
+}): ClientRewardClaimCandidate | undefined;

package/dist/client-reward-evidence.js

@@ -0,0 +1,93 @@
+/** An immutable, explicitly registered client decoder set, independent of server verification. */
+export function createClientRewardEvidenceRegistry(entries) {
+    const normalizers = new Map();
+    for (const entry of entries) {
+        if (typeof entry.schema !== 'string' || entry.schema.trim() === '' || entry.schema.length > 512
+            || typeof entry.normalize !== 'function' || normalizers.has(entry.schema)) {
+            throw new TypeError('Invalid or duplicate client reward evidence registration.');
+        }
+        normalizers.set(entry.schema, entry.normalize);
+    }
+    return Object.freeze({
+        recognizes: (schema) => normalizers.has(schema),
+        resolve(reward) {
+            if ((reward.status !== 'completed' && reward.status !== 'pending')
+                || typeof reward.rewardGranted !== 'boolean'
+                || (reward.ledgerEntryId !== undefined && (typeof reward.ledgerEntryId !== 'string' || reward.ledgerEntryId.trim() === '' || reward.ledgerEntryId.length > 512))) {
+                return undefined;
+            }
+            const evidence = cloneEvidence(reward.evidence);
+            if (evidence === undefined) {
+                return undefined;
+            }
+            const normalize = normalizers.get(evidence.schema);
+            if (normalize === undefined) {
+                return undefined;
+            }
+            try {
+                const normalized = normalize(Object.freeze({
+                    status: reward.status, rewardGranted: reward.rewardGranted, evidence,
+                    ...(reward.ledgerEntryId === undefined ? {} : { ledgerEntryId: reward.ledgerEntryId }),
+                }));
+                if (typeof normalized !== 'object' || normalized === null || Array.isArray(normalized)) {
+                    return undefined;
+                }
+                const impressionId = normalized.platformImpressionId;
+                if (impressionId !== undefined && (typeof impressionId !== 'string' || impressionId.trim() === '' || impressionId.length > 512)) {
+                    return undefined;
+                }
+                return Object.freeze({
+                    evidence,
+                    ...(impressionId === undefined ? {} : { platformImpressionId: impressionId }),
+                });
+            }
+            catch {
+                // Decoder failures cannot turn untrusted evidence into a claim or leak its contents.
+                return undefined;
+            }
+        },
+    });
+}
+/** Preserve the old SDK-flag claim path only for consumers without a versioned/registered provider. */
+export function resolveClientRewardClaim(reward, registry, options) {
+    const candidate = registry.resolve(reward);
+    if (candidate !== undefined) {
+        return candidate;
+    }
+    if (!options.allowLegacyCompletion || reward.status !== 'completed' || reward.rewardGranted !== true) {
+        return undefined;
+    }
+    const evidence = reward.evidence === undefined ? undefined : cloneEvidence(reward.evidence);
+    if ((reward.evidence !== undefined && evidence === undefined)
+        || (evidence !== undefined && registry.recognizes(evidence.schema))
+        || (reward.ledgerEntryId !== undefined && (typeof reward.ledgerEntryId !== 'string'
+            || reward.ledgerEntryId.trim() === '' || reward.ledgerEntryId.length > 512))) {
+        return undefined;
+    }
+    return Object.freeze({
+        ...(evidence === undefined ? {} : { evidence }),
+        ...(reward.ledgerEntryId === undefined ? {} : { platformImpressionId: reward.ledgerEntryId }),
+    });
+}
+function cloneEvidence(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const envelope = value;
+    const payload = envelope.payload;
+    if (typeof envelope.schema !== 'string' || envelope.schema.trim() === '' || envelope.schema.length > 512
+        || typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        return undefined;
+    }
+    const entries = Object.entries(payload);
+    if (entries.length > 64 || entries.some(([key, field]) => key.length > 128
+        || (typeof field !== 'string' && typeof field !== 'number' && typeof field !== 'boolean')
+        || (typeof field === 'string' && field.length > 8192)
+        || (typeof field === 'number' && !Number.isFinite(field)))) {
+        return undefined;
+    }
+    return Object.freeze({
+        schema: envelope.schema,
+        payload: Object.freeze(Object.fromEntries(entries)),
+    });
+}

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import { type AnalyticsSink } from '@mpgd/analytics';
 import type { LeaderboardScoreInput, PlatformGateway, PlatformTarget } from '@mpgd/platform';
+import { type ClientRewardEvidenceRegistry } from './client-reward-evidence.js';
 import type { GameServicesOperationClient } from './operations.js';
 export type { GameServicesOperationClient, GameServicesPurchaseInput, GameServicesPurchaseResult, GameServicesRewardedAdInput, GameServicesRewardedAdResult, } from './operations.js';
 import type { GameServicesContractClient } from './contract.js';
@@ -100,6 +101,8 @@ export interface CreateGameServicesClientInput {
   readonly now?: () => string;
   /** Override backend evidence timestamps without backdating analytics events. */
   readonly requestNow?: () => string;
+  /** Explicit client decoders only; server verification is configured independently. */
+  readonly rewardEvidenceRegistry?: ClientRewardEvidenceRegistry;
 }
 export interface GameServicesLeaderboardInput extends LeaderboardScoreInput {
 }

package/dist/client.js

@@ -2,7 +2,8 @@ import { createORPCClient } from '@orpc/client';
 import { RPCLink } from '@orpc/client/fetch';
 import { createAnalyticsReporter } from '@mpgd/analytics';
 import { isAuthoritativeMicrosoftStoreCompletion } from './authoritative-purchase.js';
-import { isClientRewardEvidence, resolveRewardPlatformImpressionId, } from './admob-client-reward.js';
+import { resolveClientRewardClaim, } from './client-reward-evidence.js';
+import { createDefaultClientRewardEvidenceRegistry } from './default-client-reward-evidence.js';
 import { observeGameServicesOperation } from './operation-progress.js';
 export const gameServicesBackendEndpoints = {
     verifyPurchase: '/game-services/purchases/verify',
@@ -57,6 +58,8 @@ export async function resolveGameServicesRequestHeaders(input) {
 export function createGameServicesClient(input) {
     const now = input.now ?? (() => new Date().toISOString());
     const requestNow = input.requestNow ?? now;
+    const rewardEvidenceRegistry = input.rewardEvidenceRegistry ?? createDefaultClientRewardEvidenceRegistry();
+    const allowLegacyRewardCompletion = input.rewardEvidenceRegistry === undefined && input.gateway.ads?.provider === undefined;
     const analytics = createAnalyticsReporter({
         target: input.target,
         sessionId: input.analyticsSessionId ?? input.playerId,
@@ -177,30 +180,13 @@ export function createGameServicesClient(input) {
         async claimRewardedAd(rewardInput, options) {
             return observeGameServicesOperation('rewarded-ad', options, async (progress) => {
                 const target = input.target;
-                if (!isGameServicesAdRewardTarget(target)) {
-                    const reward = {
-                        status: 'unavailable',
-                        rewardGranted: false,
-                    };
-                    await analytics.track({
-                        name: 'rewarded_ad_rejected',
-                        properties: {
-                            placementId: rewardInput.placementId,
-                            status: reward.status,
-                            rewardGranted: reward.rewardGranted,
-                            reason: 'unsupported_target',
-                        },
-                    });
-                    return {
-                        status: 'rejected',
-                        reward,
-                    };
-                }
                 progress.platformRequested();
                 const reward = await input.gateway.ads.showRewarded(rewardInput);
                 progress.platformResult(reward.status);
-                if ((reward.status !== 'completed' || !reward.rewardGranted)
-                    && !isClientRewardEvidence(reward)) {
+                const candidate = resolveClientRewardClaim(reward, rewardEvidenceRegistry, {
+                    allowLegacyCompletion: allowLegacyRewardCompletion,
+                });
+                if (candidate === undefined) {
                     await analytics.track({
                         name: reward.status === 'pending' ? 'rewarded_ad_pending' : 'rewarded_ad_rejected',
                         properties: {
@@ -214,9 +200,10 @@ export function createGameServicesClient(input) {
                         reward,
                     };
                 }
-                const platformImpressionId = resolveRewardPlatformImpressionId(reward);
+                const platformImpressionId = candidate.platformImpressionId;
                 const claimRequest = {
                     target,
+                    ...(input.gateway.ads.provider === undefined ? {} : { providerId: input.gateway.ads.provider.id }),
                     ...(input.deploymentTarget === undefined || input.deploymentTarget === target
                         ? {}
                         : { deploymentTarget: input.deploymentTarget }),
@@ -227,7 +214,7 @@ export function createGameServicesClient(input) {
                         : { platformImpressionId }),
                     idempotencyKey: rewardInput.idempotencyKey,
                     completedAt: requestNow(),
-                    ...(reward.evidence === undefined ? {} : { evidence: reward.evidence }),
+                    ...(candidate.evidence === undefined ? {} : { evidence: candidate.evidence }),
                 };
                 progress.serverRequested();
                 const claim = await input.backend.adRewards.claimAdReward(claimRequest);
@@ -414,9 +401,6 @@ function isGameServicesCommerceTarget(target) {
         || target === 'ait'
         || target === 'verse8';
 }
-function isGameServicesAdRewardTarget(target) {
-    return target === 'android' || target === 'ios' || target === 'ait' || target === 'verse8';
-}
 function isGameServicesLeaderboardTarget(target) {
     return target === 'browser'
         || target === 'microsoft-store'

package/dist/default-client-reward-evidence.d.ts

@@ -0,0 +1,4 @@
+import { type ClientRewardEvidenceNormalizer, type ClientRewardEvidenceRegistry } from './client-reward-evidence.js';
+/** Registered decoder data. Common claim and recovery code never inspects these provider payloads. */
+export declare const defaultClientRewardEvidenceNormalizers: readonly ClientRewardEvidenceNormalizer[];
+export declare function createDefaultClientRewardEvidenceRegistry(additional?: readonly ClientRewardEvidenceNormalizer[]): ClientRewardEvidenceRegistry;

package/dist/default-client-reward-evidence.js

@@ -0,0 +1,38 @@
+import { admobClientRewardEvidenceSchema, isAdMobClientRewardEvidence, isVerse8ClientRewardEvidence, verse8ClientRewardEvidenceSchema, } from './admob-client-reward.js';
+import { createClientRewardEvidenceRegistry, } from './client-reward-evidence.js';
+/** Registered decoder data. Common claim and recovery code never inspects these provider payloads. */
+export const defaultClientRewardEvidenceNormalizers = Object.freeze([
+    Object.freeze({
+        schema: admobClientRewardEvidenceSchema,
+        normalize: (reward) => isAdMobClientRewardEvidence(reward) ? {} : undefined,
+    }),
+    Object.freeze({
+        schema: verse8ClientRewardEvidenceSchema,
+        normalize: (reward) => {
+            if (!isVerse8ClientRewardEvidence(reward)) {
+                return undefined;
+            }
+            const requestId = reward.evidence?.payload.requestId;
+            return typeof requestId === 'string' ? { platformImpressionId: requestId } : undefined;
+        },
+    }),
+    Object.freeze({
+        schema: 'apps-in-toss.rewarded-ad.callback.v1',
+        normalize: (reward) => {
+            const payload = reward.evidence?.payload;
+            const correlationId = payload?.correlationId;
+            if (payload?.event !== 'user-earned-reward' || typeof correlationId !== 'string' || correlationId.trim() === ''
+                || typeof payload.placementId !== 'string' || payload.placementId.trim() === ''
+                || (reward.ledgerEntryId !== undefined && reward.ledgerEntryId !== correlationId)) {
+                return undefined;
+            }
+            return { platformImpressionId: correlationId };
+        },
+    }),
+]);
+export function createDefaultClientRewardEvidenceRegistry(additional = []) {
+    return createClientRewardEvidenceRegistry([
+        ...defaultClientRewardEvidenceNormalizers,
+        ...additional,
+    ]);
+}

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 export * from './admob-ssv.js';
+export * from './ad-reward-verifier-registry.js';
 export * from './app-store-verifier.js';
 export * from './app-store-recovery.js';
 export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
+export * from './client-reward-evidence.js';
+export * from './default-client-reward-evidence.js';
 export * from './admob-client-reward.js';
 export * from './contract.js';
 export * from './evidence-verification.js';

package/dist/index.js

@@ -1,9 +1,12 @@
 export * from './admob-ssv.js';
+export * from './ad-reward-verifier-registry.js';
 export * from './app-store-verifier.js';
 export * from './app-store-recovery.js';
 export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
+export * from './client-reward-evidence.js';
+export * from './default-client-reward-evidence.js';
 export * from './admob-client-reward.js';
 export * from './contract.js';
 export * from './evidence-verification.js';

package/dist/microsoft-store-purchase.d.ts

@@ -58,8 +58,33 @@ export interface CreateMicrosoftStorePurchaseBoundaryInput {
   * Production implementations must share this state across every game-service instance.
   */
   readonly recoveryOwnershipStore: MicrosoftStoreRecoveryOwnershipStore;
+  /**
+  * Persist validated consume/order attribution before releasing recovery ownership.
+  * Must be durable and idempotent by evidenceVerificationId/trackingId. Throw to keep
+  * finalization pending. On developer-managed retries, orderTransactions can be empty;
+  * resolve only if an exact previously persisted receipt is available in that case.
+  * This hook does not receive credentials and does not process Clawback events.
+  */
+  readonly persistConsumptionReceipt?: (receipt: MicrosoftStoreConsumptionReceipt, signal: AbortSignal) => Promise<void>;
   readonly now?: () => string;
 }
+export interface MicrosoftStoreConsumeOrderTransaction {
+  readonly orderId: string;
+  readonly orderLineItemId: string;
+  readonly quantityConsumed: number;
+}
+/** Server-only attribution for subsequent provider refund reconciliation. */
+export interface MicrosoftStoreConsumptionReceipt {
+  readonly evidenceVerificationId: string;
+  readonly playerId: string;
+  /** Stable logical product, distinct from the provider Store ID. */
+  readonly productId: string;
+  readonly storeId: string;
+  readonly collectionItemId: string;
+  readonly trackingId: string;
+  /** Empty when the provider omitted order IDs on a developer-managed retry. */
+  readonly orderTransactions: readonly MicrosoftStoreConsumeOrderTransaction[];
+}
 export interface MicrosoftStoreHistoricalProductMapping {
   readonly inAppOfferToken: string;
   readonly storeId: string;

package/dist/microsoft-store-purchase.js

@@ -1,3 +1,4 @@
+import { gameServicesRequestLimits } from './validation.js';
 export const microsoftStoreDigitalGoodsEvidenceSchema = 'mpgd.microsoft-store.digital-goods.v1';
 export const microsoftStoreCollectionsQueryUrl = 'https://collections.mp.microsoft.com/v9.0/collections/publisherQuery';
 export const microsoftStoreCollectionsConsumeUrl = 'https://collections.mp.microsoft.com/v8.0/collections/consume';
@@ -112,7 +113,9 @@ export function createMicrosoftStorePurchaseBoundary(input) {
         const clientEvidence = readRecoveryOwnershipEvidence(ownershipInput);
         if (playerId === undefined
             || productId === undefined
-            || clientEvidence === undefined) {
+            || clientEvidence === undefined
+            || (ownershipInput.idempotencyKey !== undefined
+                && (generation === undefined || generation.length > gameServicesRequestLimits.maxStringLength))) {
             return { status: 'denied' };
         }
         const currentInAppOfferToken = inAppOfferTokens.get(productId);
@@ -239,7 +242,7 @@ export function createMicrosoftStorePurchaseBoundary(input) {
                 }
                 const effective = await input.recoveryOwnershipStore.claim({
                     ...ownership.record,
-                    generation: ownership.providerPurchaseId,
+                    generation: await createRecoveryGeneration(ownership.providerPurchaseId),
                     providerPurchaseId: ownership.providerPurchaseId,
                 });
                 return effective?.playerId === ownership.record.playerId
@@ -437,6 +440,34 @@ async function consumeMicrosoftStorePurchase(input, finalizationInput, context)
             || raw.newQuantity !== 0) {
             return finalizationPending('MICROSOFT_STORE_CONSUME_RESPONSE_MISMATCH');
         }
+        if (input.persistConsumptionReceipt !== undefined) {
+            const orderTransactions = readConsumeOrderTransactions(raw.orderTransactions);
+            // Some consume responses omit the product echo. Attribution comes from the
+            // verified context and the item/tracking checks above; reject a conflicting echo.
+            if ((raw.productId !== undefined && raw.productId !== context.storeId)
+                || orderTransactions === undefined) {
+                return finalizationPending('MICROSOFT_STORE_CONSUMPTION_RECEIPT_INVALID');
+            }
+            finalizationInput.signal.throwIfAborted();
+            try {
+                await input.persistConsumptionReceipt(Object.freeze({
+                    evidenceVerificationId: finalizationInput.evidenceVerificationId,
+                    playerId: finalizationInput.request.playerId,
+                    productId: finalizationInput.request.productId,
+                    storeId: context.storeId,
+                    collectionItemId: context.collectionItemId,
+                    trackingId,
+                    orderTransactions,
+                }), finalizationInput.signal);
+            }
+            catch (error) {
+                if (finalizationInput.signal.aborted) {
+                    throw error;
+                }
+                return finalizationPending('MICROSOFT_STORE_CONSUMPTION_RECEIPT_UNAVAILABLE');
+            }
+            finalizationInput.signal.throwIfAborted();
+        }
         try {
             await input.recoveryOwnershipStore.release({
                 accountBindingHash,
@@ -462,6 +493,32 @@ async function consumeMicrosoftStorePurchase(input, finalizationInput, context)
         return finalizationPending('MICROSOFT_STORE_CONSUME_UNAVAILABLE');
     }
 }
+function readConsumeOrderTransactions(value) {
+    // Microsoft documents omitted order IDs for developer-managed consume retries.
+    // Never invent them from the collection item, client token, or tracking ID.
+    if (value === undefined) {
+        return Object.freeze([]);
+    }
+    if (!Array.isArray(value) || value.length > 1) {
+        return undefined;
+    }
+    const transactions = [];
+    const guid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/iu;
+    for (const item of value) {
+        // This boundary only grants developer-managed consumables with quantity one.
+        if (!isRecord(item) || typeof item.orderId !== 'string' || !guid.test(item.orderId)
+            || typeof item.orderLineItemId !== 'string' || !guid.test(item.orderLineItemId)
+            || item.quantityConsumed !== 1) {
+            return undefined;
+        }
+        transactions.push(Object.freeze({
+            orderId: item.orderId.toLowerCase(),
+            orderLineItemId: item.orderLineItemId.toLowerCase(),
+            quantityConsumed: 1,
+        }));
+    }
+    return Object.freeze(transactions);
+}
 function inspectPublisherQuery(raw, expectedStoreId) {
     if (!isRecord(raw)) {
         return rejected('MICROSOFT_STORE_COLLECTIONS_RESPONSE_INVALID');
@@ -592,6 +649,15 @@ function readFinalizationContext(input) {
 function createVerificationId(item) {
     return `microsoft-store:${item.productId}:${item.id}:${item.modifiedDate}`;
 }
+/** Keep existing short generations stable while bounding new provider-derived request keys. */
+async function createRecoveryGeneration(providerPurchaseId) {
+    if (providerPurchaseId.length <= gameServicesRequestLimits.maxStringLength) {
+        return providerPurchaseId;
+    }
+    const encoded = new TextEncoder().encode(providerPurchaseId);
+    const digest = new Uint8Array(await readGlobalSubtleCrypto().digest('SHA-256', encoded));
+    return `microsoft-store-recovery:${Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+}
 async function deterministicTrackingId(value) {
     const subtle = readGlobalSubtleCrypto();
     const encoded = new TextEncoder().encode(value);

package/dist/monetization-recovery.js

@@ -1,6 +1,7 @@
 import { isAuthoritativeMicrosoftStoreCompletion } from './authoritative-purchase.js';
 import { createGameServicesClient } from './client.js';
-import { isClientRewardEvidence, resolveRewardPlatformImpressionId, } from './admob-client-reward.js';
+import { resolveClientRewardClaim } from './client-reward-evidence.js';
+import { createDefaultClientRewardEvidenceRegistry } from './default-client-reward-evidence.js';
 import { forwardGameServicesProgress, observeGameServicesOperation, } from './operation-progress.js';
 /**
  * Client-side recovery coordinates UI callbacks and authoritative backend calls.
@@ -9,6 +10,8 @@ import { forwardGameServicesProgress, observeGameServicesOperation, } from './op
  */
 export function createRecoverableMonetizationClient(input) {
     const store = input.operationStore;
+    const rewardEvidenceRegistry = input.rewardEvidenceRegistry ?? createDefaultClientRewardEvidenceRegistry();
+    const allowLegacyRewardCompletion = input.rewardEvidenceRegistry === undefined && input.gateway.ads.provider === undefined;
     const observedAt = () => input.now?.() ?? new Date().toISOString();
     const inFlight = new Map();
     const unjournaledPurchases = new Map();
@@ -442,18 +445,19 @@ export function createRecoverableMonetizationClient(input) {
             assertOwner(found, 'rewarded-ad', idempotencyKey, found.input.placementId);
             const transient = unjournaledRewards.get(key);
             if (transient !== undefined && !samePlatformResult(transient.platform, platform)
-                && !(transient.platform.status === 'pending' && platform.status !== 'pending')) {
+                && !canAdvanceReward(transient.platform, platform, false)) {
                 throw new Error('A platform ad callback conflicts with the unjournaled result.');
             }
-            const canAdvance = found.platform?.status === 'pending'
-                && platform.status !== 'pending' && found.request === undefined;
+            const canAdvance = found.platform !== undefined
+                && !samePlatformResult(found.platform, platform)
+                && canAdvanceReward(found.platform, platform, found.request !== undefined);
             if (found.platform !== undefined && !samePlatformResult(found.platform, platform)
                 && !canAdvance) {
                 throw new Error('A platform ad callback conflicts with the recorded operation.');
             }
             let record = found;
             if (found.platform === undefined || canAdvance) {
-                const completedAt = observedAt();
+                const completedAt = found.platformCompletedAt ?? observedAt();
                 try {
                     record = await save(found, { platform, platformCompletedAt: completedAt });
                 }
@@ -466,6 +470,37 @@ export function createRecoverableMonetizationClient(input) {
             return resumeReward(record);
         });
     }
+    function canAdvanceReward(previous, next, hasRequest) {
+        if (previous.status !== 'pending') {
+            return false;
+        }
+        const legacyUpgrade = !hasRequest && allowLegacyRewardCompletion
+            && previous.rewardGranted === false && next.rewardGranted === true && next.status === 'completed';
+        // Once a candidate is recorded, its correlation cannot be replaced even
+        // when dispatch has not yet reached the server or its journal write failed.
+        if (previous.evidence !== undefined && (!sameRewardEvidence(previous.evidence, next.evidence)
+            || !legacyUpgrade && (previous.rewardGranted !== next.rewardGranted || previous.ledgerEntryId !== next.ledgerEntryId))) {
+            return false;
+        }
+        if (previous.ledgerEntryId !== undefined && previous.ledgerEntryId !== next.ledgerEntryId) {
+            return false;
+        }
+        const candidate = resolveClientRewardClaim(next, rewardEvidenceRegistry, {
+            allowLegacyCompletion: allowLegacyRewardCompletion,
+        });
+        if (candidate === undefined) {
+            return !hasRequest && previous.evidence === undefined && next.evidence === undefined
+                && (next.status === 'skipped' || next.status === 'unavailable' || next.status === 'failed');
+        }
+        const prior = resolveClientRewardClaim(previous, rewardEvidenceRegistry, {
+            allowLegacyCompletion: allowLegacyRewardCompletion,
+        });
+        if (prior !== undefined && (prior.platformImpressionId !== candidate.platformImpressionId
+            || !sameRewardEvidence(prior.evidence, candidate.evidence))) {
+            return false;
+        }
+        return !hasRequest || prior !== undefined;
+    }
     async function reconcile() {
         const pending = await store.listRecoverable(input.playerId);
         const summaries = [];
@@ -618,15 +653,25 @@ function assertPurchaseRequest(record, input) {
 }
 function assertRewardRequest(record, input) {
     const request = record.request;
+    const candidate = record.platform === undefined ? undefined : resolveClientRewardClaim(record.platform, input.rewardEvidenceRegistry ?? createDefaultClientRewardEvidenceRegistry(), { allowLegacyCompletion: input.rewardEvidenceRegistry === undefined && input.gateway.ads.provider === undefined });
     if (request === undefined || record.platform === undefined
-        || ((record.platform.status !== 'completed' || !record.platform.rewardGranted)
-            && !isClientRewardEvidence(record.platform))
+        || candidate === undefined
         || request.playerId !== record.playerId || request.playerId !== input.playerId
         || request.target !== record.target || request.placementId !== record.input.placementId
         || request.idempotencyKey !== record.input.idempotencyKey
-        || request.platformImpressionId !== resolveRewardPlatformImpressionId(record.platform)
+        || request.platformImpressionId !== candidate.platformImpressionId
+        || request.providerId !== undefined && request.providerId !== input.gateway.ads.provider?.id
+        || !sameRewardEvidence(request.evidence, candidate.evidence)
         || request.deploymentTarget !== (input.deploymentTarget === input.target
             ? undefined : input.deploymentTarget)) {
         throw new Error('Journaled ad claim is not bound to its platform result.');
     }
 }
+function sameRewardEvidence(request, candidate) {
+    if (request === undefined || candidate === undefined) {
+        return request === candidate;
+    }
+    return request.schema === candidate.schema
+        && Object.keys(request.payload).length === Object.keys(candidate.payload).length
+        && Object.entries(request.payload).every(([key, value]) => Object.hasOwn(candidate.payload, key) && candidate.payload[key] === value);
+}

package/dist/runtime.d.ts

@@ -2,6 +2,7 @@ import type { AnalyticsSink } from '@mpgd/analytics';
 import type { PlatformGateway, PlatformTarget } from '@mpgd/platform';
 import { type GameServicesBackendApi, type GameServicesBackendTransport, type GameServicesClient, type GameServicesHeaderResolver } from './client.js';
 import type { GameServicesLedgerTarget } from './types.js';
+import type { ClientRewardEvidenceRegistry } from './client-reward-evidence.js';
 import { type MonetizationOperationStore, type RecoverableMonetizationClient } from './monetization-recovery.js';
 export type GameServicesAuthorityMode = 'production' | 'non-production';
 export type GameServicesRuntimeMode = 'disabled' | 'local' | 'http' | 'orpc';
@@ -32,6 +33,7 @@ interface CreateGameServicesRuntimeCommonInput {
   readonly now?: () => string;
   /** Durable, compare-and-swap journal for purchase and rewarded-ad recovery. */
   readonly operationStore?: MonetizationOperationStore;
+  readonly rewardEvidenceRegistry?: ClientRewardEvidenceRegistry;
 }
 export type CreateGameServicesRuntimeInput = CreateGameServicesRuntimeCommonInput & ({
   readonly transport?: 'http';

package/dist/runtime.js

@@ -61,6 +61,7 @@ export function createGameServicesRuntime(input) {
             ? {}
             : { analyticsSessionId: input.analyticsSessionId }),
         ...(input.now === undefined ? {} : { now: input.now }),
+        ...(input.rewardEvidenceRegistry === undefined ? {} : { rewardEvidenceRegistry: input.rewardEvidenceRegistry }),
     };
     const client = createGameServicesClient(clientInput);
     const monetizationRecovery = input.operationStore === undefined

package/dist/server.js

@@ -394,11 +394,13 @@ function resolveMaxBodyBytes(maxBodyBytes) {
     return resolved;
 }
 const gameServicesDeploymentTargetPlatforms = new Set([
+    'browser',
     'microsoft-store',
     'android',
     'ios',
     'ait',
     'verse8',
+    'reddit',
 ]);
 function resolveDeploymentTargetBindings(input) {
     const bindings = {};

package/dist/types.d.ts

@@ -4,7 +4,7 @@ import type { ClaimAdRewardResponse, PurchaseGrantFinalization, VerifyPurchaseRe
 export type { ClaimAdRewardResponse, PurchaseGrantFinalization, PurchaseGrantFinalizationAction, VerifyPurchaseResponse, } from './operation-results.js';
 export type { PlatformEvidenceEnvelope } from '@mpgd/platform';
 export type GameServicesStoreTarget = Extract<PlatformTarget, 'microsoft-store' | 'android' | 'ios' | 'ait'>;
-export type GameServicesAdRewardTarget = Extract<PlatformTarget, 'android' | 'ios' | 'ait' | 'verse8'>;
+export type GameServicesAdRewardTarget = GameServicesLedgerTarget;
 export type GameServicesLeaderboardTarget = Extract<PlatformTarget, 'browser' | 'microsoft-store' | 'android' | 'ios' | 'ait' | 'reddit'>;
 export type GameServicesLedgerTarget = Extract<PlatformTarget, 'browser' | 'microsoft-store' | 'android' | 'ios' | 'ait' | 'reddit' | 'verse8'>;
 export type PurchaseIdempotencyKey = string;
@@ -25,6 +25,8 @@ export interface VerifyPurchaseRequest {
 }
 export interface ClaimAdRewardRequest {
   readonly target: GameServicesAdRewardTarget;
+  /** Versioned provider identity, independent of build target; checked by server registration. */
+  readonly providerId?: string;
   /** Deployment config key used to resolve game-owned platform placement identifiers. */
   readonly deploymentTarget?: string;
   readonly playerId: string;

package/dist/types.js

@@ -58,6 +58,7 @@ export function assertClaimAdRewardRequest(input) {
     return validateRequest(() => {
         assertRecord(input, 'ClaimAdRewardRequest');
         assertAdRewardTarget(input.target);
+        assertOptionalRequestString(input.providerId, 'providerId');
         assertOptionalGameServicesDeploymentTarget(input.deploymentTarget);
         assertRequestString(input.playerId, 'playerId');
         assertRequestString(input.placementId, 'placementId');
@@ -158,8 +159,9 @@ function assertStoreTarget(input) {
     }
 }
 function assertAdRewardTarget(input) {
-    if (input !== 'android' && input !== 'ios' && input !== 'ait' && input !== 'verse8') {
-        throw new Error('target must be android, ios, ait, or verse8.');
+    if (input !== 'browser' && input !== 'microsoft-store' && input !== 'android'
+        && input !== 'ios' && input !== 'ait' && input !== 'reddit' && input !== 'verse8') {
+        throw new Error('target must be a supported platform target.');
     }
 }
 export function assertGameServicesDeploymentTarget(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -25,6 +25,14 @@
   "type": "module",
   "sideEffects": false,
   "exports": {
+    "./client-reward-evidence": {
+      "types": "./dist/client-reward-evidence.d.ts",
+      "default": "./dist/client-reward-evidence.js"
+    },
+    "./default-client-reward-evidence": {
+      "types": "./dist/default-client-reward-evidence.d.ts",
+      "default": "./dist/default-client-reward-evidence.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
@@ -144,6 +152,10 @@
     "./operations": {
       "types": "./dist/operations.d.ts",
       "default": "./dist/operations.js"
+    },
+    "./ad-reward-verifier-registry": {
+      "types": "./dist/ad-reward-verifier-registry.d.ts",
+      "default": "./dist/ad-reward-verifier-registry.js"
     }
   },
   "files": [
@@ -154,9 +166,9 @@
     "@orpc/client": "2.0.0-beta.14",
     "@orpc/contract": "2.0.0-beta.14",
     "@orpc/server": "2.0.0-beta.14",
-    "@mpgd/analytics": "0.4.0",
-    "@mpgd/catalog": "0.7.6",
-    "@mpgd/platform": "0.14.0"
+    "@mpgd/catalog": "0.7.7",
+    "@mpgd/analytics": "0.4.1",
+    "@mpgd/platform": "0.15.0"
   },
   "devDependencies": {
     "@opentelemetry/api": "1.9.0",
@@ -174,8 +186,8 @@
     "format": "ttsc format",
     "fix": "ttsc fix",
     "build": "cd ../.. && node tools/run-ttsx.mjs tools/package/build-packages.ts @mpgd/game-services",
-    "test:packed-transport": "pnpm build && node test/runtime-transport-package-import.mjs",
-    "test:unit": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-progress.test.ts && node tools/run-ttsx.mjs packages/game-services/src/runtime.test.ts && node tools/run-ttsx.mjs packages/game-services/src/types.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-publisher-client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-identity.test.ts && node tools/run-ttsx.mjs packages/game-services/src/platform-order.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/admob-ssv.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-verifier.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-evidence-verification-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-partner-api.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-durability-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-transport.test.ts && node tools/run-ttsx.mjs packages/game-services/src/guest-session.test.ts",
+    "test:packed-transport": "pnpm build && node test/runtime-transport-package-import.mjs && node test/reward-evidence-import.mjs",
+    "test:unit": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-progress.test.ts && node tools/run-ttsx.mjs packages/game-services/src/runtime.test.ts && node tools/run-ttsx.mjs packages/game-services/src/types.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-publisher-client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-identity.test.ts && node tools/run-ttsx.mjs packages/game-services/src/platform-order.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/admob-ssv.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-verifier.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-evidence-verification-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-partner-api.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-durability-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-transport.test.ts && node tools/run-ttsx.mjs packages/game-services/src/guest-session.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-reward-evidence.test.ts && node tools/run-ttsx.mjs packages/game-services/src/ad-reward-verifier-registry.test.ts",
     "test:recovery": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/monetization-recovery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-recovery.test.ts",
     "test": "pnpm test:unit && pnpm test:recovery && pnpm test:packed-transport"
   }