Sprint 10: hardening & release readiness — backlog burn-down, reactive identify, npm rehearsal

[hynding]

Summary

Implements the Sprint 10 plan (docs/superpowers/plans/2026-07-09-sprint-10-hardening-release.md) — the consolidation sprint: the entire seven-issue backlog closed, one cross-cutting integrator fix, and the npm release pipeline rehearsed end to end.

• Reactive identify() (the sprint's one feature): SDK onUserChange listener (fires only on real identity change, per-listener exception guard — retrofitted onto onUnlock too); PromoceanProvider mirrors the identity into context (usePromoceanUser() hook; usePromocean() unchanged); every identity-gated widget (Leaderboard, RewardsStore, BadgeCabinet) live-updates on login-after-load and user switching — no more remount-via-key. Demo gains a "Switch user" control exercising the path live; e2e asserts it.
• Backlog burn-down — Closes Harden widget toast state + SDK error-status edge #5, Closes Stats endpoint polish bundle #15, Closes Post-Sprint-6 follow-ups: unlock-crossing race test, Docker image hygiene #18, Closes CMS reward lifecycles: live admin-session verification + legacy duplicate-staticCode scan #20, Closes Widgets test hardening: RewardsStore async edges + shared currentUserId reactivity #21, Closes Recurrence scale hygiene: delivered-claims retention, per-tick cost, stats bind params #23, Closes CMS: verify legacy-NULL recurrence rows against the $ne scan filter #24:
  • Harden widget toast state + SDK error-status edge #5: monotonic toast ids (same-millisecond collisions fixed), BadgeCabinet keep-stale + warn, SDK retry loop throws the TRUE final failure (network-final → plain Error, not a stale-status ApiError)
  • Stats endpoint polish bundle #15: stats accepts offset-form ISO datetimes; uniform 403 docs across all five sk endpoints; disabled-events inclusion documented; dead placements userId param removed (route + OpenAPI)
  • Post-Sprint-6 follow-ups: unlock-crossing race test, Docker image hygiene #18: 8-way unlock-crossing race test (exactly one unlock + one bonus); race pair parameterized; Docker runner stages trimmed — api image 549MB → 295MB (−46%), cms 1.24GB → 1.16GB
  • CMS reward lifecycles: live admin-session verification + legacy duplicate-staticCode scan #20 + CMS: verify legacy-NULL recurrence rows against the $ne scan filter #24: durable apps/cms/scripts/verify-lifecycles.ts (admin-session relation-shape probe, duplicate-staticCode scan, legacy-NULL recurrence probe with opt-in --fix; localhost blast-radius guard) — both probes found no real defects: all relation shapes fire the uniqueness checks; NULL recurrence behaves identically to 'none'
  • Widgets test hardening: RewardsStore async edges + shared currentUserId reactivity #21: RewardsStore async-edge tests + the all-widgets reactivity decision, fully delivered
  • Recurrence scale hygiene: delivered-claims retention, per-tick cost, stats bind params #23: delivered-claims TTL sweep (DELIVERED_CLAIMS_TTL_DAYS, default 30, floor-clamped to 1); per-tick cost documented; stats totals chunked per 50 events with cross-chunk DISTINCT dedup
• S7 notes: user_streaks composite PK (migration 0009, additive-safe, survival-tested on populated tables); shared isValidUserId; ordering-tiebreak sweep (one addition: coupon validate selection)
• Dead code removed: EventStore/PgEventStore, ProgressStore.setProgress
• Release rehearsal (prep only, no public publish): six sprints of changesets consumed — contracts/sdk/widgets versioned 0.0.1 → 0.1.0 with CHANGELOGs; pack lists validated (dist-only, workspace:* rewritten); published to a local verdaccio + scratch-project install/import smoke passed with zero findings; RELEASING.md documents the flow and the one manual step for going public (npm org + NPM_TOKEN secret, then dispatch release.yml)

The one that mattered

The final whole-branch review caught a live release hazard the rehearsal itself had missed: changeset publish filters only on package.json.private and never consults the changeset ignore list (verified against the CLI source) — the first real release dispatch would have published the GPL-licensed internal packages (core, adapter-db, adapter-strapi, config, api) to the public registry with src/ included. Fixed in f371754: all five are now private: true, RELEASING.md's incorrect safety claim corrected, and an explicit pnpm publish -r warning added. The dry-run now lists exactly the three MIT packages.

Behavior notes for existing consumers

• Widgets now re-render on identify()/re-identify — apps that remounted via a key prop can remove that workaround (README migration note). Context internals changed but usePromocean() is signature-identical.
• SDK: exhausted retries ending in a network error now throw a plain Error (previously a PromoceanApiError carrying a stale earlier 5xx status). All-5xx runs are unchanged.
• GET /v1/stats accepts offset-form ISO datetimes (+02:00); placements GET no longer accepts/documents a userId query param (it was consumed by nothing since Sprint 5).
• Migration 0009 (composite PK on user_streaks) is additive-safe; migration runs at boot as usual.
• Packages versioned to 0.1.0; internal packages are now explicitly private: true.

Test plan

• Full turbo 27–30/30 green throughout (contracts 75, sdk 52, widgets 46, adapter-db 81, api 188, adapter-strapi 53 post-fix-wave)
• Fresh-volume compose stack: 8/8 Playwright specs green incl. the new switch-user reactivity assertions
• Live verifications: cms probe suite run against a disposable DB (incl. injected-defect discrimination checks); trimmed images booted with healthchecks + smoke; verdaccio publish → scratch install → import/execute smoke, first-run clean
• CMS verification script is now a checked-in tool: pnpm --filter cms verify:lifecycles

Review notes

Eight tasks through the full gate cycle (three fix waves: widgets no-op-notify discriminating test, cms script error-type assertions + blast-radius guards, and the final wave above) plus the whole-branch review — verdict ready to merge after f371754, all seven issue closures confirmed warranted. Follow-up filed: #26 (Docker dist-list derivation, turbo typecheck self-build dep). Remaining v1.x after this sprint: config-as-code CLI, React Native SDK.

Closes #5
Closes #15
Closes #18
Closes #20
Closes #21
Closes #23
Closes #24

🤖 Generated with Claude Code