@burdenoff/microfe-movethewheels 2026.1016.13 → 2026.1017.1

package/src/movethewheels/pages/OrderDetailsPage.tsx

@@ -50,7 +50,11 @@ import { useOrder, useOrders } from '../hooks/useOrders';
 import { useVehicles, useVehicle, useDrivers, useDriver } from '../hooks/useFleet';
 import { useDebouncedValue } from '../hooks/useDebouncedValue';
 import { FormError } from '../components/FormError';
-import { Notice, useNotice } from '../components/Notice';
+import { Notice } from '../components/Notice';
+import { useOrderDispatch } from '../hooks/useOrderDispatch';
+import { isVehicleAssignable } from '../utils/orderVehicleHold';
+import { reuseRecoveryScope, reuseRecoveryContextKey } from '../utils/reuseRecovery';
+import { useTr } from '../shared/hooks/useTr';
 import { DocumentsCard } from '../components/DocumentsCard';
 import { ProofOfDeliveryCard } from '../components/ProofOfDeliveryCard';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
@@ -94,6 +98,28 @@ function nextStatus(current: OrderStatus): OrderStatus | null {
 }
 
 export default function OrderDetailsPage() {
+  const context = useMoveTheWheels();
+  const { orderId } = useParams<{ orderId: string }>();
+  const scope = reuseRecoveryScope(
+    context.currentUser?.id,
+    context.workspaceId,
+    context.tenantId,
+    context.apiGatewayUrl,
+    context.workspaceToken
+  );
+  const contextKey = JSON.stringify([
+    reuseRecoveryContextKey(scope),
+    context.currentUser?.id,
+    context.workspaceId,
+    context.tenantId,
+    context.apiGatewayUrl,
+    orderId,
+  ]);
+  return <OrderDetails key={contextKey} contextKey={contextKey} contextReady={scope !== null} />;
+}
+
+function OrderDetails({ contextKey, contextReady }: { contextKey: string; contextReady: boolean }) {
+  const tr = useTr();
   const { orderId } = useParams<{ orderId: string }>();
   const { basePath, navigate } = useMoveTheWheels();
   const { order, isLoading, error, refetch } = useOrder(orderId);
@@ -101,9 +127,6 @@ export default function OrderDetailsPage() {
   const [fleetSearch, setFleetSearch] = useState('');
   const [selectedVehicle, setSelectedVehicle] = useState('');
   const [selectedDriver, setSelectedDriver] = useState('');
-  const [assigning, setAssigning] = useState(false);
-  const [advancing, setAdvancing] = useState(false);
-  const [actionError, setActionError] = useState<string | null>(null);
   const debouncedFleetSearch = useDebouncedValue(fleetSearch);
   const {
     vehicles,
@@ -111,6 +134,8 @@ export default function OrderDetailsPage() {
     isLoadingMore: vehiclesLoadingMore,
     hasMore: vehiclesHaveMore,
     totalVehicles,
+    error: vehiclesError,
+    refetch: refreshVehicles,
     loadMore: loadMoreVehicles,
   } = useVehicles({
     limit: 20,
@@ -122,6 +147,8 @@ export default function OrderDetailsPage() {
     isLoadingMore: driversLoadingMore,
     hasMore: driversHaveMore,
     totalDrivers,
+    error: driversError,
+    refetch: refreshDrivers,
     loadMore: loadMoreDrivers,
   } = useDrivers({
     limit: 20,
@@ -130,76 +157,106 @@ export default function OrderDetailsPage() {
   // Resolved independently of the (searched, 20-row) lists above so the
   // trigger still shows the right label once a pick scrolls out of the
   // current search results.
-  const { vehicle: selectedVehicleRecord, isLoading: selectedVehicleLoading } = useVehicle(
-    selectedVehicle || undefined
-  );
-  const { driver: selectedDriverRecord, isLoading: selectedDriverLoading } = useDriver(
-    selectedDriver || undefined
-  );
-  const { message: notice, notify } = useNotice();
+  const {
+    vehicle: selectedVehicleRecord,
+    isLoading: selectedVehicleLoading,
+    error: vehicleError,
+    refetch: refreshVehicle,
+  } = useVehicle(selectedVehicle || order?.vehicleId || undefined);
+  const {
+    driver: selectedDriverRecord,
+    isLoading: selectedDriverLoading,
+    error: driverError,
+    refetch: refreshDriver,
+  } = useDriver(selectedDriver || order?.driverId || undefined);
   const availableVehicles = vehicles.filter(
-    (vehicle) => vehicle.status === 'available' || vehicle.id === order?.vehicleId
+    (vehicle) => isVehicleAssignable(vehicle.status) || vehicle.id === order?.vehicleId
   );
   const availableDrivers = drivers.filter(
     (driver) => driver.status === 'available' || driver.id === order?.driverId
   );
 
-  const handleAssign = async () => {
-    if (!orderId || !order) {
-      setActionError('This order is no longer available. Refresh and try again.');
-      return;
-    }
-
-    const vehicleId = selectedVehicle || order.vehicleId;
-    const driverId = selectedDriver || order.driverId;
-    if (!vehicleId || !driverId) {
-      setActionError('Select both a compatible vehicle and driver before dispatching.');
-      return;
-    }
-
-    const wasFullyAssigned = Boolean(order.vehicleId && order.driverId);
-    setAssigning(true);
-    setActionError(null);
-    try {
-      await updateOrder(orderId, { vehicleId, driverId });
-      if (!wasFullyAssigned && order.status === 'confirmed') {
-        await updateOrderStatus(orderId, 'assigned');
-      }
-      notify(
-        !wasFullyAssigned && order.status === 'confirmed'
-          ? 'Fleet assigned and order advanced to Assigned.'
-          : 'Assignment updated.'
-      );
-      setSelectedVehicle('');
-      setSelectedDriver('');
-      refetch();
-    } catch (err) {
-      setActionError(err instanceof Error ? err.message : 'Failed to update assignment.');
-    } finally {
-      setAssigning(false);
-    }
-  };
-
-  const handleStatusChange = async (status: OrderStatus, successMessage: string) => {
-    if (!orderId || !order) return;
-    if (status === 'assigned' && (!order.vehicleId || !order.driverId)) {
-      setActionError('Assign both a compatible vehicle and driver before advancing to Assigned.');
-      return;
-    }
-    if (TERMINAL_STATUSES.has(order.status)) return;
-
-    setAdvancing(true);
-    setActionError(null);
-    try {
-      await updateOrderStatus(orderId, status);
-      notify(successMessage);
-      refetch();
-    } catch (err) {
-      setActionError(err instanceof Error ? err.message : 'Failed to update status.');
-    } finally {
-      setAdvancing(false);
-    }
+  const {
+    vehicle: assignedVehicle,
+    isLoading: assignedVehicleLoading,
+    error: assignedVehicleError,
+    refetch: refreshAssignedVehicle,
+  } = useVehicle(order?.vehicleId);
+  const assignedVehicleVerified =
+    !order?.vehicleId ||
+    (!assignedVehicleLoading && !assignedVehicleError && assignedVehicle?.id === order.vehicleId);
+  const assignedVehicleHeld = Boolean(
+    order?.vehicleId &&
+    assignedVehicleVerified &&
+    assignedVehicle &&
+    !isVehicleAssignable(assignedVehicle.status)
+  );
+  const effectiveVehicleId = selectedVehicle || order?.vehicleId;
+  const effectiveDriverId = selectedDriver || order?.driverId;
+  const vehicleVerified =
+    !effectiveVehicleId ||
+    (!selectedVehicleLoading && !vehicleError && selectedVehicleRecord?.id === effectiveVehicleId);
+  const driverVerified =
+    !effectiveDriverId ||
+    (!selectedDriverLoading && !driverError && selectedDriverRecord?.id === effectiveDriverId);
+  const vehicleHeld = Boolean(
+    effectiveVehicleId &&
+    vehicleVerified &&
+    selectedVehicleRecord &&
+    !isVehicleAssignable(selectedVehicleRecord.status)
+  );
+  const assignmentEntersMovement = Boolean(
+    order && !(order.vehicleId && order.driverId) && order.status === 'confirmed'
+  );
+  const heldAssignmentBlocked =
+    vehicleHeld && (effectiveVehicleId !== order?.vehicleId || assignmentEntersMovement);
+  const refreshAssignment = () => {
+    refetch();
+    refreshVehicle();
+    refreshAssignedVehicle();
+    refreshDriver();
+    refreshVehicles();
+    refreshDrivers();
   };
+  const dispatch = useOrderDispatch({
+    order,
+    contextKey,
+    ready: contextReady && !isLoading && !error && Boolean(order),
+    assignmentReady:
+      Boolean(effectiveVehicleId && effectiveDriverId) &&
+      vehicleVerified &&
+      driverVerified &&
+      !heldAssignmentBlocked &&
+      !vehiclesLoading &&
+      !driversLoading &&
+      !vehiclesError &&
+      !driversError,
+    movementReady: assignedVehicleVerified && !assignedVehicleHeld,
+    updateOrder,
+    updateOrderStatus,
+    refresh: refreshAssignment,
+  });
+  const assignmentChanged =
+    effectiveVehicleId !== order?.vehicleId || effectiveDriverId !== order?.driverId;
+  const actionUnavailable =
+    dispatch.busy || dispatch.blocked || !contextReady || isLoading || Boolean(error);
+  const handleAssign = () => dispatch.assign(effectiveVehicleId ?? '', effectiveDriverId ?? '');
+  const handleStatusChange = (status: OrderStatus) => dispatch.changeStatus(status);
+  const heldMessage =
+    selectedVehicleRecord?.status === 'maintenance'
+      ? tr(
+          'movethewheels.order.vehicleMaintenance',
+          'Vehicle marked for maintenance. Choose another vehicle.'
+        )
+      : selectedVehicleRecord?.status === 'decommissioned'
+        ? tr(
+            'movethewheels.order.vehicleDecommissioned',
+            'Vehicle decommissioned. Choose another vehicle.'
+          )
+        : tr(
+            'movethewheels.order.vehicleInactive',
+            'Vehicle marked inactive. Choose another vehicle.'
+          );
 
   const goTo = (path: string) => {
     if (navigate) {
@@ -213,15 +270,18 @@ export default function OrderDetailsPage() {
     }
   };
 
-  if (isLoading) {
+  if (isLoading && !order) {
     return <LoadingState message="Loading order details..." />;
   }
 
-  if (error || !order) {
+  if (!order) {
     return (
       <ErrorState
-        title="Order not found"
-        message="The order you're looking for doesn't exist or has been removed."
+        title={tr('movethewheels.order.unavailable', 'Order unavailable')}
+        message={tr(
+          'movethewheels.order.loadUnavailable',
+          'The requested order could not be loaded. Refresh before making changes.'
+        )}
         onRetry={refetch}
       />
     );
@@ -558,8 +618,65 @@ export default function OrderDetailsPage() {
             </CardHeader>
             <CardContent>
               <div className="space-y-4">
-                {actionError && <FormError message={actionError} />}
-                {notice && <Notice message={notice} />}
+                {isLoading && (
+                  <p role="status" className="text-sm">
+                    {tr(
+                      'movethewheels.order.refreshing',
+                      'Refreshing order details. Changes are unavailable.'
+                    )}
+                  </p>
+                )}
+                {error && (
+                  <FormError
+                    message={tr(
+                      'movethewheels.order.refreshFailed',
+                      'Order details could not be refreshed. Existing values are read-only.'
+                    )}
+                  />
+                )}
+                {dispatch.message && <Notice variant="info" message={dispatch.message} />}
+                {dispatch.knownAssignment && (
+                  <p className="text-sm break-words" role="status">
+                    {tr(
+                      'movethewheels.order.knownAssignment',
+                      'Saved assignment: vehicle {{vehicle}}, driver {{driver}}.',
+                      {
+                        vehicle:
+                          selectedVehicleRecord?.id === dispatch.knownAssignment.vehicleId
+                            ? selectedVehicleRecord.vehicleNumber
+                            : dispatch.knownAssignment.vehicleId,
+                        driver:
+                          selectedDriverRecord?.id === dispatch.knownAssignment.driverId
+                            ? selectedDriverRecord.fullName
+                            : dispatch.knownAssignment.driverId,
+                      }
+                    )}
+                  </p>
+                )}
+                {dispatch.blocked && (
+                  <FormError
+                    message={tr(
+                      'movethewheels.order.blocked',
+                      'An order write is unconfirmed. Refresh is read-only and will not unlock another write.'
+                    )}
+                  />
+                )}
+                {vehicleHeld && <FormError message={heldMessage} />}
+                {(!vehicleVerified ||
+                  !driverVerified ||
+                  !assignedVehicleVerified ||
+                  vehiclesError ||
+                  driversError) && (
+                  <FormError
+                    message={tr(
+                      'movethewheels.order.unverifiedFleet',
+                      'Vehicle status could not be verified. Refresh before assigning or advancing.'
+                    )}
+                  />
+                )}
+                <Button variant="outline" onClick={refreshAssignment} disabled={dispatch.busy}>
+                  {tr('movethewheels.order.refreshAssignment', 'Refresh assignment')}
+                </Button>
 
                 <div>
                   <p className="text-sm text-text-secondary">Tracking Number</p>
@@ -576,6 +693,7 @@ export default function OrderDetailsPage() {
                       <Input
                         id="assign-fleet-search"
                         value={fleetSearch}
+                        disabled={actionUnavailable}
                         onChange={(event) => setFleetSearch(event.target.value)}
                         placeholder="Vehicle number, driver name or employee ID"
                         className="pl-9"
@@ -586,7 +704,8 @@ export default function OrderDetailsPage() {
                     <Label htmlFor="assign-vehicle">Vehicle</Label>
                     <EntityCombobox
                       id="assign-vehicle"
-                      value={selectedVehicle}
+                      disabled={actionUnavailable}
+                      value={effectiveVehicleId ?? ''}
                       onChange={setSelectedVehicle}
                       options={availableVehicles}
                       loading={vehiclesLoading}
@@ -597,8 +716,8 @@ export default function OrderDetailsPage() {
                           {vehicle.vehicleNumber} ({vehicle.type})
                         </>
                       )}
-                      selectedOption={selectedVehicleRecord}
-                      selectedLoading={selectedVehicleLoading}
+                      selectedOption={vehicleVerified ? selectedVehicleRecord : null}
+                      selectedLoading={!vehicleVerified}
                       hasMore={vehiclesHaveMore}
                       totalCount={totalVehicles}
                       onLoadMore={loadMoreVehicles}
@@ -617,7 +736,8 @@ export default function OrderDetailsPage() {
                     <Label htmlFor="assign-driver">Driver</Label>
                     <EntityCombobox
                       id="assign-driver"
-                      value={selectedDriver}
+                      disabled={actionUnavailable}
+                      value={effectiveDriverId ?? ''}
                       onChange={setSelectedDriver}
                       options={availableDrivers}
                       loading={driversLoading}
@@ -628,8 +748,8 @@ export default function OrderDetailsPage() {
                           {driver.fullName} ({driver.employeeId})
                         </>
                       )}
-                      selectedOption={selectedDriverRecord}
-                      selectedLoading={selectedDriverLoading}
+                      selectedOption={driverVerified ? selectedDriverRecord : null}
+                      selectedLoading={!driverVerified}
                       hasMore={driversHaveMore}
                       totalCount={totalDrivers}
                       onLoadMore={loadMoreDrivers}
@@ -645,10 +765,19 @@ export default function OrderDetailsPage() {
                   <Button
                     className="w-full"
                     onClick={handleAssign}
-                    disabled={assigning || (!selectedVehicle && !selectedDriver)}
+                    disabled={
+                      actionUnavailable ||
+                      !assignmentChanged ||
+                      heldAssignmentBlocked ||
+                      !vehicleVerified ||
+                      !driverVerified ||
+                      vehiclesLoading ||
+                      driversLoading ||
+                      Boolean(vehiclesError || driversError)
+                    }
                   >
                     <UserCheck size={16} />
-                    {assigning ? 'Assigning…' : 'Assign driver & vehicle'}
+                    {dispatch.busy ? 'Assigning…' : 'Assign driver & vehicle'}
                   </Button>
                 </div>
 
@@ -659,6 +788,14 @@ export default function OrderDetailsPage() {
                     Current status:{' '}
                     <span className="font-medium">{STATUS_LABELS[order.status]}</span>
                   </p>
+                  {assignedVehicleHeld && (
+                    <p className="text-sm text-status-error-text" role="status">
+                      {tr(
+                        'movethewheels.order.currentVehicleHeld',
+                        'The currently assigned vehicle is on hold. Save a replacement before advancing movement.'
+                      )}
+                    </p>
+                  )}
                   {(() => {
                     const upcoming = nextStatus(order.status);
                     if (!upcoming) return null;
@@ -669,16 +806,18 @@ export default function OrderDetailsPage() {
                         <Button
                           variant="outline"
                           className="w-full"
-                          onClick={() =>
-                            handleStatusChange(
-                              upcoming,
-                              `Order advanced to ${STATUS_LABELS[upcoming]}.`
-                            )
+                          onClick={() => handleStatusChange(upcoming)}
+                          disabled={
+                            actionUnavailable ||
+                            missingDispatchPair ||
+                            (['assigned', 'picked_up', 'in_transit', 'out_for_delivery'].includes(
+                              upcoming
+                            ) &&
+                              (!assignedVehicleVerified || assignedVehicleHeld))
                           }
-                          disabled={advancing || missingDispatchPair}
                         >
                           <ArrowRight size={16} />
-                          {advancing ? 'Updating…' : `Advance to ${STATUS_LABELS[upcoming]}`}
+                          {dispatch.busy ? 'Updating…' : `Advance to ${STATUS_LABELS[upcoming]}`}
                         </Button>
                         {missingDispatchPair && (
                           <p className="text-xs text-text-secondary">
@@ -693,8 +832,8 @@ export default function OrderDetailsPage() {
                     <Button
                       variant="outline"
                       className="w-full text-status-error-text"
-                      onClick={() => handleStatusChange('cancelled', 'Order cancelled.')}
-                      disabled={advancing}
+                      onClick={() => handleStatusChange('cancelled')}
+                      disabled={actionUnavailable}
                     >
                       <XCircle size={16} />
                       Cancel order

package/src/movethewheels/utils/graphqlClient.ts

@@ -1,3 +1,4 @@
+import { vehicleHoldRefusal, type VehicleHoldMutation } from './orderVehicleHold';
 import { prepareWorkspaceRequest } from '@burdenoff/fe-libs/shared/graphql';
 
 export type GraphQLAttemptPolicy = 'RETRY_TRANSIENT' | 'SINGLE_ATTEMPT';
@@ -111,7 +112,8 @@ export async function executeGraphQL<TData>(
   options: GraphQLRequestOptions,
   query: string,
   variables?: Record<string, unknown>,
-  attemptPolicy: GraphQLAttemptPolicy = 'RETRY_TRANSIENT'
+  attemptPolicy: GraphQLAttemptPolicy = 'RETRY_TRANSIENT',
+  holdRefusalField?: VehicleHoldMutation
 ): Promise<TData> {
   // Capture the original intent before queueing or asynchronously renewing authority.
   const request = { ...options };
@@ -152,7 +154,8 @@ export async function executeGraphQL<TData>(
       headers,
       body,
       attemptPolicy === 'SINGLE_ATTEMPT' ? 0 : MAX_RETRIES,
-      authority?.assertCurrent ?? (() => {})
+      authority?.assertCurrent ?? (() => {}),
+      attemptPolicy === 'SINGLE_ATTEMPT' ? holdRefusalField : undefined
     );
   } finally {
     releaseSlot();
@@ -160,24 +163,45 @@ export async function executeGraphQL<TData>(
 }
 
 /** Best-effort: the joined `errors[].message` of a non-2xx GraphQL response, or null. */
-async function readGraphqlErrorMessage(response: Response): Promise<string | null> {
+async function readGraphqlErrorMessage(
+  response: Response,
+  holdRefusalField?: VehicleHoldMutation
+): Promise<Error | null> {
   try {
     const payload = (await response.json()) as { errors?: Array<{ message?: string }> };
+    const refusal = vehicleHoldRefusal(payload, response.status, holdRefusalField);
+    if (refusal) return refusal;
     const messages = (payload.errors ?? [])
       .map((item) => item.message)
       .filter((message): message is string => typeof message === 'string' && message.length > 0);
-    return messages.length > 0 ? messages.join('; ') : null;
+    return messages.length > 0 ? new Error(messages.join('; ')) : null;
   } catch {
     return null;
   }
 }
 
+/** A write ACK must have one owning root and an absent or empty errors array. */
+function validWriteEnvelope(payload: unknown, field: VehicleHoldMutation): boolean {
+  if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) return false;
+  if ('errors' in payload && (!Array.isArray(payload.errors) || payload.errors.length !== 0))
+    return false;
+  if (
+    !('data' in payload) ||
+    typeof payload.data !== 'object' ||
+    payload.data === null ||
+    Array.isArray(payload.data)
+  )
+    return false;
+  return Object.keys(payload.data).length === 1 && Object.hasOwn(payload.data, field);
+}
+
 async function runWithRetries<TData>(
   url: string,
   headers: Record<string, string>,
   body: string,
   retries: number,
-  assertCurrent: () => void
+  assertCurrent: () => void,
+  holdRefusalField?: VehicleHoldMutation
 ): Promise<TData> {
   let lastError: Error = new Error('GraphQL request failed');
 
@@ -204,8 +228,8 @@ async function runWithRetries<TData>(
         // rule rejection) — show that message rather than a bare status code.
         const detail = isTransientStatus(response.status)
           ? null
-          : await readGraphqlErrorMessage(response);
-        lastError = new Error(detail ?? `GraphQL request failed with status ${response.status}`);
+          : await readGraphqlErrorMessage(response, holdRefusalField);
+        lastError = detail ?? new Error(`GraphQL request failed with status ${response.status}`);
         if (canRetry && isTransientStatus(response.status)) continue;
         throw lastError;
       }
@@ -215,6 +239,11 @@ async function runWithRetries<TData>(
         errors?: Array<{ message?: string }>;
       };
 
+      const refusal = vehicleHoldRefusal(payload, response.status, holdRefusalField);
+      if (refusal) throw refusal;
+      if (holdRefusalField && !validWriteEnvelope(payload, holdRefusalField))
+        throw new Error('The order write response could not be confirmed.');
+
       if (payload.errors?.length) {
         const message = payload.errors
           .map((item) => item.message ?? 'Unknown GraphQL error')

package/src/movethewheels/utils/orderVehicleHold.ts

@@ -0,0 +1,84 @@
+export type VehicleHoldMutation = 'updateDeliveryJob' | 'updateDeliveryJobStatus';
+
+export class VehicleHoldRefusal extends Error {
+  constructor(
+    readonly operation: VehicleHoldMutation,
+    readonly kind: 'vehicle' | 'driver' = 'vehicle'
+  ) {
+    super('The recorded eligibility prevents this assignment or movement.');
+    this.name = 'VehicleHoldRefusal';
+  }
+}
+
+function object(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Only the owning pre-write refusal is known to have made no job/history write. */
+export function vehicleHoldRefusal(
+  payload: unknown,
+  status: number,
+  operation?: VehicleHoldMutation
+): VehicleHoldRefusal | null {
+  if (!operation || (status !== 200 && status !== 400) || !object(payload)) return null;
+  if (!Array.isArray(payload.errors) || payload.errors.length !== 1) return null;
+  const error: unknown = payload.errors[0];
+  if (!object(error) || typeof error.message !== 'string' || !error.message) return null;
+  if (!Array.isArray(error.path) || error.path.length !== 1 || error.path[0] !== operation)
+    return null;
+  if (!object(error.extensions) || error.extensions.code !== 'BAD_USER_INPUT') return null;
+  const key = error.extensions.i18nKey;
+  const kind =
+    key === 'route.errors.vehicleNotAssignable'
+      ? 'vehicle'
+      : key === 'route.errors.driverInactive' ||
+          key === 'route.errors.driverLicenseUnknown' ||
+          key === 'route.errors.driverLicenseExpired'
+        ? 'driver'
+        : null;
+  if (!kind) return null;
+  if (
+    payload.data !== undefined &&
+    payload.data !== null &&
+    (!object(payload.data) ||
+      Object.keys(payload.data).length !== 1 ||
+      payload.data[operation] !== null)
+  )
+    return null;
+  return new VehicleHoldRefusal(operation, kind);
+}
+
+const API_STATUSES = new Set([
+  'PENDING',
+  'CONFIRMED',
+  'ASSIGNED',
+  'PICKED_UP',
+  'IN_TRANSIT',
+  'OUT_FOR_DELIVERY',
+  'DELIVERED',
+  'RETURNED',
+  'CANCELLED',
+  'FAILED',
+]);
+
+/** Validate the returned write identity before mapping or dispatching a dependent mutation. */
+export function assertOrderAcknowledgement(
+  value: unknown,
+  expected: { id: string; vehicleId?: string; driverId?: string; status?: string }
+): void {
+  if (
+    !object(value) ||
+    value.id !== expected.id ||
+    typeof value.status !== 'string' ||
+    !API_STATUSES.has(value.status) ||
+    (expected.vehicleId !== undefined && value.vehicleId !== expected.vehicleId) ||
+    (expected.driverId !== undefined && value.driverId !== expected.driverId) ||
+    (expected.status !== undefined && value.status !== expected.status)
+  )
+    throw new Error('The order write could not be confirmed.');
+}
+
+export function isVehicleAssignable(status: string): boolean {
+  // These are the existing view-model mappings of ACTIVE and IN_TRANSIT.
+  return status === 'available' || status === 'assigned';
+}