@mpgd/game-runtime 0.1.0 → 0.2.0

package/README.md

@@ -165,8 +165,8 @@ and rejects new registration, dispatch, emit, or setSnapshot calls. The final
 snapshot remains readable. Disposal, destruction, and unsubscribe are idempotent;
 late scoped commits still return `false` after bridge destruction.
 
-The UI subpath shares the private package's publication prerequisites. No Sampo
-changeset or generated-game dependency is added for this private-only extension.
+The UI subpath is part of the published package. Changes to its public contract
+or runtime behavior require a Sampo changeset for `@mpgd/game-runtime`.
 
 ## Platform lifecycle binding
 
@@ -285,21 +285,75 @@ restarting the process is outside this guarantee. Do not recreate it per screen
 to bypass unresolved work, and do not generate a new key for each UI retry.
 
 After `pending` or an invoked operation exception, new keys reject with
-`reconciliation-required`. The current client has no recovery/requery port, so this
-version deliberately provides no reset/retry/polling API. Integrate the existing
-provider/backend recovery policy outside these UI actions before starting a new
-application coordination session. Do not treat a retryable hint as permission to
-repurchase. Input/preflight scheduling rejections occur before the service call and
-do not invent a business outcome.
+`reconciliation-required`. Configure an optional `reconciliation` port to connect
+existing provider/backend recovery to this coordinator. `getPendingOperation()`
+returns its frozen invocation identity. `reconcile()` joins concurrent calls into
+one recovery query; it never calls `purchase` or `claimRewardedAd` again.
+The recovery adapter must not await `coordinator.reconcile()` itself: that joins
+the same in-flight query and creates a wait cycle.
+
+```ts
+const coordinator = createGameActionCoordinator({
+  execution,
+  client, // permanently bound to authenticatedPlayerId
+  reconciliation: {
+    playerId: authenticatedPlayerId,
+    async recover(operation) {
+      // Application port: query/recover the original operation using your existing
+      // authenticated backend and saved evidence. This is not a bundled HTTP API.
+      const transaction = await recoveryBackend.findCommittedGrant(operation);
+      if (!transaction || transaction.source === 'admin') return undefined;
+      return { operationId: operation.operationId, transaction };
+    },
+  },
+});
+const recovery = await coordinator.reconcile();
+if (recovery.status === 'reconciled') {
+  // Refresh authoritative entitlements. Do not grant locally from this notification.
+  await refreshEntitlements();
+}
+```
+
+The transaction shape is a structural subset of game-services
+`ProductGrantTransaction`: `playerId`, `source`, `grantId`, `idempotencyKey` and
+`ledgerEntryId`. The port is a trusted application integration boundary, like the
+operation client itself. It must return an authenticated, committed backend grant,
+not a platform callback or a receipt supplied by the UI. The coordinator checks
+player, local operation number, purchase/ad source, logical product/placement and
+original idempotency key before unlocking. It does not authenticate a server or
+verify receipt signatures itself. Keep the port and client bound to the same
+player and recreate the application runtime on account change; do not change a
+client's player behind an existing coordinator.
+
+`undefined` means still pending, a query error preserves the operation, and
+mismatched/malformed identity rejects with `invalid-reconciliation`. No port gives
+`reconciliation-unavailable`. With no unconfirmed operation, the result is
+`not-required`. Disposal or execution destruction prevents a late query result
+from being applied. Reconciliation owns no gameplay block.
+
+This first connection resolves **confirmed ledger grants only**. An empty lookup,
+a negative verification response, a timeout, cancellation or retryable provider
+hint cannot prove terminal non-grant and cannot unlock the coordinator. Such
+cases retain the conservative recovery requirement. There is no reset or automatic
+repurchase. This API does not add a recovery service or durable operation storage;
+those remain with the existing application/backend recovery policy.
+
+Successful reconciliation clears the unconfirmed operation but retains key
+history and the original Promise. That Promise still carries its original
+pending result/exception; controller snapshots and detached UI scopes are not
+rewritten by recovery. Use the reconciliation result to refresh the current UI.
+The same key never starts a second service call and `history-full` still applies.
+Input/preflight scheduling rejections occur before the service call and do not
+invent a business outcome.
 
 Packaging: `/actions` uses **type-only** imports from `@mpgd/game-services/operations`.
 The workspace dependency ensures declarations/build order; neither the basic
 runtime import nor actions import loads the service implementation, Phaser or DOM.
-Consumers use the repository-standard `skipLibCheck` for third-party typia
-ambient declarations; the headless consumer smoke supplies only ES2022 globals.
-This package remains private. Future publication requires initial npm registration,
-OIDC, and the game-services release containing `/operations` and progress options
-(planned 0.15.0). No generated game gains a dependency on this unpublished package.
+The headless consumer checks declarations with `skipLibCheck: false` and only
+ES2022 globals. The published service dependency supplies the `/operations` port
+and progress options without requiring DOM types. Changes to the public action
+contract or runtime behavior require a Sampo changeset for `@mpgd/game-runtime`.
+Generated games opt into this package explicitly.
 
 The owner that reserves an operation controls its pre-invocation startup permission.
 A reentrant same-key joiner cannot cancel that owner's startup by disposing itself.

package/dist/actions/index.d.ts

@@ -29,7 +29,7 @@ export type GameActionSnapshot<K extends GameActionKind> = Readonly<{
 })>;
 export type PurchaseActionSnapshot = GameActionSnapshot<'purchase'>;
 export type RewardedAdActionSnapshot = GameActionSnapshot<'rewarded-ad'>;
-export type GameActionErrorCode = 'disposed' | 'busy' | 'key-conflict' | 'already-completed' | 'reconciliation-required' | 'history-full' | 'invalid-input';
+export type GameActionErrorCode = 'disposed' | 'busy' | 'key-conflict' | 'already-completed' | 'reconciliation-required' | 'history-full' | 'invalid-input' | 'reconciliation-unavailable' | 'invalid-reconciliation';
 /** Scheduling/preflight rejection, distinct from a service result or external exception. */
 export declare class GameActionExecutionError extends Error {
   readonly code: GameActionErrorCode;
@@ -51,9 +51,50 @@ export interface GameActionController<K extends GameActionKind> extends GameActi
     event?(value: GameActionSnapshot<K>): E;
   }): GameActionView<K>;
 }
+/** Immutable invocation identity; no receipt, token or platform payload is retained. */
+type PendingOperation<K extends GameActionKind> = Readonly<{
+  kind: K;
+  operationId: number;
+  input: Inputs[K];
+}>;
+export type GameActionPendingOperation = PendingOperation<'purchase'> | PendingOperation<'rewarded-ad'>;
+/** Structural subset of game-services ProductGrantTransaction, returned by a trusted recovery port. */
+export interface GameActionRecoveredGrant {
+  readonly playerId: string;
+  readonly source: 'purchase' | 'ad_reward';
+  readonly grantId: string;
+  readonly idempotencyKey: string;
+  readonly ledgerEntryId: string;
+}
+export interface GameActionReconciliationPort {
+  /** Must identify the same fixed player as the operation client. Recreate on account change. */
+  readonly playerId: string;
+  /** Read/recover an authoritative committed ledger grant; never open purchase/ad UI here.
+  * Return undefined while no committed grant can be confirmed.
+  * Do not await coordinator.reconcile() here: it joins this query and would deadlock. */
+  recover(operation: GameActionPendingOperation & {
+    readonly playerId: string;
+  }): Promise<{
+    readonly operationId: number;
+    readonly transaction: GameActionRecoveredGrant;
+  } | undefined>;
+}
+export type GameActionReconciliationResult = Readonly<{
+  status: 'not-required';
+}> | Readonly<{
+  status: 'pending';
+  operation: GameActionPendingOperation;
+}> | Readonly<{
+  status: 'reconciled';
+  operation: GameActionPendingOperation;
+  ledgerEntryId: string;
+}>;
 export interface GameActionCoordinator {
   createPurchaseController(): GameActionController<'purchase'>;
   createRewardedAdController(): GameActionController<'rewarded-ad'>;
+  getPendingOperation(): GameActionPendingOperation | undefined;
+  /** Concurrent callers join one recovery query; only a matching committed grant unlocks new keys. */
+  reconcile(): Promise<GameActionReconciliationResult>;
   getAvailability(): 'ready' | 'busy' | 'reconciliation-required' | 'history-full' | 'disposed';
   /** Terminal for new calls; pending external work still settles and releases its own block. */
   dispose(): void;
@@ -64,6 +105,7 @@ export declare function createGameActionCoordinator(options: {
   readonly client: Pick<GameServicesOperationClient, 'purchase' | 'claimRewardedAd'>;
   /** Never evicts keys: once full, new keys are rejected until application teardown. Default 1024. */
   readonly maxRememberedKeys?: number;
+  readonly reconciliation?: GameActionReconciliationPort;
   readonly onObserverError?: ObserverErrorHandler;
 }): GameActionCoordinator;
 export declare function createPurchaseActionController(input: {

package/dist/actions/index.js

@@ -19,15 +19,22 @@ const purchaseSources = {
 export function createGameActionCoordinator(options) {
     const { execution, client, onObserverError } = options;
     const capacity = options.maxRememberedKeys ?? 1024;
+    const recoveryPlayerId = options.reconciliation?.playerId;
+    const recoveryPort = options.reconciliation;
+    if (recoveryPort && (typeof recoveryPlayerId !== 'string' || recoveryPlayerId.trim() === '' || typeof recoveryPort.recover !== 'function')) {
+        throw new GameActionExecutionError('invalid-input');
+    }
     if (!Number.isSafeInteger(capacity) || capacity < 1 || capacity > 10000) {
         throw new RangeError('maxRememberedKeys must be an integer from 1 to 10000.');
     }
+    const recover = recoveryPort?.recover.bind(recoveryPort);
     const history = new Map();
     let current;
     let last;
     let nextId = 0;
     let disposed = false;
-    let needsReconciliation = false;
+    let unconfirmed;
+    let recoveryFlight;
     function isDisposed() {
         return disposed || execution.getSnapshot().status === 'destroyed';
     }
@@ -65,7 +72,7 @@ export function createGameActionCoordinator(options) {
         if (prior !== undefined) {
             throw new GameActionExecutionError('already-completed');
         }
-        if (needsReconciliation) {
+        if (unconfirmed !== undefined) {
             throw new GameActionExecutionError('reconciliation-required');
         }
         if (current !== undefined) {
@@ -93,7 +100,7 @@ export function createGameActionCoordinator(options) {
         function finish(status) {
             flight.settled = true;
             if (invoked && (status === 'pending' || status === 'exception')) {
-                needsReconciliation = true;
+                unconfirmed = Object.freeze({ kind, operationId: id, input });
             }
             current = undefined;
             if (invoked) {
@@ -178,6 +185,54 @@ export function createGameActionCoordinator(options) {
         current = flight;
         return flight;
     }
+    function reconcile() {
+        if (isDisposed()) {
+            return Promise.reject(new GameActionExecutionError('disposed'));
+        }
+        if (recoveryFlight) {
+            return recoveryFlight;
+        }
+        const operation = unconfirmed;
+        if (!operation) {
+            return Promise.resolve(Object.freeze({ status: 'not-required' }));
+        }
+        if (!recover || recoveryPlayerId === undefined) {
+            return Promise.reject(new GameActionExecutionError('reconciliation-unavailable'));
+        }
+        // Queue invocation until the shared promise is installed, including reentrant port calls.
+        const work = Promise.resolve().then(async () => {
+            if (isDisposed()) {
+                throw new GameActionExecutionError('disposed');
+            }
+            const recovered = await recover(Object.freeze({ ...operation, playerId: recoveryPlayerId }));
+            if (isDisposed()) {
+                throw new GameActionExecutionError('disposed');
+            }
+            if (recovered === undefined) {
+                return Object.freeze({ status: 'pending', operation });
+            }
+            const transaction = recovered?.transaction;
+            const grantId = operation.kind === 'purchase' ? operation.input.productId : operation.input.placementId;
+            const source = operation.kind === 'purchase' ? 'purchase' : 'ad_reward';
+            if (!recovered || unconfirmed !== operation || recovered.operationId !== operation.operationId
+                || !transaction || transaction.playerId !== recoveryPlayerId || transaction.source !== source
+                || transaction.grantId !== grantId || transaction.idempotencyKey !== operation.input.idempotencyKey
+                || typeof transaction.ledgerEntryId !== 'string' || transaction.ledgerEntryId.trim() === '') {
+                throw new GameActionExecutionError('invalid-reconciliation');
+            }
+            const result = Object.freeze({ status: 'reconciled', operation, ledgerEntryId: transaction.ledgerEntryId });
+            // History and the original promise are retained: recovering never makes the same key executable again.
+            unconfirmed = undefined;
+            return result;
+        });
+        const joined = work.finally(() => {
+            if (recoveryFlight === joined) {
+                recoveryFlight = undefined;
+            }
+        });
+        void (recoveryFlight = joined);
+        return joined;
+    }
     function makeController(kind) {
         if (isDisposed()) {
             throw new GameActionExecutionError('disposed');
@@ -295,6 +350,8 @@ export function createGameActionCoordinator(options) {
     }
     return Object.freeze({
         createPurchaseController: () => makeController('purchase'),
+        getPendingOperation: () => unconfirmed,
+        reconcile,
         createRewardedAdController: () => makeController('rewarded-ad'),
         getAvailability() {
             if (isDisposed()) {
@@ -303,7 +360,7 @@ export function createGameActionCoordinator(options) {
             if (current !== undefined) {
                 return 'busy';
             }
-            if (needsReconciliation) {
+            if (unconfirmed !== undefined) {
                 return 'reconciliation-required';
             }
             return history.size >= capacity ? 'history-full' : 'ready';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-runtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Gameplay execution, scoped UI and action coordination with optional Phaser scene bindings.",
   "license": "MIT",
   "keywords": [