@mpgd/cli 0.57.0 → 0.58.0

package/templates/phaser-game/src/main.ts

@@ -17,7 +17,13 @@ import { t } from './i18n/messages';
 import { createClientId } from './runtime/id';
 import { createStarterGame } from './runtime/createGame';
 import { detectRuntime } from './platform/runtimeDetector';
-import { createStarterGameServices, type StarterMonetizationPorts } from './platform/gameServices';
+import {
+  createStarterGameServices,
+  createStarterSessionGatedGameServices,
+  type StarterMonetizationPorts,
+} from './platform/gameServices';
+import { createStarterGuestSignIn } from './platform/guestIdentity';
+import { setStarterServerSession } from './platform/serverSession';
 import { installPlatform } from './platform/installPlatform';
 import { installMicrosoftStorePwa } from './platform/microsoftStorePwa';
 
@@ -28,6 +34,7 @@ async function bootstrap(options: { readonly monetization?: StarterMonetizationP
   let gameRuntime: GamePlatformRuntime | undefined;
   let locale: Locale = 'en';
   let disposeMicrosoftStorePwa: (() => void) | undefined;
+  let disposeGuestSignIn: (() => void) | undefined;
 
   try {
     if (__APP_TARGET__ === 'ait') {
@@ -53,15 +60,45 @@ async function bootstrap(options: { readonly monetization?: StarterMonetizationP
       runtime: runtime.config.runtime,
       orientationPolicy,
     });
-    const player =
+    const platformPlayer =
       (await platform.identity.getPlayer()) ?? {
         playerId: 'local-player',
         displayName: 'Local Player',
       };
-    const [identitySession, launchIntent] = await Promise.all([
-      resolveIdentitySession(platform, player.playerId),
+    // The server-issued guest (VITE_MPGD_IDENTITY_URL): tried at boot, and when that fails,
+    // again in the background and before any purchase or restore (`guestIdentity.ts`).
+    const guestSignIn = createStarterGuestSignIn({
+      identityUrl: import.meta.env.VITE_MPGD_IDENTITY_URL,
+      credentials: platform.secureCredentials,
+    });
+    disposeGuestSignIn = () => guestSignIn.dispose();
+    const [bootSignIn, platformSession, launchIntent] = await Promise.all([
+      guestSignIn.ensure(),
+      resolveIdentitySession(platform, platformPlayer.playerId),
       resolveLaunchIntent(platform),
     ]);
+    // A background retry may have won while the other boot reads were pending.
+    const guestIdentity = guestSignIn.current() ?? bootSignIn;
+    // Before the game services read the session: at once, or when a later attempt succeeds
+    // (notifications then come up on their next open; the session-gated services read it).
+    if (guestIdentity !== undefined) {
+      setStarterServerSession(guestIdentity.serverSession);
+    } else {
+      guestSignIn.onSignedIn((later) => setStarterServerSession(later.serverSession));
+    }
+    // Signed in at boot, the server player replaces the platform's (on the native shell a local
+    // placeholder) everywhere. Signed in later, the scenes keep this run's boot player (see
+    // README, "Guest identity"); only the purchase and notification services use the server player.
+    const player = guestIdentity !== undefined
+      ? { ...platformPlayer, playerId: guestIdentity.playerId }
+      : platformPlayer;
+    const identitySession: IdentitySession = guestIdentity !== undefined
+      ? {
+          identityLevel: guestIdentity.identityLevel,
+          playerId: guestIdentity.playerId,
+          trustLevel: 'server-verified',
+        }
+      : platformSession;
     locale = resolveTargetMpgdLocale({
       capabilities: runtime.capabilities,
       ...(platform.gameSettings?.getLocale === undefined ? {} : { preferredLocales: [platform.gameSettings.getLocale()] }),
@@ -76,10 +113,16 @@ async function bootstrap(options: { readonly monetization?: StarterMonetizationP
       sessionId: analyticsSessionId,
       sink: analyticsSink,
     });
+    const sessionGated = guestIdentity === undefined && guestSignIn.configured;
     const ownedRuntime = createGamePlatformRuntime({
       gateway: platform,
       initialLifecycleState: document.visibilityState === 'hidden' ? 'inactive' : 'active',
       canShow: (placement) => {
+        // A run that booted before its sign-in shows no rewarded ad: the runtime's late
+        // reward evidence recovery is bound at boot, which had no recovery client.
+        if (placement.format === 'rewarded' && sessionGated) {
+          return false;
+        }
         const enabled = placement.format === 'rewarded'
           ? runtime.config.features.rewardedAds
           : runtime.config.features.interstitialAds;
@@ -100,15 +143,32 @@ async function bootstrap(options: { readonly monetization?: StarterMonetizationP
       onObserverError: (error) => {
         console.error('[game-runtime]', error);
       },
-      createServices: (gateway) =>
-        createStarterGameServices({
+      createServices: (gateway) => {
+        const servicesInput = {
           gateway,
-          playerId: identitySession.playerId ?? player.playerId,
           configTarget: runtime.configTarget,
           ...(options.monetization === undefined ? {} : { operationStore: options.monetization.operationStore }),
           analytics: analyticsSink,
           analyticsSessionId,
-        }),
+        };
+        // Configured but not signed in yet: the services wait for the server player, never
+        // binding purchases or the journal to the platform's local placeholder.
+        return sessionGated
+          ? createStarterSessionGatedGameServices({
+              ...servicesInput,
+              signIn: guestSignIn,
+              // The startup recovery the boot ran without a player, with the action coordinator's.
+              onActivated: () => {
+                void gameRuntime?.reconcile().catch((error: unknown) => {
+                  console.error('[game-services] recovery after sign-in failed', error);
+                });
+              },
+            })
+          : createStarterGameServices({
+              ...servicesInput,
+              playerId: identitySession.playerId ?? player.playerId,
+            });
+      },
     });
     gameRuntime = ownedRuntime;
     const gameServices = ownedRuntime.services;
@@ -149,6 +209,7 @@ async function bootstrap(options: { readonly monetization?: StarterMonetizationP
     });
   } catch (error) {
     gameRuntime?.dispose();
+    disposeGuestSignIn?.();
     disposeMicrosoftStorePwa?.();
     renderBootstrapError(error, locale);
     console.error('[bootstrap]', error);

package/templates/phaser-game/src/platform/commerceAccountBinding.ts

@@ -8,23 +8,44 @@ import type { StorePurchaseAccountBinding } from '@mpgd/platform/commerce';
  * (`resolveObfuscatedAccountId` of the Play verifier,
  * `resolveAppAccountToken` of the App Store verifier), which is how the
  * backend ties a store purchase to the player before it grants. This module
- * derives both from a SHA-256 digest of the authenticated player id; a game
- * with its own account scheme replaces these two functions and the backend
+ * derives both from a SHA-256 digest of the server player id (the reference
+ * identity Worker, apps/game-identity-worker, derives the same); a game with
+ * its own account scheme replaces these two functions and the backend
  * resolvers together. Nothing here grants anything.
  */
 export const starterAccountBindingDigestPrefix = 'mpgd-commerce-account:';
 
+/** The game's server player source; see `setStarterCommerceServerPlayer`. */
+let serverPlayer: (() => string | undefined) | undefined;
+
+/**
+ * Binds store purchases to the player of the game's server session (the
+ * identity service's player, a server-issued guest included) instead of the
+ * platform session. A generated game's `guestIdentity.ts` sets it when
+ * `VITE_MPGD_IDENTITY_URL` is configured; `undefined` restores the platform
+ * session. While it is set, no server player (not signed in yet, or the
+ * sign-in failed) binds nothing: the platform's local player never stands in.
+ */
+export function setStarterCommerceServerPlayer(source: (() => string | undefined) | undefined): void {
+  serverPlayer = source;
+}
+
 /**
- * The authenticated player id a purchase is bound to. Only an
- * `authenticated` session whose trust is not `local` binds: a guest, a
- * platform-anonymous session (the native shell's default
- * `android-local-player` / `ios-local-player`), or a locally asserted id
- * would give every install the same binding, and the backend binds the
- * purchase to its own authenticated player id anyway.
+ * The player id a purchase is bound to: the server session's player when
+ * the game set one (`setStarterCommerceServerPlayer`), else an
+ * `authenticated` platform session whose trust is not `local`. A
+ * platform-anonymous session (the native shell's `android-local-player` /
+ * `ios-local-player`) or a locally asserted id would give every install the
+ * same binding, so it binds nothing; the backend binds the purchase to the
+ * player its ingress authentication resolved anyway.
  */
 export async function resolveStarterCommercePlayerId(
   gateway: Pick<PlatformGateway, 'identity'>,
 ): Promise<string | undefined> {
+  if (serverPlayer !== undefined) {
+    const playerId = serverPlayer()?.trim();
+    return playerId === undefined || playerId.length === 0 ? undefined : playerId;
+  }
   let session: IdentitySession | undefined;
   try {
     session = await gateway.identity.getSession?.();
@@ -38,7 +59,11 @@ export async function resolveStarterCommercePlayerId(
   return playerId === undefined || playerId.length === 0 ? undefined : playerId;
 }
 
-/** Google Play `obfuscatedAccountId`: 64 hex characters, within Play's 64-character limit. */
+/**
+ * Google Play `obfuscatedAccountId`: 64 hex characters, within Play's
+ * 64-character limit. `undefined` without a player, which the Play
+ * provider refuses with `ACCOUNT_BINDING_REQUIRED`.
+ */
 export async function resolvePlayBillingAccountBinding(
   gateway: Pick<PlatformGateway, 'identity'>,
 ): Promise<StorePurchaseAccountBinding | undefined> {
@@ -55,7 +80,11 @@ export async function resolveStoreKitAppAccountToken(
 ): Promise<string> {
   const playerId = await resolveStarterCommercePlayerId(gateway);
   if (playerId === undefined) {
-    throw new Error('A StoreKit purchase requires an authenticated player session.');
+    throw new Error(
+      'A StoreKit purchase is bound to the player of a server session, and there is none: '
+        + 'sign in to an identity service first (a generated game: VITE_MPGD_IDENTITY_URL and '
+        + "src/platform/guestIdentity.ts). The native shell's local player cannot bind a purchase.",
+    );
   }
   return toUuid(await digestPlayerId(playerId));
 }

package/templates/phaser-game/src/platform/deleteAccount.ts

@@ -0,0 +1,334 @@
+import {
+  AccountDeletionError,
+  GuestSessionCoordinatorError,
+  isMonetizationOperationRecoverable,
+  type AccountDeletionClient,
+  type MonetizationOperationRecord,
+} from '@mpgd/game-services';
+import type { Locale } from '@mpgd/i18n';
+import type { SecureCredentialStore, StorageAdapter } from '@mpgd/platform';
+
+import { t } from '../i18n/messages';
+import { defaultMonetizationJournalKey } from './monetizationJournal';
+
+/**
+ * The secure credential keys of the guest session
+ * (`createGuestSessionCoordinator`'s default `credentialKey` and its family
+ * entry). A game that passes another `credentialKey` registers its own
+ * sign-out with `onStarterAccountDeleted`.
+ */
+export const starterGuestCredentialKeys = [
+  'mpgd.guest.refresh',
+  'mpgd.guest.refresh.family',
+] as const;
+
+/**
+ * The `requestConfirmation` of `createStarterAccountDeletion` for a server
+ * session that can ask the identity service for one (the guest session's
+ * `requestAccountDeletionConfirmation`), or `undefined` for one that cannot
+ * (a development session, whose server needs none). A session the identity
+ * service refused (`GUEST_SESSION_REJECTED`, now or in an earlier refresh)
+ * is `AccountDeletionError('UNAUTHORIZED')`; a backend that cannot issue one
+ * (`GUEST_SESSION_UNSUPPORTED`) is `ACCOUNT_DELETION_NOT_CONFIGURED`. Any
+ * other failure (offline, a failed credential save) passes through, a
+ * retryable failure that says nothing about an earlier request.
+ */
+export function starterAccountDeletionConfirmation(
+  session: { requestAccountDeletionConfirmation?(): Promise<string> } | undefined,
+): (() => Promise<string>) | undefined {
+  const request = session?.requestAccountDeletionConfirmation;
+  if (session === undefined || request === undefined) {
+    return undefined;
+  }
+  return async () => {
+    try {
+      return await request.call(session);
+    } catch (error) {
+      if (error instanceof GuestSessionCoordinatorError && error.code === 'GUEST_SESSION_REJECTED') {
+        throw new AccountDeletionError('UNAUTHORIZED', { cause: error });
+      }
+      if (error instanceof GuestSessionCoordinatorError && error.code === 'GUEST_SESSION_UNSUPPORTED') {
+        throw new AccountDeletionError('ACCOUNT_DELETION_NOT_CONFIGURED', { cause: error });
+      }
+      throw error;
+    }
+  };
+}
+
+export type StarterDeleteAccountOutcome =
+  /**
+   * The server deleted the account. `signedOut` is `false` when this device
+   * could not forget the session's credentials, the purchase journal, or
+   * the run checkpoint.
+   */
+  | { readonly outcome: 'deleted'; readonly retainedPurchaseRecords: number; readonly signedOut: boolean }
+  /**
+   * The server refused the session after an earlier attempt whose request
+   * was sent but whose answer was lost: the account was most likely
+   * deleted. `signedOut` reports whether this device forgot the session.
+   */
+  | { readonly outcome: 'session-ended'; readonly signedOut: boolean }
+  /** No signed-in session to delete. */
+  | { readonly outcome: 'needs-session' }
+  /** Not this time; `retryable` says whether trying again can help. */
+  | { readonly outcome: 'failed'; readonly retryable: boolean }
+  /** This build or server has no account deletion; point the player at the web page. */
+  | { readonly outcome: 'unavailable' };
+
+export interface StarterAccountDeletion {
+  /** Whether the game should show the Delete account entry: a deletion client and a signed-in session. */
+  readonly available: boolean;
+  /** Whether a purchase on this device is still being processed, to warn before deleting. */
+  hasPendingPurchase(): Promise<boolean>;
+  /** Deletes the account on the server, then signs this device out. A second call joins the first. */
+  deleteAccount(): Promise<StarterDeleteAccountOutcome>;
+}
+
+type SignOutStep = () => void | Promise<void>;
+
+const signOutSteps = new Set<SignOutStep>();
+/** Steps that close a session holder, run before the credentials are removed. */
+const sessionSteps = new Set<SignOutStep>();
+
+/**
+ * An earlier attempt's request was sent but its answer was lost or was a
+ * retryable server failure, so the deletion may have completed. Kept for
+ * the page's life, across scenes.
+ */
+let answerLost = false;
+
+/** The PlayScene run checkpoint's storage key; the scene saves under it. */
+export const starterRunKey = 'starter-run';
+
+/** A local sign-out step that hangs is given up on after this long. */
+const signOutStepTimeoutMs = 5_000;
+
+/**
+ * Registers a local sign-out step run after the account is deleted (for
+ * example the guest session's `logout()`, the notifications runtime's
+ * `unregister()`, a game-owned journal or save). Returns the unregister.
+ */
+export function onStarterAccountDeleted(
+  step: SignOutStep,
+  options: {
+    /**
+     * `session`: the step closes something that may still write the
+     * session's credentials (the guest session coordinator's `logout()`,
+     * which closes it at once and waits for a refresh in flight). It runs
+     * before the credentials are removed, so a refresh that answers late
+     * cannot write the deleted account's token back.
+     */
+    readonly phase?: 'session' | 'after';
+  } = {},
+): () => void {
+  const steps = options.phase === 'session' ? sessionSteps : signOutSteps;
+  steps.add(step);
+  return () => {
+    steps.delete(step);
+  };
+}
+
+/**
+ * Delete account for the starter's settings: App Store guideline 5.1.1(v)
+ * and Google Play require deletion in the app. The scene asks twice (see
+ * `deleteAccountConfirmText`) before calling `deleteAccount()`; the server
+ * (`POST /game-services/account/delete`) erases the player's data, keeps
+ * the purchase records the law requires without the player id, and ends
+ * every session. This device then forgets the session's credentials, the
+ * purchase journal, and whatever `onStarterAccountDeleted` registered.
+ */
+export function createStarterAccountDeletion(input: {
+  /** `context.gameServices.accountDeletion`; absent without a game-services URL. */
+  readonly client?: Pick<AccountDeletionClient, 'deleteAccount'>;
+  readonly storage: Pick<StorageAdapter, 'load' | 'save'>;
+  readonly secureCredentials?: Pick<SecureCredentialStore, 'remove'>;
+  readonly journalKey?: string;
+  /** Whether a server-backed session is signed in (`resolveStarterServerSession()?.current()`). */
+  readonly signedIn?: () => boolean;
+  /**
+   * Asks the identity service for a deletion confirmation (it takes the
+   * session's refresh token, which a stolen access token does not give),
+   * right after the player's second tap. Without it the request carries
+   * none, which only a development server accepts. It throws
+   * `AccountDeletionError('UNAUTHORIZED')` when the identity service refused
+   * the session (which is what a completed deletion looks like after a lost
+   * answer); anything else it throws is a retryable failure.
+   */
+  readonly requestConfirmation?: () => Promise<string>;
+}): StarterAccountDeletion {
+  const client = input.client;
+  const journalKey = input.journalKey ?? defaultMonetizationJournalKey;
+  let running: Promise<StarterDeleteAccountOutcome> | undefined;
+
+  /**
+   * Answers whether the credentials, the journal (unless kept), and the run checkpoint were cleared;
+   * registered steps only log. An inferred deletion keeps the journal: its
+   * open purchases may still need the store's answer if the account exists.
+   */
+  const signOut = async (options: { readonly keepJournal?: boolean } = {}): Promise<boolean> => {
+    // Every step runs; one failing or hanging does not keep the others' data around.
+    const required: (() => Promise<unknown> | unknown)[] = [
+      ...starterGuestCredentialKeys.map((key) => () => input.secureCredentials?.remove({ key })),
+      ...(options.keepJournal === true
+        ? []
+        : [() => input.storage.save({ key: journalKey, value: null })]),
+    ];
+    // The starter's own run checkpoint (PlayScene); a game's saves register a step.
+    required.push(() => input.storage.save({ key: starterRunKey, value: null }));
+    let cleared = true;
+    for (const step of [...sessionSteps, ...required, ...signOutSteps]) {
+      try {
+        await withTimeout(step);
+      } catch (error) {
+        console.error('[delete-account] local sign-out step failed', error);
+        if (required.includes(step)) {
+          cleared = false;
+        }
+      }
+    }
+    return cleared;
+  };
+
+  const run = async (): Promise<StarterDeleteAccountOutcome> => {
+    if (client === undefined) {
+      return { outcome: 'unavailable' };
+    }
+    try {
+      let confirmation: string | undefined;
+      try {
+        confirmation = await input.requestConfirmation?.();
+      } catch (error) {
+        // Nothing reached the game server, so only a refused session says
+        // anything about an earlier attempt.
+        if (error instanceof AccountDeletionError && error.code === 'UNAUTHORIZED') {
+          if (error.requestSent && answerLost) {
+            answerLost = false;
+            return { outcome: 'session-ended', signedOut: await signOut({ keepJournal: true }) };
+          }
+          return { outcome: 'needs-session' };
+        }
+        if (error instanceof AccountDeletionError && error.code === 'ACCOUNT_DELETION_NOT_CONFIGURED') {
+          return { outcome: 'unavailable' };
+        }
+        console.error('[delete-account] confirmation', error);
+        return { outcome: 'failed', retryable: true };
+      }
+      const receipt = await client.deleteAccount(
+        confirmation === undefined ? {} : { confirmation },
+      );
+      answerLost = false;
+      return {
+        outcome: 'deleted',
+        retainedPurchaseRecords: receipt.retainedPurchaseRecords,
+        signedOut: await signOut(),
+      };
+    } catch (error) {
+      if (!(error instanceof AccountDeletionError)) {
+        console.error('[delete-account]', error);
+        return { outcome: 'failed', retryable: true };
+      }
+      if (error.code === 'ACCOUNT_DELETION_UNREACHABLE') {
+        // Only a request that went out may have deleted the account.
+        answerLost ||= error.requestSent;
+        return { outcome: 'failed', retryable: true };
+      }
+      if (error.code === 'UNAUTHORIZED' && error.requestSent && answerLost) {
+        answerLost = false;
+        return { outcome: 'session-ended', signedOut: await signOut({ keepJournal: true }) };
+      }
+      if (error.requestSent && !error.retryable) {
+        // A definite answer from the server: the account was not deleted.
+        answerLost = false;
+      } else if (error.requestSent) {
+        // A retryable one (a 5xx from a proxy, a deletion whose identity step
+        // answered late) may hide a completed deletion: the next attempt reads
+        // a refused session as that.
+        answerLost = true;
+      }
+      switch (error.code) {
+        case 'UNAUTHORIZED':
+          return { outcome: 'needs-session' };
+        case 'ACCOUNT_DELETION_NOT_CONFIGURED':
+          return { outcome: 'unavailable' };
+        case 'ACCOUNT_DELETION_CONFIRMATION_REQUIRED':
+          // Expired or already used, the next tap asks for a new one;
+          // without a way to ask, the server's check cannot be met.
+          return input.requestConfirmation === undefined
+            ? { outcome: 'unavailable' }
+            : { outcome: 'failed', retryable: true };
+        default:
+          return { outcome: 'failed', retryable: error.retryable };
+      }
+    }
+  };
+
+  return {
+    available: client !== undefined && (input.signedIn?.() ?? true),
+    async hasPendingPurchase() {
+      try {
+        const loaded = await input.storage.load({ key: journalKey });
+        const records = (loaded?.value as { readonly records?: unknown } | null | undefined)?.records;
+        if (typeof records !== 'object' || records === null) {
+          return false;
+        }
+        return Object.values(records as Record<string, MonetizationOperationRecord>).some(
+          (record) => record.kind !== 'rewarded-ad' && isMonetizationOperationRecoverable(record),
+        );
+      } catch {
+        return false;
+      }
+    },
+    deleteAccount() {
+      running ??= run().finally(() => {
+        running = undefined;
+      });
+      return running;
+    },
+  };
+}
+
+function withTimeout(step: () => Promise<unknown> | unknown): Promise<unknown> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return Promise.race([
+    Promise.resolve().then(step),
+    new Promise((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error('sign-out step timed out')), signOutStepTimeoutMs);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+/** Test seam: forget a lost answer remembered by an earlier deletion attempt. */
+export function resetStarterAccountDeletionForTests(): void {
+  answerLost = false;
+}
+
+/** The confirmation shown before deleting: what goes, what stays, and a pending purchase warning. */
+export function deleteAccountConfirmText(locale: Locale, pendingPurchase: boolean): string {
+  const text = t(locale, 'deleteAccountConfirm');
+  return pendingPurchase ? `${text}\n${t(locale, 'deleteAccountPendingPurchase')}` : text;
+}
+
+/** The player-facing line for an outcome, shared by the Phaser lobby and the lite button. */
+export function deleteAccountOutcomeText(
+  locale: Locale,
+  result: StarterDeleteAccountOutcome,
+): string {
+  switch (result.outcome) {
+    case 'deleted':
+      return result.signedOut
+        ? t(locale, 'deleteAccountDone')
+        : t(locale, 'deleteAccountDoneLocalFailed');
+    case 'session-ended':
+      return result.signedOut
+        ? t(locale, 'deleteAccountSessionEnded')
+        : t(locale, 'deleteAccountDoneLocalFailed');
+    case 'needs-session':
+      return t(locale, 'deleteAccountNeedsSession');
+    case 'unavailable':
+      return t(locale, 'deleteAccountUnavailable');
+    default:
+      return result.retryable
+        ? t(locale, 'deleteAccountFailed')
+        : t(locale, 'deleteAccountRejected');
+  }
+}

package/templates/phaser-game/src/platform/gameServices.ts

@@ -14,8 +14,13 @@ import type { GameActionReconciliationPort } from '@mpgd/game-runtime/actions';
 import type { PurchasePresentationEvent } from '@mpgd/game-runtime/ads';
 
 import { resolveStarterCommerceProducts } from './commerceProducts';
+import type { StarterGuestSignIn } from './guestIdentity';
 import { createStorageMonetizationOperationStore } from './monetizationJournal';
 import { resolveStarterServerSession } from './serverSession';
+import {
+  createSessionGatedGameServices,
+  type StarterSessionGatedServices,
+} from './sessionGatedServices';
 
 const productCatalog = productCatalogJson as ProductCatalog;
 
@@ -31,24 +36,64 @@ export interface StarterMonetizationPorts {
 }
 
 export type StarterBackendMode = GameServicesRuntimeMode;
-export type StarterGameServices = GameServicesRuntime;
-
 /**
- * Game-services runtime over the commerce v2 reconciler: every purchase is
- * journaled in a durable `MonetizationOperationStore` (the reference journal
- * over the platform storage adapter unless the game supplies its own) and
- * verified through the backend ledger, with the catalog's kinds and SKUs for
- * the gateway target resolved without a store read.
+ * The game services the scenes read. In a run whose guest sign-in failed at
+ * boot they are session-gated (`ensureSession` present): see
+ * `sessionGatedServices.ts`.
  */
-export function createStarterGameServices(input: {
+export type StarterGameServices = GameServicesRuntime & {
+  readonly ensureSession?: StarterSessionGatedServices['ensureSession'];
+};
+
+interface StarterGameServicesInput {
   readonly gateway: PlatformGateway;
   readonly playerId: string;
   readonly configTarget: string;
   readonly operationStore?: MonetizationOperationStore;
   readonly analytics?: AnalyticsSink;
   readonly analyticsSessionId?: string;
-}): StarterGameServices {
-  const session = resolveStarterServerSession({ once: true });
+}
+
+/**
+ * Game-services runtime over the commerce v2 reconciler: every purchase is
+ * journaled in a durable `MonetizationOperationStore` (the reference journal
+ * over the platform storage adapter unless the game supplies its own) and
+ * verified through the backend ledger, with the catalog's kinds and SKUs for
+ * the gateway target resolved without a store read.
+ */
+export function createStarterGameServices(input: StarterGameServicesInput): StarterGameServices {
+  return createRuntime(input, resolveStarterServerSession({ once: true }));
+}
+
+/**
+ * The game services of a run whose guest sign-in failed at boot: they come
+ * up for the server player once `signIn` succeeds (in the background, or
+ * when a purchase or restore asks again), and never for the platform's local
+ * placeholder. Set the server session (`setStarterServerSession`) in a
+ * `signIn.onSignedIn` listener registered before this, so the services read it.
+ */
+export function createStarterSessionGatedGameServices(
+  input: Omit<StarterGameServicesInput, 'playerId'> & {
+    readonly signIn: StarterGuestSignIn;
+    /** Called once the services exist for the server player: run the game runtime's `reconcile()`. */
+    readonly onActivated?: () => void;
+  },
+): StarterGameServices {
+  const { signIn, onActivated, ...rest } = input;
+  return createSessionGatedGameServices({
+    // Configuration only (mode, target, whether a client exists); never sends a request.
+    probe: createRuntime({ ...rest, playerId: 'session-pending' }, undefined),
+    ensurePlayer: async () => (await signIn.ensure())?.playerId,
+    onPlayer: (listener) => signIn.onSignedIn((signedIn) => listener(signedIn.playerId)),
+    create: (playerId) => createStarterGameServices({ ...rest, playerId }),
+    ...(onActivated === undefined ? {} : { onActivated }),
+  });
+}
+
+function createRuntime(
+  input: StarterGameServicesInput,
+  session: ReturnType<typeof resolveStarterServerSession>,
+): GameServicesRuntime {
   return createGameServicesRuntime({
     gateway: input.gateway,
     playerId: input.playerId,