@stamprally/core 0.17.0 → 0.18.0

package/README.md

@@ -1,4 +1,4 @@
-# @stamprally/core v0.17.0
+# @stamprally/core v0.18.0
 
 Dependency-free domain models, immutable state transitions, storage adapters, browser detectors, and safe configuration parsers.
 
@@ -7,7 +7,7 @@ import { InMemoryStorage, StampRallyClient, type PublicRallyConfig } from "@stam
 
 const config: PublicRallyConfig = {
   id: "city-tour",
-  version: "0.17.0",
+  version: "0.18.0",
   title: "City Tour",
   spots: [{ id: "station", orderIndex: 0, name: "Central Station", conditions: [{ type: "passcode" }] }],
   rewards: [],

package/dist/index.cjs

@@ -110,78 +110,20 @@ function issueClaimTicketNumber(reward2, currentState, options = {}) {
 }
 
 // src/engine/sync.ts
-function latestTimestamp(serverTimestamp, localTimestamp) {
-  const serverTime = Date.parse(serverTimestamp);
-  const localTime = Date.parse(localTimestamp);
-  if (!Number.isNaN(serverTime) && !Number.isNaN(localTime))
-    return serverTime >= localTime ? serverTimestamp : localTimestamp;
-  if (!Number.isNaN(serverTime)) return serverTimestamp;
-  if (!Number.isNaN(localTime)) return localTimestamp;
-  return serverTimestamp >= localTimestamp ? serverTimestamp : localTimestamp;
-}
-function mergeRewardStates(serverRewards, localRewards) {
-  const merged = new Map(serverRewards.map((reward2) => [reward2.rewardId, reward2]));
-  for (const localReward of localRewards) {
-    const serverReward = merged.get(localReward.rewardId);
-    if (serverReward === void 0) {
-      merged.set(localReward.rewardId, localReward);
-      continue;
-    }
-    const winner = localReward.status === "CONSUMED" && serverReward.status !== "CONSUMED" ? localReward : serverReward;
-    merged.set(localReward.rewardId, {
-      ...winner,
-      ...serverReward.unlockedAt === void 0 && localReward.unlockedAt === void 0 ? {} : {
-        unlockedAt: serverReward.unlockedAt === void 0 ? localReward.unlockedAt : localReward.unlockedAt === void 0 ? serverReward.unlockedAt : latestTimestamp(serverReward.unlockedAt, localReward.unlockedAt)
-      },
-      ...serverReward.consumedAt === void 0 && localReward.consumedAt === void 0 ? {} : {
-        consumedAt: serverReward.consumedAt === void 0 ? localReward.consumedAt : localReward.consumedAt === void 0 ? serverReward.consumedAt : latestTimestamp(serverReward.consumedAt, localReward.consumedAt)
-      },
-      ...serverReward.redeemedCount === void 0 && localReward.redeemedCount === void 0 ? {} : {
-        redeemedCount: Math.max(
-          serverReward.redeemedCount ?? 0,
-          localReward.redeemedCount ?? 0
-        )
-      },
-      ...serverReward.userRedemptionCount === void 0 && localReward.userRedemptionCount === void 0 ? {} : {
-        userRedemptionCount: Math.max(
-          serverReward.userRedemptionCount ?? 0,
-          localReward.userRedemptionCount ?? 0
-        )
-      }
-    });
-  }
-  return [...merged.values()];
-}
-function mergeStampRecords(serverRecords, localRecords) {
-  const merged = /* @__PURE__ */ new Map();
-  for (const record of [...serverRecords, ...localRecords]) {
-    const current = merged.get(record.stampId);
-    if (current === void 0) {
-      merged.set(record.stampId, record);
-      continue;
-    }
-    const acquiredAt = latestTimestamp(current.acquiredAt, record.acquiredAt);
-    merged.set(record.stampId, {
-      ...current,
-      ...acquiredAt === current.acquiredAt ? {} : { acquiredAt },
-      ...current.metadata === void 0 && record.metadata !== void 0 ? { metadata: record.metadata } : {}
-    });
-  }
-  return [...merged.values()];
-}
-function resolveRallyStateConflict(serverState, localState, options = { policy: "merge" }) {
-  if (options.policy === "server_wins") return serverState;
-  if (options.policy === "authoritative_replay")
-    return {
-      ...serverState,
-      records: serverState.records.map((record) => ({ ...record })),
-      rewards: serverState.rewards.map((reward2) => ({ ...reward2 }))
-    };
+function resolveRallyStateConflict(serverState, _localState) {
   return {
     ...serverState,
-    records: mergeStampRecords(serverState.records, localState.records),
-    rewards: mergeRewardStates(serverState.rewards, localState.rewards),
-    updatedAt: latestTimestamp(serverState.updatedAt, localState.updatedAt)
+    records: serverState.records.map((record) => ({
+      ...record,
+      ...record.metadata === void 0 ? {} : { metadata: { ...record.metadata } }
+    })),
+    rewards: serverState.rewards.map((reward2) => ({ ...reward2 })),
+    ...serverState.inventory === void 0 ? {} : {
+      inventory: {
+        ...serverState.inventory,
+        ...serverState.inventory.rewardRemaining === void 0 ? {} : { rewardRemaining: { ...serverState.inventory.rewardRemaining } }
+      }
+    }
   };
 }
 
@@ -1274,8 +1216,6 @@ var OfflineQueue = class {
   #configuredKey;
   #rallyId;
   #userId;
-  #conflictPolicy;
-  #onSyncConflict;
   #operations = [];
   #rejectedHistory = [];
   #loaded = false;
@@ -1291,6 +1231,8 @@ var OfflineQueue = class {
   #lockStorage;
   #observedLocks = /* @__PURE__ */ new Map();
   #warnedMemoryLock = false;
+  #capabilityWarningListener;
+  #replayConfig;
   #storageListener;
   #channel = null;
   constructor(options = {}) {
@@ -1308,8 +1250,6 @@ var OfflineQueue = class {
     this.#configuredKey = options.key;
     this.#rallyId = options.rallyId;
     this.#userId = options.userId ?? null;
-    this.#conflictPolicy = options.conflictPolicy ?? "authoritative_replay";
-    this.#onSyncConflict = options.onSyncConflict;
     this.#synchronizeInstances = options.synchronizeInstances ?? true;
     const retryOptions = {
       ...DEFAULT_RETRY_OPTIONS,
@@ -1332,6 +1272,14 @@ var OfflineQueue = class {
   get queueCapability() {
     return this.#queueCapability;
   }
+  get storageCapability() {
+    if (this.#queueCapability === "memory") return "memory";
+    const locks = globalThis.navigator?.locks;
+    return locks !== void 0 || this.#lockStorage !== null ? this.#queueCapability : "volatile_single_tab";
+  }
+  get isStoragePersistent() {
+    return this.#queueCapability !== "memory";
+  }
   get rejectedHistory() {
     return this.#rejectedHistory;
   }
@@ -1341,9 +1289,6 @@ var OfflineQueue = class {
   get operations() {
     return this.#operations;
   }
-  get conflictPolicy() {
-    return this.#conflictPolicy;
-  }
   get storageKey() {
     return this.#storageKey();
   }
@@ -1359,6 +1304,12 @@ var OfflineQueue = class {
   setChangeListener(listener) {
     this.#changeListener = listener;
   }
+  setCapabilityWarningListener(listener) {
+    this.#capabilityWarningListener = listener;
+  }
+  setReplayConfig(config) {
+    this.#replayConfig = config;
+  }
   async initialize() {
     if (this.#loaded) return;
     try {
@@ -1375,6 +1326,8 @@ var OfflineQueue = class {
         `Offline queue persistence is unavailable; queued data can be lost after reload (${String(error)}).`
       );
     }
+    if (this.#queueCapability === "memory")
+      this.#warnMemoryLock("Offline queue persistence is unavailable; queued data is memory-only.");
     this.#loaded = true;
   }
   /** Releases browser listeners when the queue is no longer used. */
@@ -1423,11 +1376,19 @@ var OfflineQueue = class {
     await this.#storage.save(this.#storageKey(), this.#operations);
     this.#announceChange();
   }
-  async enqueueCheckIn(request) {
-    return this.enqueue({ kind: "checkIn", request });
+  async enqueueCheckIn(request, optimisticState) {
+    return this.enqueue({
+      kind: "checkIn",
+      request,
+      ...optimisticState === void 0 ? {} : { optimisticState }
+    });
   }
-  async enqueueClaimReward(request) {
-    return this.enqueue({ kind: "claimReward", request });
+  async enqueueClaimReward(request, optimisticState) {
+    return this.enqueue({
+      kind: "claimReward",
+      request,
+      ...optimisticState === void 0 ? {} : { optimisticState }
+    });
   }
   async clear() {
     await this.initialize();
@@ -1435,10 +1396,10 @@ var OfflineQueue = class {
     await this.#storage.save(this.#storageKey(), this.#operations);
     this.#announceChange();
   }
-  async discardRejected(operationId) {
+  async discardRejected(operationId2) {
     await this.initialize();
     const next = this.#rejectedHistory.filter(
-      (entry) => offlineOperationId(entry.operation) !== operationId
+      (entry) => offlineOperationId(entry.operation) !== operationId2
     );
     if (next.length === this.#rejectedHistory.length) return false;
     this.#rejectedHistory = next;
@@ -1446,13 +1407,13 @@ var OfflineQueue = class {
     this.#announceChange();
     return true;
   }
-  async retryRejected(operationId) {
+  async retryRejected(operationId2) {
     await this.initialize();
     const entry = this.#rejectedHistory.find(
-      (candidate) => offlineOperationId(candidate.operation) === operationId
+      (candidate) => offlineOperationId(candidate.operation) === operationId2
     );
     if (entry === void 0) return false;
-    if (!this.#operations.some((operation) => offlineOperationId(operation) === operationId))
+    if (!this.#operations.some((operation) => offlineOperationId(operation) === operationId2))
       this.#operations = [
         ...this.#operations,
         { ...entry.operation, status: "PENDING", attempts: 0 }
@@ -1463,11 +1424,11 @@ var OfflineQueue = class {
     this.#announceChange();
     return true;
   }
-  async discardRejectedOperation(operationId) {
-    return this.discardRejected(operationId);
+  async discardRejectedOperation(operationId2) {
+    return this.discardRejected(operationId2);
   }
-  async retryRejectedOperation(operationId) {
-    return this.retryRejected(operationId);
+  async retryRejectedOperation(operationId2) {
+    return this.retryRejected(operationId2);
   }
   async clearRejectedHistory() {
     await this.initialize();
@@ -1515,7 +1476,7 @@ var OfflineQueue = class {
         if (callbackStarted) throw error;
       }
     }
-    if (this.#lockStorage === null)
+    if (this.storageCapability === "volatile_single_tab")
       this.#warnMemoryLock(
         "No cross-tab storage lock is available; offline sync is single-tab only."
       );
@@ -1535,6 +1496,7 @@ var OfflineQueue = class {
       while (this.#operations.length > 0) {
         const operation = this.#operations[0];
         if (operation === void 0) break;
+        if (await this.#rejectFailedPrerequisite(operation)) continue;
         let attempt = 0;
         let response;
         while (true) {
@@ -1612,6 +1574,44 @@ var OfflineQueue = class {
     await this.#storage.save(this.#storageKey(), this.#operations);
     this.#announceChange();
   }
+  async #rejectFailedPrerequisite(operation) {
+    if (operation.kind !== "checkIn" || this.#replayConfig === void 0) return false;
+    const spot2 = this.#replayConfig.spots.find(
+      (candidate) => candidate.id === operation.request.spotId
+    );
+    if (spot2 === void 0) return false;
+    const failedSpots = new Set(
+      this.#rejectedHistory.filter((entry) => entry.operation.kind === "checkIn").map(
+        (entry) => entry.operation.kind === "checkIn" ? entry.operation.request.spotId : void 0
+      ).filter((spotId) => spotId !== void 0)
+    );
+    if (!spot2.prerequisites?.some((prerequisite) => failedSpots.has(prerequisite))) return false;
+    const error = {
+      code: "REJECTED_PREREQUISITE_FAILED",
+      message: "A prerequisite operation was rejected by the server."
+    };
+    const rejectedOperation = { ...operation, status: "REJECTED_PERMANENT" };
+    this.#rejectedHistory = [
+      ...this.#rejectedHistory,
+      {
+        operation: rejectedOperation,
+        reason: error,
+        errorCode: error.code,
+        rejectedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        attempts: operation.attempts ?? 0
+      }
+    ];
+    this.#operations = this.#operations.slice(1);
+    await this.#storage.save(this.#storageKey(), this.#operations);
+    await this.#saveRejectedHistory();
+    this.#announceChange();
+    await this.#syncResultListener?.({
+      operation,
+      status: "REJECTED_PERMANENT",
+      error
+    });
+    return true;
+  }
   #subscribeToExternalChanges() {
     const windowLike = globalThis.window;
     if (windowLike !== void 0) {
@@ -1736,11 +1736,6 @@ var OfflineQueue = class {
     }
     return { status: "ACCEPTED", result: value };
   }
-  async resolveConflict(operation, localState, serverState) {
-    const configured = this.#onSyncConflict;
-    const policy = (typeof configured === "function" ? await configured({ operation, localState, serverState }) : configured) ?? this.#conflictPolicy;
-    return resolveRallyStateConflict(serverState, localState, { policy });
-  }
   async #saveRejectedHistory() {
     await this.#storage.saveRejectedHistory?.(this.#storageKey(), this.#rejectedHistory);
   }
@@ -1748,6 +1743,12 @@ var OfflineQueue = class {
     if (this.#warnedMemoryLock) return;
     this.#warnedMemoryLock = true;
     console.warn(`[@stamprally/core] ${message}`);
+    this.#capabilityWarningListener?.({
+      type: "STORAGE_CAPABILITY_WARNING",
+      storageCapability: this.storageCapability === "memory" ? "memory" : "volatile_single_tab",
+      isStoragePersistent: this.isStoragePersistent,
+      message
+    });
   }
 };
 function normalizeOperation(operation) {
@@ -1769,6 +1770,100 @@ function normalizeRejectedHistory(entry) {
   };
 }
 
+// src/client/sync.ts
+function isReplayable(operation) {
+  return operation.status === void 0 || operation.status === "ACCEPTED" || operation.status === "PENDING" || operation.status === "IN_FLIGHT" || operation.status === "FAILED_RETRYABLE";
+}
+function operationId(operation) {
+  const identity = operation.request.userId ?? operation.request.anonymousSessionId ?? "anonymous";
+  return `${operation.kind}:${operation.request.rallyId}:${identity}:${operation.request.idempotencyKey}`;
+}
+function applyInventoryDelta(state, previous, optimistic) {
+  const previousInventory = previous.inventory;
+  const optimisticInventory = optimistic.inventory;
+  if (previousInventory === void 0 || optimisticInventory === void 0) return state;
+  const currentInventory = state.inventory ?? {};
+  const sharedDelta = previousInventory.sharedRemaining === void 0 || optimisticInventory.sharedRemaining === void 0 ? void 0 : optimisticInventory.sharedRemaining - previousInventory.sharedRemaining;
+  const previousRewards = previousInventory.rewardRemaining ?? {};
+  const optimisticRewards = optimisticInventory.rewardRemaining ?? {};
+  const currentRewards = currentInventory.rewardRemaining ?? {};
+  const rewardRemaining = { ...currentRewards };
+  for (const key of /* @__PURE__ */ new Set([...Object.keys(previousRewards), ...Object.keys(optimisticRewards)])) {
+    const before = previousRewards[key];
+    const after = optimisticRewards[key];
+    if (before !== void 0 && after !== void 0)
+      rewardRemaining[key] = Math.max(0, (currentRewards[key] ?? before) + after - before);
+  }
+  return {
+    ...state,
+    inventory: {
+      ...currentInventory.sharedRemaining === void 0 || sharedDelta === void 0 ? {} : { sharedRemaining: Math.max(0, currentInventory.sharedRemaining + sharedDelta) },
+      ...Object.keys(rewardRemaining).length === 0 ? {} : { rewardRemaining }
+    }
+  };
+}
+function applyOperation(state, operation, config) {
+  if (operation.kind === "checkIn") {
+    const spot2 = config?.spots.find((candidate) => candidate.id === operation.request.spotId);
+    if (spot2?.prerequisites?.some((id2) => !state.records.some((record2) => record2.stampId === id2)))
+      return { state, prerequisiteFailed: true };
+    if (state.records.some((record2) => record2.stampId === operation.request.spotId))
+      return { state, prerequisiteFailed: false };
+    const optimisticRecord = operation.optimisticState?.records.find(
+      (record2) => record2.stampId === operation.request.spotId
+    );
+    const record = optimisticRecord ?? {
+      stampId: operation.request.spotId,
+      acquiredAt: operation.request.now
+    };
+    const records = [...state.records, { ...record }];
+    const rewards2 = config === void 0 ? state.rewards : reconcileRewardStates(config.rewards, state.rewards, records.length, record.acquiredAt);
+    return {
+      state: { ...state, records, rewards: rewards2, updatedAt: record.acquiredAt },
+      prerequisiteFailed: false
+    };
+  }
+  const optimisticState = operation.optimisticState;
+  if (optimisticState === void 0) return { state, prerequisiteFailed: false };
+  const optimisticReward = optimisticState?.rewards.find(
+    (reward2) => reward2.rewardId === operation.request.rewardId
+  );
+  if (optimisticReward === void 0) return { state, prerequisiteFailed: false };
+  const rewards = state.rewards.some((reward2) => reward2.rewardId === optimisticReward.rewardId) ? state.rewards.map(
+    (reward2) => reward2.rewardId === optimisticReward.rewardId ? { ...optimisticReward } : reward2
+  ) : [...state.rewards, { ...optimisticReward }];
+  return {
+    state: applyInventoryDelta(
+      { ...state, rewards, updatedAt: optimisticReward.consumedAt ?? state.updatedAt },
+      operation.request.state,
+      optimisticState
+    ),
+    prerequisiteFailed: false
+  };
+}
+function rebuildUserStateFromLog(baselineOrOptions, operationsArgument, configArgument) {
+  const { state } = rebuildUserStateLog(
+    "baseline" in baselineOrOptions ? baselineOrOptions.baseline : baselineOrOptions,
+    "baseline" in baselineOrOptions ? baselineOrOptions.operations : operationsArgument ?? [],
+    "baseline" in baselineOrOptions ? baselineOrOptions.config : configArgument
+  );
+  return state;
+}
+function rebuildUserStateLog(baseline, operations, config) {
+  let state = cloneState(baseline);
+  const rejectedOperationIds = [];
+  for (const operation of operations) {
+    if (!isReplayable(operation)) continue;
+    const replay = applyOperation(state, operation, config);
+    if (replay.prerequisiteFailed) {
+      rejectedOperationIds.push(operationId(operation));
+      continue;
+    }
+    state = replay.state;
+  }
+  return { state, rejectedOperationIds };
+}
+
 // src/client/client.ts
 function isStorage(value) {
   return "load" in value && "save" in value && "remove" in value;
@@ -1834,6 +1929,7 @@ var StampRallyClient = class {
     this.#anonymousSessionId = this.#options.anonymousSessionId ?? createAnonymousSessionId();
     this.#userId = this.#options.userId ?? this.#anonymousSessionId;
     this.#offlineQueue = this.#options.offlineQueue;
+    this.#offlineQueue?.setReplayConfig(config);
     this.#offlineQueue?.setSyncResultListener((event) => this.#handleOfflineSyncResult(event));
     this.#offlineQueue?.setChangeListener(() => {
       this.#syncRevision += 1;
@@ -1867,17 +1963,23 @@ var StampRallyClient = class {
   get queueCapability() {
     return this.#offlineQueue?.queueCapability ?? "custom";
   }
-  discardRejected(operationId) {
-    return this.#offlineQueue?.discardRejected(operationId) ?? Promise.resolve(false);
+  get storageCapability() {
+    return this.#offlineQueue?.storageCapability ?? "custom";
+  }
+  get isStoragePersistent() {
+    return this.#offlineQueue?.isStoragePersistent ?? true;
+  }
+  discardRejected(operationId2) {
+    return this.#offlineQueue?.discardRejected(operationId2) ?? Promise.resolve(false);
   }
-  retryRejected(operationId) {
-    return this.#offlineQueue?.retryRejected(operationId) ?? Promise.resolve(false);
+  retryRejected(operationId2) {
+    return this.#offlineQueue?.retryRejected(operationId2) ?? Promise.resolve(false);
   }
-  dismissRejectedOperation(operationId) {
-    return this.discardRejected(operationId);
+  dismissRejectedOperation(operationId2) {
+    return this.discardRejected(operationId2);
   }
-  retryOperation(operationId) {
-    return this.retryRejected(operationId);
+  retryOperation(operationId2) {
+    return this.retryRejected(operationId2);
   }
   subscribe(listener) {
     this.#listeners.add(listener);
@@ -2002,13 +2104,13 @@ var StampRallyClient = class {
           return result.ok ? this.#commitCheckIn(result) : this.#fail(result.error);
         } catch (error) {
           if (this.#offlineQueue === void 0) throw error;
-          await this.#offlineQueue.enqueueCheckIn(request);
           const record2 = { stampId: spotId, acquiredAt: now };
           const next2 = this.#reconcile({
             ...current,
             records: [...current.records, record2],
             updatedAt: now
           });
+          await this.#offlineQueue.enqueueCheckIn(request, next2);
           await this.#storage.save(next2);
           return this.#commitCheckIn({ ok: true, value: { state: next2, record: record2 } });
         }
@@ -2059,7 +2161,6 @@ var StampRallyClient = class {
           return result.ok ? this.#commitClaim(result) : this.#fail(result.error);
         } catch (error) {
           if (this.#offlineQueue === void 0) throw error;
-          await this.#offlineQueue.enqueueClaimReward(request);
           const next2 = {
             ...current,
             rewards: current.rewards.map(
@@ -2067,6 +2168,7 @@ var StampRallyClient = class {
             ),
             updatedAt: now
           };
+          await this.#offlineQueue.enqueueClaimReward(request, next2);
           await this.#storage.save(next2);
           return this.#commitClaim({ ok: true, value: { state: next2, reward: local.value } });
         }
@@ -2109,9 +2211,11 @@ var StampRallyClient = class {
           state: localState,
           ...this.#userId === this.#anonymousSessionId ? { anonymousSessionId: this.#anonymousSessionId } : {}
         });
-        const resolved = resolveRallyStateConflict(serverState, localState, {
-          policy: this.#options.conflictResolutionPolicy ?? this.#options.conflictPolicy ?? "authoritative_replay"
-        });
+        const resolved = rebuildUserStateFromLog(
+          serverState,
+          this.#offlineQueue?.operations ?? [],
+          this.#config
+        );
         const next = this.#reconcile(resolved);
         await this.#storage.save(next);
         this.#state = next;
@@ -2185,7 +2289,12 @@ var StampRallyClient = class {
     if (event.status === "ACCEPTED") {
       if (this.#syncMetrics !== null) this.#syncMetrics.processed += 1;
       if (event.state !== void 0) {
-        const next = this.#reconcile(event.state);
+        const rebuilt = rebuildUserStateFromLog(
+          event.state,
+          this.#offlineQueue?.operations ?? [],
+          this.#config
+        );
+        const next = this.#reconcile(rebuilt);
         await this.#storage.save(next);
         this.#state = next;
         this.#emit(next);
@@ -2205,7 +2314,13 @@ var StampRallyClient = class {
         this.#syncMetrics.failed += 1;
       }
       const base = event.state ?? this.#state ?? event.operation.request.state;
-      const next = this.#reconcile(rollbackOptimisticOperation(base, event.operation));
+      const rollbackBase = event.state === void 0 ? rollbackOptimisticOperation(base, event.operation) : base;
+      const rebuilt = rebuildUserStateFromLog(
+        rollbackBase,
+        this.#offlineQueue?.operations ?? [],
+        this.#config
+      );
+      const next = this.#reconcile(rebuilt);
       await this.#storage.save(next);
       this.#state = next;
       this.#emit(next);
@@ -2808,7 +2923,11 @@ function theme(value, path, errors) {
   finiteNumber(value, "gridColumns", path, errors, 1);
   if (typeof value.gridColumns === "number" && !Number.isInteger(value.gridColumns))
     add(errors, `${path}.gridColumns`, "Expected an integer.", "invalid_integer");
-  if (hasOwn(value, "unclaimedOpacity")) finiteNumber(value, "unclaimedOpacity", path, errors, 0);
+  if (hasOwn(value, "unclaimedOpacity")) {
+    finiteNumber(value, "unclaimedOpacity", path, errors, 0);
+    if (typeof value.unclaimedOpacity === "number" && value.unclaimedOpacity > 1)
+      add(errors, `${path}.unclaimedOpacity`, "Expected a value between 0 and 1.", "out_of_range");
+  }
 }
 function externalReferences(value, path, errors) {
   if (!Array.isArray(value)) {
@@ -2971,12 +3090,14 @@ function reward(value, path, errors, isPublic) {
     String(value.redemptionMethod)
   ))
     add(errors, `${path}.redemptionMethod`, "Unknown redemption method.", "invalid_enum");
-  finiteNumber(value, "requiredStampCount", path, errors, 0);
+  nonNegativeInteger(value, "requiredStampCount", path, errors);
   for (const key of ["stockLimit", "userClaimLimit"]) {
     if (hasOwn(value, key) && value[key] !== void 0) {
       nonNegativeInteger(value, key, path, errors);
     }
   }
+  optionalString(value, "stockKey", path, errors);
+  optionalString(value, "secondaryStockKey", path, errors);
   optionalString(value, "validUntil", path, errors);
   if (typeof value.validUntil === "string" && Number.isNaN(Date.parse(value.validUntil)))
     add(errors, `${path}.validUntil`, "Expected a valid date string.", "invalid_date");
@@ -3024,8 +3145,25 @@ function validate(value, isPublic) {
       if (!isRecord3(value.inventory))
         add(errors, "$.inventory", "Expected an object.", "invalid_type");
       else {
-        for (const [key, item] of Object.entries(value.inventory))
+        for (const [key, item] of Object.entries(value.inventory)) {
+          if (key === "global") {
+            add(
+              errors,
+              "$.inventory.global",
+              "Use sharedStock instead of global.",
+              "deprecated_field"
+            );
+            continue;
+          }
           if (item !== void 0) nonNegativeInteger(value.inventory, key, "$.inventory", errors);
+        }
+        if (hasOwn(value.inventory, "sharedStock") && hasOwn(value.inventory, "global"))
+          add(
+            errors,
+            "$.inventory",
+            "sharedStock and global cannot be configured together.",
+            "conflicting_fields"
+          );
       }
     }
     if (hasOwn(value, "inventoryMode") && value.inventoryMode !== void 0 && value.inventoryMode !== "shared" && value.inventoryMode !== "per_reward")
@@ -3101,6 +3239,33 @@ function validateRallyConfigRelations(config) {
     reward2.conditions?.forEach((condition2, conditionIndex) => {
       visit(condition2, `rewards[${index}].conditions[${conditionIndex}]`);
     });
+    if (reward2.requiredStampCount > config.spots.length)
+      add(
+        errors,
+        `rewards[${index}].requiredStampCount`,
+        "requiredStampCount cannot exceed the number of spots.",
+        "required_stamp_count_exceeds_spots"
+      );
+    const inventory = "inventory" in config ? config.inventory : void 0;
+    for (const [field, key] of [
+      ["stockKey", reward2.stockKey],
+      ["secondaryStockKey", reward2.secondaryStockKey]
+    ]) {
+      if (key !== void 0 && key !== "__shared__" && inventory?.[key] === void 0)
+        add(
+          errors,
+          `rewards[${index}].${field}`,
+          "Referenced inventory key does not exist.",
+          "missing_inventory_key"
+        );
+    }
+    if (reward2.stockKey === "__shared__" && inventory?.sharedStock === void 0)
+      add(
+        errors,
+        `rewards[${index}].stockKey`,
+        "sharedStock is not defined.",
+        "missing_inventory_key"
+      );
   });
   const visiting = /* @__PURE__ */ new Set();
   const visited = /* @__PURE__ */ new Set();
@@ -3313,6 +3478,8 @@ exports.parsePublicConfig = parsePublicConfig;
 exports.processStamp = processStamp;
 exports.readNfcContext = readNfcContext;
 exports.readQrContext = readQrContext;
+exports.rebuildUserStateFromLog = rebuildUserStateFromLog;
+exports.rebuildUserStateLog = rebuildUserStateLog;
 exports.reconcileRewardStates = reconcileRewardStates;
 exports.resolveLocalizedText = resolveLocalizedText;
 exports.resolveRallyStateConflict = resolveRallyStateConflict;