[kris1027]

What

Signed in users can now set a game's status on /games/{id} (Want to play, Playing, Finished) and give it a personal score from 1 to 10. Clicking the pill that is already on removes the game. Removing a game, or losing a score by moving back to Want to play, shows a toast with Undo.

Why

Implements spec 0026, scope feature G4 in docs/scope/games.md. It builds on the user_game_state table from spec 0024 and the game page from spec 0025. Options and reasoning are in rationale.md.

Changes

• Database: a new migration 20261024120000_game_tracking_functions.sql adds five security invoker functions: set_game_status, rate_game, remove_game, restore_game_status and restore_removed_game. Each is granted to authenticated only and writes auth.uid() itself, so RLS still applies. set_game_status locks the row before it reads the old values, so two tabs never get the same Undo payload. The restores refuse (P0002) outside a 10 minute window. A score on a game with no row, or on Want to play, is refused with a new code, BS004. There is no new table or column.
• Server Actions (app/games/actions.ts): setGameStatus, setGameRating, removeGame, restoreGameStatus and restoreRemovedGame. They share one order: Zod parse, then the session check, then the IGDB check and the release check, then the write under the user's JWT, then refresh(). None of them throws or redirects. IGDB is only called when a write could move a game forward. Removing, clearing a score and both restores skip IGDB, so they still work during an IGDB outage, on a hidden game, or before release. Clearing a score only touches a row that has a score.
• Release gate: before a game's first release (UTC day), Playing, Finished and scoring are disabled on the page, and the actions also refuse them with not_released. A pressed pill on an unreleased game can still be clicked to remove it.
• UI: GameTrackingSlot and GameStatusControl go in the hero's tracking slot, shaped like the movie pills. The control updates optimistically through useOptimistic and the pure reducer applyGameIntent. Moving into Finished opens the score picker when the game has no score yet. Failures roll back and show the matching toast, including a session expired toast with Sign in. Visitors see nothing in the slot, and the page shell stays prerendered.
• Shared tracking code: game types, schemas, copy, error classification (classifyGameTrackingError) and game_tracking.* log events in lib/tracking/. The release helpers live in lib/catalog/game-page.ts.
• Tests: pgTAP 190-game-tracking-functions and new grant checks in 020-security-configuration. Vitest covers the actions, the reducer, schemas, errors, the control, the slot and the release helpers. Every new action is registered in private-actions-boundary.test.ts.

How to test / verify

• Start the local stack with supabase db reset, then pnpm dev:docker. Sign in as user-a@example.test. The seed has 1942 as Playing with score 8.
• Open /games/1942. The pills show Playing pressed with score 8, and the state doesn't flicker on load.
• Click Finished: the score stays. Click Want to play: the score disappears, and the toast offers Undo, which brings back Finished, 8 and the exact dates.
• Click the pressed pill: the game is removed, and Undo brings it all back.
• On an unreleased game, you see Releases {date} or Release date to be announced, and Playing and Finished are disabled.
• Commands: pnpm test:db, pnpm db:types:check, pnpm typecheck, pnpm lint, pnpm test and pnpm build. The full manual list is in verify.md, and every step is checked off there.

Risk & rollout

• One additive migration (functions only). Per the verify record, it has already been applied to the cloud project with supabase db push, as docs/deploy.md asks before merge.
• To roll back, revert the PR. The functions can stay, because nothing else calls them.
• No feature flags. The GAMES tab stays hidden until G5, so only someone who opens /games/{id} directly sees this.
• Review: approve with nits. The three minor findings are fixed in 60e1de9: Undo rows are typed from the generated types, clearing only touches a scored row, and the spec now matches the migration. Two nits are open on purpose: a comment on why opening the picker outside the transition is safe, and a separate log outcome for errors in readGame that don't come from IGDB.

Notes for reviewers

• Worth a close look: the row lock in set_game_status, and how bestats.restore_game is turned back off on every path, including before a raise (the migration).
• The page decides the release line with requestTodayUtc(), and the action uses todayUtc(new Date()). Around UTC midnight they can disagree, so an enabled pill can still return not_released. The spec accepts this (AC-9).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
bestats	Ready	Preview	Oct 24, 2026 4:30pm UTC