doormile_backend/docs/customer-app-api.md

Customer App API (doormile_cx) — change record & integration guide

Audience: the doormile_cx app developer, plus anyone reviewing this before it goes to production. Backend: Go + Fiber, api.doormile.com/api/v1, namespace /customer/*. Status: code complete, compiler- and unit-verified, not yet run against a real database. Read §11 before deploying.

OpenAPI 3.1 spec	openapi-customer.yaml
Staging seed	../seed_customer_app.sql
Requirements this answers	Doormile — Backend Requirements (Customer App v1)
Reviewed	Once, by a reviewer with the Flutter apps but not this repo — §13 records every finding and what changed

---

0. The one question first: does this affect the Miler app or the consoles?

YES.

Not "no". Anyone telling you otherwise has not read the diff. The customer work could not be built without touching shared code, because the thing it changes — one pickup producing many orders — is a fact the rider app and the consoles both have to cope with.

Here is the complete list, with severity. Nothing is omitted.

🔴 Behaviour changes those clients WILL observe

#	What changed	Who sees it	Action needed
1	Booking references are now DM-482913, not DM-BK-A1B2C3D4-48291. New bookings only; existing rows keep their old strings.	Admin console, hub console, Miler app — anywhere a booking number is displayed	None in code (nothing parses the format). Tell ops the format changed.
2	Tracking numbers are now DMX10482913, not DM-TRK-A1B2C3D4-48291. New consignments only.	Same as above, plus any printed label or customer-facing tracking link	Same. Check label templates for a hardcoded width.
3	GET /miler/bookings can return more than one row per booking. A customer-app pickup with 3 destinations becomes 3 stops after collection — each with its own consignmentid, trackingno, address and COD. Before collection it is still 1 row. Console/express bookings are still always 1 row.	Miler app	A multi-file change, not a one-liner. See §0.6.
4	POST /miler/bookings/{id}/pickup-complete gained a consignments array listing every order the pickup produced. All previous top-level fields still describe the first order, unchanged.	Miler app	Purely additive — safe to ignore, but a multi-destination build should read it.
5	POST /miler/bookings/{id}/parcel accepts an optional photos: [] per parcel (storage keys from /miler/uploads/sign). Response shape unchanged.	Miler app	Optional. Without photos the customer receipt shows a weight and no evidence.
6	PickupBooking JSON gained 10 fields (slotid, customerstage, customerstatus, estimateminrupees, estimatemaxrupees, routekm, pickuptitle, pickupsub, cancelreason, destinations) and BookingParcel gained bookingdestinationid. These serialise on every admin/hub endpoint that returns the model raw.	Admin + hub consoles	Additive JSON. Safe for a JS client that reads named keys.
7	Every response now carries an X-Request-Id header.	Everyone	None. Log it — it is how a support report gets correlated.
8	Unknown paths under /customer/* answer 401, not 404. So the retired doormile_customer_app calling POST /customer/login gets 401 "authorization header is required".	The old customer app	Expected — that app is being retired. Pre-existing Fiber group behaviour, not introduced here.

🟡 Internal changes with no client-visible contract change

#	What changed	Why it is safe
9	Three miler endpoints now resolve a consignment through bookingdestinations instead of pickupbookings.consignmentid	Bug fix. Identical result for a single-destination booking; the old query returned nothing for orders 2..N. See §5.
10	assignMilerTx and commitAssignment record a customer stage	Guarded: returns immediately for any booking whose source is not Customer_App. An express booking does zero extra writes.
11	AcceptMilerAssignment, BookingReachedCustomer, MilerCancelAssignment, MilerStartDelivery, MilerInwardConsignmentAtHub, MilerDeliverConsignment record customer stages	Same guard. Response bodies unchanged.
12	middlewares.Idempotency scopes anonymous callers differently	Authenticated key format is byte-identical to before (idem:<uid>:<key>), so no in-flight rider key is orphaned at deploy. See §5.4.
13	Request logs gained client, platform, requestid fields	Log-only.
14	utils.GenerateToken delegates to a new GenerateTokenWithTTL	Still 24h for miler/admin/hub. Only the customer surface passes a different TTL.
15	internal/storage gained PresignGet	New function; nothing existing calls it.
16	middlewares/city_gate.go gained an exported PincodeInOperatingCity	New function; CityGateMiddleware itself is unchanged.
17	9 new tables + 11 new columns via AutoMigrate; 2 sequences, 2 indexes	All additive and nullable/defaulted. See §11 for the deploy note.

🟢 Deliberately NOT changed, though I was tempted

Two things I changed while building, then reverted, because they were miler behaviour and out of scope:

• Rider availability after pickup-complete. I had made a rider stay Picked_Up when a hyperlocal parcel goes straight to Out_for_Delivery. The endpoint has always set them Available there. The existing code comment says the opposite of what the code does — a pre-existing inconsistency I have flagged rather than silently "fixed", because changing it alters live rider availability and the dispatch pool. Ops decision, not mine.
• POST /miler/consignments/{id}/deliver error status. I had changed a "not yours" failure from 404 to 403 for consistency with start-delivery. Reverted: the deployed rider app was built against 404 and its exact messages. Only the broken lookup is fixed.

---

0.5 Page-by-page: exactly which screens are affected

Read from the client source in this workspace (doormile_crm = admin console, doormile_hub_console = hub console), not inferred from the API. The Miler app is not in this workspace, so its rows are derived from the endpoints it calls and must be confirmed against the Flutter source.

Legend: 🔴 needs a code change · 🟡 visible change, no code change · 🟢 fixed by this work · ⚪ no impact

Miler app (Flutter — verify against the app source)

Screen	Endpoint behind it	Impact
Home / my stops	GET /miler/bookings	🔴 A pickup can now be several rows. After collection, a 3-destination customer booking returns 3 stops sharing one bookingid. Key the list on consignmentid. New fields destinationseq / destinationcount give you "Stop 2 of 3", and trackingno, recipientname, recipientphone are now per stop. Before collection it is still exactly 1 row, and console/express bookings are always 1 row.
Pickup — complete	POST /miler/bookings/{id}/pickup-complete	🟡 Response gained consignments[] (every order the visit produced). All existing top-level fields still describe the first order and are unchanged, so an old build keeps working.
Pickup — weigh/photograph parcels	POST /miler/bookings/{id}/parcel	🟡 Each parcel now accepts an optional photos: [] of storage keys from /miler/uploads/sign. Response shape unchanged. Without photos the customer's receipt shows a weight with no evidence behind it.
Delivery — deliver / skip	POST /miler/consignments/{id}/deliver	⚪ Contract unchanged. The internal lookup was broken for orders 2..N and is fixed; status codes and messages are byte-identical.
Base handover	POST /miler/consignments/{id}/inward-at-hub	⚪ Contract unchanged; same lookup fix.
Earnings	GET /miler/earnings	🟢 Fixed before it shipped. Customer-app jobs would have recorded ₹0 — see §5.6.
Any screen showing a tracking number	—	🟡 DMX10482913 instead of DM-TRK-A1B2C3D4-48291. Ten characters shorter, so nothing overflows.
Duty, breaks, notifications, support, profile, bases	—	⚪ Untouched.

Admin console (doormile_crm)

Only one of its screens reads booking shape at all. Verified by grep across src/pages.

Screen	File	Impact
Orders list	src/pages/bookings/Bookings.jsx	🟡 Four things: (1) the Booking No column now shows DM-482913 — column is proportional(1.5), the string is shorter, nothing overflows; (2) search filters bookingno by substring, so typing DM-BK finds no new bookings — tell ops; (3) the Delivery City column reads the flat deliverycity, which is destination 0 only — a 3-destination pickup shows "Chennai" and does not hint at the other two; (4) the Price column reads serviceoptions[0].estimatedprice and 🟢 would have shown "N/A" for every customer booking until §5.6 was fixed.
Cancel order (from the Orders list)	POST /admin/bookings/{id}/cancel, .../bulk-cancel	🟢 Fixed before it shipped. An ops cancel never reached the customer's app — see §5.7. No console change needed; the fix is backend-side.
Dashboard, Tenants, Customers, Pricing, Riders, Reports, Invoices, Team, Settings, Survey, auth & error screens	—	⚪ None of them read booking or consignment shape.

Hub console (doormile_hub_console)

Screen	File	Reads	Impact
Inbound	src/pages/operations/Inbound.jsx	trackingno	🟡 Tracking-number format change is visible in the table. Destination cell already ellipsises at maxWidth: 200px.
Routing	src/pages/operations/Routing.jsx	trackingno	🟡 Format change visible in the package list and the detail card (monospace, 0.85rem). Search-by-tracking-number still works — it matches the value the API returns, not a pattern.
Order Assignment	src/pages/operations/OrderAssignment.jsx	bookingid, deliveryaddress	🟡 The row id uses the numeric bookingid, so the ID-format change does not touch it. But drop reads the flat deliveryaddress, which is destination 0 only — staff assigning a 3-destination pickup see one address. Not broken; incomplete.
Rider Routes	src/pages/operations/RiderRoutes.jsx	bookingid, consignmentid, parcels	🟡 Reads consignmentid off the booking, which names only the first order. A rider carrying three parcels from one visit may render as one stop on this screen.
Tracking Map	src/pages/operations/TrackingMap.jsx	bookingid	⚪ Numeric id only.
Dashboard	src/pages/Dashboard.jsx	parcels	⚪ Counts only. Every parcel still hangs off the booking, so the totals stay correct.
Dispatch	src/pages/operations/Dispatch.jsx	parcels	⚪ As above.
Riders	src/pages/operations/Riders.jsx	parcels	⚪ As above.
Hub Settings, Login, Signup	—	⚪ Untouched.

What nobody has to change today

Multi-destination pickups only exist once the new customer app is live. Every booking in the database today has zero destination rows and therefore takes the single-leg path everywhere — the rider queue returns one row, the consoles show one address, and the fan-out never runs. The 🟡 "destination 0 only" rows above become real on the day the first three-destination pickup is booked, not on the day this deploys.

The exceptions that are live immediately: the ID formats (§0 items 1–2) and the extra JSON fields (§0 item 6).

---

0.6 The rider-app change, scoped properly

An earlier draft of this document said "key the list on consignmentid" as though that were a small edit. It is not, and the correction came from a review with access to the Flutter source that this backend repo does not have. Recorded here in full because the item is assigned to the app team and was understated.

The rider app's identity key is orderid, not bookingid. The adapter sets it at lib/data/api_config.dart:321:

'orderid': ref ?? id,   // ref = bookingreference, id = bookingid

Both of those are booking-level, and all three destination rows of one pickup carry the same bookingid and the same bookingreference. So orderid is identical across the three — and orderid is what dedupes:

• lib/data/accepted_store.dart:527 — accepted stops live in a Map keyed on orderid. Three stops collapse to one, and because that store is SharedPreferences-backed, the collapse survives an app restart.
• lib/data/work_repository.dart:314,321 and order_events.dart — per-order event stamps key on orderid, so orders 2..N overwrite order 1's clocks.

consignmentid is available to the adapter (api_config.dart:443), so the change is feasible — but it lands across accepted_store, work_repository, order_events and assignment_lookup.

Until it ships, a multi-destination pickup shows the rider one stop instead of three — the same customer-visible failure §5.1 fixed on the server. The server being right is not enough here.

destinationseq / destinationcount are invisible to the app today. pickupFromBooking builds a fixed map, so a field the adapter does not name is a field the app can never see (the file says as much around line 583). "Stop 2 of 3" needs those two keys added to the adapter as well.

The mitigation that needs no app release

maxDestinations is server configuration, not a constant — the client reads it from GET /customer/config/booking-limits and adapts. Setting customerbookinglimits.maxdestinations = 1 keeps every pickup single-destination until the rider build lands, which means:

• the customer app can ship and book end to end today;
• the fan-out code stays dormant, so no order can be stranded;
• lifting the cap later is one UPDATE, with no deploy on any side.

Recommendation: seed it at 1 and raise it only once a rider build that keys on consignmentid is live. This is the same discipline MILER_HUB_HANDOVER_ENABLED already applies in this codebase — do not turn on a server behaviour the deployed rider app cannot complete.

---

0.7 Fan-out row audit — field by field

Requested audit, run against the code and locked down by tests. GET /miler/bookings after collection, one row per order.

Field	Source	Destination-specific?	Test
consignmentid	bookingdestinations.consignmentid	✅	TestFanoutTrackingAndConsignmentIdsStayWithTheirStop
trackingno	bookingdestinations.trackingno	✅	same
deliveryaddress	built from the destination's building / street / landmark / district / state	✅	TestFanoutStopsHaveDistinctAddresses
deliverylatitude	destination pin, else district centre	✅	TestFanoutStopsHaveDistinctCoordinates
deliverylongitude	same	✅	same
recipientname	bookingdestinations.recipientname	✅	TestFanoutRecipientsStayWithTheirStop
recipientphone	bookingdestinations.recipientphone	✅	same
collectionamt	consignment codamount − codcollected, falling back to the destination's own codamount	✅ newly added	TestFanoutCodIsNotCopiedAcrossDestinations
destinationseq	bookingdestinations.seq	✅	TestFanoutRouteOrderFollowsDestinationSeq
destinationcount	number of stops on the pickup	✅ uniform per booking	TestFanoutDestinationCountIsUniform

Three findings from running this audit:

1. collectionamt did not exist. The endpoint emitted codamount only. Added as an additional key rather than a rename — codamount is what this endpoint has always sent and the deployed rider build parses it, so removing it would break every stop on every existing device. Both are written from one variable and cannot drift.

2. COD was not on the stop at all. It was resolved in the handler from the consignment map, so it could not be unit-proven, and it fell back to 0 if the consignment row failed to load. A rider shown ₹0 collects nothing. The stop now carries the destination's own codamount as the fallback.

3. Stop ordering was not guaranteed. milerStopsForBooking iterated the slice as given and relied entirely on the caller's ORDER BY seq. It worked, but the ordering is the route the rider drives, and leaving it as an unstated precondition means the next caller silently reorders someone's afternoon. It now sorts by seq on a copy.

Booking-level fallback is confined to one place and one case: a booking with no destination rows — every console/express booking and every row written before this table existed — produces exactly one stop from the booking's flat columns. A booking that has destination rows never reads them. Destination 0's coordinates are used as a fallback for stop 0 only, and only when that destination has no pin of its own, because that is the same row mirrored.

---

1. v1 requirements → what actually shipped

The requirements doc described the target. This is the delta between it and the code as it now stands.

1.1 Endpoints — all 22 requirement endpoints implemented

Route arithmetic, since three numbers in this document have to reconcile: 28 registered customer routes = 8 pre-auth (4 auth + 4 catalogue) + 20 authenticated. The 22 below is the count of endpoints the requirements asked for; the remaining 6 are the profile and saved-address routes in the table under it. The OpenAPI spec now documents all 28 (24 paths / 28 operations).

§	Endpoint	Status	Deviation from the requirement
4.1	POST /customer/auth/otp/request	✅	Answers identically whether or not the account exists — telling an anonymous caller "no account found" would make this a directory of who is registered.
4.2	POST /customer/auth/signup	✅	Existing phone treated as sign-in, as specified.
4.3	POST /customer/auth/otp/verify	✅	Idempotency-Key honoured.
4.4	POST /customer/auth/refresh	✅	Rotation. A revoked token replayed revokes the whole chain.
4.4	POST /customer/auth/logout	✅	No refreshToken in the body ⇒ signs out everywhere.
4.4	GET /customer/auth/me	✅	—
5.1	GET /customer/serviceability/states	✅	+ ETag/304.
5.2	GET .../states/{code}/districts	✅	+ ETag/304.
5.3	GET /customer/pickup-slots	✅	Slot ids encode their date (slot_20260905_t1) so a stale cached slot resolves to that day and is refused, not silently booked today.
5.4	GET /customer/config/booking-limits	✅	Accepts lat/lng for per-city limits.
6.1	GET /customer/places/reverse-geocode	✅	On upstream failure returns a coordinate label, not an error.
6.2	GET /customer/places/search	✅	Empty q ⇒ saved + recent places.
7	POST /customer/fare/estimate	✅	—
9.1	POST /customer/bookings	✅	—
9.2	GET /customer/bookings	✅	Keyset pagination, not offset.
9.3	GET /customer/bookings/{reference}	✅	+ ETag/304 for polling.
9.4	POST .../cancel	✅	Cancelling an already-cancelled booking returns 200, not 409.
9.5	PATCH .../destinations/{index}	✅	—
9.6	GET /customer/orders/{trackingId}	✅	Returns the full booking object (the requirement offered a slimmer shape; the client already parses this one).
10	POST /customer/devices	✅	+ DELETE /customer/devices/{token}.
10	Push on milestone change	✅	on_the_way and order_created deliberately silent, per §10.
11	POST /customer/ops/bookings/{ref}/stage	✅	Double-gated. Walks every intermediate stage rather than jumping.

Also kept (not in the requirements, not removed): GET/PUT /customer/profile, GET/POST/PUT/DELETE /customer/locations — these answer §13.5 "saved addresses".

Identifier scrambling — sequence-backed, but not readable

Both identifiers come off a Postgres sequence, because a sequence is the only generator here that can promise uniqueness: the columns are UNIQUE, and a random 8-digit id collides with ~43% probability by the ten-thousandth parcel — a rider unable to complete a pickup.

But a raw sequence is readable. DMX10000042 and DMX10000043 are visibly adjacent, so anyone holding two numbers learns the throughput between them, and anyone holding one can guess its neighbours. So the index goes through a keyed 4-round Feistel permutation before it is formatted (controllers/cxIdentifierScramble.go):

seq 10004200  ->  DMX35031894        seq 100000  ->  DM-499505
seq 10004201  ->  DMX31070203        seq 100001  ->  DM-341775
seq 10004202  ->  DMX62788115        seq 100002  ->  DM-106366

A Feistel network is a bijection for any round function, so uniqueness is untouched. TestBookingScrambleIsCollisionFree proves it exhaustively across all 900,000 booking references; the tracking test covers 200,000 consecutive values; TestFeistelIsAPermutation checks the primitive itself exhaustively.

Deliberately not the obvious one-liner (multiply by a coprime). That is also a bijection, but it is linear — and a multi-destination pickup hands one customer three consecutive sequence values, so the differences between their three tracking numbers would all equal the multiplier. A single booking would reveal the mapping and make the whole range walkable. TestOneBookingDoesNotLeakTheMapping rejects that design.

Past the fixed-width range (900,000 bookings / 90,000,000 orders) the identifier grows a digit rather than wrapping onto one already issued. Uniqueness is never traded for appearance.

This is not a security boundary. Every route that resolves a tracking number is already authenticated and owner-scoped — that is what stops a stranger reading someone's parcel. This removes the leak in the identifier itself, so authorisation is not the only thing standing between an outsider and your volume figures. Key: CX_ID_SCRAMBLE_KEY; a working default ships so the scrambling can never be silently off.

1.2 Contract decisions the requirements left open

Question	Decision	Consequence for the app
§3.2 field naming	camelCase, as preferred	No mapping layer needed. Served from purpose-built projections, so /miler/* keeps its lowercase keys.
§3.3 timestamps	Epoch milliseconds, UTC, integer	DateTime.fromMillisecondsSinceEpoch(int) works as-is.
§3.1 envelope	Payload in data on every response, auth included	One parser for the whole surface.
§9.6 order shape	Full booking object	⚠️ Not "reuse Booking.fromJson" as written earlier. That parser exists but today reads only reference, stage, cancellable, createdAt, pickup, slotId and four destination fields. It ignores status, miler, deliveryAgent, fare, amountPaid, deliveredAt, history, verification, details, per-destination stage, routeKm and expectedDelivery. The server shape is right; the client parser has to be finished. Appendix B of the requirements said so and this document should not have glossed it.
§9.3 miler.phone	Proxy when MILER_CALL_PROXY is set, real number otherwise	Currently unset ⇒ real number. See §10.2.
Identifier format	Sequence-backed DM-###### / DMX########	Matches the designs.

1.3 Timestamps — the defect that would have shipped silently

This database stores IST wall-clock digits in its timestamp columns (the DSN sets TimeZone=Asia/Kolkata; utils.DBNow exists because of it). Calling .UnixMilli() on a value read back from those columns is off by 5h30m — the same class of fault as a naive local string with a Z on it, which already produced "yesterday's work shown as today" on the Miler app.

Every timestamp leaving /customer/* goes through utils.EpochMillis, which reinterprets the wall clock in IST first. It is correct for both shapes the driver can produce (UTC-tagged-with-IST-digits, and correctly +05:30-tagged), so a future column-type change cannot silently shift the tracking screen. Asserted in utils/epoch_test.go.

---

2. The structural change: one pickup → many orders

pickupbookings carried exactly one delivery address in its own columns. There was nowhere to put a second, so the "one visit, three orders" model in §1 of the requirements was not expressible at all.

Pickup booking  DM-482913
    ├── destination 0 : Chennai, TN        · 2 packages
    ├── destination 1 : Ernakulam, KL      · 1 package
    └── destination 2 : Bengaluru Urban, KA· 1 package
                    │  miler collects everything in ONE visit
                    ▼
    pickup-complete fans out → 3 consignments, 3 tracking numbers
    DMX10482913        DMX10559120        DMX10662004

The compatibility rule that makes this safe — do not break it: destination 0 is mirrored onto the booking's flat delivery* columns. The Miler app, the hub console, the routing code and the hyperlocal check all read those columns and none of them changed. A booking with no destination rows — every console-created express booking and every pre-existing row — produces exactly one consignment through the same loop, byte-for-byte as before.

Single-destination is one leg, not a special case, in either direction.

---

3. File-by-file: what changed and why

3.1 New files (23)

File	Lines	Purpose
models/customer_app.go	241	The 9 new tables. BookingDestination is the one that makes multi-destination expressible.
internal/cxstage/stage.go	405	The core of §8.3. Records one append-only stage row per transition, in the caller's transaction. Owns the slowest-order rollup and the Release walk-back.
controllers/cxBookingView.go	744	The canonical §9.3 booking object. Every read that returns a booking goes through renderCxBooking; loadCxBundle batches so a tracking poll is a fixed number of queries.
controllers/cxBookingController.go	819	§9.1–9.6 — create, list, detail, cancel, patch, order-by-tracking-id.
controllers/cxAuthController.go	614	§4 — OTP over phone/email, rotation-backed refresh, E.164 normalisation.
controllers/cxCatalogueController.go	516	§5 — serviceability, capacity-aware slots, limits, ETag support.
controllers/cxPlacesController.go	350	§6 — geocoder proxy + Redis cache.
controllers/cxFareController.go	266	§7 — estimate range, multi-stop uplift.
controllers/cxPickupFanout.go	251	Splits a booking into the journeys created at pickup-complete. Decides single-vs-fan-out; nothing downstream needs to know which.
controllers/cxOpsController.go	160	§11 QA stage override, double-gated.
controllers/cxConsignmentHooks.go	100	Maps a consignment status onto a customer stage for one order.
controllers/cxDeviceController.go	85	§10 push registration.
controllers/cxIdentifiers.go	80	Sequence-backed DM-###### / DMX########.
utils/epoch.go	103	IST→epoch conversion. Read §1.3.
utils/response_cx.go	97	The customer envelope. Separate from utils.OK/Fail on purpose.
internal/sms/sms.go	105	The seam for an SMS gateway. No provider is wired in.
middlewares/requestid.go	33	X-Request-Id echo.
seed_customer_app.sql	153	Staging data mirroring the client mock.
controllers/cxHttp_test.go	606	HTTP status-code + envelope contract tests.
controllers/cxCustomerApp_test.go	473	Pure-logic unit tests.
routes/routes_customer_test.go	323	Routing + the regression guard proving miler/console are untouched.
internal/cxstage/stage_test.go	126	Stage rollup and cancellation-window tests.
utils/epoch_test.go	116	Timestamp conversion tests.

3.2 Modified files (20)

File	Δ	What changed	Why
controllers/customerController.go	+98 / −593	PIN auth + single-destination booking handlers deleted; profile and locations kept, moved to the customer envelope	Replaced by the new surface; the old request shape is no longer a valid booking
controllers/milerController.go	+593	BookingPickupComplete rewritten for fan-out; BookingParcelConfirm accepts photos + writes transactionally; stage hooks added to accept/reached/cancel	§8.3 derivation and the §1 fan-out
controllers/milerAppController.go	+410	MilerGetMyBookings emits one stop per order after collection; MilerDeliverConsignment + MilerStartDelivery lookups fixed; stage hooks	Without this, orders 2..N are undeliverable — see §5.1
routes/routes.go	+82	Customer routes replaced: 19 → 28	The new contract
models/booking.go	+60	10 columns on PickupBooking, 1 on BookingParcel, Destinations relation	Storage for the customer projection
constants/constants.go	+71	9 stage keys, 3 statuses, 4 actor types, rank/cancellable helpers	The wire contract; never inline these
migrations/migrate.go	+55	9 tables, 2 sequences, 2 indexes	Schema
internal/storage/spaces.go	+74	PresignGet	Signed parcel-photo URLs
dto/auth.go	−41	Retired customer PIN DTOs removed	Dead after the auth replacement
middlewares/logger.go	+38	Logs client, platform, requestid	§3 "accept and log"
middlewares/idempotency.go	+34	Anonymous-caller scoping	Security fix — see §5.4
controllers/logisticsHandoverController.go	+24	Consignment→booking lookup fixed; in_transit recorded	Fan-out correctness
middlewares/city_gate.go	+18	Exported PincodeInOperatingCity	Security fix — see §5.3
internal/assignment/crm_assignment.go	+17	assigned recorded on auto-assign	Most B2C bookings get a rider this way
controllers/booking_assignment_service.go	+16	assigned recorded on manual assign	Console assignment must reach the customer too
config/config.go	+13	GEOCODER_URL, GEOCODER_EMAIL	§6 proxy
utils/helper.go	+13	GenerateTokenWithTTL	1h access tokens for customers only
main.go	+7	RequestID() registered	§3
controllers/otpController.go	−128	Deleted	Its two routes were customer-only and are superseded
CLAUDE.md	+147	Project memory updated	Continuity

---

4. Stage derivation (§8.3)

The operational writes already existed and were already correct. What did not exist was any record of when a parcel reached a stage in the vocabulary the customer sees. A consignment status says where a parcel is now; it cannot say when it got there.

Existing Miler write	Customer stage produced
assignMilerTx / commitAssignment	assigned
POST /miler/assignments/{id}/accept	on_the_way (re-asserts assigned; deduped)
POST /miler/bookings/{id}/reached	arrived — cancellation closes here, recorded in the same transaction as the arrival fact so there is no window to cancel through
POST /miler/bookings/{id}/parcel	populates verification (weight per destination + photos)
POST /miler/bookings/{id}/pickup-complete	picked_up, then order_created per destination
POST /miler/consignments/{id}/inward-at-hub	in_transit, per order
POST /miler/consignments/{id}/start-delivery	out_for_delivery, per order
POST /miler/consignments/{id}/deliver	delivered, per order
POST /miler/bookings/{id}/cancel	Release, not cancel

Four rules worth knowing as the app developer:

1. Nothing is backfilled. A booking that predates this work has a short history. A short honest history beats a long invented one — the customer cannot tell which entries were guessed.
2. A booking rolls up from its SLOWEST order. Taking the maximum would show "Delivered" while one of three parcels was still at a hub.
3. on_the_way comes from accept, not the GPS stream. Deriving it from location pings means re-deriving on every ping. Distance and ETA are still live from the rider's Redis position.
4. Release is the one place a stage moves backwards. A miler cancelling returns the pickup to the pool. Without walking the stage back, the customer keeps seeing a rider card for someone who is not coming. The assigned / on_the_way history rows stay — those things happened.

§8.4 gaps — all five closed

Gap in the requirements	Status
No per-destination consignment id	✅ bookingdestinations.consignmentid + trackingno
No COD amount on the booking	✅ bookingdestinations.codamount → consignments.codamount. Per destination, because COD is collected per delivery
No per-stop attribution for stages 6–8	✅ Every per-order stage records against its destination
No customer-side cancel	✅ Server-enforced through arrived
Parcel weight/photos not exposed	✅ verification block, photos as signed URLs

---

5. Bugs found and fixed (not requested — found because the fan-out forced every consignment lookup to be re-read)

5.1 🔴 The rider could never deliver orders 2..N

GET /miler/bookings emitted one row per booking, keyed on pickupbookings.consignmentid — a column that names only the first order. On a three-destination pickup, two parcels would sit in the rider's bag with no stop, no deliver button and no way to close them.

Without this fix the entire multi-destination feature would have created orders nobody could deliver. milerStopsForBooking now emits one stop per order after collection (and still exactly one visit before it — the rider goes to the door once). Tested in controllers/cxCustomerApp_test.go.

5.2 🔴 Three endpoints broken for orders 2..N (same root cause)

• MilerDeliverConsignment returned 404 "assigned consignment not found" — the rider could not complete the delivery at all.
• MilerStartDelivery sent no push and no receiver OTP.
• MilerInwardConsignmentAtHub left the assignment open (so the rider could not go off duty — MilerEndDuty refuses on an open assignment) and recorded the leg's distance and earnings as zero.

All three now resolve through cxDestinationForConsignment.

5.3 🟠 CityGateMiddleware was a no-op for customer bookings

It sniffs the request body for pickuppincode. The new request shape does not carry one — its pickup is a title/sub/lat/lng from the place search — so every customer booking sailed past the operating-city gate. Now checked in the handler against the pincode resolved from the coordinates; a pickup outside an operating city returns 422 unserviceable.

5.4 🔴 Idempotency key collision (introduced by me, caught in review)

Keys were namespaced by user id. On the unauthenticated POST /customer/auth/otp/verify that id is 0 — so two customers who happened to pick the same Idempotency-Key would collide and the second would be handed the first's access token, refresh token and customer record.

Fixed: anonymous callers are scoped by request path + body hash. The authenticated key format is left byte-identical, so no in-flight rider key is orphaned at deploy.

5.9 🟠 Fan-out row audit: three gaps closed

Found by auditing every row-level field the rider app reads, rather than assuming the fan-out was complete:

• collectionamt was never emitted — only codamount. Added alongside it, not as a rename, so the deployed build keeps working.
• COD fell back to 0 when a consignment row did not load, instead of to the destination's own figure. A rider shown ₹0 collects nothing.
• Stop ordering depended on the caller's ORDER BY. Now guaranteed inside milerStopsForBooking, because the ordering is the route.

Also hardened at the same time: CreateCxBooking now rejects an absurd destination count before any database work (cxAbsoluteMaxDestinations), because the district lookup built a WHERE districtcode IN (...) from unbounded caller input; and cxDefaultMaxDestinations dropped from 5 to 1, so a missing configuration row resolves to the safest cap rather than the most permissive — a gate that opens when its config is absent is not a gate.

5.10 🟠 Two different mistakes shared one error message

POST /customer/bookings answered an empty destinations array with "Every destination needs a serviceable state and district" — the same string it uses when a destination is present but missing its state or district.

The contract renders message verbatim, so a customer who had added nothing was told to go and fix details on destinations they did not have. The message described a problem they did not have and hid the one they did. Both cases also carried the same error.code, so the app could not tell them apart either.

Now "Add at least one destination", matching what /customer/fare/estimate already said for the identical mistake. TestEmptyDestinationsSaysAddOneNotFixTheirDetails asserts the two endpoints agree and that the message names the actual fix.

Found by reading the messages rather than the status codes — every one of them is customer-facing copy, and a 400 being correct says nothing about whether it is useful.

5.5 🟡 Pre-existing, flagged not fixed

BookingPickupComplete's comment says a hyperlocal parcel keeps the rider Picked_Up; the code sets them Available. This is the default path today. Changing it alters live rider availability and the dispatch pool — ops decision.

---

5.6 🔴 Rider earnings would have read ₹0 on every customer job (introduced by me, caught while mapping screens)

CreateCxBooking stored the estimate in its own new columns and did not create a BookingServiceOption row — but three places still read one:

• MilerDeliverConsignment and MilerInwardConsignmentAtHub copy Estimatedprice onto BookingAssignment.ridercharges when a leg closes.
• GET /miler/earnings sums that column.
• The admin console's Orders list renders serviceoptions[0].estimatedprice as its Price column.

So every customer-app job a rider completed would have recorded zero earnings on their Earnings screen, and the admin Orders list would have shown "N/A" for the price of every customer booking. Fixed: the booking now creates a service option carrying the midpoint of the band the customer was shown, which is what lookupDoormilePrice returns everywhere else in this codebase.

5.7 🔴 An ops cancellation never reached the customer

AdminCancelBooking, AdminBulkCancelBookings and AdminUpdateBookingStatus all cancel by writing pickupbookings.status directly. None of them knows the customer projection exists — and because customerstatus is written as "active" at booking time, the projection's empty-string fallback never fired.

A customer whose pickup ops cancelled would have kept seeing it as active and cancellable, indefinitely. They would also still have received stage notifications for it.

Fixed in two places, deliberately: the projection now treats the operational status as the authority on cancellation, which covers all three paths and any added later; and the two real cancel paths call cxstage.Cancel so the customer gets a reason and the audit trail records which ops user did it. Both are no-ops for console-created bookings.

5.8 🟠 An expired slot was reported as a full one

CreateCxBooking answered a slot whose window had already passed with 409 "That pickup window just filled up". That is untrue and points the customer at the wrong recovery — they need to re-fetch the slot list, not retry for a place in a queue. A client that caches slots for a session and is left open across midnight hits this on the first booking of the day.

Now 400 invalid with "That pickup time has passed — pick a new slot", which is what the contract already maps to "Pick a pickup slot". A stale date is also now caught by CxSlotDateIsPast before any database access, since the slot id carries its own date — the cheapest validation in the path, and the one that actually fires. 409 is reserved for the genuine capacity race.

Found by a reviewer noticing that §5.3 and §7.7 of this document could not both be comfortable at once. They were right.

6. Tests

go build ./..., go vet ./..., go test ./... all pass. 305 passing assertions/subtests, all runnable with no database.

File	What it proves
controllers/cxHttp_test.go	Status codes and envelopes through a real router. Every validation path answers 4xx with a machine-readable error.code and customer-safe English — never 500, never a router 404. Malformed JSON is 400. All 9 contract error codes map to the right status. CxInternal never leaks the cause. The QA override is invisible unless both gates are open.
routes/routes_customer_test.go	All 20 authenticated routes exist and return 401 without a token (not 404, not 500). All refuse roles 1/3/4/5/6 with 403. Pre-auth routes are reachable and answer from the handler. Retired PIN routes no longer mint a credential. TestMilerSurfaceIsUnchanged / TestConsoleSurfaceIsUnchanged are the regression guard for §0.
controllers/cxCustomerApp_test.go	Phone normalisation (7 spellings → one stored value, so a build change cannot create a duplicate account); the fan-out stop split; timeline dedup and per-order timestamping; deliveredAt waiting for the last parcel; pickup title/sub never empty.
internal/cxstage/stage_test.go	Slowest-order rollup; stage ordering as a wire contract; the cancellation window closing exactly after arrived.
utils/epoch_test.go	IST→epoch for both driver taggings; null stays null; slot window and day formatting.

What the tests do NOT prove

No happy path is asserted. A 200 from CreateCxBooking needs Postgres, Redis and NATS. Mocking them would test the mock. Everything from the handler inwards is still unverified — that is the integration pass in §11.

---

7. Answers to the requirements' §13 open questions

(“§13” here and in §9 means section 13 of the requirements document. Section 13 of THIS document, at the bottom, is the review log.)

1. Payment. v1 is cash/UPI at the door, settled outside the app. No payment step exists and there is no payment contract to hand you. amountPaid is the sum of bookingpayments rows the miler recorded, in whole rupees, present from picked_up. Two different pots of money: the pickup fee is Doormile's, collected once per visit and recorded against the first order; COD at the destination is the customer's own collection, per destination. Doormile is the carrier, never the seller. ⚠️ No settlement/remittance flow exists — money can be collected and recorded, nothing pays it back to the customer.

2. Masked calling. Implemented as a switch: MILER_CALL_PROXY returns a proxy when set, the rider's real number otherwise. Recommendation: set it before launch. A customer handed a rider's personal mobile has it permanently. ⚠️ Currently unset.

3. Partial pickup. Not modelled, not guessed at. Pickup-complete is all-or-nothing. The fan-out makes it expressible (legs are built per destination), but there is no stage key, no miler endpoint and no screen. ⚠️ Product decision needed.

4. Failed delivery / reattempt. Exists operationally — POST /miler/consignments/{id}/skip increments attemptcount and leaves the parcel Out_for_Delivery. Deliberately not mapped to a customer stage: there is no key for it in the nine, and an unknown key renders as booked on the client. So today a failed attempt is invisible to the customer — their parcel stays "Out for delivery". ⚠️ This is the most customer-visible gap in v1. Needs a tenth stage key + a client release.

5. Saved addresses / notification preferences / payment methods. Saved addresses built (capped at 10, same title/sub shape as a place search result). Notification preferences not built. Payment methods not built, correctly, while v1 settles at the door.

6. Support. Not built for the customer. /miler/support exists and the shape would extend. ⚠️ A phone number is the cheapest thing that is not a dead end.

7. Slot capacity semantics. Per zone. A window's remaining capacity counts live bookings whose preferredpickupfrom falls inside it, within 12km of the pickup point, excluding cancelled and completed. The list read is advisory and cached 30s; capacity is re-checked at confirm and a lost race returns 409. The client does not need to re-fetch before confirming.

8. Pricing. Reuses the existing doormile_pricing slab (zone × service type × weight band → min/max), with a distance-and-weight fallback for unpriced lanes. Additional destinations carry a +35% uplift each. Weight assumed 3kg/package until weighed. ⚠️ The 35% is a placeholder, and there is no breakdown when amountPaid exceeds fare.max — the receipt can show amountPaid − fare.min as a weight adjustment, but nothing explains an overage. Product owns both.

9. Cancellation fee. Confirmed free through arrived. No fee is computed, charged or recorded anywhere in the cancel path. The UI copy is accurate. From picked_up onward the server returns 409.

10. Retention. Not implemented — no policy exists to implement. Parcel photos stored indefinitely, PII stored indefinitely, bookingstageevents never pruned. The 30-minute signed-URL TTL limits link lifetime, not object lifetime. ⚠️ This is the answer most likely to matter to a regulator and it is currently blank.

11. Tenancy. Logistics only in v1. Customer JWTs carry tenantid: 0 and B2C bookings leave pickupbookings.tenantid null. The customer app does not switch mode on tenantid the way the Miler app does. ⚠️ Decide before revenue reporting depends on it.

---

8. Non-functional (§3.5)

• Idempotency — POST /customer/bookings and POST /customer/auth/otp/verify. 24h replay.
• Caching — serviceability ETag/If-None-Match → 304, max-age=300. Slots max-age=30. Booking detail supports 304 (it is polled).
• Rate limits — OTP ≤5 per identifier per hour, ≤3 verify attempts per code, 30s resend cooldown that does not consume one of the five. Plus the shared 10/minute per-IP credential budget.
• Pagination — ?limit=&cursor=, default 20, max 50. Keyset, so a new booking landing mid-scroll cannot show the same row twice. total reflects the filtered tab.
• PII — phone masked in SMS logs; parcel photos as signed URLs.
• Audit — actor type, actor id, source endpoint and timestamp on every transition.
• Tenancy — every customer read is scoped by appcustomerid in the query itself, never by a check afterwards.
• ⚠️ Latency is UNMEASURED. Reads are batched (loadCxBundle is a fixed query count regardless of page size) and pricing is Redis-warmed — but p95 ≤ 400ms is an argument, not a measurement.

---

9. Deliverables (§11)

Asked for	Status
OpenAPI 3.1 spec	✅ openapi-customer.yaml — 24 paths, 28 operations, validated. Covers every registered route including profile and saved addresses.
Postman collection	❌ Not produced. The OpenAPI file imports directly into Postman.
Staging seed mirroring the mock	✅ TN/KL/KA open, PY serviceable with no open district, Madurai/Kozhikode/Mangaluru unavailable with reasons, slot t5 at capacity 0
Test accounts + fixed staging OTP	✅ Two accounts seeded; CX_STAGING_OTP=1234, refused when ENV=production
Force a booking to any stage	✅ Double-gated; walks every intermediate stage
Documented error responses	✅ Implemented verbatim; asserted in tests
Error injection	❌ Not built. Happy-path states are forceable; failure states are not.
Written answer to the requirements' §13	✅ §7 above

---

10. Environment variables

GEOCODER_URL=https://nominatim.openstreetmap.org  # place search / reverse geocode upstream
GEOCODER_EMAIL=ops@doormile.com                   # Nominatim policy requires a contact
MILER_CALL_PROXY=                                 # ⚠️ empty exposes the rider's real number
CX_STAGING_OTP=1234                               # refused when ENV=production
CX_ID_SCRAMBLE_KEY=                               # keys the identifier permutation; a working default ships
CX_ALLOW_STAGE_OVERRIDE=false                     # also requires ENV != production

---

11. Before this goes to production — read this

Blockers, stated plainly:

1. 🔴 No SMS provider exists. internal/sms is the seam (a Sender interface, a logging sink, sms.Register()). Until a gateway is plugged in, OTP codes go to the application log and nowhere else. Real customer sign-in is blocked on this. It is the same wall the previous end-to-end test hit. sms.Configured() reports it.
2. 🔴 No integration test has touched any of this. The 305 passing tests cover pure logic, routing, status codes and envelopes. Nothing has run against a real Postgres, Redis or NATS. A clean compile says the code is well-formed, not that it works.
3. 🟠 The migration has not run against a real database. It is additive (AutoMigrate + CREATE SEQUENCE/CREATE INDEX IF NOT EXISTS) and Postgres 11+ adds nullable/defaulted columns without a table rewrite — but should be safe is not has been observed. Run it on staging first and watch pickupbookings.
4. 🟠 MILER_CALL_PROXY is unset, so the tracking screen will show riders' personal mobile numbers.
5. 🟠 No retention policy for parcel photos or PII.
6. 🟡 Failed delivery is invisible to the customer (§7.4).
7. 🟡 Latency unmeasured (§8).
8. 🔴 Multi-destination pickups must stay capped at 1 destination until a rider build keying on consignmentid ships (§0.6). The cap is a database value, not code — verify it, do not assume it.

Suggested deploy order:

1. Staging: deploy, let AutoMigrate run, apply seed_customer_app.sql, set CX_STAGING_OTP=1234.

2. Confirm maxdestinations = 1 in customerbookinglimits (the seed sets it). This is the gate that keeps the fan-out dormant until the rider app can handle it — see §0.6. Nothing else prevents a stranded parcel.

   SELECT applocationid, maxpackages, maxdestinations FROM customerbookinglimits;
   

3. Smoke the customer surface end to end — this is the pass that has never happened.

4. Regression-test the Miler app against staging, specifically: pickup-complete on a single-destination booking, deliver, inward-at-hub, and off-duty. Those are the paths §0 items 3–5 and §5.2 touch.

5. Plug in the SMS gateway before any production customer traffic.

6. Only after a rider build keying on consignmentid is live, raise the cap and test a multi-destination pickup — the genuinely new path:

   UPDATE customerbookinglimits SET maxdestinations = 5 WHERE applocationid IS NULL;
   

---

11.5 Client-side prerequisites — none of §12 works until these land

§12 below is a correct set of instructions for a client that can make requests. Today it cannot, and these are outstanding on the app side (all four are in Appendix B of the requirements, and this document should have carried them forward rather than assuming them done):

1. pubspec.yaml has no http and no shared_preferences. Every rule about headers, idempotency keys and token rotation presumes a network layer that is not yet added.
2. Booking.fromJson parses roughly a third of §9.3. See the §9.6 row above.
3. PickupSlot.fromJson drops tag, milersNearby and caption. The server sends all three; the picker will not show any of them.
4. AppState.loadSlots caches for the whole session and startBooking clears only districtCache (lib/state/app_state.dart:89). An app left open across midnight books against yesterday's slot. The server now answers that with 400 and "That pickup time has passed — pick a new slot" rather than the misleading "just filled up" it used to (§5.8) — but the client fix is to clear slotsCache in startBooking so the customer never reaches that error.

---

12. Quick reference for the app developer

• Base: https://api.doormile.com/api/v1
• Auth: Authorization: Bearer <accessToken> on everything except /customer/auth/otp/request, /auth/signup, /auth/otp/verify, /auth/refresh, and the four catalogue reads.
• Access token 1h, refresh 60 days, rotated on every use. A revoked refresh token replayed kills the whole chain — always store the newest one.
• Send X-Client: doormile-cx/<version>+<build> and X-Platform: android|ios. They are logged and are the only way to tell one build's failures from another's.
• Send Idempotency-Key on booking create and OTP verify.
• Every timestamp is epoch milliseconds, UTC, integer.
• Every string in message is safe to render verbatim. Branch on error.code, never on the message text.
• pickup, slotId, destinations[].stateName and districtName are never null. The rest of details may be absent — that is the "Not added" state, not an error.
• trackingId and stage on a destination are null until order_created. There is no order to track before the parcels are collected.
• An unknown stage key renders as booked. If you see that on a moving parcel, the backend sent a key this build does not know — tell us; it means a new stage shipped without a client release.

---

13. Review log

This document has been reviewed once, by a reviewer with access to the two Flutter apps but not to this Go backend. That split matters and is why the review was useful: every claim it made about the apps was checkable by them and not by me, and every claim about this repo was checkable by me and not by them. The findings below are recorded verbatim in substance, with what was done about each.

Standing caveat the reviewer stated and this document repeats: the 305 tests, the fan-out, the idempotency fix and the epoch conversion are unverified from their side. Nothing in §11 has changed — this code has still never run against a real database.

13.1 Findings — all upheld

#	Finding	Status	What changed
1	The rider-app action item is materially understated. The app's identity key is orderid (api_config.dart:321, 'orderid': ref ?? id), not bookingid. Both are booking-level, so all three fan-out rows collapse — in accepted_store.dart:527 (SharedPreferences-backed, survives restart) and in work_repository.dart:314,321 / order_events.dart. Keying on consignmentid touches four files.	Upheld. Consistent with what this server sends: the three rows share bookingid and bookingreference.	New §0.6 replaces the one-line framing. §0 item 3 now points at it. Mitigation added: maxdestinations seeded at 1, and a deploy-checklist step to verify it.
2	destinationseq / destinationcount are invisible — pickupFromBooking builds a fixed map, so a field the adapter does not name cannot reach the app.	Upheld.	Recorded in §0.6. Adding fields server-side does not help until the adapter names them.
3	"Reuse Booking.fromJson" is optimistic. It parses only reference, stage, cancellable, createdAt, pickup, slotId and four destination fields — ignoring status, miler, deliveryAgent, fare, amountPaid, deliveredAt, history, verification, details, per-destination stage, routeKm, expectedDelivery.	Upheld, and it was avoidable — Appendix B of the requirements said exactly this and this document glossed it.	§1.2's §9.6 row rewritten to state the gap instead of assuming the parser.
4	Slot staleness is a trap handed to the client. §5.3 and §7.7 could not both be comfortable: AppState.loadSlots caches for a session, startBooking clears only districtCache (app_state.dart:89), so an app open across midnight books yesterday's slot.	Upheld — and it exposed a server defect. The server answered 409 "That pickup window just filled up", which is untrue and points at the wrong recovery.	Code fixed (§5.8): now 400 with "That pickup time has passed — pick a new slot", plus a new DB-free CxSlotDateIsPast guard that runs before any query. Test added. Client-side fix (clear slotsCache) recorded in §11.5.
5	§12's header/idempotency/rotation rules assume a client that can make requests; pubspec.yaml has no http, no shared_preferences.	Upheld.	New §11.5 lists the client prerequisites ahead of §12.
6	PickupSlot.fromJson drops tag, milersNearby, caption — the server now sends all three.	Upheld.	§11.5 item 3.
7	§3.2 contains a literal unfilled placeholder: customerController.go │ −691/+?.	Upheld.	Corrected to the real churn, +98 / −593.
8	The counts do not reconcile: 19→28 routes, 8 exempt from auth ⇒ 20 authenticated, but §6 asserts 22.	Upheld. Verified: 28 registered = 8 pre-auth + 20 authenticated; the routing test has exactly 20 entries.	§6 corrected to 20. §1.1 now states the arithmetic explicitly so the three numbers reconcile on the page.
9	The OpenAPI file's 22 operations imply /customer/profile and /customer/locations are absent, though §1.1 relies on them to answer §13.5.	Upheld, and the worst of the three — the app developer works from the spec and would not have found saved addresses.	6 endpoints added to the spec with SavedAddress / SavedAddressInput schemas. Now 24 paths / 28 operations, matching the 28 registered routes exactly.

13.2 What the review confirmed as correct

Recorded because it is the half that did not change, and it is the half the app is built against:

• camelCase throughout — no mapping layer needed on the client.
• Epoch-millis UTC — DateTime.fromMillisecondsSinceEpoch works as-is.
• Payload always in data, auth included.
• pickup, slotId, stateName, districtName non-null — the client types these non-nullable and would throw otherwise.
• "An unknown stage key renders as booked" is accurate against models.dart (JourneyStage.fromKey falls back to booked).
• The §1.3 IST timestamp defect is real and is the bug that already bit the Miler app.
• §8.4's five gaps match independently.
• The two reverts — rider availability, and the 404→403 change — were the right call.
• §11's honesty about what is unverified was called the most useful section here. It has not been softened.

13.3 Reviewer's verdict, unedited in substance

The backend contract is sound and answers the requirements; the impact assessment is accurate in direction but under-scopes the rider-app work, and its "reuse the existing parser" claims describe the client we intend to have, not the one in the repo. Nothing here contradicts the requirements doc.

Both criticisms are now addressed in the text: §0.6 for the rider-app scope, §11.5 and the §9.6 row for the parser claims.

13.4 What still cannot be checked from either side

• Nobody has run this against a real Postgres, Redis or NATS.
• The reviewer could not verify the Go changes; this document's author could not open the Flutter apps. Nothing in §0.6 or §11.5 has been executed — those file and line references come from the review, not from this repo.
• The single integration pass in §11 remains the thing that would close both gaps at once.