@diffenderfer-games/hub 2.0.0-next.1 → 2.0.0-next.10

package/src/core/connection.ts

@@ -1,36 +1,45 @@
 /**
  * The machinery under every `Hub` call: reaching the REST API, falling back
- * to the offline cache, queueing writes made offline and replaying them,
- * buffering analytics, warming the cache for every game, and reporting
- * online/offline/sync status (to `onStatus` listeners and as `hub:*` window
- * events, which the injected menu listens for).
+ * to the offline cache, queueing writes made offline in the outbox and
+ * replaying them, buffering analytics, warming the cache for every game, and
+ * reporting online/offline/sync status (to `onStatus` listeners and as
+ * `hub:*` window events, which the injected menu listens for).
  */
+import type { Json } from '@diffenderfer-games/hub-contract';
 import { HubError } from './errors';
+import { registerHubKinds, legacyOperation } from './offline/hub-kinds';
 import { LocalStore } from './offline/local-store';
-import type { QueueOp, QueueOpInput } from './offline/queue';
+import { OfflineApi } from './offline/offline-api';
+import { Outbox, type OfflineOp } from './offline/outbox';
+import { LocalResumeStore } from './resume/local-resume';
+import { LocalDailyStore } from './saved/local-saved';
 import { absoluteApiBase, detectApiBase, detectSlug, emitWindowEvent, isBrowserPage } from './page';
 import { createRestClient, type RestClient } from './rest/rest-client';
+import { createPageStore } from './storage/key-value';
 import type { HubOptions, HubStatus, SnapshotResponse } from './types';
 
 /** How long `prefetchAll()` waits between snapshots unless forced. */
 const PREFETCH_INTERVAL_MS = 30_000;
 
-/** A queued write the hub refused during a sync: dropped, with the hub's message. */
+/** A queued op the hub refused during a sync (or that kept failing): dropped, with the reason. */
 export interface SyncConflict {
-  /** The refused op. */
-  readonly op: QueueOp;
-  /** The hub's message. */
+  /** The dropped op. */
+  readonly op: OfflineOp;
+  /** The hub's (or the handler's) message. */
   readonly error?: string;
 }
 
 /** What one `sync()` did. */
 export interface SyncResult {
-  /** Queued writes the hub accepted. */
+  /** Queued ops that landed. */
   readonly flushed: number;
-  /** Queued writes the hub refused (and that were dropped). */
+  /** Queued ops that were dropped. */
   readonly conflicts: SyncConflict[];
 }
 
+/** A sync that did nothing. */
+const NOTHING_SYNCED: SyncResult = { flushed: 0, conflicts: [] };
+
 /** Whether a failure means "the hub can't be reached" (rather than a refusal). */
 // eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a call threw
 function isTransportFailure(failure: unknown): boolean {
@@ -51,12 +60,22 @@ export class HubConnection {
   readonly apiBase: string;
   /** Typed REST calls to {@link apiBase}. */
   protected readonly rest: RestClient;
-  /** This game's offline cache, queue and event buffer. */
+  /** This game's offline cache and event buffer. */
   protected readonly store: LocalStore;
+  /** This game's queued operations. */
+  protected readonly outbox: Outbox;
+  /** The device copies of every game's resume slot (`hub.resume`). */
+  protected readonly resumeStore: LocalResumeStore;
+  /** The device copies of daily challenges in progress (every game's). */
+  protected readonly dailyStore: LocalDailyStore;
   private readonly offlineMode: NonNullable<HubOptions['offline']>;
   private isReachable = true;
-  private isSyncing = false;
+  private runningSync: Promise<SyncResult> | null = null;
+  private followingSync: Promise<SyncResult> | null = null;
+  private isFollowingEager = false;
+  private directSend: Promise<Json | undefined> | null = null;
   private lastPrefetchAt = 0;
+  private offlineApi: OfflineApi | undefined;
   private readonly statusListeners = new Set<(status: HubStatus) => void>();
 
   /** A connection for `options` (slug and API base default to the page's). */
@@ -71,17 +90,43 @@ export class HubConnection {
         this.setReachable(true);
       },
     });
-    this.store = new LocalStore(this.slug ?? 'app');
+    const pageStore = createPageStore();
+    this.store = new LocalStore(this.slug ?? 'app', pageStore);
+    this.resumeStore = new LocalResumeStore(pageStore);
+    this.dailyStore = new LocalDailyStore(pageStore);
+    this.outbox = new Outbox({
+      slug: this.slug ?? 'app',
+      store: pageStore,
+      rest: this.rest,
+      emit: emitWindowEvent,
+      onUnreachable: () => {
+        this.setReachable(false);
+      },
+      onChange: () => {
+        this.notifyStatus();
+      },
+      onRetryDue: () => {
+        void this.retrySync();
+      },
+    });
+    registerHubKinds(this.outbox, {
+      game: () => this.gameFields(),
+      onDailyComplete: (payload, completion) => {
+        if (this.slug !== null) {
+          this.dailyStore.remove(this.slug, payload.day);
+        }
+        emitWindowEvent('hub:daily-complete', { day: payload.day, count: completion.count, rank: completion.rank, meta: payload.meta });
+      },
+      resume: this.resumeStore,
+      dailies: this.dailyStore,
+      cloudSaves: this.store,
+    });
+    this.importLegacyQueue();
     if (typeof navigator !== 'undefined' && 'onLine' in navigator) {
       this.isReachable = navigator.onLine;
     }
     if (isBrowserPage()) {
-      window.addEventListener('online', () => {
-        this.setReachable(true);
-      });
-      window.addEventListener('offline', () => {
-        this.setReachable(false);
-      });
+      this.listenToPage();
     }
   }
 
@@ -95,9 +140,25 @@ export class HubConnection {
     return this.isReachable;
   }
 
-  /** Queued writes plus buffered analytics events waiting to sync. */
+  /**
+   * The offline outbox: define your own kinds of operation, queue them, and
+   * hear how they replay (`hub.offline.define`, `enqueue`, `pending`, `on`).
+   */
+  get offline(): OfflineApi {
+    this.offlineApi ??= new OfflineApi({
+      outbox: this.outbox,
+      requestSync: () => {
+        if (!this.isOffline) {
+          void this.sync();
+        }
+      },
+    });
+    return this.offlineApi;
+  }
+
+  /** Queued operations plus buffered analytics events waiting to sync. */
   pending(): number {
-    return this.store.queueLength() + this.store.getEvents().length;
+    return this.outbox.count() + this.store.getEvents().length;
   }
 
   /** Subscribe to connection and sync status changes; returns the unsubscribe function. */
@@ -121,7 +182,7 @@ export class HubConnection {
     emitWindowEvent('hub:status', status);
   }
 
-  /** Record reachability; coming back online syncs the queue and re-warms the cache. */
+  /** Record reachability; coming back online replays the outbox and re-warms the cache. */
   protected setReachable(isReachableNow: boolean): void {
     if (isReachableNow === this.isReachable) {
       return;
@@ -130,8 +191,8 @@ export class HubConnection {
     emitWindowEvent(isReachableNow ? 'hub:online' : 'hub:offline', { pending: this.pending() });
     this.notifyStatus();
     if (isReachableNow) {
-      void this.sync();
-      void this.prefetchAll().catch(() => undefined);
+      // Replay first, so the snapshot that re-warms the cache already has the queued changes.
+      void this.replayAll(true).then(() => this.prefetchAll()).catch(() => undefined);
     }
   }
 
@@ -163,98 +224,105 @@ export class HubConnection {
     }
   }
 
-  /** Send one queued write. */
-  private async sendOp(op: QueueOpInput): Promise<void> {
-    const game = this.gameFields();
-    switch (op.kind) {
-      case 'putSave':
-        await this.rest.call('writeSave', { ...game, slot: op.slot, data: op.data, label: op.label });
-        return;
-      case 'deleteSave':
-        await this.rest.call('deleteSave', { ...game, slot: op.slot });
-        return;
-      case 'setStat':
-        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.value, mode: 'set' });
-        return;
-      case 'maxStat':
-        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.value, mode: 'max' });
-        return;
-      case 'incrStat':
-        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.amount, mode: 'incr' });
-        return;
-      case 'submitScore':
-        await this.rest.call('submitScore', { ...game, key: op.key, score: op.score, ...op.opts });
-        return;
-      case 'setProfile':
-        await this.rest.call('setGameProfile', { ...game, ...op.patch });
-        return;
-    }
-  }
-
   /**
-   * Apply a write to the offline cache at once, then send it now (online
-   * with an empty queue) or queue it behind the others. Resolves with the
-   * local answer; a real API error on the direct path reaches the caller and
-   * is not queued.
+   * Apply a write to the offline cache at once, then perform it as an op of
+   * `kind`: sent now when online with nothing waiting, else queued behind
+   * the others. Resolves with the local answer (or, sent now, with
+   * `replyAnswer`'s reading of the hub's reply). A real API error on the
+   * direct path reaches the caller and is not queued; a transport failure
+   * queues the op under the same id, so if the request did land, its replay
+   * is recognised by the hub and not applied twice.
    */
-  protected async mutateQueued<Reply>(input: QueueOpInput, localAnswer: () => Reply): Promise<Reply> {
+  protected async mutateOffline<Reply>(kind: string, payload: Json, localAnswer: () => Reply, replyAnswer?: (result: Json | undefined) => Reply | undefined): Promise<Reply> {
     const answer = localAnswer();
-    if (this.isOffline || this.store.queueLength() > 0) {
-      this.store.enqueue(input);
-      this.notifyStatus();
+    const op = this.outbox.stamp(kind, payload);
+    if (this.isOffline || this.outbox.count() > 0 || this.runningSync !== null || this.directSend !== null) {
+      this.outbox.add(op);
       if (!this.isOffline) {
         void this.sync();
       }
       return answer;
     }
+    const sending = this.outbox.runNow(op);
+    this.directSend = sending;
     try {
-      await this.sendOp(input);
-      return answer;
+      const result = await sending;
+      return replyAnswer?.(result) ?? answer;
     } catch (failure) {
       if (!isTransportFailure(failure)) {
         throw failure;
       }
       this.setReachable(false);
-      this.store.enqueue(input);
-      this.notifyStatus();
+      this.outbox.add({ ...op, attempts: 1 });
       return answer;
+    } finally {
+      if (this.directSend === sending) {
+        this.directSend = null;
+      }
     }
   }
 
   /**
-   * Replay the queue, then the buffered events, in order. Stops at the first
-   * transport failure (offline again: the rest stays queued); a write the hub
-   * refuses is dropped and reported as a conflict.
+   * Replay the outbox, then the buffered events, in order. Stops at the
+   * first transport failure (offline again: the rest stays queued); an op
+   * the hub refuses is dropped and reported as a conflict.
+   */
+  sync(): Promise<SyncResult> {
+    return this.isOffline ? Promise.resolve(NOTHING_SYNCED) : this.replayAll(false);
+  }
+
+  /** A retry came due: try again even when the hub was last unreachable (the try is the probe), unless the browser itself is offline. */
+  private retrySync(): Promise<SyncResult> {
+    const isBrowserOffline = typeof navigator !== 'undefined' && 'onLine' in navigator && !navigator.onLine;
+    return this.offlineMode === 'always' || isBrowserOffline ? Promise.resolve(NOTHING_SYNCED) : this.replayAll(false);
+  }
+
+  /**
+   * One replay at a time per client. A call during one queues a single
+   * follow-up replay (eager if any caller asked for that), so an op queued
+   * or a reconnect that happens mid-replay is never missed.
    */
-  async sync(): Promise<SyncResult> {
-    if (this.isSyncing || this.isOffline || this.slug === null) {
-      return { flushed: 0, conflicts: [] };
+  private replayAll(isEager: boolean): Promise<SyncResult> {
+    if (this.slug === null || this.offlineMode === 'always') {
+      return Promise.resolve(NOTHING_SYNCED);
     }
-    this.isSyncing = true;
-    let flushed = 0;
-    const conflicts: SyncConflict[] = [];
-    try {
-      let queue = this.store.getQueue();
-      for (let op = queue[0]; op !== undefined; op = queue[0]) {
-        try {
-          await this.sendOp(op);
-          flushed += 1;
-        } catch (failure) {
-          if (isTransportFailure(failure)) {
-            break;
-          }
-          conflicts.push({ op, error: failure instanceof Error ? failure.message : String(failure) });
-        }
-        queue = queue.slice(1);
-        this.store.setQueue(queue);
+    const running = this.runningSync;
+    if (running === null) {
+      return this.startReplay(isEager);
+    }
+    this.isFollowingEager ||= isEager;
+    this.followingSync ??= running.catch(() => NOTHING_SYNCED).then(() => {
+      const isFollowUpEager = this.isFollowingEager;
+      this.isFollowingEager = false;
+      this.followingSync = null;
+      return this.startReplay(isFollowUpEager);
+    });
+    return this.followingSync;
+  }
+
+  private startReplay(isEager: boolean): Promise<SyncResult> {
+    const run = this.runReplay(isEager).finally(() => {
+      if (this.runningSync === run) {
+        this.runningSync = null;
       }
+    });
+    this.runningSync = run;
+    return run;
+  }
+
+  private async runReplay(isEager: boolean): Promise<SyncResult> {
+    if (this.directSend !== null) {
+      await this.directSend.catch(() => undefined);
+    }
+    const report = await this.outbox.replay(isEager);
+    const conflicts = report.failed.map((failure) => ({ op: failure.entry, error: failure.error }));
+    if (report.stoppedBy !== 'connection') {
       await this.flushEvents();
-    } finally {
-      this.isSyncing = false;
     }
-    emitWindowEvent('hub:sync', { pending: this.pending(), flushed, conflicts });
+    const result: SyncResult = { flushed: report.replayed.length, conflicts };
+    emitWindowEvent('hub:sync', { pending: this.pending(), ...result });
     this.notifyStatus();
-    return { flushed, conflicts };
+    return result;
   }
 
   /** Send the buffered analytics events; a refused one is dropped (telemetry never blocks). */
@@ -273,6 +341,43 @@ export class HubConnection {
     }
   }
 
+  /** Move a v1 copy's queued writes into the outbox, in their order. */
+  private importLegacyQueue(): void {
+    if (this.slug === null) {
+      return;
+    }
+    try {
+      for (const legacy of this.store.takeLegacyQueue()) {
+        const operation = legacyOperation(legacy);
+        if (operation !== undefined) {
+          this.outbox.add(this.outbox.stamp(operation.kind, operation.payload));
+        }
+      }
+    } catch {
+      // A full outbox keeps what fitted; the client must still start.
+    }
+  }
+
+  /** Follow the browser's connection, other tabs' outbox changes, and replay what an earlier page left queued. */
+  private listenToPage(): void {
+    window.addEventListener('online', () => {
+      this.setReachable(true);
+    });
+    window.addEventListener('offline', () => {
+      this.setReachable(false);
+    });
+    window.addEventListener('storage', (event) => {
+      if (event instanceof StorageEvent && this.outbox.entries.owns(event.key)) {
+        this.notifyStatus();
+      }
+    });
+    if (this.outbox.count() > 0) {
+      setTimeout(() => {
+        void this.sync();
+      }, 0);
+    }
+  }
+
   /**
    * Warm the offline cache for every game the player has touched, in one
    * request, so going offline later still shows complete progress.
@@ -292,6 +397,10 @@ export class HubConnection {
       throw failure;
     }
     this.lastPrefetchAt = Date.now();
+    if (this.outbox.count() > 0) {
+      // Changes are still waiting to sync: the cache already holds them, and the snapshot doesn't yet.
+      return snapshot;
+    }
     this.store.hydrate(snapshot);
     emitWindowEvent('hub:prefetch', { games: Object.keys(snapshot.games).length });
     return snapshot;

package/src/core/errors.ts

@@ -15,12 +15,19 @@ export const UNSUPPORTED_BY_HUB = 'unsupported_by_hub';
 /** The code the social runtime gives a call it could not send (no connection). */
 export const OFFLINE_CODE = 'offline';
 
+/**
+ * The code `getSave` rejects with when the hub can't be reached and this
+ * device has no copy of the slot it can trust (a fresh device or cleared
+ * browser): the slot may well hold a save, so it is not reported empty.
+ */
+export const SAVE_UNKNOWN_CODE = 'save_unknown';
+
 /**
  * A machine-readable error code: one of the contract's public codes
  * (`content_rejected`, `rate_limited`, `suspended`, `claim_required`, ...),
  * {@link UNSUPPORTED_BY_HUB}, or a code a newer hub added.
  */
-export type HubErrorCode = ErrorCode | typeof UNSUPPORTED_BY_HUB | typeof OFFLINE_CODE | (string & Record<never, never>);
+export type HubErrorCode = ErrorCode | typeof UNSUPPORTED_BY_HUB | typeof OFFLINE_CODE | typeof SAVE_UNKNOWN_CODE | (string & Record<never, never>);
 
 /** The machine-readable extras the hub attaches to an error body. */
 export interface HubErrorDetails {
@@ -34,6 +41,8 @@ export interface HubErrorDetails {
   readonly retryAfterMs?: number | undefined;
   /** When a suspension or mute ends (epoch ms). */
   readonly until?: number | undefined;
+  /** An online game's rules refused a move (`illegal`): the rules' own short code. */
+  readonly rule?: string | undefined;
 }
 
 /**
@@ -55,6 +64,8 @@ export class HubError extends Error {
   readonly retryAfterMs: number | undefined;
   /** When a suspension or mute ends (epoch ms). */
   readonly until: number | undefined;
+  /** An online game's rules refused a move (`code` is `illegal`): the rules' own short code, such as `cell_taken`. */
+  readonly rule: string | undefined;
 
   /** An error with a player-safe `message`, the HTTP `status` (if any) and the body's extras. */
   constructor(message: string, status?: number, details: HubErrorDetails = {}) {
@@ -66,6 +77,7 @@ export class HubError extends Error {
     this.hint = details.hint;
     this.retryAfterMs = details.retryAfterMs;
     this.until = details.until;
+    this.rule = details.rule;
   }
 
   /** `true` when the failure was a network or transport error, not an HTTP status. */
@@ -115,12 +127,13 @@ export function readErrorFields(body: unknown): ErrorBodyFields {
     hint: optionalString(body.hint),
     retryAfterMs: optionalNumber(body.retryAfterMs),
     until: optionalNumber(body.until),
+    rule: optionalString(body.rule),
   };
 }
 
 /** The right error class for a failure: a 422 or `content_rejected` is a {@link ContentRejectedError}. */
 export function errorFor(message: string, status: number | undefined, details: HubErrorDetails): HubError {
-  return status === 422 || details.code === 'content_rejected'
+  return (status === 422 && details.code !== 'illegal') || details.code === 'content_rejected'
     ? new ContentRejectedError(message, status, details)
     : new HubError(message, status, details);
 }

package/src/core/game-data.ts

@@ -6,26 +6,28 @@
  * v1 client. These two functions are the only places that hand-over happens.
  */
 import type { Json } from '@diffenderfer-games/hub-contract';
+import { isJson, parseJsonText } from './storage/json-guards';
 
 /** Anything a game may store as JSON: an object (interfaces included), an array, text, a number, a boolean or `null`. */
 export type GamePayload = object | string | number | boolean | null;
 
-/** Always true: a game's payload is sent as JSON (`JSON.stringify` drops what JSON can't hold). */
-function isSentAsJson(_payload: GamePayload): _payload is GamePayload & Json {
-  return true;
-}
-
 /** Always true: JSON the game stored is read back as the game's type. */
 function isGameOwnData<TData>(_stored: Json): _stored is Json & TData {
   return true;
 }
 
-/** A game's payload as the JSON the hub stores. */
+/**
+ * A game's payload as the JSON the hub stores: a copy of exactly what
+ * `JSON.stringify` sends, so an optional field left `undefined` is simply
+ * absent (as on the wire) and the outbox's payload checks accept it, and a
+ * later change to the game's object can't alter a queued write.
+ */
 export function toStoredJson(payload: GamePayload): Json {
-  if (isSentAsJson(payload)) {
-    return payload;
+  const stored = parseJsonText(JSON.stringify(payload));
+  if (isJson(stored)) {
+    return stored;
   }
-  throw new TypeError('unreachable: every payload is sent as JSON');
+  throw new TypeError('This value cannot be stored as JSON.');
 }
 
 /** JSON the game stored, typed as the game's own type. */

package/src/core/hub-economy.ts

@@ -4,9 +4,13 @@
  * offline they are buffered and sent when the hub is back. Method names are
  * the v1 client's, unchanged.
  */
+import type { Json } from '@diffenderfer-games/hub-contract';
 import { HubProgress } from './hub-progress';
 import { readLocalFavorites, writeLocalFavorites } from './offline/favorites';
+import { ECONOMY_KINDS, type ExchangePayload } from './offline/hub-kinds';
+import { readInventory, withGoods, withoutGoods, type GoodsPayload } from './offline/local-inventory';
 import { HubError } from './errors';
+import { isRecord, stringsIn } from './storage/json-guards';
 import type { EndpointFields, EndpointReply } from './rest/endpoint-types';
 import type { GameAnalytics, GameInfo, GlobalAnalytics, InventorySnapshot } from './types';
 
@@ -25,6 +29,18 @@ export interface TradeNoteOptions {
   readonly note?: string;
 }
 
+/** Goods as queued: `null` parts left out. */
+function goodsOf(bundle: TradeBundle | GrantBundle | undefined): GoodsPayload {
+  const items = bundle?.items ?? undefined;
+  const coins = bundle?.coins ?? undefined;
+  return { ...(items === undefined ? {} : { items }), ...(coins === undefined ? {} : { coins }) };
+}
+
+/** The holdings in a grant or exchange reply, or `undefined` when it doesn't read as one. */
+function inventoryReply(result: Json | undefined): InventorySnapshot | undefined {
+  return readInventory(result) ?? undefined;
+}
+
 /** Which trades `listTrades` lists. */
 export type TradeListOptions = Omit<EndpointFields<'listMyTrades'>, 'slug'>;
 
@@ -92,11 +108,14 @@ export class HubEconomy extends HubProgress {
     }, () => ({ games: readLocalFavorites() }));
   }
 
-  /** Star (`isOn = true`) or unstar a game. Needs a connection. */
-  async setFavorite(slug: string, isOn: boolean): Promise<{ games: string[] }> {
-    const reply = await this.rest.call('setGameFavorite', { slug, on: isOn });
-    writeLocalFavorites(reply.games);
-    return reply;
+  /** Star (`isOn = true`) or unstar a game. Offline, the local list changes at once and the hub's when it is back. */
+  setFavorite(slug: string, isOn: boolean): Promise<{ games: string[] }> {
+    return this.mutateOffline(ECONOMY_KINDS.favorite, { slug, on: isOn }, () => {
+      const others = readLocalFavorites().filter((starred) => starred !== slug);
+      const games = isOn ? [...others, slug] : others;
+      writeLocalFavorites(games);
+      return { games };
+    }, (result) => (isRecord(result) ? { games: stringsIn(result.games) } : undefined));
   }
 
   /** The player's leaderboard standings, grouped by game (every game, or one via `forSlug`). Empty offline or signed out. */
@@ -109,7 +128,7 @@ export class HubEconomy extends HubProgress {
 
   /** This game's inventory and coin balance for the current user. */
   getInventory(): Promise<InventorySnapshot> {
-    return this.withFallback(() => this.rest.call('getMyInventory', this.gameFields()), () => ({ items: [], coins: 0 }));
+    return this.withFallback(async () => this.store.setInventory(await this.rest.call('getMyInventory', this.gameFields())), () => this.store.getInventory());
   }
 
   /** Another player's available holdings (to compose a trade). */
@@ -117,14 +136,32 @@ export class HubEconomy extends HubProgress {
     return this.withFallback(() => this.rest.call('getPlayerInventory', { ...this.gameFields(), userId }), () => ({ items: [], coins: 0 }));
   }
 
-  /** Add goods to the player (gameplay rewards); answers the new holdings. */
+  /**
+   * Add goods to the player (gameplay rewards); answers the new holdings.
+   * Offline, the cached holdings change at once and the grant replays later.
+   */
   grant(bundle: GrantBundle): Promise<EndpointReply<'grantInventoryItems'>> {
-    return this.rest.call('grantInventoryItems', { ...this.gameFields(), ...bundle });
+    const goods = goodsOf(bundle);
+    return this.mutateOffline(ECONOMY_KINDS.grant, goods, () => this.store.setInventory(withGoods(this.store.getInventory(), goods)), inventoryReply);
   }
 
-  /** An atomic swap with the house: remove `take`, add `give`. */
+  /**
+   * An atomic swap with the house: remove `take`, add `give`. Offline it is
+   * checked against the cached holdings (409 when they can't cover `take`),
+   * applied to them at once, and replayed later; the hub has the last word.
+   */
   exchange(take?: TradeBundle, give?: TradeBundle): Promise<EndpointReply<'exchangeInventoryItems'>> {
-    return this.rest.call('exchangeInventoryItems', { ...this.gameFields(), ...(take === undefined ? {} : { take }), ...(give === undefined ? {} : { give }) });
+    const payload: ExchangePayload = { ...(take === undefined ? {} : { take: goodsOf(take) }), ...(give === undefined ? {} : { give: goodsOf(give) }) };
+    return this.mutateOffline(ECONOMY_KINDS.exchange, payload, () => {
+      const remaining = withoutGoods(this.store.getInventory(), payload.take ?? {});
+      if (typeof remaining === 'string') {
+        if (this.isOffline) {
+          throw new HubError(remaining, 409);
+        }
+        return this.store.getInventory();
+      }
+      return this.store.setInventory(withGoods(remaining, payload.give ?? {}));
+    }, inventoryReply);
   }
 
   /** Sell items to the house for coins. */