Use the reviewed order mutation contract
Driver order mutation is a server-authorized state transition, not a button press or client-side status assignment. One-order and grouped updates, assignment decisions, media, location, reasons, ETA, queue effects, and follow-ons must remain separate.
The current contract is source-api-only. No public claim may treat navigation,
toast, returned order, image preview, location check, socket event, or member
aggregation as durable mutation success.
Availability
Mutation controls are conditional on order/request type, current returned state, Driver ownership, project configuration, permissions, connectivity, loading, locks, assignment context, and visible requirements.
Control visibility is only a client gate. The service must independently authorize the Driver, order/assignment relationship, target transition, lock, concurrency, required reason, media, and location.
Prerequisites
- Bind actor identity to the authenticated session.
- Read the current order/assignment revision immediately before mutation.
- Use a typed transition command rather than a generic client status value.
- Define required reason/comment, ETA, image, location and configuration per transition.
- Supply an idempotency/concurrency strategy and an observable result receipt.
- For groups, identify every member and expected per-member result explicitly.
Responsibility boundaries
| Owner | Responsibility |
|---|---|
| Driver App UI | Present eligible-looking controls, requirements, loading, and errors without claiming authority |
| Client controller | Build one typed intent, preserve uncertain state, and avoid blind retry |
| Order API | Authenticate, authorize ownership, lock, validate transition and inputs, and produce durable receipt |
| Assignment API | Own accept/reject assignment decisions separately from order status |
| Media/location services | Validate/store only after authorization with cleanup on failure |
| Group coordinator | Return one result per member; never hide partial outcomes |
| Follow-on services | History, messages, reports, queue, logistics, sockets, notifications, mail, webhooks, jobs, plugins |
| Dispatcher/operator | Reconcile uncertain, competing, or partial outcomes |
Inputs and result
One-order inputs can include intended transition, reason/comment, ETA, delivery position, location candidate, image, and order revision. Requirements vary by transition/configuration; no complete old-to-new graph is accepted from the client alone.
The result contract must distinguish:
- request rejected before any effect;
- order write accepted;
- media/location write accepted or cleaned up;
- follow-ons complete, partial, or failed;
- current returned order revision; and
- safe retry/duplicate classification.
Grouped mutation is a collection of independently authorized member updates. Current client aggregation can return null for failed members and obscure partial success. A safe contract returns explicit per-member receipts and does not claim atomic rollback.
Security and privacy
- Authorize before image upload, location write, or order mutation.
- Validate finite coordinates, freshness, mock policy, target, timestamp and purpose server-side.
- Trim and validate meaningful reasons/comments; do not accept whitespace as policy evidence.
- Keep media, location, order, participant, token, lock and provider details out of public logs/evidence.
- Do not treat a client PIN, image, permission gate, or local location checklist as server authorization.
Limits and failure states
| State | Required interpretation |
|---|---|
| Control visible/enabled | Client candidate only |
| Requirements modal | Local precheck only |
| Request loading | Outcome unresolved; no retry |
| Returned error | Earlier media/location/follow-on effects may still require cleanup |
| Returned order | Order response only, not all follow-ons |
| Navigation/toast | Client presentation only |
| Group mixed/null results | Partial member outcomes |
| Socket/push | Transport hint, not durable receipt |
| Force/recovery form | Conditional client branch, not guaranteed server contract |
Current source does not establish exactly-once mutation, complete idempotency, atomic media/location/order/follow-ons, group rollback, or deployed success.
Troubleshooting
A control is visible but the service rejects it
Treat UI and server validation as separate. Refresh the authorized order once and reconcile ownership/lock/configuration; do not bypass the gate.
A request times out or navigation changes
Do not repeat. Query the current order/assignment revision and require an idempotency/result receipt before deciding whether a retry is safe.
One group member differs
Record every member result and reconcile independently. Do not report group success from aggregate navigation or a subset of cards.
Media or location succeeded before an order error
Run the approved cleanup/reconciliation path. Do not assume rollback; report the order, media and location stages separately.
A force form appears
Treat it as conditional recovery, not proof the server emitted the expected typed condition. Require an explicit reviewed error contract.
Related guides: Use the logistic request contract · Use the reviewed maps contract · Accept a delivery request · Run governed evidence safely