@stamprally/server 0.14.0 → 0.16.0

package/dist/index.cjs

@@ -3,32 +3,72 @@
 var core = require('@stamprally/core');
 
 // src/examples/transaction.ts
-async function executeClaimRewardTransaction(database, store, params, mutation) {
+async function executeClaimRewardTransaction(database, store, params2, mutation2) {
   try {
     return await database.transaction(async (transaction) => {
-      const current = await store.readContext(transaction, params);
-      const next = mutation(current);
+      const current = await store.readContext(transaction, params2);
+      const next = mutation2(current);
       if (next.error !== void 0) {
         await store.writeAudit(transaction, next.auditLog);
-        if (params.idempotencyKey !== void 0 && next.result !== void 0)
-          await store.writeIdempotency(transaction, params, next.result);
+        if (params2.idempotencyKey !== void 0 && next.result !== void 0)
+          await store.writeIdempotency(transaction, params2, next.result);
         return { success: false, error: next.error };
       }
-      if (next.nextStock !== null) await store.writeStock(transaction, params, next.nextStock);
-      await store.writeUserState(transaction, params, next.nextUserState);
-      await store.writeClaimRecord(transaction, params, next.nextUserState);
+      if (next.nextSecondaryStock !== void 0 && store.writeSecondaryStock === void 0)
+        return { success: false, error: "INVENTORY_NOT_SUPPORTED" };
+      if (next.nextStock !== null) await store.writeStock(transaction, params2, next.nextStock);
+      if (next.nextSecondaryStock !== void 0 && store.writeSecondaryStock !== void 0) {
+        if (next.nextSecondaryStock !== null)
+          await store.writeSecondaryStock(transaction, params2, next.nextSecondaryStock);
+      }
+      await store.writeUserState(transaction, params2, next.nextUserState);
+      await store.writeClaimRecord(transaction, params2, next.nextUserState);
       await store.writeAudit(transaction, next.auditLog);
-      if (params.idempotencyKey !== void 0 && next.result !== void 0)
-        await store.writeIdempotency(transaction, params, next.result);
+      if (params2.idempotencyKey !== void 0 && next.result !== void 0)
+        await store.writeIdempotency(transaction, params2, next.result);
       return { success: true };
     });
-  } catch (error2) {
-    return { success: false, error: error2 instanceof Error ? error2.message : String(error2) };
+  } catch (error) {
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+async function executeCheckInTransaction(database, store, params2, mutation2, current) {
+  try {
+    return await database.transaction(async (transaction) => {
+      const userState = current ?? (store.readUserState === void 0 ? (() => {
+        throw new Error("A current user state or readUserState implementation is required.");
+      })() : await store.readUserState(transaction, params2));
+      const next = mutation2({ userState });
+      if (next.error !== void 0) {
+        await store.writeAudit(transaction, next.auditLog);
+        if (params2.idempotencyKey !== void 0 && next.result !== void 0)
+          await store.writeIdempotency(transaction, params2, next.result);
+        return { success: false, error: next.error };
+      }
+      await store.writeUserState(transaction, params2, next.nextUserState);
+      await store.writeAudit(transaction, next.auditLog);
+      if (params2.idempotencyKey !== void 0 && next.result !== void 0)
+        await store.writeIdempotency(transaction, params2, next.result);
+      return { success: true };
+    });
+  } catch (error) {
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+async function executeRedisTransaction(redis, queue) {
+  try {
+    const multi = redis.multi();
+    queue(multi);
+    const result = await redis.exec(multi);
+    return result === null ? { success: false, error: "Redis transaction was aborted." } : { success: true };
+  } catch (error) {
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
   }
 }
 
 // src/persistence.ts
 var InMemoryServerPersistenceAdapter = class {
+  supportsRewardStock = true;
   #locks = /* @__PURE__ */ new Map();
   #idempotent = /* @__PURE__ */ new Map();
   #states = /* @__PURE__ */ new Map();
@@ -37,6 +77,7 @@ var InMemoryServerPersistenceAdapter = class {
   #claims = /* @__PURE__ */ new Map();
   #claimRecords = [];
   #auditLogs = [];
+  #transactionTails = /* @__PURE__ */ new Map();
   constructor(options = {}) {
     this.#stocks = /* @__PURE__ */ new Map();
     this.#stockDefaults = /* @__PURE__ */ new Map();
@@ -85,96 +126,140 @@ var InMemoryServerPersistenceAdapter = class {
     const current = this.#stocks.get(key);
     if (current !== void 0) this.#stocks.set(key, current + Math.max(0, count));
   }
-  async executeClaimRewardTransaction(params, mutation) {
+  async executeClaimRewardTransaction(params2, mutation2) {
     try {
-      return await this.runTransaction(params.rallyId, async () => {
-        const userState = await this.getUserState(params.rallyId, params.userId) ?? params.initialUserState;
+      const initialStock = params2.initialStock !== void 0 ? params2.initialStock : params2.stockKey === "__shared__" ? params2.sharedStockLimit : params2.rewardStockLimit;
+      const initialSecondaryStock = params2.initialSecondaryStock !== void 0 ? params2.initialSecondaryStock : params2.rewardStockLimit;
+      return await this.runTransaction(params2.rallyId, async () => {
+        if (params2.idempotencyKey !== void 0) {
+          const previous = await this.getIdempotentResult(
+            params2.rallyId,
+            params2.idempotencyKey
+          );
+          if (previous !== null) return { success: true };
+        }
+        const userState = await this.getUserState(params2.rallyId, params2.userId) ?? params2.initialUserState;
         if (userState === void 0)
           return { success: false, error: "A user state is required for this transaction." };
-        const mutationResult = mutation({
-          stock: await this.getRewardStock(params.rallyId, params.rewardId),
-          claimCount: await this.getUserClaimCount(params.rallyId, params.userId, params.rewardId),
+        const storedStock = await this.getRewardStock(
+          params2.rallyId,
+          params2.stockKey ?? params2.rewardId
+        );
+        const storedSecondaryStock = params2.secondaryStockKey === void 0 ? null : await this.getRewardStock(params2.rallyId, params2.secondaryStockKey);
+        const mutationResult = mutation2({
+          stock: storedStock ?? initialStock,
+          secondaryStock: storedSecondaryStock ?? initialSecondaryStock,
+          claimCount: await this.getUserClaimCount(params2.rallyId, params2.userId, params2.rewardId),
           userState
         });
-        const idempotencyKey = params.idempotencyKey;
+        const idempotencyKey = params2.idempotencyKey;
         if (mutationResult.error !== void 0) {
           await this.recordAuditLog(mutationResult.auditLog);
           if (idempotencyKey !== void 0 && mutationResult.result !== void 0)
             await this.saveIdempotentResult(
-              params.rallyId,
+              params2.rallyId,
               idempotencyKey,
               mutationResult.result,
-              params.idempotencyTtlMs ?? 864e5
+              params2.idempotencyTtlMs ?? 864e5
             );
           return { success: false, error: mutationResult.error };
         }
-        const currentStock = await this.getRewardStock(params.rallyId, params.rewardId);
-        if (currentStock !== null && (mutationResult.nextStock === null || mutationResult.nextStock < 0))
+        const currentStock = await this.getRewardStock(
+          params2.rallyId,
+          params2.stockKey ?? params2.rewardId
+        );
+        const effectiveStock = currentStock ?? initialStock;
+        if (currentStock === null && initialStock !== void 0 && initialStock !== null)
+          this.#stocks.set(
+            this.#stockKey(params2.rallyId, params2.stockKey ?? params2.rewardId),
+            initialStock
+          );
+        const currentSecondaryStock = params2.secondaryStockKey === void 0 ? null : await this.getRewardStock(params2.rallyId, params2.secondaryStockKey);
+        const effectiveSecondaryStock = currentSecondaryStock ?? initialSecondaryStock;
+        if (currentSecondaryStock === null && params2.secondaryStockKey !== void 0 && initialSecondaryStock !== void 0 && initialSecondaryStock !== null)
+          this.#stocks.set(
+            this.#stockKey(params2.rallyId, params2.secondaryStockKey),
+            initialSecondaryStock
+          );
+        if (effectiveStock !== null && (mutationResult.nextStock === null || mutationResult.nextStock < 0))
           throw new Error("The transaction produced an invalid stock value.");
-        if (currentStock === null && mutationResult.nextStock !== null)
+        if (effectiveStock === null && mutationResult.nextStock !== null)
           throw new Error("The transaction changed an unlimited stock to a limited stock.");
         if (mutationResult.nextStock !== null)
           this.#stocks.set(
-            this.#stockKey(params.rallyId, params.rewardId),
+            this.#stockKey(params2.rallyId, params2.stockKey ?? params2.rewardId),
             mutationResult.nextStock
           );
-        await this.saveUserState(params.rallyId, params.userId, mutationResult.nextUserState);
+        if (params2.secondaryStockKey !== void 0 && mutationResult.nextSecondaryStock !== void 0) {
+          if (effectiveSecondaryStock !== null && (mutationResult.nextSecondaryStock === null || mutationResult.nextSecondaryStock < 0))
+            throw new Error("The transaction produced an invalid secondary stock value.");
+          if (effectiveSecondaryStock === null && mutationResult.nextSecondaryStock !== null)
+            throw new Error(
+              "The transaction changed an unlimited secondary stock to a limited stock."
+            );
+          if (mutationResult.nextSecondaryStock !== null)
+            this.#stocks.set(
+              this.#stockKey(params2.rallyId, params2.secondaryStockKey),
+              mutationResult.nextSecondaryStock
+            );
+        }
+        await this.saveUserState(params2.rallyId, params2.userId, mutationResult.nextUserState);
         const reward = mutationResult.nextUserState.rewards.find(
-          (item) => item.rewardId === params.rewardId
+          (item) => item.rewardId === params2.rewardId
         );
         if (reward?.claimTicketNumber !== void 0)
           await this.recordUserClaim({
-            rallyId: params.rallyId,
-            userId: params.userId,
-            rewardId: params.rewardId,
+            rallyId: params2.rallyId,
+            userId: params2.userId,
+            rewardId: params2.rewardId,
             ticketNumber: reward.claimTicketNumber,
-            timestamp: params.timestamp
+            timestamp: params2.timestamp
           });
         await this.recordAuditLog(mutationResult.auditLog);
         if (idempotencyKey !== void 0 && mutationResult.result !== void 0)
           await this.saveIdempotentResult(
-            params.rallyId,
+            params2.rallyId,
             idempotencyKey,
             mutationResult.result,
-            params.idempotencyTtlMs ?? 864e5
+            params2.idempotencyTtlMs ?? 864e5
           );
         return { success: true };
       });
-    } catch (error2) {
-      return { success: false, error: error2 instanceof Error ? error2.message : String(error2) };
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : String(error) };
     }
   }
-  async executeCheckInTransaction(params, mutation) {
+  async executeCheckInTransaction(params2, mutation2) {
     try {
-      return await this.runTransaction(params.rallyId, async () => {
-        const userState = await this.getUserState(params.rallyId, params.userId) ?? params.initialUserState;
+      return await this.runTransaction(params2.rallyId, async () => {
+        const userState = await this.getUserState(params2.rallyId, params2.userId) ?? params2.initialUserState;
         if (userState === void 0)
           return { success: false, error: "A user state is required for this transaction." };
-        const mutationResult = mutation({ userState });
+        const mutationResult = mutation2({ userState });
         if (mutationResult.error !== void 0) {
           await this.recordAuditLog(mutationResult.auditLog);
-          if (params.idempotencyKey !== void 0 && mutationResult.result !== void 0)
+          if (params2.idempotencyKey !== void 0 && mutationResult.result !== void 0)
             await this.saveIdempotentResult(
-              params.rallyId,
-              params.idempotencyKey,
+              params2.rallyId,
+              params2.idempotencyKey,
               mutationResult.result,
-              params.idempotencyTtlMs ?? 864e5
+              params2.idempotencyTtlMs ?? 864e5
             );
           return { success: false, error: mutationResult.error };
         }
-        await this.saveUserState(params.rallyId, params.userId, mutationResult.nextUserState);
+        await this.saveUserState(params2.rallyId, params2.userId, mutationResult.nextUserState);
         await this.recordAuditLog(mutationResult.auditLog);
-        if (params.idempotencyKey !== void 0 && mutationResult.result !== void 0)
+        if (params2.idempotencyKey !== void 0 && mutationResult.result !== void 0)
           await this.saveIdempotentResult(
-            params.rallyId,
-            params.idempotencyKey,
+            params2.rallyId,
+            params2.idempotencyKey,
             mutationResult.result,
-            params.idempotencyTtlMs ?? 864e5
+            params2.idempotencyTtlMs ?? 864e5
           );
         return { success: true };
       });
-    } catch (error2) {
-      return { success: false, error: error2 instanceof Error ? error2.message : String(error2) };
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : String(error) };
     }
   }
   async rollbackUserState(rallyId, userId, previousState) {
@@ -203,8 +288,8 @@ var InMemoryServerPersistenceAdapter = class {
     const value = this.#states.get(`${rallyId}:${userId}`);
     return value === void 0 ? null : structuredClone(value);
   }
-  async saveUserState(rallyId, userId, state) {
-    this.#states.set(`${rallyId}:${userId}`, structuredClone(state));
+  async saveUserState(rallyId, userId, state2) {
+    this.#states.set(`${rallyId}:${userId}`, structuredClone(state2));
   }
   async recordAuditLog(log) {
     this.#auditLogs.push(structuredClone(log));
@@ -216,11 +301,11 @@ var InMemoryServerPersistenceAdapter = class {
   getAuditLogs() {
     return structuredClone(this.#auditLogs);
   }
-  async recordUserClaim(params) {
-    const { rallyId, userId, rewardId } = params;
+  async recordUserClaim(params2) {
+    const { rallyId, userId, rewardId } = params2;
     const key = `${rallyId}:${userId}:${rewardId}`;
     this.#claims.set(key, (this.#claims.get(key) ?? 0) + 1);
-    this.#claimRecords.push(structuredClone(params));
+    this.#claimRecords.push(structuredClone(params2));
   }
   async rollbackUserClaim(rallyId, userId, rewardId, ticketNumber) {
     const key = `${rallyId}:${userId}:${rewardId}`;
@@ -240,46 +325,66 @@ var InMemoryServerPersistenceAdapter = class {
     return structuredClone(this.#claimRecords);
   }
   recordClaim(paramsOrRallyId, userId, rewardId) {
-    const params = typeof paramsOrRallyId === "string" ? {
+    const params2 = typeof paramsOrRallyId === "string" ? {
       rallyId: paramsOrRallyId,
       userId: userId ?? "",
       rewardId: rewardId ?? "",
       ticketNumber: "",
       timestamp: Date.now()
     } : paramsOrRallyId;
-    return this.recordUserClaim(params);
-  }
-  async runTransaction(_rallyId, operation) {
-    const snapshot = {
-      stocks: new Map(this.#stocks),
-      idempotent: new Map(this.#idempotent),
-      states: new Map(this.#states),
-      claims: new Map(this.#claims),
-      claimRecords: structuredClone(this.#claimRecords),
-      auditLogs: structuredClone(this.#auditLogs)
-    };
-    try {
-      return await operation(this);
-    } catch (error2) {
-      this.#stocks.clear();
-      for (const [key, value] of snapshot.stocks) this.#stocks.set(key, value);
-      this.#idempotent.clear();
-      for (const [key, value] of snapshot.idempotent)
-        this.#idempotent.set(key, structuredClone(value));
-      this.#states.clear();
-      for (const [key, value] of snapshot.states) this.#states.set(key, structuredClone(value));
-      this.#claims.clear();
-      for (const [key, value] of snapshot.claims) this.#claims.set(key, value);
-      this.#claimRecords.splice(0, this.#claimRecords.length, ...snapshot.claimRecords);
-      this.#auditLogs.splice(0, this.#auditLogs.length, ...snapshot.auditLogs);
-      throw error2;
-    }
+    return this.recordUserClaim(params2);
+  }
+  async runTransaction(rallyId, operation) {
+    const previous = this.#transactionTails.get(rallyId) ?? Promise.resolve();
+    const current = previous.then(async () => {
+      const snapshot = {
+        stocks: new Map(this.#stocks),
+        idempotent: new Map(this.#idempotent),
+        states: new Map(this.#states),
+        claims: new Map(this.#claims),
+        claimRecords: structuredClone(this.#claimRecords),
+        auditLogs: structuredClone(this.#auditLogs)
+      };
+      try {
+        return await operation(this);
+      } catch (error) {
+        this.#stocks.clear();
+        for (const [key, value] of snapshot.stocks) this.#stocks.set(key, value);
+        this.#idempotent.clear();
+        for (const [key, value] of snapshot.idempotent)
+          this.#idempotent.set(key, structuredClone(value));
+        this.#states.clear();
+        for (const [key, value] of snapshot.states) this.#states.set(key, structuredClone(value));
+        this.#claims.clear();
+        for (const [key, value] of snapshot.claims) this.#claims.set(key, value);
+        this.#claimRecords.splice(0, this.#claimRecords.length, ...snapshot.claimRecords);
+        this.#auditLogs.splice(0, this.#auditLogs.length, ...snapshot.auditLogs);
+        throw error;
+      }
+    });
+    this.#transactionTails.set(
+      rallyId,
+      current.then(
+        () => void 0,
+        () => void 0
+      )
+    );
+    return current;
   }
 };
 
 // src/security.ts
-function error(path, message) {
-  return { success: false, errors: [{ path, message, code: "invalid_request" }] };
+var RequestValidationException = class extends Error {
+  code = "VALIDATION_FAILED";
+  errors;
+  constructor(errors2) {
+    super("Request validation failed.");
+    this.name = "RequestValidationException";
+    this.errors = errors2;
+  }
+};
+function errors(...items) {
+  return { success: false, errors: items };
 }
 function record(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -287,47 +392,199 @@ function record(value) {
 function nonEmpty(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
-function context(value) {
-  if (!record(value) || typeof value.type !== "string") return false;
-  if (value.type === "qr") return nonEmpty(value.token);
-  if (value.type === "passcode") return nonEmpty(value.code);
-  if (value.type === "nfc") return nonEmpty(value.tagId);
-  if (value.type === "custom") return "value" in value;
-  return value.type === "gps" && typeof value.latitude === "number" && Number.isFinite(value.latitude) && typeof value.longitude === "number" && Number.isFinite(value.longitude);
+function contextErrors(value) {
+  if (!record(value) || typeof value.type !== "string")
+    return [
+      {
+        path: "proof",
+        message: "proof is not a valid verification context.",
+        code: "INVALID_TYPE"
+      }
+    ];
+  if (value.type === "qr" && !nonEmpty(value.token))
+    return [
+      { path: "proof.token", message: "token must be a non-empty string.", code: "INVALID_TYPE" }
+    ];
+  if (value.type === "passcode" && !nonEmpty(value.code))
+    return [
+      { path: "proof.code", message: "code must be a non-empty string.", code: "INVALID_TYPE" }
+    ];
+  if (value.type === "nfc" && !nonEmpty(value.tagId))
+    return [
+      { path: "proof.tagId", message: "tagId must be a non-empty string.", code: "INVALID_TYPE" }
+    ];
+  if (value.type === "custom")
+    return "value" in value ? [] : [{ path: "proof.value", message: "value is required.", code: "REQUIRED" }];
+  if (value.type === "qr" || value.type === "passcode" || value.type === "nfc") return [];
+  if (value.type !== "gps")
+    return [{ path: "proof.type", message: "Unknown verification type.", code: "INVALID_ENUM" }];
+  const result = [];
+  if (typeof value.latitude !== "number" || !Number.isFinite(value.latitude))
+    result.push({
+      path: "proof.latitude",
+      message: "Latitude must be a finite number.",
+      code: "INVALID_TYPE"
+    });
+  else if (value.latitude < -90 || value.latitude > 90)
+    result.push({
+      path: "proof.latitude",
+      message: "Latitude must be between -90 and 90.",
+      code: "INVALID_RANGE"
+    });
+  if (typeof value.longitude !== "number" || !Number.isFinite(value.longitude))
+    result.push({
+      path: "proof.longitude",
+      message: "Longitude must be a finite number.",
+      code: "INVALID_TYPE"
+    });
+  else if (value.longitude < -180 || value.longitude > 180)
+    result.push({
+      path: "proof.longitude",
+      message: "Longitude must be between -180 and 180.",
+      code: "INVALID_RANGE"
+    });
+  if ("radiusMeters" in value && (typeof value.radiusMeters !== "number" || !Number.isFinite(value.radiusMeters) || value.radiusMeters <= 0))
+    result.push({
+      path: "proof.radiusMeters",
+      message: "Radius must be greater than zero.",
+      code: "INVALID_RANGE"
+    });
+  return result;
+}
+function dateInput(value) {
+  if (typeof value === "number") return Number.isInteger(value) && value > 0;
+  if (typeof value !== "string" || value.trim() === "") return false;
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:?\d{2})$/.test(value) && !Number.isNaN(Date.parse(value));
 }
-function common(value, fields) {
-  if (!record(value)) return false;
-  return fields.every((field) => nonEmpty(value[field]));
+function requiredErrors(value, fields) {
+  if (record(value) && fields.every((field) => nonEmpty(value[field]))) return [];
+  return fields.filter((field) => !record(value) || !nonEmpty(value[field])).map((field) => ({
+    path: field,
+    message: `${field} must be a non-empty string.`,
+    code: "REQUIRED"
+  }));
 }
 function validateCheckInRequest(value) {
-  if (!common(value, ["rallyId", "spotId", "idempotencyKey"]))
-    return error("$", "rallyId, spotId, and idempotencyKey must be non-empty strings.");
-  if (!context(value.context))
-    return error("context", "context is not a valid verification context.");
+  const required = requiredErrors(value, ["rallyId", "spotId", "idempotencyKey"]);
+  if (required.length > 0) return errors(...required);
+  if (!record(value))
+    return errors({ path: "$", message: "Expected an object.", code: "INVALID_TYPE" });
+  const proof = contextErrors(value.context);
+  if (proof.length > 0) return errors(...proof);
   if (value.userId !== void 0 && !nonEmpty(value.userId))
-    return error("userId", "userId must be non-empty.");
-  if (value.now !== void 0 && !nonEmpty(value.now))
-    return error("now", "now must be non-empty when provided.");
+    return errors({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
+  if (value.now !== void 0 && !dateInput(value.now))
+    return errors({
+      path: "now",
+      message: "now must be an ISO 8601 date or positive timestamp.",
+      code: "INVALID_DATE"
+    });
   return { success: true, data: value };
 }
 function validateClaimRewardRequest(value) {
-  if (!common(value, ["rallyId", "rewardId", "idempotencyKey"]))
-    return error("$", "rallyId, rewardId, and idempotencyKey must be non-empty strings.");
+  const required = requiredErrors(value, ["rallyId", "rewardId", "idempotencyKey"]);
+  if (required.length > 0) return errors(...required);
+  if (!record(value))
+    return errors({ path: "$", message: "Expected an object.", code: "INVALID_TYPE" });
   if (value.userId !== void 0 && !nonEmpty(value.userId))
-    return error("userId", "userId must be non-empty.");
+    return errors({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
   if (value.staffPasscode !== void 0 && !nonEmpty(value.staffPasscode))
-    return error("staffPasscode", "staffPasscode must be non-empty.");
+    return errors({
+      path: "staffPasscode",
+      message: "staffPasscode must be non-empty.",
+      code: "INVALID_TYPE"
+    });
   if (value.staffId !== void 0 && !nonEmpty(value.staffId))
-    return error("staffId", "staffId must be non-empty.");
-  if (value.now !== void 0 && !nonEmpty(value.now))
-    return error("now", "now must be non-empty when provided.");
+    return errors({ path: "staffId", message: "staffId must be non-empty.", code: "INVALID_TYPE" });
+  if (value.now !== void 0 && !dateInput(value.now))
+    return errors({
+      path: "now",
+      message: "now must be an ISO 8601 date or positive timestamp.",
+      code: "INVALID_DATE"
+    });
   return { success: true, data: value };
 }
+function uuid(value) {
+  return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function identityErrors(value) {
+  const result = [];
+  if (value.userId === void 0 && value.anonymousSessionId === void 0)
+    result.push({
+      path: "userId",
+      message: "An authenticated userId or anonymousSessionId is required.",
+      code: "REQUIRED"
+    });
+  if (value.userId !== void 0 && !nonEmpty(value.userId))
+    result.push({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
+  if (value.anonymousSessionId !== void 0 && !uuid(value.anonymousSessionId))
+    result.push({
+      path: "anonymousSessionId",
+      message: "anonymousSessionId must be a UUID v4.",
+      code: "INVALID_FORMAT"
+    });
+  if (value.userId !== void 0 && value.anonymousSessionId !== void 0 && value.userId !== value.anonymousSessionId)
+    result.push({
+      path: "anonymousSessionId",
+      message: "userId and anonymousSessionId must identify the same session.",
+      code: "IDENTITY_MISMATCH"
+    });
+  return result;
+}
+function directErrors(value, config, kind) {
+  const validated = kind === "check-in" ? validateCheckInRequest(value) : validateClaimRewardRequest(value);
+  if (!validated.success) return validated.errors;
+  const errors2 = [];
+  if (validated.data.rallyId !== config.id)
+    errors2.push({
+      path: "rallyId",
+      message: "The rally does not match this server.",
+      code: "INVALID_VALUE"
+    });
+  const resourceId = kind === "check-in" ? validated.data.spotId : validated.data.rewardId;
+  const exists = kind === "check-in" ? config.spots.some((spot) => spot.id === resourceId) : config.rewards.some((reward) => reward.id === resourceId);
+  if (!exists)
+    errors2.push({
+      path: kind === "check-in" ? "spotId" : "rewardId",
+      message: `${kind === "check-in" ? "Spot" : "Reward"} was not found.`,
+      code: kind === "check-in" ? "SPOT_NOT_FOUND" : "REWARD_NOT_FOUND"
+    });
+  errors2.push(...identityErrors(validated.data));
+  return errors2;
+}
+function assertValidCheckInParams(value, config) {
+  const errors2 = directErrors(value, config, "check-in");
+  if (errors2.length > 0) throw new RequestValidationException(errors2);
+}
+function assertValidClaimParams(value, config) {
+  const errors2 = directErrors(value, config, "claim");
+  if (errors2.length > 0) throw new RequestValidationException(errors2);
+}
+function assertValidSyncParams(value, config) {
+  const validated = validateSyncRequest(value);
+  const errors2 = validated.success ? [
+    ...validated.data.rallyId !== config.id ? [
+      {
+        path: "rallyId",
+        message: "The rally does not match this server.",
+        code: "INVALID_VALUE"
+      }
+    ] : []
+  ] : [...validated.errors];
+  if (validated.success) errors2.push(...identityErrors(validated.data));
+  if (errors2.length > 0) throw new RequestValidationException(errors2);
+}
 function validateSyncRequest(value) {
-  if (!common(value, ["rallyId"])) return error("rallyId", "rallyId must be a non-empty string.");
+  const required = requiredErrors(value, ["rallyId"]);
+  if (required.length > 0) return errors(...required);
+  if (!record(value))
+    return errors({ path: "$", message: "Expected an object.", code: "INVALID_TYPE" });
   if (value.userId !== void 0 && !nonEmpty(value.userId))
-    return error("userId", "userId must be non-empty.");
-  return { success: true, data: value };
+    return errors({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
+  return {
+    success: true,
+    data: value
+  };
 }
 function json(body, status = 200) {
   return new Response(JSON.stringify(body), {
@@ -338,6 +595,9 @@ function json(body, status = 200) {
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isUuidV4(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
 function requestId(prefix) {
   return `${prefix}-${globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`}`;
 }
@@ -348,6 +608,15 @@ function timestampMillis(timestamp) {
   const value = Date.parse(timestamp);
   return Number.isFinite(value) ? value : Date.now();
 }
+function validationResponse(errors2) {
+  return json(
+    {
+      error: "VALIDATION_FAILED",
+      details: errors2.map(({ path, message, code }) => ({ path, message, code }))
+    },
+    400
+  );
+}
 function initialState(config, userId, timestamp) {
   return {
     rallyId: config.id,
@@ -357,16 +626,37 @@ function initialState(config, userId, timestamp) {
     updatedAt: timestamp
   };
 }
-function getProof(context2) {
-  return context2.type === "qr" ? context2.token : context2.type === "passcode" ? context2.code : context2.type === "gps" ? { latitude: context2.latitude, longitude: context2.longitude } : context2.type === "nfc" ? context2.tagId : context2.value;
+function rewardStock(config, rewardId, stockLimit) {
+  const configured = config.inventory?.[rewardId];
+  if (stockLimit === void 0) return configured ?? null;
+  if (configured === void 0) return stockLimit;
+  return Math.min(stockLimit, configured);
+}
+function sharedStock(config) {
+  return config.inventory?.sharedStock ?? config.inventory?.global ?? null;
 }
-async function evaluate(condition, context2, validator, base) {
-  if (condition.type !== "custom") return core.evaluateConditionDetailed(condition, context2).ok;
+function inventoryPlan(config, rewardId, stockLimit) {
+  const individual = rewardStock(config, rewardId, stockLimit);
+  const shared = sharedStock(config);
+  if (config.inventoryMode === "shared" && shared !== null) {
+    return {
+      primaryKey: "__shared__",
+      primaryInitial: shared,
+      ...individual === null ? {} : { secondaryKey: rewardId, secondaryInitial: individual }
+    };
+  }
+  return { primaryKey: rewardId, primaryInitial: individual };
+}
+function getProof(context) {
+  return context.type === "qr" ? context.token : context.type === "passcode" ? context.code : context.type === "gps" ? { latitude: context.latitude, longitude: context.longitude } : context.type === "nfc" ? context.tagId : context.value;
+}
+async function evaluate(condition, context, validator, base) {
+  if (condition.type !== "custom") return core.evaluateConditionDetailed(condition, context).ok;
   if (validator === void 0) return false;
   const validationContext = {
     rallyId: base.rallyId,
     spotId: base.spotId,
-    proofData: getProof(context2),
+    proofData: getProof(context),
     condition,
     userState: base.state
   };
@@ -390,6 +680,18 @@ function operationStatus(result) {
   if (result.ok) return "ACCEPTED";
   return result.code === "CONFLICT" || result.code === "PERSISTENCE_FAILED" ? "RETRYABLE_ERROR" : "REJECTED_PERMANENT";
 }
+function withDirectIdentity(request) {
+  if (request.userId !== void 0) return { ...request, userId: request.userId };
+  if (request.anonymousSessionId !== void 0 && isUuidV4(request.anonymousSessionId))
+    return { ...request, userId: request.anonymousSessionId };
+  throw new RequestValidationException([
+    {
+      path: "userId",
+      message: "An authenticated userId or anonymousSessionId is required.",
+      code: "REQUIRED"
+    }
+  ]);
+}
 var StampRallyServer = class {
   #config;
   #persistence;
@@ -410,18 +712,33 @@ var StampRallyServer = class {
   }
   async handleCheckIn(request) {
     const body = validateCheckInRequest(await this.#body(request));
-    if (!body.success || body.data.rallyId !== this.#config.id)
-      return json(
-        { ok: false, code: "INVALID_REQUEST", message: "Invalid check-in request." },
-        400
-      );
+    if (!body.success) return validationResponse(body.errors);
+    if (body.data.rallyId !== this.#config.id)
+      return validationResponse([
+        {
+          path: "rallyId",
+          message: "The rally does not match this server.",
+          code: "INVALID_VALUE"
+        }
+      ]);
     const userId = await this.#user(request);
     if (userId === null)
       return json(
         { ok: false, code: "UNAUTHENTICATED", message: "Authentication is required." },
         401
       );
-    const result = await this.checkIn({ ...body.data, userId });
+    const sessionId = request.headers.get("x-anonymous-session-id");
+    let result;
+    try {
+      result = await this.checkIn({
+        ...body.data,
+        userId,
+        ...sessionId === null ? {} : { anonymousSessionId: sessionId }
+      });
+    } catch (error) {
+      if (error instanceof RequestValidationException) return validationResponse(error.errors);
+      throw error;
+    }
     return json(
       { ...result, status: operationStatus(result) },
       result.ok ? 200 : result.code === "SPOT_NOT_FOUND" ? 404 : 422
@@ -429,15 +746,33 @@ var StampRallyServer = class {
   }
   async handleClaimReward(request) {
     const body = validateClaimRewardRequest(await this.#body(request));
-    if (!body.success || body.data.rallyId !== this.#config.id)
-      return json({ ok: false, code: "INVALID_REQUEST", message: "Invalid reward request." }, 400);
+    if (!body.success) return validationResponse(body.errors);
+    if (body.data.rallyId !== this.#config.id)
+      return validationResponse([
+        {
+          path: "rallyId",
+          message: "The rally does not match this server.",
+          code: "INVALID_VALUE"
+        }
+      ]);
     const userId = await this.#user(request);
     if (userId === null)
       return json(
         { ok: false, code: "UNAUTHENTICATED", message: "Authentication is required." },
         401
       );
-    const result = await this.claimReward({ ...body.data, userId });
+    const sessionId = request.headers.get("x-anonymous-session-id");
+    let result;
+    try {
+      result = await this.claimReward({
+        ...body.data,
+        userId,
+        ...sessionId === null ? {} : { anonymousSessionId: sessionId }
+      });
+    } catch (error) {
+      if (error instanceof RequestValidationException) return validationResponse(error.errors);
+      throw error;
+    }
     return json(
       { ...result, status: operationStatus(result) },
       result.ok ? 200 : result.code === "REWARD_NOT_FOUND" ? 404 : 422
@@ -445,24 +780,47 @@ var StampRallyServer = class {
   }
   async handleSync(request) {
     const body = validateSyncRequest(await this.#body(request));
-    if (!body.success || body.data.rallyId !== this.#config.id)
-      return json({ ok: false, code: "INVALID_REQUEST", message: "Invalid sync request." }, 400);
+    if (!body.success) return validationResponse(body.errors);
+    if (body.data.rallyId !== this.#config.id)
+      return validationResponse([
+        {
+          path: "rallyId",
+          message: "The rally does not match this server.",
+          code: "INVALID_VALUE"
+        }
+      ]);
     const userId = await this.#user(request);
     if (userId === null)
       return json(
         { ok: false, code: "UNAUTHENTICATED", message: "Authentication is required." },
         401
       );
-    return json({ ok: true, state: await this.sync(body.data.rallyId, userId) });
+    const sessionId = request.headers.get("x-anonymous-session-id");
+    try {
+      return json({
+        ok: true,
+        state: await this.syncProgress({
+          rallyId: body.data.rallyId,
+          userId,
+          ...sessionId === null ? {} : { anonymousSessionId: sessionId }
+        })
+      });
+    } catch (error) {
+      if (error instanceof RequestValidationException) return validationResponse(error.errors);
+      throw error;
+    }
   }
   async checkIn(request) {
-    const key = `check-in:${request.rallyId}:${request.userId}:${request.idempotencyKey}`;
+    const directRequest = withDirectIdentity(request);
+    assertValidCheckInParams(directRequest, this.#config);
+    const { userId } = directRequest;
+    const key = `check-in:${request.rallyId}:${userId}:${request.idempotencyKey}`;
     const previous = await this.#persistence.getIdempotentResult(
       request.rallyId,
       key
     );
     if (previous !== null) return previous;
-    const lockKey = `state:${request.rallyId}:${request.userId}`;
+    const lockKey = `state:${request.rallyId}:${userId}`;
     if (!await this.#persistence.acquireLock(
       request.rallyId,
       lockKey,
@@ -471,11 +829,11 @@ var StampRallyServer = class {
       return { ok: false, code: "CONFLICT", message: "The user state is being updated." };
     const timestamp = now(this.#options);
     try {
-      const current = await this.#persistence.getUserState(request.rallyId, request.userId) ?? initialState(this.#config, request.userId, timestamp);
+      const current = await this.#persistence.getUserState(request.rallyId, userId) ?? initialState(this.#config, userId, timestamp);
       const responseHolder = { value: null };
       const makeAudit = (status, code) => audit(
         request.rallyId,
-        request.userId,
+        userId,
         "CHECK_IN",
         request.spotId,
         request.idempotencyKey,
@@ -491,7 +849,7 @@ var StampRallyServer = class {
           message: "Spot was not found."
         };
         return await this.#rememberCheckInTransaction(
-          request,
+          directRequest,
           timestamp,
           key,
           current,
@@ -515,7 +873,7 @@ var StampRallyServer = class {
       };
       if (current.records.some((record2) => record2.stampId === request.spotId))
         return await this.#rememberCheckInTransaction(
-          request,
+          directRequest,
           timestamp,
           key,
           current,
@@ -525,7 +883,7 @@ var StampRallyServer = class {
       const acquired = new Set(current.records.map((record2) => record2.stampId));
       if (spot.prerequisites?.some((id) => !acquired.has(id)))
         return await this.#rememberCheckInTransaction(
-          request,
+          directRequest,
           timestamp,
           key,
           current,
@@ -540,7 +898,7 @@ var StampRallyServer = class {
           { rallyId: request.rallyId, spotId: request.spotId, state: current }
         ))
           return await this.#rememberCheckInTransaction(
-            request,
+            directRequest,
             timestamp,
             key,
             current,
@@ -562,7 +920,7 @@ var StampRallyServer = class {
       const transaction = await this.#persistence.executeCheckInTransaction(
         {
           rallyId: request.rallyId,
-          userId: request.userId,
+          userId,
           spotId: request.spotId,
           timestamp: timestampMillis(timestamp),
           idempotencyKey: key,
@@ -587,7 +945,10 @@ var StampRallyServer = class {
     }
   }
   async claimReward(request) {
-    const key = `claim:${request.rallyId}:${request.userId}:${request.rewardId}:${request.idempotencyKey}`;
+    const directRequest = withDirectIdentity(request);
+    assertValidClaimParams(directRequest, this.#config);
+    const { userId } = directRequest;
+    const key = `claim:${request.rallyId}:${userId}:${request.rewardId}:${request.idempotencyKey}`;
     const previous = await this.#persistence.getIdempotentResult(
       request.rallyId,
       key
@@ -598,10 +959,22 @@ var StampRallyServer = class {
       return this.#rememberClaim(
         key,
         { ok: false, code: "REWARD_NOT_FOUND", message: "Reward was not found." },
-        request,
+        directRequest,
         now(this.#options)
       );
-    const lockKey = `reward:${request.rallyId}:${reward.id}`;
+    const plan = inventoryPlan(this.#config, reward.id, reward.stockLimit);
+    if (rewardStock(this.#config, reward.id, reward.stockLimit) !== null && (this.#persistence.supportsRewardStock === false || typeof this.#persistence.getRewardStock !== "function"))
+      return this.#rememberClaim(
+        key,
+        {
+          ok: false,
+          code: "INVENTORY_NOT_SUPPORTED",
+          message: "This persistence adapter cannot store per-reward inventory."
+        },
+        directRequest,
+        now(this.#options)
+      );
+    const lockKey = this.#config.inventoryMode === "shared" ? "inventory:shared" : `reward:${request.rallyId}:${reward.id}`;
     if (!await this.#persistence.acquireLock(
       request.rallyId,
       lockKey,
@@ -619,16 +992,22 @@ var StampRallyServer = class {
       const result = await this.#persistence.executeClaimRewardTransaction(
         {
           rallyId: request.rallyId,
-          userId: request.userId,
+          userId,
           rewardId: reward.id,
+          stockKey: plan.primaryKey,
+          ...plan.secondaryKey === void 0 ? {} : { secondaryStockKey: plan.secondaryKey },
+          rewardStockLimit: rewardStock(this.#config, reward.id, reward.stockLimit),
+          sharedStockLimit: this.#config.inventoryMode === "shared" ? sharedStock(this.#config) : null,
+          initialStock: plan.primaryInitial,
+          ...plan.secondaryInitial === void 0 ? {} : { initialSecondaryStock: plan.secondaryInitial },
           ticketNumber: request.idempotencyKey,
           timestamp: Number.isNaN(Date.parse(timestamp)) ? Date.now() : Date.parse(timestamp),
           idempotencyKey: key,
           ...request.staffPasscode === void 0 ? {} : { proofData: request.staffPasscode },
           ...this.#options.idempotencyTtlMs === void 0 ? {} : { idempotencyTtlMs: this.#options.idempotencyTtlMs },
-          initialUserState: initialState(this.#config, request.userId, timestamp)
+          initialUserState: initialState(this.#config, userId, timestamp)
         },
-        ({ stock, claimCount, userState }) => {
+        ({ stock, secondaryStock, claimCount, userState }) => {
           const storedReward = userState.rewards.find((item) => item.rewardId === reward.id) ?? {
             rewardId: reward.id,
             status: "LOCKED"
@@ -636,7 +1015,7 @@ var StampRallyServer = class {
           const currentReward = reward.redemptionMethod === "server_claim" && storedReward.status === "CONSUMED" && (reward.userClaimLimit === void 0 || claimCount < reward.userClaimLimit) ? { ...storedReward, status: "AVAILABLE" } : storedReward;
           const makeAudit = (status, code) => audit(
             request.rallyId,
-            request.userId,
+            userId,
             "CLAIM_REWARD",
             reward.id,
             request.idempotencyKey,
@@ -644,7 +1023,7 @@ var StampRallyServer = class {
             timestamp,
             code
           );
-          if (stock !== null && stock <= 0) {
+          if (stock !== null && stock <= 0 || secondaryStock !== null && secondaryStock <= 0) {
             responseHolder.value = {
               ok: false,
               code: "OUT_OF_STOCK",
@@ -652,6 +1031,7 @@ var StampRallyServer = class {
             };
             return {
               nextStock: stock,
+              ...plan.secondaryKey === void 0 ? {} : { nextSecondaryStock: secondaryStock },
               nextUserState: userState,
               auditLog: makeAudit("REJECTED", "OUT_OF_STOCK"),
               result: responseHolder.value,
@@ -682,14 +1062,35 @@ var StampRallyServer = class {
             };
           }
           const nextRewards = userState.rewards.some((item) => item.rewardId === reward.id) ? userState.rewards.map((item) => item.rewardId === reward.id ? local.value : item) : [...userState.rewards, local.value];
+          const consumed = local.value.claimTicketNumber !== void 0;
+          const nextStock = consumed && stock !== null ? Math.max(0, stock - 1) : stock;
+          const nextSecondaryStock = consumed && secondaryStock !== null ? Math.max(0, secondaryStock - 1) : secondaryStock;
           const next = {
             ...userState,
             rewards: nextRewards,
-            updatedAt: timestamp
+            updatedAt: timestamp,
+            inventory: {
+              ...plan.primaryKey === "__shared__" && nextStock !== null ? { sharedRemaining: nextStock } : {},
+              ...plan.secondaryKey !== void 0 && nextSecondaryStock !== null ? { rewardRemaining: { [reward.id]: nextSecondaryStock } } : plan.primaryKey === reward.id && nextStock !== null ? { rewardRemaining: { [reward.id]: nextStock } } : {}
+            }
+          };
+          const inventory = {
+            ...plan.primaryKey === "__shared__" && nextStock !== null ? { sharedRemaining: nextStock } : {},
+            ...plan.secondaryKey !== void 0 && nextSecondaryStock !== null ? { rewardRemaining: nextSecondaryStock } : plan.primaryKey === reward.id && nextStock !== null ? { rewardRemaining: nextStock } : {}
+          };
+          responseHolder.value = local.value.claimTicketNumber === void 0 ? {
+            ok: true,
+            state: next,
+            ...Object.keys(inventory).length === 0 ? {} : { inventory }
+          } : {
+            ok: true,
+            state: next,
+            claimTicketNumber: local.value.claimTicketNumber,
+            ...Object.keys(inventory).length === 0 ? {} : { inventory }
           };
-          responseHolder.value = local.value.claimTicketNumber === void 0 ? { ok: true, state: next } : { ok: true, state: next, claimTicketNumber: local.value.claimTicketNumber };
           return {
-            nextStock: stock === null ? null : stock - 1,
+            nextStock,
+            ...plan.secondaryKey === void 0 ? {} : { nextSecondaryStock },
             nextUserState: next,
             auditLog: makeAudit("SUCCESS"),
             result: responseHolder.value
@@ -699,6 +1100,12 @@ var StampRallyServer = class {
       const response = responseHolder.value;
       if (!result.success) {
         if (response !== null && !response.ok && response.code === result.error) return response;
+        if (result.error === "INVENTORY_NOT_SUPPORTED")
+          return {
+            ok: false,
+            code: "INVENTORY_NOT_SUPPORTED",
+            message: "This persistence adapter cannot store per-reward inventory."
+          };
         return {
           ok: false,
           code: "PERSISTENCE_FAILED",
@@ -711,18 +1118,52 @@ var StampRallyServer = class {
         code: "PERSISTENCE_FAILED",
         message: result.error ?? "Reward claim failed."
       };
-    } catch (error2) {
+    } catch (error) {
       return {
         ok: false,
         code: "PERSISTENCE_FAILED",
-        message: error2 instanceof Error ? error2.message : "Reward claim failed."
+        message: error instanceof Error ? error.message : "Reward claim failed."
       };
     } finally {
       await this.#persistence.releaseLock(request.rallyId, lockKey);
     }
   }
   async sync(rallyId, userId) {
-    return await this.#persistence.getUserState(rallyId, userId) ?? initialState(this.#config, userId, now(this.#options));
+    assertValidSyncParams({ rallyId, userId }, this.#config);
+    const state2 = await this.#persistence.getUserState(rallyId, userId) ?? initialState(this.#config, userId, now(this.#options));
+    return this.#attachInventory(state2);
+  }
+  async syncProgress(request) {
+    const directRequest = withDirectIdentity(request);
+    assertValidSyncParams(directRequest, this.#config);
+    return this.sync(directRequest.rallyId, directRequest.userId);
+  }
+  async #attachInventory(state2) {
+    const rewardRemaining = {};
+    for (const reward of this.#config.rewards) {
+      const plan = inventoryPlan(this.#config, reward.id, reward.stockLimit);
+      if (plan.secondaryKey !== void 0) {
+        const stock = await this.#persistence.getRewardStock(state2.rallyId, plan.secondaryKey);
+        const remaining = stock ?? plan.secondaryInitial ?? null;
+        if (remaining !== null) rewardRemaining[reward.id] = Math.max(0, remaining);
+      } else if (plan.primaryKey !== "__shared__") {
+        const stock = await this.#persistence.getRewardStock(state2.rallyId, plan.primaryKey);
+        const remaining = stock ?? plan.primaryInitial;
+        if (remaining !== null) rewardRemaining[reward.id] = Math.max(0, remaining);
+      }
+    }
+    const shared = sharedStock(this.#config);
+    const storedShared = await this.#persistence.getRewardStock(state2.rallyId, "__shared__");
+    const sharedRemaining = this.#config.inventoryMode === "shared" && shared !== null ? Math.max(0, storedShared ?? shared) : void 0;
+    return {
+      ...state2,
+      ...Object.keys(rewardRemaining).length === 0 && sharedRemaining === void 0 ? {} : {
+        inventory: {
+          ...sharedRemaining === void 0 ? {} : { sharedRemaining },
+          ...Object.keys(rewardRemaining).length === 0 ? {} : { rewardRemaining }
+        }
+      }
+    };
   }
   async #body(request) {
     try {
@@ -740,9 +1181,14 @@ var StampRallyServer = class {
       const authenticatedUserId = identity.authenticatedUserId;
       return authenticatedUserId.length > 0 ? authenticatedUserId : null;
     }
+    const policy = this.#options.anonymousPolicy ?? "session_scoped";
+    if (policy === "reject") return null;
+    const sessionId = request.headers.get("X-Anonymous-Session-Id");
+    if (sessionId !== null) return isUuidV4(sessionId) ? sessionId : null;
+    if (policy === "session_scoped") return null;
     return "anonymous";
   }
-  async #rememberCheckInTransaction(request, timestamp, key, current, mutation, responseHolder) {
+  async #rememberCheckInTransaction(request, timestamp, key, current, mutation2, responseHolder) {
     const transaction = await this.#persistence.executeCheckInTransaction(
       {
         rallyId: request.rallyId,
@@ -753,9 +1199,9 @@ var StampRallyServer = class {
         ...this.#options.idempotencyTtlMs === void 0 ? {} : { idempotencyTtlMs: this.#options.idempotencyTtlMs },
         initialUserState: current
       },
-      () => mutation
+      () => mutation2
     );
-    if (responseHolder.value !== null && (transaction.success || transaction.error === mutation.error))
+    if (responseHolder.value !== null && (transaction.success || transaction.error === mutation2.error))
       return responseHolder.value;
     return {
       ok: false,
@@ -786,9 +1232,127 @@ var StampRallyServer = class {
   }
 };
 
+// src/testing/compliance.ts
+var state = (userId) => ({
+  rallyId: "compliance-rally",
+  userId,
+  records: [],
+  rewards: [{ rewardId: "reward", status: "AVAILABLE" }],
+  updatedAt: "2026-01-01T00:00:00.000Z"
+});
+function audit2(idempotencyKey, userId) {
+  return {
+    id: `audit-${idempotencyKey}`,
+    timestamp: "2026-01-01T00:00:00.000Z",
+    rallyId: "compliance-rally",
+    userId,
+    action: "CLAIM_REWARD",
+    resourceId: "reward",
+    status: "SUCCESS",
+    idempotencyKey
+  };
+}
+function params(userId, idempotencyKey) {
+  return {
+    rallyId: "compliance-rally",
+    userId,
+    rewardId: "reward",
+    ticketNumber: `ticket-${idempotencyKey}`,
+    timestamp: Date.parse("2026-01-01T00:00:00.000Z"),
+    idempotencyKey,
+    rewardStockLimit: 1,
+    sharedStockLimit: 1,
+    stockKey: "__shared__",
+    secondaryStockKey: "reward",
+    initialStock: 1,
+    initialSecondaryStock: 1,
+    initialUserState: state(userId)
+  };
+}
+function mutation(current) {
+  if (current.stock === 0 || current.secondaryStock === 0)
+    return {
+      nextStock: current.stock,
+      nextSecondaryStock: current.secondaryStock,
+      nextUserState: current.userState,
+      auditLog: audit2("rejected", current.userState.userId ?? "unknown"),
+      error: "OUT_OF_STOCK"
+    };
+  return {
+    nextStock: current.stock === null ? null : current.stock - 1,
+    nextSecondaryStock: current.secondaryStock === null ? null : current.secondaryStock - 1,
+    nextUserState: {
+      ...current.userState,
+      rewards: [{ rewardId: "reward", status: "CONSUMED" }],
+      updatedAt: "2026-01-01T00:00:00.000Z"
+    },
+    auditLog: audit2("success", current.userState.userId ?? "unknown"),
+    result: { ok: true }
+  };
+}
+function assert(condition, message) {
+  if (!condition) throw new Error(`Persistence adapter compliance failed: ${message}`);
+}
+async function runPersistenceAdapterComplianceTests(createAdapter) {
+  const adapter = await createAdapter();
+  assert(
+    adapter.supportsRewardStock !== false,
+    "the adapter must explicitly support reward stock for this suite"
+  );
+  const [first, second] = await Promise.all([
+    adapter.executeClaimRewardTransaction(params("alice", "race-a"), mutation),
+    adapter.executeClaimRewardTransaction(params("bob", "race-b"), mutation)
+  ]);
+  assert([first.success, second.success].filter(Boolean).length === 1, "race was not serialized");
+  assert(
+    await adapter.getRewardStock("compliance-rally", "__shared__") === 0,
+    "shared stock was not decremented atomically"
+  );
+  assert(
+    await adapter.getRewardStock("compliance-rally", "reward") === 0,
+    "per-reward stock was not decremented atomically"
+  );
+  const idempotentAdapter = await createAdapter();
+  const idempotentParams = params("alice", "same-key");
+  const firstClaim = await idempotentAdapter.executeClaimRewardTransaction(
+    idempotentParams,
+    mutation
+  );
+  const secondClaim = await idempotentAdapter.executeClaimRewardTransaction(
+    idempotentParams,
+    mutation
+  );
+  assert(firstClaim.success && secondClaim.success, "idempotent claim did not remain successful");
+  assert(
+    await idempotentAdapter.getRewardStock("compliance-rally", "__shared__") === 0,
+    "idempotent retry decremented shared stock twice"
+  );
+  const rollbackAdapter = await createAdapter();
+  const rollbackParams = params("alice", "rollback");
+  const rollback = await rollbackAdapter.executeClaimRewardTransaction(rollbackParams, () => {
+    throw new Error("forced rollback");
+  });
+  assert(!rollback.success, "a failed mutation was committed");
+  assert(
+    await rollbackAdapter.getRewardStock("compliance-rally", "__shared__") === null,
+    "rollback changed shared stock"
+  );
+  assert(
+    await rollbackAdapter.getRewardStock("compliance-rally", "reward") === null,
+    "rollback changed per-reward stock"
+  );
+}
+
 exports.InMemoryServerPersistenceAdapter = InMemoryServerPersistenceAdapter;
+exports.RequestValidationException = RequestValidationException;
 exports.StampRallyServer = StampRallyServer;
+exports.assertValidCheckInParams = assertValidCheckInParams;
+exports.assertValidClaimParams = assertValidClaimParams;
+exports.assertValidSyncParams = assertValidSyncParams;
+exports.executeCheckInTransaction = executeCheckInTransaction;
 exports.executeClaimRewardTransaction = executeClaimRewardTransaction;
+exports.executeRedisTransaction = executeRedisTransaction;
+exports.runPersistenceAdapterComplianceTests = runPersistenceAdapterComplianceTests;
 exports.validateCheckInRequest = validateCheckInRequest;
 exports.validateClaimRewardRequest = validateClaimRewardRequest;
 exports.validateSyncRequest = validateSyncRequest;