Achievements & Stats — Behavior Contract

What this feature is

Achievements turn what a user already does — buying, stashing, favoriting, ranking, reading notebooks — into badges. There are ten tracks of four tiers each, from Core Collection and Spending Milestones through Activity Streaks and Notebook Mastery, with each card carrying a rarity (Common, Rare, Epic, Legendary) worth XP toward a level and an identity title. Users see them in the Achievements Hub, on a detail screen where up to five can be pinned to their profile, in the profile’s “Active Quests” strip, and as a celebration that fires the moment something unlocks. Nothing here is entered by hand: every number is derived from the user’s own orders, stash, collection and notebooks, and the same derived numbers power the lifetime totals on the Stats tab.

How to read the contract

Every case ID below is a live test. Cases built during the feature-test programme carry their ID in the test title, so grep 'ACH-045' finds the assertion. A handful of rows point at coverage that predates the programme; those are cited by ID and file, and the test is found by its plain-English name in that file.

The behavior contract

Earning a badge

Behavior	Verified by	Tier(s)	Where
Core Collection unlocks at 5, 15, 35 and 60 strains and at no count in between, awarding the rarity XP its tier declares	ACH-001, ACH-002	A	`achievements.featuretests.test.ts`
Spending Milestones unlock at $50,$ 250, $750 and$ 2,000 of finalized spend, on exact money values with no float drift, and an order with no total contributes nothing	ACH-003, ACH-004	A	`achievements.featuretests.test.ts`
Order Milestones unlock at 3, 10, 20 and 35 orders and count only finalized orders — a draft never counts	ACH-005	A	`achievements.featuretests.test.ts`
Dispensary Explorer unlocks at 2, 4, 6 and 8 distinct shops, where casing, whitespace and punctuation differences are the same shop, and a blank shop name is not a shop	ACH-006, ACH-008	A	`achievements.featuretests.test.ts`
Deleting an order gives back the dispensary it contributed, so the distinct-shop count falls again	ACH-007	A	`achievements.featuretests.test.ts`
Strain Variety measures the least-represented of sativa, indica and hybrid, unlocking at 1, 3, 10 and 20	ACH-009	A	`achievements.featuretests.test.ts`
Changing a strain’s type moves the count one down and one up; emptying a type regresses the metric but never revokes a badge already earned	ACH-010, ACH-011	A	`achievements.featuretests.test.ts`
Activity Streaks unlock at 7, 14, 30 and 60 consecutive days	ACH-012	A	`achievements.featuretests.test.ts`
Collection Curator unlocks at 5, 15, 30 and 50 favorites	ACH-013	A	`achievements.featuretests.test.ts`
Stash Manager unlocks at 5, 15, 30 and 50 stash items, and deleting an item decrements	ACH-014	A	`achievements.featuretests.test.ts`
Notebook Mastery unlocks at 3, 10, 25 and 50 notebooks viewed, counting each notebook once however many times it is opened	ACH-015	A	`achievements.featuretests.test.ts`
The Daily Stories track’s thresholds are defined and correct, but the track is quarantined and no product path can reach it	ACH-016, ACH-017	A	`achievements.featuretests.test.ts`, `achievements.test.ts`
The Hub hides the quarantined track entirely, so 100% completion is reachable rather than permanently capped	ACH-018	B	`AchievementsHub.test.tsx`

Activity streaks

Behavior	Verified by	Tier(s)	Where
Activity on a day that sits between two runs merges them into one longer streak	ACH-020	A	`achievements.featuretests.test.ts`
Activity on the day before or after a run extends that run rather than starting a new one	ACH-021	A	`achievements.featuretests.test.ts`
Removing the activity that created a middle day splits the run in two; removing an edge day or a lone day shortens or clears it	ACH-022, ACH-023	A	`achievements.featuretests.test.ts`
Several actions on one day count as one streak day, and removing one of them does not end the streak	ACH-024	A	`achievements.featuretests.test.ts`
A morning and an evening action on the same Central day are one streak day, not two	ACH-026	A	`achievements.featuretests.test.ts`
The longest streak is a high-water mark in both directions — deleting history never inflates it and never silently rewrites it	ACH-025	A	`achievements.featuretests.test.ts`
Streaks cross month, year and leap-day boundaries without a gap, and a daylight-saving transition introduces neither a gap nor a duplicate day	ACH-027, ACH-028	A	`achievements.featuretests.test.ts`
A malformed day key is rejected rather than silently shifting a streak	ACH-029	A	`achievements.featuretests.test.ts`
A story-view streak counts the server’s day, not the moment the row happened to be written	ACH-030	A	`achievements.featuretests.test.ts`

Unlocking exactly once

Behavior	Verified by	Tier(s)	Where
Running the engine repeatedly over unchanged data awards nothing new	ACH-040	A	`achievements.test.ts`
The engine does no work when it has already evaluated the current revision of a user’s numbers	ACH-041	A	`achievements.featuretests.part2.test.ts`
A user whose numbers are not yet materialized is never evaluated, so no badge is awarded from a partial picture	ACH-042, ACH-054	A	`achievements.featuretests.part2.test.ts`
Every badge unlocked in one evaluation shares a batch id and an unlock time, which is what makes it a single celebration	ACH-043	A	`achievements.featuretests.part2.test.ts`
A bulk import produces one celebration batch, not one per row, and a long serial burst arms exactly one evaluation while still evaluating every revision	ACH-052, ACH-052c	A	`achievements.featuretests.part2.test.ts`
Rapid concurrent increments coalesce into one evaluation, and two engine runs in flight never double-award	ACH-050, ACH-051	A	`achievements.featuretests.part2.test.ts`
XP is never revoked: a badge survives deletion of the data that earned it, and re-earning it awards nothing a second time	ACH-048, ACH-049	A	`achievements.test.ts`, `achievements.featuretests.part2.test.ts`
A level change is reported only when the level actually moves, and the level curve is exact at every boundary from 1 to 25	ACH-044, ACH-045	A	`achievements.featuretests.part2.test.ts`
A user with no profile gets one created on their first unlock	ACH-046	A	`achievements.featuretests.part2.test.ts`
The profile’s metric snapshot is written when the numbers changed and skipped when they are identical	ACH-047	A	`achievements.featuretests.part2.test.ts`
A projection that would go negative fails loudly inside the write rather than persisting an impossible count	ACH-053	A	`achievements.featuretests.part2.test.ts`

Derived numbers always reconcile with source data

Behavior	Verified by	Tier(s)	Where
Every rewritten lifetime query answers identically whether it reads the projection or recomputes from source — the two paths are compared over the same settled data	STATS-001	A	`statsProjection.test.ts`
The projection reports exactly what the underlying rows imply: drafts count as orders but not as spend, an untyped line joins the distinct-strain union without landing in a type bucket, and an untrackable unit is a purchase of zero grams	STATS-002	A	`statsProjection.test.ts`
Reading lifetime numbers never scans the source tables — 1,200 rows inserted behind the triggers move nothing a read returns	STATS-003	A	`statsProjection.test.ts`
A heavy user’s hundreds of source documents compress into a handful of roll-up rows without losing a number	STATS-004	A	`statsProjection.test.ts`
Deleting an order reverses every counter exactly, including the earliest- and largest-purchase values a plain counter cannot recover	STATS-005	A	`statsProjection.test.ts`
Un-finalizing and re-finalizing an order round-trips to the same numbers, and adding a line to an existing order updates its shop roll-up instead of emptying it	STATS-006, STATS-011	A	`statsProjection.test.ts`
Renaming a shop moves its whole roll-up — spend and gram totals together	STATS-007	A	`statsProjection.test.ts`
A user whose projection does not exist yet still gets correct numbers, computed from source, rather than confident zeroes	STATS-008	A	`statsProjection.test.ts`
One user’s roll-ups are never visible to another	STATS-009	A	`statsProjection.test.ts`
Cent-precise amounts that cancel out settle to a clean zero rather than throwing on floating-point residue, in either direction	STATS-014	A	`statsProjection.test.ts`
A forty-line import writes one history event and forty counted lines	STATS-015	A	`statsProjection.test.ts`
A source write after the queue has fully drained re-arms exactly one evaluation	STATS-012	A	`statsProjection.test.ts`

Backfilling a user whose history predates the projection

Behavior	Verified by	Tier(s)	Where
A full backfill replays every stage with pagination and finishes only if it matches a full-history recount	ACH-060, STATS-010	A	`achievements.test.ts`, `statsProjection.test.ts`
A legacy user’s first write materializes their real totals rather than starting them from that one write	ACH-061	A	`achievements.featuretests.part2.test.ts`
A backfill refuses to start for a user who is already materialized, resumes an interrupted job from its cursor, and refuses a job that has already drifted	ACH-062, ACH-063, ACH-064	A	`achievements.featuretests.part2.test.ts`
When the replayed numbers disagree with the recount, the job is parked as drifted instead of publishing a wrong total	ACH-065	A	`achievements.featuretests.part2.test.ts`
A successful backfill schedules an evaluation so the badges the user had already earned appear	ACH-066	A	`achievements.featuretests.part2.test.ts`
Replaying a backfill counts nothing twice, and it counts only finalized orders	ACH-067, ACH-068	A	`achievements.featuretests.part2.test.ts`
The one-shot V1→V2 migration is safe to run again and pages rather than collecting whole tables	ACH-069	A	`achievements.featuretests.part2.test.ts`
Re-keying collapsed dispensary references merges the shops that were duplicates and reclaims the distinct-shop count	STATS-013	A	`statsProjection.test.ts`

Who can see and change what

Behavior	Verified by	Tier(s)	Where
Every achievement query rejects a caller whose owner key does not match the signed-in user, and rejects an unauthenticated caller outright	ACH-080, ACH-081	A	`achievements.featuretests.part2.test.ts`
There is no client-writable unlock surface — a badge cannot be granted from a client, only earned	ACH-082	A	`achievements.featuretests.part2.test.ts`
Pinning a badge requires a matching owner key, so a pin landing after an account switch cannot overwrite the new account’s pinned list	ACH-084, ACH-085	A	`achievementUnlocks.test.ts`, `achievements.featuretests.part2.test.ts`
The pinned list caps at five, de-duplicates, drops ids the user has not unlocked, and the dashboard filters stale pins out of older profiles	ACH-086, ACH-087	A	`achievementUnlocks.test.ts`
One user’s unlocks never appear for another	ACH-091	A	`achievements.featuretests.part2.test.ts`
Deleting an account purges all nine achievement tables	ACH-088	A	`achievements.featuretests.part2.test.ts`
A data export contains the user’s profile and unlocks but not the internal projection	ACH-089	A	`achievements.featuretests.part2.test.ts`

Reading achievements in the app

Behavior	Verified by	Tier(s)	Where
The hooks send exactly the arguments each deployed validator declares	ACH-100	B	`useAchievementsV2.featuretests.test.tsx`
The XP and level shown are the server’s, never a client recomputation from unlock rows	ACH-105	B	`useAchievementsV2.featuretests.test.tsx`
A gated or disabled achievements view returns a zero result without subscribing, and renders the mock dashboard behind the access gate	ACH-112, ACH-113	B	`useAchievementsV2.featuretests.test.tsx`, `AchievementsHub.test.tsx`
The screen distinguishes loading, offline, empty, error, gated and ready — six states, not two	ACH-101	B	`achievementOfflineState.test.ts`, `achievementQueryState.test.ts`
Switching accounts and back never shows the first account’s values, and a cold offline launch is visibly different from “locked with zero progress”	ACH-102, ACH-103	B	`AchievementsColdOffline.test.tsx`
Legacy unlock rows are filtered out of the V2 view	ACH-104	B	`achievements-utils.test.ts`
Progress reads at most 99.9% while locked and exactly 100% only once unlocked, and each track’s progress comes from its own metric with no cross-wiring	ACH-110, ACH-111	B	`AchievementsHub.test.tsx`
The identity title resolves for every track × rarity rule with both fallbacks, breaking an XP tie by the most recent unlock	ACH-106, ACH-107	B	`achievements-v2.featuretests.test.ts`
”Almost there” nudges start at 70% of a threshold and stop once it is met	ACH-109	B	`achievements-v2.featuretests.test.ts`
Active Quests shows at most three nearest badges and never one with zero progress	ACH-108	B	`achievements-v2.config.test.ts`
The Hub’s layout, header count, filters and enlarged-text rendering hold, and a detail screen for an unknown badge id degrades gracefully	ACH-114, ACH-115	B	`AchievementsHubLayout.test.tsx`, `AchievementsColdOffline.test.tsx`

Celebrating an unlock

Behavior	Verified by	Tier(s)	Where
One new badge is a toast, two or three a modal, four or more a batch	ACH-120	B	`celebration.helpers.test.ts`
The first run after install marks everything as already seen and replays nothing	ACH-121	B	`AchievementsCelebration.test.tsx`
Dismissing a celebration remembers the newest badge it covered, and it stays dismissed across a remount	ACH-122	B	`AchievementsCelebration.test.tsx`
Rapid unlocks are debounced into one surface rather than a queue of popups	ACH-123	B	`AchievementsCelebration.test.tsx`
Once the unlock window is saturated the count is shown as partial rather than as an exact number	ACH-124	B	`AchievementsCelebration.test.tsx`
An unrecognized badge id in the feed is skipped without crashing or wedging the celebration host	ACH-125	B	`AchievementsCelebration.test.tsx`
A celebration that arrives while a native sheet is open is held and played afterwards, not dropped	ACH-126	B	`AchievementsCelebration.test.tsx`
A second engine run sharing the first run’s timestamp is still celebrated, not swallowed	ACH-130	B	`AchievementsCelebration.test.tsx`
A failed pin leaves the sheet open to retry rather than closing on an error	ACH-129	B	`AchievementsCelebration.test.tsx`
Switching accounts clears in-flight celebration state before anything paints, and the pinned-badge query is subscribed only while a modal is actually visible	ACH-127, ACH-128	B	`CelebrationHost.test.tsx`
Toast, modal and batch all render every rarity and survive long copy	ACH-131	B	`AchievementsCelebration.test.tsx`

What the live tier proves end-to-end

Tier C runs against the deployed staging backend. Because thresholds are one-shot, each case uses a brand-new, really-signed-in identity and deletes it afterwards.

A real order placed through the deployed backend produces a real unlock (ACH-140).
A spending threshold crosses on cent-precise real money with no float drift, and the teardown that reverses it settles to a clean zero (ACH-141).
Shops whose names differ only by casing, whitespace or trailing punctuation collapse to one dispensary under the production identity rules (ACH-142).
Five real stash writes unlock the first Stash Manager tier and open a one-day streak (ACH-143); three distinct notebook views unlock the first Notebook Mastery tier while a repeat view is ignored (ACH-145).
All five public achievement functions accept the literal payloads the app sends (ACH-146), and deleting the source orders leaves the unlock standing (ACH-147).
The celebration feed comes back newest-first with one shared batch id per engine run, and a pin round-trips and normalizes (ACH-148, ACH-149).
Ten parallel writes yield one consistent evaluation, not ten (ACH-151).
No client-writable unlock surface exists on the deployed backend, and the deployed validator rejects a pin without an owner key (ACH-154, ACH-085C).

Deliberate gaps & conditions

The Daily Stories track is a deliberate product quarantine, not a bug. All ten tracks remain defined in the rules so no earned badge is ever rewritten, but there is no story producer, the feature flag is hard-disabled, and the track is excluded from the visible set — nine tracks and thirty-six cards. ACH-016 proves the thresholds are correct; ACH-017 proves the product path cannot reach them; ACH-018 proves the Hub hides the track so completion is not permanently capped.
There is no steady-state drift detector. ACH-070 is blocked because the thing it would test does not exist. Drift is caught at backfill time (ACH-065) and by the differential in STATS-001, not by a scheduled reconciliation.
The backfill has no client-callable entry point, so ACH-152 cannot run a real backfill against staging. Backfill correctness is proved at Tier A instead (ACH-060 – ACH-069, STATS-010).
The recent-unlocks limit clamp landed after ACH-090 was written; the row is buildable now and is the one remaining deferred case in this area.
Engine latency has no budget test (ACH-150). Asserting a p95 would need ten repeat runs on a fresh identity each time, and a flaky timing gate is worse signal than none.
Cross-feature chains are proved once, in the owning suite. The order → stash → achievement chain and account-deletion-clears-achievements are asserted in the orders and users integration suites rather than duplicated here (ACH-144, ACH-153).
Tier C skips cleanly without credentials, naming exactly what is missing, and is never part of pnpm test, pnpm check, or a cached Turbo run.

Where to extend

A new track, threshold, streak rule, or projection counter gets its Tier A case in apps/mobile/convex/tests/achievements.featuretests.test.ts (metrics and streaks), achievements.featuretests.part2.test.ts (engine, backfill, auth), or apps/mobile/convex/tests/statsProjection.test.ts (anything a lifetime number depends on). A new hook argument or rendered state goes in the co-located useAchievementsV2.featuretests.test.tsx / achievements-v2.featuretests.test.ts, or in apps/mobile/test/ui/features/AchievementsHub.test.tsx / AchievementsCelebration.test.tsx. Reach for apps/mobile/test/integration/suites/achievements.integration.test.ts only when the claim is about the deployed backend — and remember every threshold there needs a fresh identity. Then add the row to the master matrix; see Mobile Feature Test Platform for naming, tags, and the tier decision.

Product Strategy

Roadmap

Testing & Quality

Notebooks

Core Features

AI & Media

Growth & Social

Personalization

Infrastructure & Costs

Pricing & Strategy

Achievements & Stats — Behavior Contract

What this feature is

How to read the contract

The behavior contract

Earning a badge

Activity streaks

Unlocking exactly once

Derived numbers always reconcile with source data

Backfilling a user whose history predates the projection

Who can see and change what

Reading achievements in the app

Celebrating an unlock

What the live tier proves end-to-end

Deliberate gaps & conditions

Where to extend

​What this feature is

​How to read the contract

​The behavior contract

​Earning a badge

​Activity streaks

​Unlocking exactly once

​Derived numbers always reconcile with source data

​Backfilling a user whose history predates the projection

​Who can see and change what

​Reading achievements in the app

​Celebrating an unlock

​What the live tier proves end-to-end

​Deliberate gaps & conditions

​Where to extend

What this feature is

How to read the contract

The behavior contract

Earning a badge

Activity streaks

Unlocking exactly once

Derived numbers always reconcile with source data

Backfilling a user whose history predates the projection

Who can see and change what

Reading achievements in the app

Celebrating an unlock

What the live tier proves end-to-end

Deliberate gaps & conditions

Where to extend