Sprint 7: engagement mechanics — points wallet, leaderboards, streaks

[hynding]

Summary

Implements the Sprint 7 plan (docs/superpowers/plans/2026-07-08-sprint-7-engagement.md) — the v1.x engagement trio in thin, demo-visible slices, built on the transactional ingestion substrate from Sprint 5:

• Points ledger + wallet: append-only points_ledger written inside the ingestion transaction (dedup/rollback semantics inherited — a replayed event or unlock awards nothing); points flow from per-event rules (project.pointRules) and achievement unlock bonuses (pointsValue); GET /v1/users/:id/wallet returns the computed balance + last 20 entries
• Leaderboards: GET /v1/leaderboard?window=all|7d|30d&limit=1..100 — SUM(delta) ranked, deterministic ties, windowed by ledger timestamps; <Leaderboard> widget highlights the current user
• Streaks: consecutive-local-day counter maintained in the same transaction via SELECT ... FOR UPDATE (race-tested); the SDK auto-sends the device tz offset per event, with an always-lenient schema (catch(undefined)) so an invalid offset degrades to UTC-day rather than 400ing the track
• SDK: getWallet(), getStreak(), getLeaderboard(opts), currentUserId getter
• Demo + e2e: wallet/streak readouts + leaderboard; new engagement e2e asserts the exact seeded math (10 rule + 50 bonus = 60) against a fresh-seeded compose stack

Behavior notes

• No existing wire shapes changed — tzOffsetMinutes is additive; three new pk endpoints (rate-limit + auth middleware inherited)
• Leaderboard privacy posture (documented): entries expose external user ids to any pk holder — host apps map ids to display names; pass opaque ids to identify() for pseudonymity. Wallet/streak reads for arbitrary userIds match the pre-existing GET /v1/users/:id/achievements posture — not a new grant, but the leaderboard makes id discovery easier
• Timed-event multipliers apply to achievement progress only; point awards are never multiplied (documented in READMEs; a "double points" mechanic is future work)
• Streaks are always-on (every ingest carries the streak lock-compute-write + a cached pointRules fetch); the points feature is what goes dormant when nothing is configured
• Erasure extended: DELETE /v1/users/:id now also removes points_ledger + user_streaks rows (counts additive in the response)

Test plan

• 27/27 turbo tasks green post fix-wave (contracts 42, core 56, adapter-db 41 Testcontainers incl. FOR UPDATE race + rollback + erasure matrix, sdk 32, api 135)
• Fresh-seeded compose stack: all 4 Playwright specs green incl. the new engagement loop; hand-curl confirmed wallet=60, streak=1, leaderboard row=60
• CI runs on this PR (test + compose e2e) — first CI run of the branch; treat green checks as the merge precondition

Review notes

Nine tasks through the full gate cycle (four fix→re-review loops: zod idiom equivalents, seed coherence, api boundary tests) plus a final whole-branch review — verdict ready to merge with fixes; fix wave 53606d0 applied and re-approved: the erasure gap (the one Critical — erased users would have persisted on the leaderboard), spec-lenient tz schema, multiplier docs, wallet-order determinism, Node-portability nit, Math.floor guard. Delivers the third v1.x roadmap slice (leaderboards, streaks, points/XP wallet).

🤖 Generated with Claude Code