@stamprally/server 0.15.0 → 0.16.0

package/dist/index.cjs

@@ -3,50 +3,52 @@
 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);
+      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, params, next.nextSecondaryStock);
+          await store.writeSecondaryStock(transaction, params2, next.nextSecondaryStock);
       }
-      await store.writeUserState(transaction, params, next.nextUserState);
-      await store.writeClaimRecord(transaction, params, next.nextUserState);
+      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 (error) {
     return { success: false, error: error instanceof Error ? error.message : String(error) };
   }
 }
-async function executeCheckInTransaction(database, store, params, mutation, current) {
+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, params));
-      const next = mutation({ userState });
+      })() : await store.readUserState(transaction, params2));
+      const next = mutation2({ userState });
       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 };
       }
-      await store.writeUserState(transaction, params, next.nextUserState);
+      await store.writeUserState(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 (error) {
@@ -66,6 +68,7 @@ async function executeRedisTransaction(redis, queue) {
 
 // src/persistence.ts
 var InMemoryServerPersistenceAdapter = class {
+  supportsRewardStock = true;
   #locks = /* @__PURE__ */ new Map();
   #idempotent = /* @__PURE__ */ new Map();
   #states = /* @__PURE__ */ new Map();
@@ -74,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();
@@ -122,51 +126,60 @@ 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 storedStock = await this.getRewardStock(
-          params.rallyId,
-          params.stockKey ?? params.rewardId
+          params2.rallyId,
+          params2.stockKey ?? params2.rewardId
         );
-        const storedSecondaryStock = params.secondaryStockKey === void 0 ? null : await this.getRewardStock(params.rallyId, params.secondaryStockKey);
-        const mutationResult = mutation({
-          stock: storedStock ?? params.initialStock ?? null,
-          secondaryStock: storedSecondaryStock ?? params.initialSecondaryStock ?? null,
-          claimCount: await this.getUserClaimCount(params.rallyId, params.userId, params.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.stockKey ?? params.rewardId
+          params2.rallyId,
+          params2.stockKey ?? params2.rewardId
         );
-        const effectiveStock = currentStock ?? params.initialStock ?? null;
-        if (currentStock === null && params.initialStock !== void 0 && params.initialStock !== null)
+        const effectiveStock = currentStock ?? initialStock;
+        if (currentStock === null && initialStock !== void 0 && initialStock !== null)
           this.#stocks.set(
-            this.#stockKey(params.rallyId, params.stockKey ?? params.rewardId),
-            params.initialStock
+            this.#stockKey(params2.rallyId, params2.stockKey ?? params2.rewardId),
+            initialStock
           );
-        const currentSecondaryStock = params.secondaryStockKey === void 0 ? null : await this.getRewardStock(params.rallyId, params.secondaryStockKey);
-        const effectiveSecondaryStock = currentSecondaryStock ?? params.initialSecondaryStock ?? null;
-        if (currentSecondaryStock === null && params.secondaryStockKey !== void 0 && params.initialSecondaryStock !== void 0 && params.initialSecondaryStock !== null)
+        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(params.rallyId, params.secondaryStockKey),
-            params.initialSecondaryStock
+            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.");
@@ -174,10 +187,10 @@ var InMemoryServerPersistenceAdapter = class {
           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.stockKey ?? params.rewardId),
+            this.#stockKey(params2.rallyId, params2.stockKey ?? params2.rewardId),
             mutationResult.nextStock
           );
-        if (params.secondaryStockKey !== void 0 && mutationResult.nextSecondaryStock !== void 0) {
+        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)
@@ -186,29 +199,29 @@ var InMemoryServerPersistenceAdapter = class {
             );
           if (mutationResult.nextSecondaryStock !== null)
             this.#stocks.set(
-              this.#stockKey(params.rallyId, params.secondaryStockKey),
+              this.#stockKey(params2.rallyId, params2.secondaryStockKey),
               mutationResult.nextSecondaryStock
             );
         }
-        await this.saveUserState(params.rallyId, params.userId, mutationResult.nextUserState);
+        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 };
       });
@@ -216,32 +229,32 @@ var InMemoryServerPersistenceAdapter = class {
       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 };
       });
@@ -275,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));
@@ -288,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}`;
@@ -312,44 +325,64 @@ 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);
+    return this.recordUserClaim(params2);
   }
-  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 (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;
-    }
+  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
+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 };
 }
@@ -463,7 +496,7 @@ function validateClaimRewardRequest(value) {
     });
   if (value.staffId !== void 0 && !nonEmpty(value.staffId))
     return errors({ path: "staffId", message: "staffId must be non-empty.", code: "INVALID_TYPE" });
-  if (value.now !== void 0 && !nonEmpty(value.now))
+  if (value.now !== void 0 && !dateInput(value.now))
     return errors({
       path: "now",
       message: "now must be an ISO 8601 date or positive timestamp.",
@@ -471,6 +504,76 @@ function validateClaimRewardRequest(value) {
     });
   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) {
   const required = requiredErrors(value, ["rallyId"]);
   if (required.length > 0) return errors(...required);
@@ -478,7 +581,10 @@ function validateSyncRequest(value) {
     return errors({ path: "$", message: "Expected an object.", code: "INVALID_TYPE" });
   if (value.userId !== void 0 && !nonEmpty(value.userId))
     return errors({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
-  return { success: true, data: value };
+  return {
+    success: true,
+    data: value
+  };
 }
 function json(body, status = 200) {
   return new Response(JSON.stringify(body), {
@@ -574,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;
@@ -609,7 +727,18 @@ var StampRallyServer = class {
         { 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
@@ -632,7 +761,18 @@ var StampRallyServer = class {
         { 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
@@ -655,16 +795,32 @@ var StampRallyServer = class {
         { 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,
@@ -673,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,
@@ -693,7 +849,7 @@ var StampRallyServer = class {
           message: "Spot was not found."
         };
         return await this.#rememberCheckInTransaction(
-          request,
+          directRequest,
           timestamp,
           key,
           current,
@@ -717,7 +873,7 @@ var StampRallyServer = class {
       };
       if (current.records.some((record2) => record2.stampId === request.spotId))
         return await this.#rememberCheckInTransaction(
-          request,
+          directRequest,
           timestamp,
           key,
           current,
@@ -727,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,
@@ -742,7 +898,7 @@ var StampRallyServer = class {
           { rallyId: request.rallyId, spotId: request.spotId, state: current }
         ))
           return await this.#rememberCheckInTransaction(
-            request,
+            directRequest,
             timestamp,
             key,
             current,
@@ -764,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,
@@ -789,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
@@ -800,7 +959,19 @@ var StampRallyServer = class {
       return this.#rememberClaim(
         key,
         { ok: false, code: "REWARD_NOT_FOUND", message: "Reward was not found." },
-        request,
+        directRequest,
+        now(this.#options)
+      );
+    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}`;
@@ -811,7 +982,6 @@ var StampRallyServer = class {
     ))
       return { ok: false, code: "CONFLICT", message: "The reward is being claimed." };
     const timestamp = now(this.#options);
-    const plan = inventoryPlan(this.#config, reward.id, reward.stockLimit);
     try {
       const checked = await this.#persistence.getIdempotentResult(
         request.rallyId,
@@ -822,10 +992,12 @@ 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,
@@ -833,7 +1005,7 @@ var StampRallyServer = class {
           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, secondaryStock, claimCount, userState }) => {
           const storedReward = userState.rewards.find((item) => item.rewardId === reward.id) ?? {
@@ -843,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,
@@ -928,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",
@@ -951,28 +1129,34 @@ var StampRallyServer = class {
     }
   }
   async sync(rallyId, userId) {
-    const state = await this.#persistence.getUserState(rallyId, userId) ?? initialState(this.#config, userId, now(this.#options));
-    return this.#attachInventory(state);
+    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(state) {
+  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(state.rallyId, plan.secondaryKey);
+        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(state.rallyId, plan.primaryKey);
+        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(state.rallyId, "__shared__");
+    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 {
-      ...state,
+      ...state2,
       ...Object.keys(rewardRemaining).length === 0 && sharedRemaining === void 0 ? {} : {
         inventory: {
           ...sharedRemaining === void 0 ? {} : { sharedRemaining },
@@ -997,13 +1181,14 @@ var StampRallyServer = class {
       const authenticatedUserId = identity.authenticatedUserId;
       return authenticatedUserId.length > 0 ? authenticatedUserId : null;
     }
-    if (this.#options.anonymousPolicy === "reject") return 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 && isUuidV4(sessionId)) return sessionId;
-    if (this.#options.anonymousPolicy === "session_scoped") return null;
+    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,
@@ -1014,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,
@@ -1047,11 +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;