Fix Hunt Week double-counting of pre-game activities

Activities logged before game start but with loggedDate on the start date
were counted in both initialState.points and getPointsInPeriod, inflating
scores unevenly across players and distorting predator/prey outcomes.

Add startedAt to miniGames schema, store it on activation, and filter
Hunt Week period activities by _creationTime > gameStartedAt to exclude
activities already baked into the initial snapshot.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cole-pierce

packages/backend/lib/miniGameCalculations.ts

@@ -266,6 +266,7 @@ export async function previewHuntWeekEnd(
   endsAt: number,
   config: any,
   participants: MiniGameParticipantData[],
+  gameStartedAt: number,
 ): Promise<{ outcomes: HuntWeekOutcome[]; totalBonusPoints: number }> {
   return calculateHuntWeekOutcomes(
     ctx,
@@ -274,6 +275,7 @@ export async function previewHuntWeekEnd(
     endsAt,
     config,
     participants,
+    gameStartedAt,
   );
 }
 
@@ -284,6 +286,7 @@ export async function calculateHuntWeekOutcomes(
   endsAt: number,
   config: any,
   participants: MiniGameParticipantData[],
+  gameStartedAt: number,
 ): Promise<{ outcomes: HuntWeekOutcome[]; totalBonusPoints: number }> {
   const catchBonus = config?.catchBonus ?? 75;
   const caughtPenalty = config?.caughtPenalty ?? 25;
@@ -294,6 +297,7 @@ export async function calculateHuntWeekOutcomes(
     startsAt,
     endsAt,
     participants,
+    gameStartedAt,
   );
   const rankMap = new Map<string, number>();
   leaderboard.forEach((entry, index) => {
@@ -354,16 +358,18 @@ async function getHuntWeekLeaderboard(
   startsAt: number,
   endsAt: number,
   participants: MiniGameParticipantData[],
+  gameStartedAt: number,
 ): Promise<LeaderboardEntry[]> {
   const entries = await Promise.all(
     participants.map(async (participant) => {
       const initialPoints = participant.initialState?.points ?? 0;
-      const periodPoints = await getPointsInPeriod(
+      const periodPoints = await getHuntWeekPointsInPeriod(
         ctx,
         participant.userId,
         challengeId,
         startsAt,
         endsAt,
+        gameStartedAt,
       );
 
       return {
@@ -505,6 +511,42 @@ export async function getPointsInPeriod(
     .reduce((sum, a) => sum + a.pointsEarned, 0);
 }
 
+/**
+ * Get total points earned by a user during a Hunt Week period.
+ *
+ * Unlike `getPointsInPeriod`, this:
+ * - Includes all non-mini-game activities (not just PR_ELIGIBLE_KINDS), since
+ *   Hunt Week rankings include bonus-kind activities.
+ * - Filters by `_creationTime > gameStartedAt` so activities that existed before
+ *   the game started (already baked into `initialState.points`) are not double-counted.
+ */
+export async function getHuntWeekPointsInPeriod(
+  ctx: ReadCtx,
+  userId: Id<"users">,
+  challengeId: Id<"challenges">,
+  startDate: number,
+  endDate: number,
+  gameStartedAt: number,
+): Promise<number> {
+  const activities = await ctx.db
+    .query("activities")
+    .withIndex("by_user_challenge_date", (q) =>
+      q.eq("userId", userId).eq("challengeId", challengeId),
+    )
+    .filter(notDeleted)
+    .collect();
+
+  return activities
+    .filter(
+      (a) =>
+        a.loggedDate >= startDate &&
+        a.loggedDate <= endDate &&
+        a.source !== "mini_game" &&
+        a._creationTime > gameStartedAt,
+    )
+    .reduce((sum, a) => sum + a.pointsEarned, 0);
+}
+
 /**
  * Get the maximum single-day points total during a time period.
  * Only includes core, special, and penalty activities (excludes bonus kind).

packages/backend/mutations/miniGames.ts

@@ -252,6 +252,7 @@ export const start = mutation({
     // Update game status
     await ctx.db.patch(args.miniGameId, {
       status: "active",
+      startedAt: now,
       updatedAt: now,
     });
 
@@ -663,6 +664,7 @@ async function calculateHuntWeekOutcomes(
     miniGame.endsAt,
     miniGame.config,
     participants,
+    miniGame.startedAt ?? miniGame.updatedAt,
   );
 
   for (const outcome of outcomes) {

packages/backend/queries/miniGames.ts

@@ -609,6 +609,7 @@ export const previewEnd = query({
         miniGame.endsAt,
         miniGame.config,
         participants,
+        miniGame.startedAt ?? miniGame.updatedAt,
       );
       return {
         type: "hunt_week" as const,

packages/backend/schema.ts

@@ -456,6 +456,7 @@ export default defineSchema({
       v.literal("completed"),
     ),
     config: v.any(), // Game-specific config (bonus percentages, point values, etc.)
+    startedAt: v.optional(v.number()), // Timestamp when game was activated (used to exclude pre-game activities)
     createdAt: v.number(),
     updatedAt: v.number(),
   })

tasks/fix-hunt-week-double-counting.md

@@ -0,0 +1,53 @@
+# Fix Hunt Week Double-Counting Bug
+
+**Date:** 2026-03-27
+
+## Root Cause
+
+`getHuntWeekLeaderboard()` computes each player's score as:
+
+```
+initialState.points + getPointsInPeriod(startsAt, endsAt)
+```
+
+- `initialState.points` is captured at game start time (e.g. 18:05:35 UTC on Mar 15).
+- `getPointsInPeriod` counts activities where `loggedDate >= startsAt`, and `startsAt` is midnight UTC (00:00:00) on Mar 15.
+- Activities logged between 00:00 UTC and 18:05 UTC on Mar 15 are already included in `initialState.points` **and** matched by the `loggedDate >= startsAt` filter — they are **double-counted**.
+
+The magnitude varies per player (depends on how many activities they logged that morning before the game started), which distorts the Hunt Week leaderboard and can flip predator/prey outcomes.
+
+## Fix (this PR)
+
+- [x] Add `startedAt` field to `miniGames` schema
+- [x] Store `startedAt: now` when a game transitions to `"active"`
+- [x] Add `getHuntWeekPointsInPeriod()` helper that filters by `_creationTime > gameStartedAt` to exclude pre-game activities
+- [x] Thread `gameStartedAt` through `getHuntWeekLeaderboard` → `calculateHuntWeekOutcomes` → `previewHuntWeekEnd`
+- [x] Pass `miniGame.startedAt ?? miniGame.updatedAt` from both mutation and query callers
+
+## Affected Data
+
+The Mar 15-21 Hunt Week game (the only Hunt Week run so far) has already been ended. Its bonus awards were calculated with the double-counted leaderboard. Specific impacts:
+
+- Players who logged activities the morning of Mar 15 before game start had inflated Hunt Week scores.
+- This may have changed who "caught" their prey and who "was caught," affecting the +75 / -25 bonus distribution.
+
+## Remediation Steps (Post-Merge)
+
+After this PR is merged and deployed, a repo admin should remediate the existing Mar 15-21 game:
+
+1. **Identify the game:** Find the Hunt Week miniGame document for Mar 15-21 in the Convex dashboard or via CLI:
+   ```bash
+   npx convex run miniGames:list '{}' --prod
+   ```
+
+2. **Revoke existing bonus awards:** Delete the `source: "mini_game"` bonus activities that were awarded when the game ended. These are the activities with descriptions like "Hunt Week Bonus" tied to participants of this game.
+
+3. **Backfill `startedAt`:** Patch the miniGame document to set `startedAt` to the original activation timestamp. Check the `updatedAt` field or Convex audit log for the exact time the game went active (should be ~18:05 UTC on Mar 15).
+   ```bash
+   npx convex run --prod miniGames:backfillStartedAt '{"miniGameId": "<id>", "startedAt": <timestamp>}'
+   ```
+   (You may need to write a small one-off mutation for this.)
+
+4. **Re-end the game:** Set the game status back to `"active"`, then call the `end` mutation again. The new code will use `startedAt` to correctly compute the leaderboard and award bonuses without double-counting.
+
+5. **Verify:** Compare the new outcomes against the original to confirm the fix resolves the discrepancy. Check that affected players' total points are updated correctly.