HHA task list — Synchron route integration — October 6, 2026, 4:55 PM ET
Workspace work for route purchase totals about 6.5 to 7.5 working days, including the two tasks Synchron added (HW-9 and HW-10). Tasks HW-1 to HW-3 must be done by the end of Synchron's phase 0, about one week after Synchron starts, because Synchron's staging tests depend on them. Synchron has not yet set its start date.
Naming and addresses (Nash, October 6): the HeavyHaul Factory is renamed the Brain and moves to its own subdomain, brain.heavyhaulagent.com. The Workspace moves to heavyhaulagent.com. Synchron must move its calls to the Brain before heavyhaulagent.com switches to the Workspace.
Phase 0 — by the end of Synchron's first week
| ID | Task | Done when | Owner | Estimate |
|---|---|---|---|---|
| HW-1 | Built October 6; waits on migration 0053. Order-number register. Keep every issued 9-digit number permanently. Production numbers 200000000–999999999, staging 100000000–100999999. Issue a new order number when a trip's carrier changes, linked by the trip number. Fix the trip-number generator, which today draws from 100–999 million. | Numbers never repeat, even after a trip is deleted; a carrier change produces a new order number; staging refuses a production number. | Workspace | 0.5 day |
| HW-2 | Signing client. Every request carries Authorization: Bearer, X-HHA-Timestamp, X-HHA-Signature (hex HMAC-SHA256 of timestamp + "." + raw body; for GET, timestamp + "." + METHOD + " " + path?query), Idempotency-Key, X-Request-Id and Synchron-Api-Version: 2026-10-01. | Passes the signing test vectors in Synchron's contract repository. | Workspace | 0.5 day |
| HW-3 | Callback receiver for the new events. Verify the signature on the raw body, reject timestamps more than 5 minutes off, deduplicate event_id, apply only higher version numbers, answer 2xx within 10 seconds and process in the background. | Reachable over HTTPS from Synchron staging; passes replay, out-of-order, bad-signature, duplicate and slow-handler tests. | Workspace | 1 day |
| HW-4 | Move the addresses in this order: bring the Brain up on brain.heavyhaulagent.com; Synchron moves its calls to it; HHA moves its own settings to it; then point heavyhaulagent.com at the Workspace (app address, Google sign-in and reCAPTCHA domains, email webhook, redirect from heavyhaulgbt.com; mail DNS records untouched). Replaces the earlier app.heavyhaulagent.com idea. | Synchron's calls reach the Brain at its new address, the Workspace answers on heavyhaulagent.com, and old heavyhaulgbt.com links still work. | Nash / hosting + Synchron | Depends on hosting |
| HW-5 | Workspace staging. A small staging copy without customer data, on its own HTTPS address, with staging-only secrets and API key. | Synchron staging delivers a signed test event to it. | Nash / hosting + Workspace | Depends on hosting |
| HW-6 | Schedule the permit retry job every minute. | No permit job stays in retry longer than its backoff; the four stuck permits are re-read. | Nash / server access | 1–2 hours |
| HW-7 | Send Synchron the staging and production callback paths, document storage domains (heavy-haul-agent.s3.us-east-1.amazonaws.com, oytpfcinxxtjpytjheaq.supabase.co), the conflict-alert address and named technical contacts. | Synchron confirms its allowlists and contacts. | Nash | 1 hour |
Phase 1 — route purchase and delivery
| ID | Task | Done when | Owner | Estimate |
|---|---|---|---|---|
| HW-8 | Live purchase client, replacing the mock: POST /route-purchases, GET /route-purchases/{token}, GET /orders/{n}/routes, GET /orders/{n}/route-history, GET /trips/{n}/orders. Retry 5xx and timeouts with the same Idempotency-Key and backoff; never retry 4xx unchanged. | A forced timeout and retry produce one purchase; the browser never calls Synchron. | Workspace | 1 day |
| HW-9 | Release check before showing Express: call POST /route-quotes and offer Express only when auto_release_eligible is true. | A permit that would not release automatically is offered as Extended. | Workspace | 0.5 day |
| HW-10 | Permit document on every route item: a 24-hour S3 link with filename, content type, size and SHA-256. | Synchron stores the document on the state item; a failed download flags the item and does not block the purchase. | Workspace | 0.5 day |
| HW-11 | Complete purchase data. Carrier with HHA company ID, legal name, DOT and MC (one may be null), Synchron carrier token when held. Purchaser with role (carrier_user, broker, pilot, driver, shipper, hha_admin) and Synchron user token when held. Driver when known. Trip data filled from permit-derived profiles first. placeholder_fields for 1111 or XXXXX, never for DOT, MC, VIN, email or order numbers. Route token (may be null), route description as route text, up to 5 suggested route_urls. | Staging purchases pass validation with no manual fixes. | Workspace | 0.5 day |
| HW-12 | Event handling and customer states: purchase.paid, purchase.payment_failed, purchase.expired, purchase.refunded, purchase.partially_refunded (purchase only), item.in_progress, route.completed, item.fulfillment_failed, matched by hha_permit_id. Show the agreed wording list. Never expire a purchase on the Workspace clock; if no event arrives 15 minutes after expires_at, read the purchase status. | Every item status maps to a customer-facing label; closing the browser before the redirect still ends with the route paid. | Workspace | 0.5 day |
| HW-13 | Credits as separate $0 purchases with credit_reference = the route request token; return the credit on refund. | No cart mixes credit and card items; a refunded credit route returns the credit. | Workspace | 0.5 day |
| HW-14 | Daily reconciliation with route-history for orders active in the last 7 days. | The report flags any purchase whose state differs between the two systems. | Workspace | 0.5 day |
| HW-15 | Refund path from Workspace support to Synchron staff, with purchase and route request tokens. | Documented and shared with both support teams. | Workspace + support | 2 hours |
| HW-16 | Done October 6 (the month importer already skipped it; the single-carrier importer now refuses 43 and 49). Training carrier: skip Synchron carrier #43, "Training PAN LOGISTICS INC" (USDOT 3462028), in every import. | A fresh import brings in none of its orders. | Workspace | 1–2 hours |
| HW-17 | Decided October 6: keep HH-74256240, HH-48152963, HH-13246289 and HH-58694333. They come from Synchron carrier #1, "PAN LOGISTICS INC", not the training carrier #43; both share DOT 3462028. Ask the Synchron CTO whether carrier #1's orders are real jobs or test data. | Synchron confirms; the trips are removed only if they are test data. | Nash | — |
| HW-18 | Done October 6. Permit request email subject carries the trip number as [HH-512048337], so Synchron staff can fill the new Workspace trip number field. | The next emailed request shows the bracketed number in its subject. | Workspace | 15 minutes |
| HW-19 | Done October 6, with the expiry-date fix. Treat 1111 as unknown when reading permits, since it is Synchron's placeholder, so it raises no weight alert. | A permit with a 1,111 lb weight shows no weight mismatch. | Workspace | 1–2 hours |
| HW-20 | Buyers: allow all six purchaser roles in the Workspace, keeping purchasing limited to admins and moderators until launch. | At launch, any of the six roles on a trip can buy. | Workspace | 1 hour at launch |
Phase 4 — permit ordering
| ID | Task | Done when | Owner | Estimate |
|---|---|---|---|---|
| HW-21 | Permit ordering: card-setup redirect, payment profile display, 3-D Secure link display (also emailed by Synchron), permit.attached and permit.replaced handling, documents as 24-hour links with SHA-256. Replace the old CVV step. | Phase 4 contract tests pass. | Workspace | 1–1.5 days |
| HW-22 | Permit form fields: license plate and plate state for truck and trailer, truck axle count, trailer type and length, and axle spacing and axle weights (optional at first). | A permit order passes Synchron's required-field check with no follow-up from staff. | Workspace | 0.5 day |
The Brain team (formerly the Brain)
| ID | Task | Done when | Owner | Estimate |
|---|---|---|---|---|
| HF-1 | Stop sending the literal text "route_token"; send a real token or null (F1). | No new record holds the literal text. | Brain | Brain to estimate |
| HF-2 | Answer /api/workspace/route-token-usage with use counts (F2). | Documented rule and endpoint answering in staging. | Brain | Brain to estimate |
| HF-3 | Return route text next to every route token in the permit reading response (F3). | Every token the Workspace receives has route text. | Brain | Brain to estimate |
| HF-4 | List every Synchron endpoint the Brain calls, and get its own scoped key (F4). | List complete and shared. | Brain | Brain to estimate |
| HF-5 | Verify Synchron's signature on every call it receives, first logging only, then enforcing (F5). | Enforcement on; old shared token revoked. | Brain | Brain to estimate |
| HF-6 | Confirm what, if anything, the Brain relays to the Workspace (F6). The Workspace has received nothing. | Documented in the contract repository. | Brain | Brain to estimate |
| HF-7 | Produce GPX and Hummer files for 9-digit Workspace orders like 8-digit Synchron orders (F7). | A purchased Express and a purchased Extended route both get files in staging. | Brain | Brain to estimate |
| HF-8 | Answer Synchron's calls within 10 seconds and handle repeats safely (F8). | A repeated update-order causes no duplicate work. | Brain | Brain to estimate |
| HF-9 | Switch from Synchron internal IDs to tokens (F9). | No Synchron internal IDs read. | Brain | Brain to estimate |
| HF-10 | Document the Front Desk service (F10). | Documented in the contract repository. | Brain | Brain to estimate |
| HF-11 | Issue the new token for Synchron's calls and revoke the old one (F11). | The old token returns 401. | Brain | Brain to estimate |
| HF-12 | Signed files-ready message to the Workspace with order number, permit token, HHA permit ID, GPX link and Hummer link (F12, from HHA's proposal). | Purchased routes in staging show both files in the Workspace. | Brain sends, Workspace receives | Brain to estimate; Workspace 0.5 day |
| HF-13 | Stop calling permittoken for 9-digit orders; Synchron will answer 409 for them. | No permittoken calls for HHA orders in Synchron's logs. | Brain | Brain to estimate |