Collection & Rankings — Behavior Contract

What this feature is

Collection is the user’s personal library of strains. From a strain card, a strain page, the browse results, or the home screen, a user can favorite a strain, dislike it, or mark it owned, tasted, or want to try — and attach private notes to any of those. The Collection screen gathers all of it into six tabs with sorting, search, and six card layouts. Once three strains are marked owned or tasted, the user can rank them by head-to-head A/B comparison: pick one of two strains ten times per session, and an ELO rating produces a personal leaderboard. Collection is also an input to other features — it feeds the Safari shopping extension’s slug lists, two achievement tracks, Professor High’s answers, and 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 'COL-063' 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

Favoriting a strain

Behavior	Verified by	Tier(s)	Where
Tapping the heart on a strain with no library row creates one, favorited, stamped with how it was favorited and when	COL-001	A	`collection.featuretests.test.ts`
Tapping the heart twice returns the strain to neutral and leaves exactly one row behind — the row survives because the user’s notes and tags live on it	COL-002, COL-013	A	`collection.featuretests.test.ts`
A strain that has been un-favorited stops counting toward the library — the surviving row is a husk, not a collected strain	COL-160, COL-162	A	`collection.featuretests.test.ts`
Notes and tags written while a strain was favorited survive an unfavorite → refavorite cycle	COL-003	A	`collection.featuretests.test.ts`
Setting a favorite that is already set changes nothing, and un-favoriting a strain the user never collected must not add it to the library	COL-005, COL-006	A	`collection.featuretests.test.ts`
A favorite write never downgrades a strain’s stored name to a placeholder	COL-007, COL-168	A	`collection.featuretests.test.ts`
Favorite and dislike are mutually exclusive in both directions — favoriting a disliked strain clears the dislike, and vice versa	COL-004, COL-008, COL-021	A	`collection.featuretests.test.ts`, `collection.test.ts`
Every favorite toggle sends the strain’s real name, type and slug — never `'Unknown'` — and warns rather than inventing data when metadata is genuinely absent	COL-009, COL-010	B	`useCollectionPreferences.featuretests.test.tsx`
A favorite tap on the home screen is refused before the mutation is sent when the owner key does not match or the device is offline	COL-011	B	`useCollectionPreferences.featuretests.test.tsx`
The heart’s optimistic fill reverts when the mutation rejects	COL-012	B	`CollectionScreens.test.tsx`
Editing a favorite’s notes or tags is rejected on a strain that is not favorited, and an empty tag array clears the tags	COL-014, COL-015	A	`collection.featuretests.test.ts`

Disliking a strain

Behavior	Verified by	Tier(s)	Where
Disliking a strain records it in both the status list and the preference state, so no surface can disagree about it	COL-020	A	`collection.featuretests.test.ts`
A dislike recorded by an older app version is visible to every dislike surface — the Disliked tab, the strain page, stats, the extension, and Professor High all read one predicate	COL-023, COL-026	A, B	`collection.featuretests.test.ts`, `useCollectionPreferences.featuretests.test.tsx`
Removing a dislike must never clear an unrelated favorite	COL-022	A	`collection.featuretests.test.ts`
Disliking an already-disliked strain changes nothing, and a dislike reason is rejected on a strain that is not disliked	COL-024, COL-025	A	`collection.featuretests.test.ts`
Dislike statistics average potency only over the strains that actually carry THC/CBD values	COL-027	A	`collection.featuretests.test.ts`

Marking owned, tasted, or want-to-try

Behavior	Verified by	Tier(s)	Where
Marking a strain owned initializes its ranking state; marking it want-to-try does not	COL-030, COL-031	A	`collection.featuretests.test.ts`
Adding a second experienced status to a strain keeps its single existing rating rather than resetting it	COL-032	A	`collection.featuretests.test.ts`
Adding a status the strain already has is a no-op; removing one it does not have still records the interaction; and a status write may only link a stash item the caller owns	COL-034, COL-035, COL-036	A	`collection.featuretests.test.ts`
Losing the last owned/tasted status tears down that strain’s ranking state and comparison history	COL-033	A	`collection.test.ts`
A collection row created by a stash purchase carries full preference provenance, so it is reachable by every favorite and dislike projection	COL-037, COL-038	A	`collection.featuretests.test.ts`
Choosing “owned” in the edit sheet reroutes the user to the stash-add flow instead of writing a bare status	COL-039	B	`CollectionScreens.test.tsx`
Removing the last owned/tasted status warns the user that ranking data will be lost before it happens	COL-040	B	`CollectionScreens.test.tsx`
The strain-page bottom banner chooses between creating a row and updating one, forwards the full strain identity, sends an absent slug as absent rather than empty, and turns a rejected write into a message instead of a crash	COL-041	B	`collection-bottom-banner.featuretests.test.ts`
The banner’s optimistic status reconciles with the server value once it arrives	COL-042	B	`CollectionScreens.test.tsx`

Notes and removing a strain

Behavior	Verified by	Tier(s)	Where
Notes round-trip intact, including an empty string and the full 500 characters	COL-051	A	`collection.featuretests.test.ts`
The notes editor enforces the 500-character cap and shows the remaining count	COL-052	B	`CollectionScreens.test.tsx`
Notes cannot be written onto another user’s row	COL-050	A	`collection.featuretests.test.ts`
Removing a strain deletes its row and every comparison naming it, then re-ranks the survivors so ranks stay contiguous from 1	COL-053	A	`collection.featuretests.test.ts`
Removing a strain that is not in the collection reports not-found, removing another user’s row is refused, and removing a favorited strain decrements the favorite count	COL-054, COL-055, COL-056	A	`collection.featuretests.test.ts`
Removal always asks for confirmation first	COL-057	B	`CollectionScreens.test.tsx`

Ranking strains head to head

Behavior	Verified by	Tier(s)	Where
Ranking unlocks at three eligible strains, and want-to-try strains never count toward that three	COL-060, COL-061	A	`collection.featuretests.test.ts`
The ranking entry point appears only once three experienced strains exist	COL-143	B	`CollectionRankings.test.tsx`
Starting a session returns a fresh session id and its comparison budget, and the screen auto-starts a session exactly once per mount	COL-062, COL-089	A, B	`collection.featuretests.test.ts`, `CollectionRankings.test.tsx`
Picking a winner moves both strains’ ratings symmetrically at the new-strain volatility factor	COL-063	A	`collection.featuretests.test.ts`
Calling two equally-rated strains a tie changes neither rating but counts the comparison; an upset moves ratings further than an expected result; and no outcome depends on which strain was shown first	COL-064	A	`collectionHelpers.test.ts`
Skipping a pair records the skip but moves no rating and no win/loss counter	COL-065, COL-088	A, B	`collection.featuretests.test.ts`, `strain-rankings.featuretests.test.ts`
Every comparison is stored under one normalized pair key with the result flipped to match, so the same pair is never stored two ways	COL-066	A	`collection.featuretests.test.ts`
A comparison is refused when either strain belongs to another user, when either has never been owned or tasted, or when a strain is compared against itself	COL-067, COL-068, COL-069	A	`collection.featuretests.test.ts`
Session counters track completed and skipped comparisons separately and cannot be moved through another user’s session id	COL-070, COL-071	A	`collection.featuretests.test.ts`
The next pair never repeats a pair already decided, and a skipped pair is re-offered in a later session but not again within the same one	COL-073, COL-074	A	`collection.featuretests.test.ts`, `collection.test.ts`
Pairing prefers strains the user has never compared, then the least-calibrated ones, and breaks score ties deterministically	COL-077, COL-078	A	`collection.featuretests.test.ts`
Pairing returns nothing — rather than an error or a repeat — when the pair space is exhausted or fewer than two strains are eligible	COL-075, COL-076	A	`collection.featuretests.test.ts`
Progress reports a status ladder whose remaining-pairs count never goes negative, and ignores comparisons naming a strain that has since been removed	COL-079, COL-080	A	`collection.featuretests.test.ts`, `collectionHelpers.test.ts`
The leaderboard shows only strains that have actually been compared, numbered contiguously from 1, and agrees with the collection’s own ranked count	COL-081	A	`collection.featuretests.test.ts`
Strains on identical ratings share a rank and the next rank skips accordingly	COL-082	A	`collectionHelpers.test.ts`
The leaderboard honours a requested length limit	COL-083	A	`collection.featuretests.test.ts`
The My Rankings list drops uncompared rows, sorts by rank, tolerates an empty payload, and treats a missing or negative comparison count as uncompared	COL-093	B	`my-rankings.featuretests.test.ts`
The podium renders second-first-third, and the compare shortcut hides once no pairs remain	COL-094, COL-095	B	`CollectionRankings.test.tsx`
Ending a session stamps its end time and is safe to call twice; it reveals nothing about another user’s session	COL-084, COL-085	A	`collection.featuretests.test.ts`
The comparison screen’s four verdicts map to the right outcomes and go inert while a comparison is in flight; not-enough-strains, session-complete and loading each render their own state	COL-086, COL-092	B	`CollectionRankings.test.tsx`
The session ends at exactly ten comparisons; a failed comparison or a failed end reports failure rather than a false completion	COL-087	B	`strain-rankings.featuretests.test.ts`
The ten-comparison budget is declared identically in all three places that declare it	COL-091	B	`strain-rankings.featuretests.test.ts`
Switching accounts clears in-flight session state, and ending with no session is a no-op	COL-090	B	`useCollection.featuretests.test.tsx`

Browsing the collection

Behavior	Verified by	Tier(s)	Where
The collection lists newest first and pages correctly, and a filtered listing returns full pages rather than short ones	COL-100, COL-101	A	`collection.featuretests.test.ts`
A collection read is refused when the owner key does not match the signed-in user, and a favorites page contains only the caller’s rows	COL-102, COL-105	A	`collection.featuretests.test.ts`
An unauthenticated read returns an empty collection rather than throwing, so a screen mid-sign-in never renders an error	COL-103	A	`collection.featuretests.test.ts`
The unpaginated listing sorts newest-first and honours a status filter	COL-104	A	`collection.featuretests.test.ts`
A favorite carries the moment it was favorited in its own field, distinct from when its row was created, and a fully drained favorites listing stays in newest-first order	COL-106, COL-106b	A	`collection.featuretests.test.ts`
Favorites hooks drain every page automatically, and skip the drain entirely while authentication has not settled	COL-121	B	`useCollectionPreferences.featuretests.test.tsx`
Paginated mode reports whether more pages exist and whether one is loading; “load more” is a no-op in unpaginated mode and is fenced while offline	COL-122, COL-123	B	`useCollection.featuretests.test.tsx`
Searching favorites matches name, notes and tags case-insensitively, clamps the requested limit, and is honest about only searching a recent window	COL-107, COL-108, COL-109	A	`collection.featuretests.test.ts`
Filtering favorites by tag matches the whole tag, not a substring of one	COL-110	A	`collection.featuretests.test.ts`
Favorite statistics aggregate by strain type, average potency and the five most-used tags; collection statistics count every bucket the screens display	COL-111, COL-112	A	`collection.featuretests.test.ts`
Asking for the status of a strain that is not in the collection returns the empty shape, not an error, and the home preview returns only the three fields it renders	COL-113, COL-114	A	`collection.featuretests.test.ts`
The My Strains list counts only completed orders, keys a line with no strain id by its name, converts every purchase unit to grams, sorts ranked strains first then alphabetically, and returns nulls rather than absent fields	COL-116, COL-117, COL-118, COL-119, COL-120	A	`collection.test.ts`, `collection.featuretests.test.ts`
The six tabs filter to their own status, and the manage-favorites route opens on the Favorites tab	COL-130, COL-131	B	`collection-management.helpers.test.ts`
Sorting by rank puts unranked strains last; sorting by name is A–Z	COL-132	B	`collection-management.helpers.test.ts`
The chosen card layout persists across mounts, maps to its own column count, drops to two columns on a narrow or large-text screen, falls back to the default when the stored value is unreadable, and warns without crashing when the write fails	COL-134, COL-135, COL-136, COL-137	B	`CollectionScreens.test.tsx`, `collectionCardVariantPreferenceStorage.test.ts`, `collection-management.featuretests.test.ts`
A cold offline launch shows the controls, not a false empty state; retry is blocked while offline; the genuine empty state appears only after an online resolve	COL-138, COL-139, COL-140	B	`CollectionColdOffline.test.tsx`
”No results for your search” is a different state from “your collection is empty”	COL-141	B	`CollectionScreens.test.tsx`
Every write action is blocked while the screen reports that actions are unavailable, and a user without the entitlement sees the mock collection behind the access gate	COL-142, COL-145	B	`CollectionScreens.test.tsx`
Switching accounts never shows the previous account’s rows	COL-144	B	`CollectionColdOffline.test.tsx`

Identifying the right strain

Behavior	Verified by	Tier(s)	Where
A strain’s cache key prefers its slug and lowercases and trims either identifier form	COL-150	B	`strain-detail-identity.featuretests.test.ts`
A deleted slug must not silently resolve to a different strain with the same name; a slug that resolves short-circuits the name fallback; a slug-less row still resolves by name	COL-151	B	`strain-detail-queries.featuretests.test.ts`
Tapping a collection row that has no slug navigates by strain id, and a strain page that 404s shows an error rather than spinning forever	COL-152, COL-153	B	`CollectionScreens.test.tsx`
A row whose strain id is not a UUID still round-trips through every collection surface	COL-154	A	`collection.featuretests.test.ts`
Favoriting the same strain under two different ids creates two library rows, but the extension payload still lists its slug once	COL-155	A	`collection.featuretests.test.ts`

Everything downstream of the collection

Behavior	Verified by	Tier(s)	Where
The Safari extension’s slug lists skip rows that carry no slug, de-duplicate, and reflect a favorite made in the same write chain	COL-115, COL-165	A	`collection.featuretests.test.ts`
The extension payload is sorted and bounded to the native contract’s length	COL-166	B	`useExtensionSync.test.ts`
Favoriting a strain increments the favorite count by exactly one	COL-160	A	`collection.featuretests.test.ts`
One collection write arms exactly one history event no matter how large the library, and a twenty-write burst settles to a projection that matches source	COL-177a, COL-177b	A	`collection.featuretests.test.ts`
The Collection Curator card copy matches the thresholds the rules actually use	COL-164	B	`achievements-v2.collection.featuretests.test.ts`
Deleting an account removes every collection row, comparison and ranking session, and the account’s reported favorite and dislike counts match what the collection projections return	COL-169, COL-170	A	`collection.featuretests.test.ts`

What the live tier proves end-to-end

Tier C runs against the deployed staging backend with a brand-new, really-signed-in identity per test, and deletes it afterwards.

A favorite survives the full round trip — mutation, deployed validators, and read back through the deployed queries (COL-180).
All twenty-three deployed collection queries accept the exact argument shapes the app’s hooks send (COL-181).
A complete ranking session runs start → ten comparisons → automatic end against the real deployment (COL-182).
The Revyl ranked-collection seed is idempotent on staging and is statically proven to reject production (COL-183).
A collection write reaches the achievements engine through the real debounce, not a test-forced flush (COL-184).
An order becomes a stash item which becomes an owned collection row, across three features on one deployment (COL-185).
One user’s collection is invisible to another, and a mismatched owner key is rejected by the deployed functions rather than only by local code (COL-186, COL-187).

Deliberate gaps & conditions

The ten-comparison session cap is advisory. The backend accepts an eleventh comparison; the cap lives only in the three client declarations that COL-091 keeps in agreement. COL-072 pins “advisory only” as the contract as a characterization — if that decision reverses, COL-072 must be rewritten, not deleted.
Ranking-session counters have no reader. Nothing in the app reads a session’s completed/skipped counts or its end time, so COL-182 can prove only half of the session contract on a real deployment. Either the columns get a reader or they are dead; the decision is open.
Sort choice is deliberately not persisted across mounts. No test asserts it (COL-133 is deferred) because a passing characterization here would only make a future product change look like a regression.
There are no bulk operations. Multi-select and bulk delete do not exist in this feature, so nothing in the contract covers them.
Curator thresholds, per-type variety counters, and the Professor High favorite path are contracted here but proved in the achievements and users suites, so the same rule is not asserted twice against two copies of the thresholds (COL-161 → ACH-013, COL-163 → ACH-009/ACH-011, COL-167 → CHAT-014).
Tier C skips cleanly without credentials, naming exactly what is missing. It is never part of pnpm test, pnpm check, or a cached Turbo run.

Where to extend

A new favorite/dislike/status/ranking rule gets its Tier A case in apps/mobile/convex/tests/collection.featuretests.test.ts; a pure helper rule goes next to its helper as a *.featuretests.test.ts. A new hook argument or screen state gets a Tier B case in the co-located *.featuretests.test.tsx for that hook, or in apps/mobile/test/ui/features/CollectionScreens.test.tsx / CollectionRankings.test.tsx for rendering. Only reach for apps/mobile/test/integration/suites/collection.integration.test.ts when the claim is about the deployed backend. 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

Collection & Rankings — Behavior Contract

What this feature is

How to read the contract

The behavior contract

Favoriting a strain

Disliking a strain

Marking owned, tasted, or want-to-try

Notes and removing a strain

Ranking strains head to head

Browsing the collection

Identifying the right strain

Everything downstream of the collection

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

​Favoriting a strain

​Disliking a strain

​Marking owned, tasted, or want-to-try

​Notes and removing a strain

​Ranking strains head to head

​Browsing the collection

​Identifying the right strain

​Everything downstream of the collection

​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

Favoriting a strain

Disliking a strain

Marking owned, tasted, or want-to-try

Notes and removing a strain

Ranking strains head to head

Browsing the collection

Identifying the right strain

Everything downstream of the collection

What the live tier proves end-to-end

Deliberate gaps & conditions

Where to extend