# Route purchase rule for trips created in HeavyHaul Agent

Source: Nash, 2026-10-01, plus his answers to four questions the same day.

## The rule

When a permit is uploaded to a trip created in HeavyHaul Agent, reading it finds the route token. **That does not give anyone the route.** Someone on the trip must take it, with a prepaid credit or by paying.

| # | Decision |
|---|---|
| R1 | **Price follows how well the route is known.** Count the permits in our whole history that carry the same route token, the one just uploaded included. **3 or more → Express Route. 2 or fewer (or no token) → Extended Route.** Prices come from `routing_products` ($1.99 / $10.00 today). |
| R5 | **The count comes from MongoDB, through the agent backend, not from Supabase** (Nash: "that's where we keep all the tokens for every single route"). Order: live backend lookup → the count the backend returned when it read the permit → Workspace's own database as a temporary fallback. The backend does not send the count yet: `docs/BACKEND-REQUEST-2026-10-01-ROUTE-TOKEN-USAGE.md`. Which MongoDB number it is (catalog `Frequency`, `workspace_route_usage`, or both) is an open question for the backend developer. |
| R2 | **Prepaid credits cover Express Routes only.** An Extended Route always goes to the cart. |
| R3 | **Every unpaid route is locked, on old trips as well as new.** A route nobody took is hidden until it is bought. A route somebody already took stays visible. |
| R4 | **After taking an Extended Route whose map is not prepared yet,** the card shows "Route purchased · being prepared" and the map appears as soon as it is ready. An Express Route shows its map at once. |
| — | Unchanged: a permit pushed by Synchron Permits includes its route (`routeIncludedWithPermit`) and is never sold. Cart and checkout stay Carrier Dispatch only (purchasing D6). |

## Where it lives

| Piece | Path |
|---|---|
| The rule: threshold, access states, labels (pure) | `src/lib/domain/route-offers.ts` |
| Where the count comes from (`resolveTokenUses`), payload gating, the answer the purchase endpoints trust | `src/lib/data/route-offers.ts` |
| Backend calls: `route_usage_count` in the permit reader's response, `getRouteTokenUsage` live lookup | `src/lib/adapters/flask.ts` |
| Loaders that gate permits before they leave the server | `src/lib/data/trip-page.ts` (both payloads), `src/lib/data/dashboard.ts` |
| Credit path: Express only, balance checked, product decided by the server; paying is refused here | `src/app/api/trips/[id]/requests/route.ts` |
| Cart: the server picks the product from the token history, the browser's product code is ignored | `src/app/api/trips/[id]/cart/items/route.ts`, `addCartItem` |
| Permit card, driver card, purchase control | `src/components/app/trip-workspace/trip-workspace.tsx`, `src/app/ct-dashboard/driver-view.tsx`, `src/components/app/route-purchase.tsx` |
| Tests | `tests/route-offers.test.ts`, `tests/purchases-permit-gate.test.ts` |

## How the lock works

The control is on the server, not in the interface. `applyRouteAccess` decides each permit's state (`included`, `purchased`, `reading`, `offer`) and, unless the route is included or purchased, removes every copy of it from the row before it is sent: `route_links`, `route_gpx_url`, `route_hummer_url`, `route_token`, and the same fields plus the raw reader output inside `extraction`. A purchase is a live `route_request` for that state on that trip; one purchase unlocks the route for everyone on the trip.

## Not covered here

- The agent backend receives the full trip through the existing sync, so the AI assistant could still describe a route the trip has not bought. That is a backend-side rule.
- Freight Broker, Pilot and Driver views show "available · not purchased" but cannot pay (D6). Drivers can spend an Express credit.
- Payments are still not operational (`docs/SYNCHRON-PAYMENTS-INTEGRATION.md`): until Synchron's checkout is connected, an Extended Route can be added to the cart but not paid for, so it stays locked.
