@burdenoff/microfe-movethewheels 2026.1010.2 → 2026.1011.2

package/src/movethewheels/MoveTheWheelsRoot.tsx

@@ -92,6 +92,20 @@ const NavRegistrar: FC<Pick<MoveTheWheelsRootProps, 'registerNavItems' | 'basePa
           path: joinPath(basePath, 'tracking'),
           icon: <Map size={16} />,
           order: 3,
+          children: [
+            {
+              id: 'mtw-tracking-quality',
+              label: tr('movethewheels.root.nav.trackingQuality', 'Tracking event quality'),
+              path: joinPath(basePath, 'tracking/event-quality'),
+              icon: <Map size={16} />,
+            },
+            {
+              id: 'mtw-status-authority',
+              label: tr('movethewheels.root.nav.statusAuthority', 'Shipment status authority'),
+              path: joinPath(basePath, 'shipments/status-authority'),
+              icon: <ClipboardList size={16} />,
+            },
+          ],
         },
         {
           id: 'mtw-consolidation',

package/src/movethewheels/MoveTheWheelsRoutes.tsx

@@ -55,6 +55,8 @@ const OrdersListPage = lazy(() => import('./pages/OrdersListPage'));
 const OrderDetailsPage = lazy(() => import('./pages/OrderDetailsPage'));
 const CreateOrderPage = lazy(() => import('./pages/CreateOrderPage'));
 const TrackingPage = lazy(() => import('./pages/TrackingPage'));
+const TrackingEventQualityPage = lazy(() => import('./pages/TrackingEventQualityPage'));
+const ShipmentStatusAuthorityPage = lazy(() => import('./pages/ShipmentStatusAuthorityPage'));
 const LiveTrackingPage = lazy(() => import('./pages/LiveTrackingPage'));
 const FleetPage = lazy(() => import('./pages/FleetPage'));
 const VehiclesPage = lazy(() => import('./pages/VehiclesPage'));
@@ -108,6 +110,8 @@ export function MoveTheWheelsRoutes() {
         {/* Tracking */}
         <Route path="tracking" element={<TrackingPage />} />
         <Route path="tracking/live" element={<LiveTrackingPage />} />
+        <Route path="tracking/event-quality" element={<TrackingEventQualityPage />} />
+        <Route path="shipments/status-authority" element={<ShipmentStatusAuthorityPage />} />
 
         {/* Driver ePOD capture (BOFF-4399) */}
         <Route path="deliveries/mine" element={<DeliveryCapturePage />} />

package/src/movethewheels/hooks/useEpod.ts

@@ -12,11 +12,13 @@
  * multi-language delivery instructions.
  */
 import { useCallback, useEffect, useMemo, useState } from 'react';
+import { parse } from 'graphql';
+import { useShipmentStatusCommand } from './useShipmentStatusAuthority';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import type { Order, ProofOfDelivery, SignatureType } from '../types';
 import { executeGraphQL } from '../utils/graphqlClient';
 
-interface ApiProofOfDelivery {
+export interface ApiProofOfDelivery {
   id: string;
   deliveryJobId: string;
   shipmentId?: string | null;
@@ -81,6 +83,7 @@ const CAPTURE_EPOD_MUTATION = `
     }
   }
 `;
+const CAPTURE_EPOD_DOCUMENT = parse(CAPTURE_EPOD_MUTATION);
 
 const INITIATE_UPLOAD_MUTATION = `
   mutation EpodInitiateUpload($input: InitiateUploadInput!) {
@@ -257,6 +260,9 @@ export function useMyPendingEpodDeliveryJobs(options: { limit?: number; offset?:
 }
 
 export interface CaptureEpodArgs {
+  expectedShipmentId: string | null;
+  expectedShipmentStatusRevision?: number;
+  completionAttestation: boolean;
   deliveryJobId: string;
   recipientName: string;
   signatureType: SignatureType;
@@ -268,22 +274,48 @@ export interface CaptureEpodArgs {
   notes?: string;
 }
 
+export function epodAcknowledged(
+  actual: ApiProofOfDelivery | null | undefined,
+  expected: CaptureEpodArgs
+): boolean {
+  return (
+    !!actual &&
+    typeof actual.id === 'string' &&
+    actual.id.trim().length > 0 &&
+    actual.deliveryJobId === expected.deliveryJobId &&
+    actual.shipmentId === expected.expectedShipmentId &&
+    actual.recipientName === expected.recipientName &&
+    actual.signatureType === toApiSignatureType(expected.signatureType) &&
+    actual.signatureData === expected.signatureData &&
+    typeof actual.capturedByDriverId === 'string' &&
+    actual.capturedByDriverId.trim().length > 0 &&
+    typeof actual.deliveredAt === 'string' &&
+    Number.isFinite(Date.parse(actual.deliveredAt)) &&
+    Array.isArray(actual.photoFileIds) &&
+    actual.photoFileIds.length === (expected.photoFileIds ?? []).length &&
+    actual.photoFileIds.every((id, index) => id === (expected.photoFileIds ?? [])[index]) &&
+    actual.latitude === (expected.latitude ?? null) &&
+    actual.longitude === (expected.longitude ?? null) &&
+    actual.locationAccuracy === (expected.locationAccuracy ?? null) &&
+    actual.notes === (expected.notes ?? null)
+  );
+}
+
 /** Driver-facing capture mutation. Identity/ownership is enforced server-side — this never sends a driver id. */
 export function useCaptureEpod() {
-  const graphQLOptions = useGraphQLOptions();
-  const [isSubmitting, setIsSubmitting] = useState(false);
+  const command = useShipmentStatusCommand();
   const [error, setError] = useState<Error | null>(null);
 
   const captureEpod = useCallback(
     async (args: CaptureEpodArgs): Promise<ProofOfDelivery> => {
-      setIsSubmitting(true);
       setError(null);
       try {
-        const data = await executeGraphQL<{ captureEpod: ApiProofOfDelivery }>(
-          graphQLOptions,
-          CAPTURE_EPOD_MUTATION,
+        const data = await command.run<{ captureEpod: ApiProofOfDelivery }>(
+          CAPTURE_EPOD_DOCUMENT,
           {
             input: {
+              expectedShipmentStatusRevision: args.expectedShipmentStatusRevision,
+              completionAttestation: args.completionAttestation,
               deliveryJobId: args.deliveryJobId,
               recipientName: args.recipientName,
               signatureType: toApiSignatureType(args.signatureType),
@@ -294,8 +326,13 @@ export function useCaptureEpod() {
               locationAccuracy: args.locationAccuracy,
               notes: args.notes,
             },
-          }
+          },
+          (data) => epodAcknowledged(data.captureEpod, args)
         );
+        if (!data)
+          throw new Error(
+            'Capture was not acknowledged. Review the recorded status and the capture message before taking further action.'
+          );
         return mapEpod(data.captureEpod);
       } catch (captureError) {
         const err =
@@ -304,14 +341,12 @@ export function useCaptureEpod() {
             : new Error('Failed to capture proof of delivery');
         setError(err);
         throw err;
-      } finally {
-        setIsSubmitting(false);
       }
     },
-    [graphQLOptions]
+    [command]
   );
 
-  return { captureEpod, isSubmitting, error };
+  return { captureEpod, isSubmitting: command.busy, error, captureFeedback: command.feedback };
 }
 
 export interface UploadedEpodPhoto {

package/src/movethewheels/hooks/useShipmentStatusAuthority.ts

@@ -0,0 +1,179 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { print, type DocumentNode } from 'graphql';
+import { graphqlFetch, clearGraphqlFetchResponseCache } from '@burdenoff/fe-libs/shared/graphql';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+
+const KNOWN_REJECTIONS = new Set([
+  'STATUS_REVISION_CONFLICT',
+  'BAD_USER_INPUT',
+  'FORBIDDEN',
+  'UNAUTHENTICATED',
+  'NOT_FOUND',
+]);
+
+export class ShipmentStatusRequestError extends Error {
+  constructor(
+    message: string,
+    readonly code: string | null
+  ) {
+    super(message);
+    this.name = 'ShipmentStatusRequestError';
+  }
+}
+
+/** Normal shared gateway transport; mutation acknowledgements are never automatically retried. */
+export function useShipmentStatusApi() {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId } = useMoveTheWheels();
+  const context = useMemo(
+    () => ({ apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId]
+  );
+  return useCallback(
+    async <T>(
+      document: DocumentNode,
+      variables: Record<string, unknown>,
+      mutation = false,
+      signal?: AbortSignal
+    ): Promise<T> => {
+      const response = await graphqlFetch<T>({
+        gateway: 'workspace',
+        query: print(document),
+        variables,
+        baseUrl: context.apiGatewayUrl,
+        authToken: context.authToken,
+        workspaceToken: context.workspaceToken || true,
+        workspaceId: context.workspaceId || true,
+        tenantId: context.tenantId || true,
+        organizationId: true,
+        signal,
+        skipAuthRetry: mutation,
+      });
+      if (response.errors?.length) {
+        // A single verified rejection is distinct from a transport failure or partial response.
+        const first = response.errors[0];
+        const code =
+          response.data === null &&
+          response.errors.length === 1 &&
+          typeof first?.extensions?.code === 'string'
+            ? first.extensions.code
+            : null;
+        throw new ShipmentStatusRequestError(
+          first?.message ?? 'Unable to load the recorded status.',
+          code
+        );
+      }
+      if (response.data == null)
+        throw new ShipmentStatusRequestError('No acknowledgement was received.', null);
+      return response.data;
+    },
+    [context]
+  );
+}
+
+export function useShipmentStatusQuery<T>(
+  document: DocumentNode,
+  variables: Record<string, unknown> | null,
+  revision = 0
+) {
+  const request = useShipmentStatusApi();
+  const key = JSON.stringify(variables);
+  const [state, setState] = useState<{
+    request: typeof request;
+    key: string;
+    revision: number;
+    data: T | null;
+    error: string | null;
+    loading: boolean;
+  } | null>(null);
+  useEffect(() => {
+    const controller = new AbortController();
+    const scope = { request, key, revision };
+    setState({ ...scope, data: null, error: null, loading: key !== 'null' });
+    if (key === 'null') return;
+    // An explicit review refresh must read the gateway rather than its short-lived response cache.
+    if (revision > 0) clearGraphqlFetchResponseCache();
+    const input: Record<string, unknown> = JSON.parse(key);
+    void request<T>(document, input, false, controller.signal)
+      .then((data) => {
+        if (!controller.signal.aborted) setState({ ...scope, data, error: null, loading: false });
+      })
+      .catch((failure: unknown) => {
+        if (!controller.signal.aborted)
+          setState({
+            ...scope,
+            data: null,
+            error: failure instanceof Error ? failure.message : 'Unable to load recorded status.',
+            loading: false,
+          });
+      });
+    return () => controller.abort();
+  }, [document, request, key, revision]);
+  const current = state?.request === request && state.key === key && state.revision === revision;
+  return {
+    data: current ? state.data : null,
+    error: current ? state.error : null,
+    loading: current ? state.loading : key !== 'null',
+  };
+}
+
+export function useShipmentStatusCommand() {
+  const request = useShipmentStatusApi();
+  const lock = useRef(false);
+  const uncertain = useRef(false);
+  const [busy, setBusy] = useState(false);
+  const [feedback, setFeedback] = useState<{
+    kind: 'APPLIED' | 'REJECTED' | 'UNKNOWN';
+    message: string;
+  } | null>(null);
+  const [revision, setRevision] = useState(0);
+  const run = async <T>(
+    document: DocumentNode,
+    variables: Record<string, unknown>,
+    acknowledged: (result: T) => boolean
+  ): Promise<T | null> => {
+    if (lock.current || uncertain.current) return null;
+    lock.current = true;
+    setBusy(true);
+    setFeedback(null);
+    try {
+      const result = await request<T>(document, variables, true);
+      if (!acknowledged(result))
+        throw new ShipmentStatusRequestError(
+          'The returned acknowledgement does not identify this decision.',
+          null
+        );
+      setFeedback({
+        kind: 'APPLIED',
+        message: 'Decision recorded. Review the refreshed status and history.',
+      });
+      setRevision((value) => value + 1);
+      return result;
+    } catch (failure) {
+      const known =
+        failure instanceof ShipmentStatusRequestError &&
+        failure.code !== null &&
+        KNOWN_REJECTIONS.has(failure.code);
+      uncertain.current = !known;
+      setFeedback({
+        kind: known ? 'REJECTED' : 'UNKNOWN',
+        message: known
+          ? `${failure.message} Your input is preserved; refresh and review the recorded status before another action.`
+          : 'Acknowledgement is uncertain. Do not resend this action. Refresh the recorded status and review its decisions before beginning a separate new action.',
+      });
+      return null;
+    } finally {
+      lock.current = false;
+      setBusy(false);
+    }
+  };
+  return {
+    run,
+    busy,
+    feedback,
+    revision,
+    beginSeparateAction: () => {
+      uncertain.current = false;
+      setFeedback(null);
+    },
+  };
+}

package/src/movethewheels/hooks/useTracking.ts

@@ -108,6 +108,10 @@ const LOOKUP_DELIVERY_JOBS_QUERY = `
 
 const DELIVERY_JOB_TRACKING_QUERY = `
   query GetDeliveryJobTracking($deliveryJobId: ID!, $pagination: PaginationInput) {
+    shipments(filter: { deliveryJobId: $deliveryJobId }, pagination: { limit: 2, offset: 0 }) {
+      id
+      status
+    }
     deliveryJobTracking(deliveryJobId: $deliveryJobId, pagination: $pagination) {
       id
       shipmentId
@@ -232,7 +236,8 @@ function mapTrackingEventToLocation(event: ApiTrackingEvent): Location | null {
 
 function mapTrackingEventsToTracking(
   events: ApiTrackingEvent[],
-  entityId: string
+  entityId: string,
+  recordedShipmentStatus?: string
 ): Tracking | null {
   const latest = events[0];
   if (!latest) return null;
@@ -248,7 +253,8 @@ function mapTrackingEventsToTracking(
     entityType: 'order',
     currentLocation,
     locationHistory,
-    status: latest.eventType.toLowerCase(),
+    // Observation history is not shipment-status authority. Ambiguous/unlinked shipments stay unknown.
+    status: recordedShipmentStatus?.toLowerCase() ?? 'unknown',
     estimatedArrival: undefined,
     nextCheckpoint: latest.details ?? undefined,
     alerts: [],
@@ -472,18 +478,23 @@ export function useOrderTracking(orderLookup: string | undefined) {
     setTrackingLoading(true);
     setTrackingError(null);
     try {
-      const data = await executeGraphQL<{ deliveryJobTracking: ApiTrackingEvent[] }>(
-        graphQLOptions,
-        DELIVERY_JOB_TRACKING_QUERY,
-        {
-          deliveryJobId: resolvedOrderId,
-          pagination: { limit: 50, offset: 0 },
-        }
-      );
+      const data = await executeGraphQL<{
+        deliveryJobTracking: ApiTrackingEvent[];
+        shipments: Array<{ id: string; status: string }>;
+      }>(graphQLOptions, DELIVERY_JOB_TRACKING_QUERY, {
+        deliveryJobId: resolvedOrderId,
+        pagination: { limit: 50, offset: 0 },
+      });
       const events = [...data.deliveryJobTracking].sort(
         (first, second) => Date.parse(second.timestamp) - Date.parse(first.timestamp)
       );
-      setTracking(mapTrackingEventsToTracking(events, resolvedOrderId));
+      setTracking(
+        mapTrackingEventsToTracking(
+          events,
+          resolvedOrderId,
+          data.shipments.length === 1 ? data.shipments[0]?.status : undefined
+        )
+      );
     } catch (fetchError) {
       setTrackingError(
         fetchError instanceof Error ? fetchError : new Error('Failed to load order tracking')
@@ -580,7 +591,11 @@ export function useLiveTracking() {
             order: mapOrder(deliveryJob),
             driver: deliveryJob.driver ? mapDriver(deliveryJob.driver) : null,
             vehicle: deliveryJob.vehicle ? mapVehicle(deliveryJob.vehicle) : null,
-            tracking: mapTrackingEventsToTracking(shipment.trackingEvents ?? [], deliveryJob.id),
+            tracking: mapTrackingEventsToTracking(
+              shipment.trackingEvents ?? [],
+              deliveryJob.id,
+              shipment.status
+            ),
             estimatedArrival: shipment.estimatedDelivery
               ? new Date(shipment.estimatedDelivery)
               : undefined,

package/src/movethewheels/hooks/useTrackingEventQuality.ts

@@ -0,0 +1,110 @@
+import {
+  TrackingQualityIntegrationsDocument,
+  TrackingQualityDeliveriesDocument,
+  TrackingQualityShipmentDocument,
+} from '../../generated/tracking-quality-operations';
+export {
+  TrackingQualityIntegrationsDocument as QualityIntegrationsDocument,
+  TrackingQualityDeliveriesDocument as QualityDeliveriesDocument,
+  TrackingQualityShipmentDocument as QualityShipmentDocument,
+};
+
+export interface TrackingUpdateOutcome {
+  index: number;
+  externalEventId: string | null;
+  shipmentReference: string;
+  shipmentId: string | null;
+  status: 'ACCEPTED' | 'DUPLICATE' | 'CONFLICT' | 'REJECTED';
+  errorCode: string | null;
+  projection: {
+    status: 'APPLIED' | 'HELD' | 'LEGACY_NO_DECISION';
+    decisionId: string | null;
+    heldReason: string | null;
+  } | null;
+}
+
+const statuses = new Set(['ACCEPTED', 'DUPLICATE', 'CONFLICT', 'REJECTED']);
+const heldReasons = new Set([
+  'LEGACY_AUTHORITY',
+  'MANUAL_AUTHORITY',
+  'NON_DESIGNATED_SOURCE',
+  'UNKNOWN_SOURCE_TIME',
+  'OLDER_SOURCE_TIME',
+  'EQUAL_SOURCE_TIME',
+  'SOURCE_TIME_TOO_OLD',
+  'SOURCE_TIME_IN_FUTURE',
+  'UNMAPPED_EVENT_TYPE',
+  'UNRECEIPTED_EVIDENCE',
+]);
+const codes = new Set([
+  'KEY_CONFLICT',
+  'BUDGET_EXHAUSTED',
+  'INTEGRATION_UNAVAILABLE',
+  'SHIPMENT_UNAVAILABLE',
+  'UPDATE_REJECTED',
+]);
+const bounded = (value: unknown, max: number): value is string =>
+  typeof value === 'string' && value.length <= max;
+const nullable = (value: unknown, max: number): value is string | null =>
+  value === null || bounded(value, max);
+
+/** JSON scalar decoding fails closed; legacy delivery history has no outcomes. */
+export function trackingOutcomes(value: unknown): TrackingUpdateOutcome[] | null {
+  if (!Array.isArray(value) || value.length > 5) return null;
+  const result: TrackingUpdateOutcome[] = [];
+  for (const item of value) {
+    if (typeof item !== 'object' || item === null || Array.isArray(item)) return null;
+    const row: Record<string, unknown> = item;
+    if (
+      !Number.isInteger(row.index) ||
+      typeof row.index !== 'number' ||
+      row.index !== result.length ||
+      row.index < 0 ||
+      row.index > 4 ||
+      !nullable(row.externalEventId, 255) ||
+      !bounded(row.shipmentReference, 255) ||
+      !nullable(row.shipmentId, 255) ||
+      typeof row.status !== 'string' ||
+      !statuses.has(row.status) ||
+      (row.status === 'CONFLICT' && row.shipmentId !== null) ||
+      !(row.errorCode === null || (typeof row.errorCode === 'string' && codes.has(row.errorCode)))
+    ) {
+      return null;
+    }
+    let projection: TrackingUpdateOutcome['projection'] = null;
+    const projectionStatus = row.projectionStatus;
+    const decisionId = row.projectionDecisionId ?? null;
+    const heldReason = row.projectionHeldReason ?? null;
+    if (projectionStatus !== undefined && projectionStatus !== null) {
+      if (row.status !== 'ACCEPTED' && row.status !== 'DUPLICATE') return null;
+      if (projectionStatus === 'LEGACY_NO_DECISION') {
+        if (row.status !== 'DUPLICATE' || decisionId !== null || heldReason !== null) return null;
+      } else if (projectionStatus === 'APPLIED' || projectionStatus === 'HELD') {
+        if (!bounded(decisionId, 255) || !decisionId) return null;
+        if (
+          projectionStatus === 'APPLIED'
+            ? heldReason !== null
+            : typeof heldReason !== 'string' || !heldReasons.has(heldReason)
+        )
+          return null;
+      } else return null;
+      // The guarded finite status and bounded identifiers justify the JSON narrowing.
+      projection = {
+        status: projectionStatus,
+        decisionId: decisionId as string | null,
+        heldReason: heldReason as string | null,
+      };
+    } else if (decisionId !== null || heldReason !== null) return null;
+    // The finite status/code guards justify narrowing the untyped JSON scalar.
+    result.push({
+      index: row.index,
+      externalEventId: row.externalEventId,
+      shipmentReference: row.shipmentReference,
+      shipmentId: row.shipmentId,
+      status: row.status as TrackingUpdateOutcome['status'],
+      errorCode: row.errorCode,
+      projection,
+    });
+  }
+  return result;
+}