Orders & Receipts — Behavior Spec

What this feature is

A user turns a dispensary receipt into a record in the app. They paste or dictate the receipt text, or photograph it, and an AI parse returns line items. They review that parse — fix a strain name, pick a different match, add a missing strain, remove a line, correct a price or amount, set the shop and purchase date, mark it a personal purchase — and then save it one of three ways: stats only, plus stash, or plus stash and a notebook. Saved orders live in an archive they can filter, search, open, edit, add to their stash, and delete. Receipts that arrive from Gmail enter this same review screen once a draft exists. A dev-only Order Import Lab seeds realistic historical receipts so the whole path can be exercised without a mailbox.

This page is the contract, not a coverage report. Every line below is true of the code on main today and is enforced by the cited tests. Behaviors that are deliberately unproven live in Deliberate gaps, never in the tables.

The behavior contract

Importing a receipt by text

Behavior	Verified by	Tier	Where
Parsing pasted receipt text requires an active Pro subscription, and the gate holds on every deployment including the deployed backend.	ORD-102, ORD-213	A, C	`orders.test.ts`, `orders.integration.test.ts`
Text shorter than 10 or longer than 50,000 characters is rejected on the device, before any paid parse runs.	ORD-103, ORD-147	A, B	`orders.test.ts`, `receiptUpload.featuretests.test.tsx`
A parse that returns zero line items never becomes a draft — the user is told the receipt could not be read and stays on the input screen.	ORD-144	B	`receiptUpload.featuretests.test.tsx`
A parse failure returns a message the screen can render; the action never throws, and it resolves the API host from configuration, canonicalizing a retired one.	ORD-106, ORD-107	A	`orders.featuretests.test.ts`, `orders.test.ts`
Retrying the same receipt reuses the same attempt id so one receipt is never billed twice, while editing the receipt first mints a new id that the deployed parser distinguishes.	ORD-146, ORD-146a, ORD-146b, ORD-214, ORD-215	B, C	`receiptUpload.featuretests.test.tsx`, `orders.integration.test.ts`
Tapping retry while a parse is still in flight does not consume one of the three allowed retries.	ORD-145	B	`receiptUpload.featuretests.test.tsx`
A cancelled-order email must never become an order — every item is dropped when the source says the purchase was cancelled, while a confirmation that merely offers cancellation is kept.	ORD-231, `rejectCancelledPurchase`	C, A	`orders.integration.test.ts`, `receipt-parser.test.ts`
An extraction carrying no price, subtotal, or total anywhere is emptied rather than presented as a free order; a zero price is not evidence of money; and extraction runs at temperature 0 so two parses of one receipt agree.	`enforceReceiptMonetaryEvidence`, `BUG-051`	A	`receipt-parser.test.ts`

Importing a receipt by photo

Behavior	Verified by	Tier	Where
Photo parsing is Pro-gated and locally validated on the same terms as text, including the paid-path header the text lane sends.	ORD-104	A	`orders.featuretests.test.ts`
A photo that parses to zero line items is rejected instead of pushing the user into an empty review screen.	ORD-143	B	`receiptUpload.featuretests.test.tsx`
An image above the 6 MiB client ceiling is rejected before the action, and the real edge refuses an oversized upload with a shaped, user-readable failure.	ORD-147, ORD-216	B, C	`receiptUpload.featuretests.test.tsx`, `orders.integration.test.ts`
Omitting the media type produces an accurate message, and a failed picker resize falls back without misdeclaring the media type.	ORD-105, ORD-148	A, B	`orders.featuretests.test.ts`, `receiptUpload.featuretests.test.tsx`
A real JPEG carrying trailing camera metadata is accepted at its true media type, and a HEIC photo is refused with a clear error before a provider call is spent.	`BUG-052`, `BUG-053`	A	`receipt-parser.test.ts`

Reviewing and editing before save

Behavior	Verified by	Tier	Where
Every review action — edit name, pick an alternative match, add a missing strain, remove and restore, edit price and amount, decide cannabis for an unknown name — is handled by the reducer.	ORD-159	B	`reviewItemsReducer.test.ts`
Editing the product type can only ever produce one of the six supported literals.	ORD-160	B	`reviewItemsReducer.featuretests.test.ts`
Retrying strain matching sends the strain names the backend expects and needs only sign-in, not Pro.	ORD-136, ORD-100, ORD-217	B, A, C	`useOrderReview.featuretests.test.tsx`, `orders.featuretests.test.ts`, `orders.integration.test.ts`
A cold deep link into review re-initializes its items once the signed-in user settles, and never renders an empty item list.	ORD-135, ORD-165	B	`useOrderReview.featuretests.test.tsx`, `OrdersScreens.test.tsx`
An expired draft and a missing draft show different copy.	ORD-137	B	`useOrderReview.featuretests.test.tsx`
The total-amount field rejects an invalid or over-cap entry visibly rather than silently discarding the keystroke.	ORD-158	B	`OrdersScreens.test.tsx`
The payload the review screen builds satisfies the commit validator field for field, on the in-memory backend and on the deployed one.	ORD-138, ORD-200	B, C	`orderCommitPayload.featuretests.test.ts`, `orders.integration.test.ts`
Strain names are normalized and length-capped on the way in, and an item can never be marked as matched without a strain id.	ORD-026, ORD-027	A	`orders.featuretests.test.ts`

Saving an order

Behavior	Verified by	Tier	Where
The three save variants map to the correct add-to-stash and generate-notebook pair.	ORD-139	B	`useOrderSaveFlow.featuretests.test.tsx`
One save keeps one idempotency key across every retry, so a user tapping save twice gets one order — including two clients racing the deployed backend — and that key is scoped to its own user.	ORD-140, ORD-005, ORD-006, ORD-071, ORD-202, ORD-230	B, A, C	`useOrderSaveFlow.featuretests.test.tsx`, `orders.test.ts`, `orderPostSave.test.ts`, `orders.integration.test.ts`
Replaying a key with a different immutable payload is rejected rather than silently overwriting, live as well as locally.	ORD-072, ORD-203	A, C	`orderPostSave.test.ts`, `orders.integration.test.ts`
A saved order is `confirmed` and counts toward the user’s stats immediately, without waiting for its effects.	ORD-070	A	`orders.featuretests.test.ts`
A free user who asks for a notebook still gets the order — without one.	ORD-074	A	`orderPostSave.test.ts`
A cold remount after save recovers the outcome instead of re-committing, and the deployed backend reports that outcome.	ORD-141, ORD-201	B, C	`useOrderSaveFlow.featuretests.test.tsx`, `orders.integration.test.ts`
Waiting for a notebook shell reads, never writes, and stops after 8 attempts.	ORD-142	B	`useOrderSaveFlow.featuretests.test.tsx`
An order persists its items and computes a total, and a receipt-stated total wins over the item sum so tax and fees survive.	ORD-001, ORD-022, ORD-023	A	`orders.test.ts`, `order-confirm.test.ts`
Every receipt field is bounded before it is stored: at least one item and no more than the item cap; finite, positive, under-cap quantities; no negative price or total; an integer purchase date inside the supported window; an http(s) receipt URL within its length cap.	ORD-002, ORD-003, ORD-018, ORD-019, ORD-020, ORD-021, ORD-024, ORD-025	A	`orders.featuretests.test.ts`, `order-confirm.test.ts`
All six product types and all ten stash units round-trip, an item with no product type commits as flower, and an unrecognised product type is refused by the validator.	ORD-009 – ORD-017	A	`order-confirm.test.ts`, `orders.featuretests.test.ts`
Saving with a shop name creates or revives that dispensary, a personal purchase creates none, duplicate shop identities never mint a competing key, and a dispensary id belonging to someone else is dropped rather than throwing the save away.	ORD-117, ORD-118, ORD-119, ORD-008	A	`orderPostSave.test.ts`, `orders.featuretests.test.ts`

What happens after a save — the effect chain

Behavior	Verified by	Tier	Where
Effects are reserved and drained in one order: dispensary visit, then stash, then strain research, then notebook — and effects the user did not ask for are never reserved.	ORD-076, ORD-077, ORD-209	A, C	`orders.featuretests.test.ts`, `orderPostSave.test.ts`, `orders.integration.test.ts`
A dispensary visit is counted exactly once across worker retries, and is skipped when the shop was deleted.	ORD-078, ORD-079, ORD-205	A, C	`orderPostSave.test.ts`, `orders.featuretests.test.ts`, `orders.integration.test.ts`
Resolved lines project into the stash exactly once with a single audit event, and a twelve-line order schedules one projection rather than one per line.	ORD-081, ORD-069b, ORD-204	A, C	`orderPostSave.test.ts`, `orders.featuretests.test.ts`, `orders.integration.test.ts`
Two receipt lines that resolve to the same stash identity accumulate into one jar.	ORD-082	A	`orders.featuretests.test.ts`
Strain research is reserved only for unresolved lines the user confirmed as cannabis, bound to the exact item and never re-matched by name; every terminal state reconciles idempotently and a late resolution re-projects that item into the stash.	ORD-083, ORD-084, ORD-085, ORD-086, ORD-087, ORD-207	A, C	`orderPostSave.test.ts`, `orders.integration.test.ts`
A notebook shell is created before the readiness gate is evaluated, readiness degrades past the two-hour budget, a shell the user deleted cancels the effect, and a subject above the cap is normalized away rather than failing the save.	ORD-088, ORD-089, ORD-090, ORD-075	A	`orders.featuretests.part2.test.ts`, `orders.featuretests.test.ts`
A stale finalizer cannot overwrite a newer lease, a failed effect surfaces as attention and retries to completion, and an effect whose order was deleted mid-flight is skipped rather than retried forever.	ORD-092, ORD-093, ORD-080	A	`orderPostSave.test.ts`, `orders.featuretests.test.ts`
The reconciliation cron picks up due and lease-expired effects, taking at most 100 per status.	ORD-095, ORD-096	A	`orders.featuretests.test.ts`
Saving an order moves the user’s achievement metrics on the deployed backend.	ORD-206	C	`orders.integration.test.ts`
A Gmail-sourced order’s source is decided from the owned import job, not from what the client sent.	ORD-120, ORD-225	A, C	`orders.featuretests.test.ts`, `gmail.integration.test.ts`

Browsing and searching the order library

Behavior	Verified by	Tier	Where
The library returns only the signed-in user’s orders.	ORD-028, ORD-221	A, C	`orders.test.ts`, `orders.integration.test.ts`
Pagination fills sparse filtered pages without skipping an eligible order, holds over a large live archive, and the recent-orders list honours its limit bounds.	ORD-029, ORD-039, ORD-219	A, C	`orders.test.ts`, `orders.featuretests.test.ts`, `orders.integration.test.ts`
Contradictory status and review filters return an empty result rather than ignoring one of them.	ORD-030	A	`orders.test.ts`
The end-date filter actually filters, and each filter facet selects its intended index.	ORD-031, ORD-033	A	`orders.featuretests.test.ts`
Search returns at most 100 matches and says so rather than implying a total.	ORD-034, ORD-220	A, C	`orders.featuretests.test.ts`, `orders.integration.test.ts`
An empty search is rejected and a long one is clamped by one rule the client and server share, so a query the screen accepts is a query the backend accepts.	ORD-035, ORD-036, ORD-036b, ORD-156	A, B	`orders.featuretests.test.ts`, `OrdersScreens.test.tsx`
The library hook sends exactly the arguments the backend validates, skips every subscription while signed out, and switches to search on non-empty trimmed text.	ORD-130, ORD-131, ORD-132	B	`useOrders.featuretests.test.tsx`
The library screen renders loading, empty, search-empty, error, and data, and requests one more page per end-reached.	ORD-154, ORD-155	B	`OrdersScreens.test.tsx`

Opening and editing a saved order

Behavior	Verified by	Tier	Where
Opening an order returns it with its items; a missing or foreign order throws rather than leaking.	ORD-037, ORD-038	A	`orders.test.ts`
Order detail shows a loading state while auth settles instead of “order not found”, skips entirely when no order id was passed, and renders loading, empty, error, and data.	ORD-133, ORD-134, ORD-153	B	`useOrders.featuretests.test.tsx`, `OrdersScreens.test.tsx`
Editing shop, date, total, and items is atomic across the order and its items, round-trips on the deployed backend, and rejects duplicate item ids, a foreign item, or more than 100 item updates with no partial write.	ORD-049, ORD-050, ORD-051, ORD-052, ORD-152, ORD-224	A, B, C	`orders.test.ts`, `orders.featuretests.test.ts`, `useOrderDetailManagement.featuretests.test.ts`, `orders.integration.test.ts`
An edit cannot change an item’s strain identity.	ORD-053	A	`orders.featuretests.test.ts`
Renaming the shop detaches a stale managed-shop link.	ORD-048	A	`orders.test.ts`
Editing an item price recomputes the order total by delta, a non-price edit leaves the total alone, invalid numerics are refused, adding an item enforces the cap and adds its price, and removing one subtracts and floors at zero.	ORD-054, ORD-055, ORD-056, ORD-057, ORD-058	A	`orders.test.ts`, `orders.featuretests.test.ts`
Item mutations reject an item owned by someone else, checking both the item and its parent order.	ORD-059	A	`orders.featuretests.test.ts`
The delete confirmation clears its loading state on success rather than spinning forever.	ORD-151	B	`useOrderDetailManagement.featuretests.test.ts`

Adding an order’s items to the stash

Behavior	Verified by	Tier	Where
While the stash is still loading, the screen shows loading rather than an add button that could double-add.	ORD-149	B	`useOrderDetailStash.featuretests.test.tsx`
Add-to-stash sends the plan the bulk mutation expects, tagged as an order upload.	ORD-150	B	`useOrderDetailStash.featuretests.test.tsx`
Merging a single unmatched item is refused outright; a bulk merge merges what is matched and skips what is not.	ORD-097, ORD-098	A	`orders.featuretests.test.ts`
Completing an order marks every item stash-requested and projects once, leaving unmatched items pending for later.	ORD-067, ORD-068	A	`orders.featuretests.test.ts`

Deleting an order

Behavior	Verified by	Tier	Where
Deleting an order deletes its items, cascades its durable attempt and pending effects, and decrements the achievement metrics the order contributed.	ORD-060, ORD-064, ORD-065	A	`orders.test.ts`, `orderPostSave.test.ts`, `orders.featuretests.test.ts`
A notebook generated from the order survives the delete; only its backlink is cleared.	ORD-061, ORD-223	A, C	`orders.test.ts`, `orders.integration.test.ts`
Deleting the receipt does not un-purchase the inventory: stash quantities are untouched and their events are unlinked, not deleted.	ORD-062, ORD-063	A	`orders.featuretests.test.ts`
Deleting another user’s order is refused.	ORD-066	A	`orders.featuretests.test.ts`

Dispensary order history and stats

Behavior	Verified by	Tier	Where
Dispensary history paginates one owned shop without duplicates even when purchase dates tie.	ORD-045	A	`orders.test.ts`
A malformed or foreign dispensary id returns an invalid or unavailable state instead of throwing or leaking, and a shop deleted while the screen is open becomes unavailable.	ORD-044, ORD-046, ORD-157	A, B	`orders.test.ts`, `OrdersScreens.test.tsx`
The history header’s order count is bounded rather than scanning the whole archive.	ORD-031b	A	`orders.featuretests.test.ts`
Lifetime stats aggregate exactly from the per-status buckets with no scan cap, a date-windowed query uses the range index and honours its cap, and an empty account returns zeros without dividing by zero.	ORD-040, ORD-041, ORD-041b, ORD-041c, ORD-042	A	`orders.test.ts`, `orders.featuretests.test.ts`

Historical import and the Order Import Lab

Behavior	Verified by	Tier	Where
The Lab is off on production even when its flag says enabled, and an authenticated caller cannot turn it on there.	ORD-108	A	`orderImportLab.test.ts`
Lab configuration clamps its hours and receipt count, and the Pro grant it issues is self-only and bounded.	ORD-109, ORD-110	A	`orderImportLab.test.ts`
A Lab seed produces the requested number of ready-for-review drafts, chunks above 20 rows, and cleans up after itself — skipping jobs whose drafts were already committed.	ORD-111, ORD-112, ORD-113	A	`orderImportLab.test.ts`, `orders.featuretests.test.ts`
A caller holding only the Lab flag cannot list Lab jobs.	ORD-114	A	`orders.featuretests.test.ts`
Historical import entitlement is enforced server-side at every call site, not by the screen, and while entitlement is still loading the client treats every historical-import capability as unavailable.	ORD-115, GML-040, ORD-162	A, B	`gmail.featuretests.test.ts`, `useHistoricalImportAccess.featuretests.test.tsx`
The launch smoke-order fixture is idempotent and only seeds for the designated test identity.	ORD-116	A	`order-confirm.test.ts`

Gmail-sourced orders in this screen

Behavior	Verified by	Tier	Where
Discarding a Gmail draft calls both discard mutations in order and leaves no order behind.	ORD-163, ORD-228	B, C	`useOrderReview.featuretests.test.tsx`, `gmail.integration.test.ts`
Finalizing a Gmail draft passes the draft and the new order id after the save, never before.	ORD-164	B	`useOrderReview.featuretests.test.tsx`

Ownership and access

Behavior	Verified by	Tier	Where
Creating an order requires authentication, and outcome and resume are isolated to the owner of the attempt.	ORD-004, ORD-094	A	`orders.test.ts`, `orderPostSave.test.ts`
Ownership and unauthenticated rejection are enforced by the deployed backend, using two real signed-in identities.	ORD-221, ORD-222	C	`orders.integration.test.ts`

What the live tier proves end-to-end

Tier C drives the deployed backend with really-logged-in throwaway identities and cleans up after itself.

A save is a save. The exact payload the review screen builds is accepted by the deployed commit, its outcome is readable, a replay is idempotent, a divergent replay is rejected, and two clients racing the same key produce one order — ORD-200, ORD-201, ORD-202, ORD-203, ORD-230.
The effect chain actually runs on real infrastructure. A committed order lands in the stash, increments the dispensary’s visit, and moves achievement metrics — ORD-204, ORD-205, ORD-206.
Slow strain research still finishes the job. An unresolved line goes out to the research pipeline, comes back, and re-projects into the stash; the whole chain runs in reservation order and a stuck attempt is driven to completion by resume — ORD-207, ORD-209, ORD-210.
Real receipts parse, and non-receipts do not. Real text and a real photo parse end to end through the deployed API, a cancelled-order text yields zero items, and the Pro gate is enforced live — ORD-211, ORD-212, ORD-231, ORD-213.
Paid work is not billed twice. The same attempt id replays instead of re-parsing, a different payload under the same id conflicts, and an oversized image is refused at the real edge — ORD-214, ORD-215, ORD-216.
Strain matching works against real strain data for a signed-in free user, with confidence bands rather than exact floats — ORD-217, ORD-218.
Other people’s orders stay other people’s, enforced by the deployment rather than the client — ORD-221, ORD-222.
Life after save. A live delete leaves the notebook and the stash intact, an edit round-trips, and the Order Import Lab seeds, reviews, commits, and cleans up a realistic historical batch — ORD-223, ORD-224, ORD-225.

Deliberate gaps & conditions

A gap listed here is a decision, not coverage. Nothing below is evidence that the behavior works.

The large-archive cases are opt-in. Live pagination over a 60-plus-order archive and its search truncation (ORD-219, ORD-220) run only with TIER_C_PAID=1, because every Lab-committed draft queues real notebook work. They skip by default.
The Lab’s production hard-off is proven statically only. ORD-226 would need a mutation invoked against the production deployment, which the programme forbids. The boundary is covered by ORD-108 instead, which asserts the same predicate over the production configuration.
Cron healing of a stranded effect is not run live. ORD-229 needs a five-minute-plus wait for the reconciliation cron. The reconciliation logic itself is proven at Tier A by ORD-095 and ORD-096.
Four low-value assertions are deliberately unbuilt. A start-after-end date range (ORD-032), an empty dispensary name (ORD-043), an empty retry list (ORD-101), and a parsed-float NaN already contained downstream (ORD-161) are single validator strings with no user-visible behavior of their own.
Unbounded stats at 17,000 orders is not simulated. ORD-121 would need a bulk seed script; the bounded behavior that matters is proven by ORD-041b and ORD-041c.
Notebook writes are quarantined by product decision. With V2 writes off, a notebook effect finalizes shell-only and records a durable marker for a later backfill. ORD-091 asserts that quarantined behavior and flips the moment writes are enabled.
Deleting an order does not reverse stash inventory. This is intentional, not a missing cascade — the user still physically holds what they bought. ORD-063 pins it.
Duplicate coverage lives with the primary. The order-to-notebook journey is proven in the notebooks suite, the Gmail-sourced confirm-to-finalize journey in the Gmail suite, and draft orders not counting toward achievements in the achievements suite.

Where to extend

A new Orders behavior gets its test in the tier that can see it: backend logic and validators in apps/mobile/convex/tests/orders.featuretests.test.ts (its .part2 sibling holds the notebook-effect cases); hook and screen contracts in the co-located *.featuretests.test.tsx beside the hook, or in apps/mobile/test/ui/features/OrdersScreens.test.tsx for render states; deployed-backend journeys in apps/mobile/test/integration/suites/orders.integration.test.ts. Receipt-parser behavior — the monetary-evidence and cancelled-purchase gates, media-type detection, determinism — belongs to the API suite at apps/api/src/services/ai-sdk/receipt-parser.test.ts. Give the case an ORD- id, add its matrix row, and follow the tier and naming rules on Mobile Feature Test Platform.

Product Strategy

Roadmap

Testing & Quality

Notebooks

Core Features

AI & Media

Growth & Social

Personalization

Infrastructure & Costs

Pricing & Strategy

Orders & Receipts — Behavior Spec

What this feature is

The behavior contract

Importing a receipt by text

Importing a receipt by photo

Reviewing and editing before save

Saving an order

What happens after a save — the effect chain

Browsing and searching the order library

Opening and editing a saved order

Adding an order’s items to the stash

Deleting an order

Dispensary order history and stats

Historical import and the Order Import Lab

Gmail-sourced orders in this screen

Ownership and access

What the live tier proves end-to-end

Deliberate gaps & conditions

Where to extend

​What this feature is

​The behavior contract

​Importing a receipt by text

​Importing a receipt by photo

​Reviewing and editing before save

​Saving an order

​What happens after a save — the effect chain

​Browsing and searching the order library

​Opening and editing a saved order

​Adding an order’s items to the stash

​Deleting an order

​Dispensary order history and stats

​Historical import and the Order Import Lab

​Gmail-sourced orders in this screen

​Ownership and access

​What the live tier proves end-to-end

​Deliberate gaps & conditions

​Where to extend

What this feature is

The behavior contract

Importing a receipt by text

Importing a receipt by photo

Reviewing and editing before save

Saving an order

What happens after a save — the effect chain

Browsing and searching the order library

Opening and editing a saved order

Adding an order’s items to the stash

Deleting an order

Dispensary order history and stats

Historical import and the Order Import Lab

Gmail-sourced orders in this screen

Ownership and access

What the live tier proves end-to-end

Deliberate gaps & conditions

Where to extend