@burdenoff/microfe-movethewheels 2026.930.5 → 2026.1010.1

package/src/movethewheels/pages/TripUtilizationPage.tsx

@@ -0,0 +1,315 @@
+import { useRef, useState } from 'react';
+import { Gauge } from 'lucide-react';
+import { PageLayout } from '../components/PageLayout';
+import { Button } from '../components/ui';
+import { PinnedSelect, ReusePager, ReuseState, reuseCard } from '../components/ReuseControls';
+import { TripReportForm } from '../components/trip-utilization/TripReportForm';
+import { TripReportHistory } from '../components/trip-utilization/TripReportHistory';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { useConditionApi, useConditionQuery } from '../hooks/useContainerCondition';
+import { useEmptyReuseAction } from '../hooks/useEmptyReuseAction';
+import type { TripReportDraft } from '../utils/tripUtilizationForm';
+import {
+  inputForTripDraft,
+  tripRouteStillMatches,
+  tripContextStillMatches,
+  type TripDraftContext,
+} from '../utils/tripDraftContext';
+import {
+  UtilizationRoutesDocument,
+  UtilizationCurrentRouteDocument,
+  UtilizationCurrentVehicleDocument,
+  UtilizationReportsDocument,
+  RecordUtilizationReportDocument,
+  type UtilizationRoutesQuery,
+  type UtilizationCurrentRouteQuery,
+  type UtilizationCurrentVehicleQuery,
+  type UtilizationReportsQuery,
+  type UtilizationReportFragment,
+  type RecordUtilizationReportMutation,
+} from '../../generated/trip-utilization-operations';
+export default function TripUtilizationPage() {
+  const { workspaceId, tenantId, currentUser, apiGatewayUrl } = useMoveTheWheels();
+  return (
+    <PageLayout
+      title="Reported trip utilization"
+      subtitle="Measured or estimated segment facts, separate ratios and immutable source history."
+      icon={<Gauge aria-hidden="true" />}
+    >
+      <TripUtilizationWorkbench
+        key={`${workspaceId}:${tenantId}:${currentUser?.id}:${apiGatewayUrl}`}
+      />
+    </PageLayout>
+  );
+}
+function TripUtilizationWorkbench() {
+  const [routeOffset, setRouteOffset] = useState(0);
+  const [reportOffset, setReportOffset] = useState(0);
+  const [routeSelection, setRouteSelection] = useState<{ id: string; label: string } | null>(null);
+  const [draftContext, setDraftContext] = useState<
+    (TripDraftContext & { generation: string }) | null
+  >(null);
+  const [contextMismatch, setContextMismatch] = useState(false);
+  const [selected, setSelected] = useState<UtilizationReportFragment | null>(null);
+  const checkingNow = useRef(false);
+  const [checking, setChecking] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const actions = useEmptyReuseAction();
+  const request = useConditionApi();
+  const routes = useConditionQuery<UtilizationRoutesQuery>(
+    UtilizationRoutesDocument,
+    { pagination: { limit: 25, offset: routeOffset } },
+    actions.revision
+  );
+  const current = useConditionQuery<UtilizationCurrentRouteQuery>(
+    UtilizationCurrentRouteDocument,
+    routeSelection ? { id: routeSelection.id } : null,
+    actions.revision
+  );
+  const route = current.data?.route;
+  const reports = useConditionQuery<UtilizationReportsQuery>(
+    UtilizationReportsDocument,
+    routeSelection
+      ? { routeId: routeSelection.id, pagination: { limit: 25, offset: reportOffset } }
+      : null,
+    actions.revision
+  );
+  const busy = actions.busy || checking;
+  const routePage = routes.data
+    ? {
+        total: routes.data.routesCount,
+        limit: 25,
+        offset: routeOffset,
+        hasMore: routeOffset + routes.data.routes.length < routes.data.routesCount,
+        nextOffset: routeOffset + 25,
+      }
+    : undefined;
+  const routeOptions =
+    routes.data?.routes.map((item) => ({
+      id: item.id,
+      label: `${item.name} — ${item.status} — ${item.vehicle?.vehicleNumber ?? 'No assigned vehicle'}`,
+    })) ?? [];
+  if (routeSelection && !routeOptions.some((item) => item.id === routeSelection.id))
+    routeOptions.unshift({
+      id: routeSelection.id,
+      label: `${route?.name ?? routeSelection.label} — selected outside this page`,
+    });
+  const displayedContextChanged =
+    !!draftContext &&
+    !!current.data &&
+    !tripContextStillMatches(draftContext, route, route?.vehicle);
+  const record = async (draft: TripReportDraft) => {
+    if (checkingNow.current) return;
+    if (!draftContext)
+      throw new Error('Review the displayed route and assigned vehicle before starting a report.');
+    const pin = draftContext;
+    checkingNow.current = true;
+    setChecking(true);
+    setError(null);
+    try {
+      const latest = await request<UtilizationCurrentRouteQuery>(UtilizationCurrentRouteDocument, {
+        id: pin.routeId,
+      });
+      const freshRoute = latest.route;
+      if (!tripRouteStillMatches(pin, freshRoute)) {
+        setContextMismatch(true);
+        throw new Error(
+          'The route or assigned vehicle changed since this draft began. Refresh context and review it before starting a new report. No measurements were rebound.'
+        );
+      }
+      const vehicleResult = await request<UtilizationCurrentVehicleQuery>(
+        UtilizationCurrentVehicleDocument,
+        { id: pin.vehicleId }
+      );
+      if (!tripContextStillMatches(pin, freshRoute, vehicleResult.vehicle))
+        setContextMismatch(true);
+      const input = inputForTripDraft(draft, pin, freshRoute, vehicleResult.vehicle);
+      const result = await actions.run<RecordUtilizationReportMutation>(
+        RecordUtilizationReportDocument,
+        input,
+        'Immutable operator report recorded; assignments and operational state unchanged.'
+      );
+      if (result) {
+        setSelected(result.recordMtwTripUtilizationReport);
+        setReportOffset(0);
+      }
+    } catch (failure) {
+      setError(
+        failure instanceof Error ? failure.message : 'Unable to verify the captured report context.'
+      );
+      throw failure;
+    } finally {
+      checkingNow.current = false;
+      setChecking(false);
+    }
+  };
+  return (
+    <div className="min-w-0 space-y-6 break-words">
+      <p className="rounded border p-4 text-sm">
+        These are operator-reported interval facts. COMPLETE coverage and measured/source labels are
+        declarations, not independently certified whole-trip measurements. Ratios do not establish
+        axle/road legality, physical packing, dispatch feasibility, fuel consumption or savings.
+        This page does not assign work or start a route.
+      </p>
+      <section className={reuseCard} aria-label="Choose route and current assigned vehicle">
+        <h2 className="text-lg font-semibold">Route and assigned vehicle</h2>
+        <PinnedSelect
+          label="Route"
+          value={routeSelection?.id ?? ''}
+          disabled={busy || actions.uncertain}
+          options={routeOptions}
+          onChange={(id) => {
+            const row = routes.data?.routes.find((item) => item.id === id);
+            setRouteSelection(row ? { id: row.id, label: row.name } : null);
+            setDraftContext(null);
+            setContextMismatch(false);
+            setSelected(null);
+            setReportOffset(0);
+            setError(null);
+            actions.discardAttempt();
+          }}
+        />
+        <ReuseState {...routes} />
+        <ReusePager
+          page={routePage}
+          offset={routeOffset}
+          onChange={setRouteOffset}
+          busy={busy || routes.loading}
+        />
+        {routeSelection && (
+          <p>
+            Selected route {route?.name ?? routeSelection.label}.{' '}
+            {route
+              ? `Current status ${route.status}; revision ${route.updatedAt}.`
+              : 'Current record not loaded; new report blocked.'}
+          </p>
+        )}
+        <ReuseState {...current} />
+        {route && (
+          <p>
+            Currently assigned vehicle:{' '}
+            {route.vehicle
+              ? `${route.vehicle.vehicleNumber}${route.vehicle.licensePlate ? ` (${route.vehicle.licensePlate})` : ''} — ${route.vehicle.type} — ${route.vehicle.status}; revision ${route.vehicle.updatedAt}`
+              : 'unavailable / unassigned'}
+            . Assignment changes belong to the existing route workflow.
+          </p>
+        )}
+        <Button
+          type="button"
+          variant="outline"
+          disabled={busy}
+          onClick={() => {
+            setContextMismatch(false);
+            setError(null);
+            actions.refresh();
+          }}
+        >
+          Refresh current context and history
+        </Button>
+      </section>
+      {routeSelection && (
+        <>
+          <section className={reuseCard} aria-label="Record reported utilization">
+            <h2 className="text-lg font-semibold">Record interval facts</h2>
+            <p className="text-sm">
+              Start a report only after reviewing the displayed route and assigned vehicle. The
+              draft retains those identities and revisions. Fresh reads verify them; they do not
+              substitute a new vehicle or retag entered measurements.
+            </p>
+            {draftContext && (
+              <p>
+                Draft context: {draftContext.routeName} / {draftContext.vehicleNumber}; route
+                revision {draftContext.routeUpdatedAt}; vehicle revision{' '}
+                {draftContext.vehicleUpdatedAt}.
+              </p>
+            )}
+            {(contextMismatch || displayedContextChanged) && (
+              <p role="alert">
+                The draft context changed. Unsaved measurement fields are cleared. Refresh and
+                review the current context before starting a replacement report. An uncertain
+                original request remains separate.
+              </p>
+            )}
+            {actions.uncertain && (
+              <p>
+                Resolve the uncertain original request or explicitly abandon it after inspecting
+                history before starting another draft.
+              </p>
+            )}
+            <Button
+              type="button"
+              variant="outline"
+              disabled={
+                busy ||
+                actions.uncertain ||
+                contextMismatch ||
+                current.loading ||
+                !route?.vehicle ||
+                route.vehicleId !== route.vehicle.id
+              }
+              onClick={() => {
+                if (!route?.vehicle || route.vehicleId !== route.vehicle.id) return;
+                setDraftContext({
+                  routeId: route.id,
+                  routeUpdatedAt: route.updatedAt,
+                  vehicleId: route.vehicle.id,
+                  vehicleUpdatedAt: route.vehicle.updatedAt,
+                  routeName: route.name,
+                  vehicleNumber: route.vehicle.vehicleNumber,
+                  generation: crypto.randomUUID(),
+                });
+                setContextMismatch(false);
+                setError(null);
+              }}
+            >
+              Review current context and start a new report
+            </Button>
+            {draftContext && !contextMismatch && !displayedContextChanged && (
+              <TripReportForm
+                key={`${draftContext.generation}:${draftContext.routeId}:${draftContext.routeUpdatedAt}:${draftContext.vehicleId}:${draftContext.vehicleUpdatedAt}`}
+                busy={
+                  busy ||
+                  actions.uncertain ||
+                  current.loading ||
+                  !route?.vehicleId ||
+                  !route.vehicle
+                }
+                onSubmit={record}
+              />
+            )}
+          </section>
+          <TripReportHistory
+            query={reports}
+            offset={reportOffset}
+            onPage={setReportOffset}
+            selected={selected}
+            onSelect={setSelected}
+            busy={busy}
+          />
+        </>
+      )}
+      {error && <p role="alert">{error}</p>}
+      {actions.error && <p role="alert">{actions.error}</p>}
+      {actions.notice && <p role="status">{actions.notice}</p>}
+      {actions.uncertain && (
+        <div className="space-y-3 rounded border p-4">
+          <p>
+            Result may be uncertain. Inspect refreshed history first. Retry original request sends
+            the original submitted body, route/vehicle revisions and key, ignoring edited form
+            fields. A new submitted semantic payload starts a new key. Attempts are not retained
+            after a browser reload.
+          </p>
+          <Button type="button" variant="outline" disabled={busy} onClick={actions.refresh}>
+            Refresh report history
+          </Button>
+          <Button type="button" disabled={busy} onClick={actions.retryOriginal}>
+            Retry original request
+          </Button>
+          <Button type="button" variant="outline" disabled={busy} onClick={actions.discardAttempt}>
+            Abandon retry after inspecting history
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/movethewheels/utils/consolidationHistoryTarget.ts

@@ -0,0 +1,39 @@
+import { print } from 'graphql';
+import {
+  SaveConsolidationPlanDocument,
+  RecordConsolidationObservationDocument,
+  SaveConsolidationManifestDocument,
+} from '../../generated/consolidation-operations';
+import {
+  sameReuseRecoveryScope,
+  type ReuseRecovery,
+  type ReuseRecoveryScope,
+} from './reuseRecovery';
+
+export type OriginalConsolidationHistoryTarget =
+  | { kind: 'plan'; shipmentId: string; planReference: string }
+  | { kind: 'observation' | 'manifest'; planId: string };
+
+function reference(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0 && value.length <= 200;
+}
+
+/** Retained input supplies read targets only in its original context; it never rebinds a draft. */
+export function originalConsolidationHistoryTarget(
+  pending: ReuseRecovery | null,
+  scope: ReuseRecoveryScope | null
+): OriginalConsolidationHistoryTarget | null {
+  if (!pending || !sameReuseRecoveryScope(pending.scope, scope)) return null;
+  if (pending.operation === print(SaveConsolidationPlanDocument)) {
+    const { shipmentId, planReference } = pending.input;
+    return reference(shipmentId) && reference(planReference)
+      ? { kind: 'plan', shipmentId, planReference }
+      : null;
+  }
+  if (!reference(pending.input.planId)) return null;
+  if (pending.operation === print(RecordConsolidationObservationDocument))
+    return { kind: 'observation', planId: pending.input.planId };
+  if (pending.operation === print(SaveConsolidationManifestDocument))
+    return { kind: 'manifest', planId: pending.input.planId };
+  return null;
+}

package/src/movethewheels/utils/consolidationInput.ts

@@ -0,0 +1,70 @@
+import { object, localProcedureInstant } from './procedureInput';
+export const consolidationInstant = localProcedureInstant;
+export function nullableText(value: string): string | null {
+  return value.trim() || null;
+}
+/** Keep decimal source text exact. Blank facts are unknown, and explicit zero remains zero. */
+export function consolidationQuantity(value: string): string | null {
+  const text = value.trim();
+  if (!text) return null;
+  if (!/^(?:0|[1-9]\d{0,19})(?:\.\d{1,6})?$/.test(text))
+    throw new Error('Use a nonnegative decimal with at most six decimal places.');
+  return text;
+}
+export function sameConsolidationPin(
+  a: { id: string; version: number } | null,
+  b: { id: string; version: number } | null
+): boolean {
+  return a?.id === b?.id && a?.version === b?.version;
+}
+/** Require the scoped immutable acknowledgement before clearing the original request. */
+export function consolidationAcknowledgement(
+  result: Record<string, unknown>,
+  input: Record<string, unknown>,
+  actorId?: string
+): boolean {
+  const field =
+    'facts' in input
+      ? 'saveMtwConsolidationPlan'
+      : 'kind' in input
+        ? 'recordMtwConsolidationObservation'
+        : 'saveMtwConsolidationManifest';
+  const row = result[field];
+  if (
+    !object(row) ||
+    typeof row.id !== 'string' ||
+    !row.id.trim() ||
+    row.createdBy !== actorId ||
+    typeof input.expectedVersion !== 'number' ||
+    !Number.isInteger(input.expectedVersion) ||
+    input.expectedVersion < 0 ||
+    row.version !== input.expectedVersion + 1 ||
+    row.previousVersionId !== input.expectedPreviousVersionId
+  )
+    return false;
+  if ('facts' in input)
+    return (
+      row.shipmentId === input.shipmentId &&
+      row.cycleId === input.cycleId &&
+      row.planReference === input.planReference &&
+      object(row.sourceCapture) &&
+      row.sourceCapture.shipmentUpdatedAt === input.expectedShipmentUpdatedAt &&
+      row.sourceCapture.cycleVersion === input.expectedCycleVersion
+    );
+  if ('kind' in input)
+    return (
+      row.planId === input.planId &&
+      row.lotId === input.lotId &&
+      row.kind === input.kind &&
+      row.issueReference === input.issueReference &&
+      row.reportedQuantity === input.reportedQuantity &&
+      Number.isInteger(row.receiptSequence)
+    );
+  return (
+    row.planId === input.planId &&
+    row.observationSequence === input.expectedObservationSequence &&
+    object(row.snapshot) &&
+    row.snapshot.planId === input.planId &&
+    row.snapshot.observationSequence === input.expectedObservationSequence
+  );
+}

package/src/movethewheels/utils/consolidationLot.ts

@@ -0,0 +1,24 @@
+import type { MtwConsolidationLotInput } from '../../generated/consolidation-operations';
+export function emptyConsolidationLot(): MtwConsolidationLotInput {
+  return {
+    id: crypto.randomUUID(),
+    supplierReference: '',
+    lotReference: '',
+    consignmentReference: '',
+    sourceRevision: '',
+    quantityBasis: 'UNKNOWN',
+    unitReference: null,
+    unitRevision: null,
+    balanceRevision: null,
+    reportedAvailableQuantity: null,
+    plannedQuantity: null,
+    grossKg: null,
+    cubeM3: null,
+    originReference: null,
+    destinationReference: null,
+    importerReference: null,
+    transportReference: null,
+    documentReference: null,
+    source: { reference: null, revision: null },
+  };
+}

package/src/movethewheels/utils/consolidationPins.ts

@@ -0,0 +1,52 @@
+import type {
+  ConsolidationContainersQuery,
+  ConsolidationCyclesQuery,
+  ConsolidationShipmentQuery,
+} from '../../generated/consolidation-operations';
+import { sameConsolidationPin } from './consolidationInput';
+export type ConsolidationContextPin = {
+  shipmentId: string;
+  shipmentUpdatedAt: string;
+  cycleId: string;
+  cycleVersion: number;
+  containerId: string;
+};
+export function matchesConsolidationContext(
+  pin: ConsolidationContextPin,
+  shipment: ConsolidationShipmentQuery['shipment'],
+  cycle: ConsolidationCyclesQuery['mtwContainerCyclePage']['items'][number] | null
+): boolean {
+  return (
+    !!shipment &&
+    !!cycle &&
+    shipment.id === pin.shipmentId &&
+    shipment.updatedAt === pin.shipmentUpdatedAt &&
+    cycle.id === pin.cycleId &&
+    cycle.containerId === pin.containerId &&
+    cycle.shipmentId === pin.shipmentId &&
+    cycle.version === pin.cycleVersion &&
+    cycle.status === 'OPEN'
+  );
+}
+export function assertConsolidationPredecessor(
+  pin: { id: string; version: number } | null,
+  current: { id: string; version: number } | null
+): void {
+  if (!sameConsolidationPin(pin, current))
+    throw new Error('Recorded history changed. Refresh and review before opening a new form.');
+}
+
+export type ConsolidationContainerOption = Pick<
+  ConsolidationContainersQuery['mtwContainerPage']['items'][number],
+  'id' | 'containerNumber' | 'equipmentType'
+>;
+/** Retain the selected label across pagination without asserting current source validity. */
+export function offPageConsolidationContainer(
+  selectedId: string,
+  selected: ConsolidationContainerOption | null,
+  visible: readonly ConsolidationContainerOption[]
+): ConsolidationContainerOption | null {
+  return selected?.id === selectedId && !visible.some((row) => row.id === selectedId)
+    ? selected
+    : null;
+}

package/src/movethewheels/utils/consolidationRecovery.ts

@@ -0,0 +1,88 @@
+import { print } from 'graphql';
+import {
+  SaveConsolidationPlanDocument,
+  RecordConsolidationObservationDocument,
+  SaveConsolidationManifestDocument,
+} from '../../generated/consolidation-operations';
+import type { ReuseRecovery } from './reuseRecovery';
+export const CONSOLIDATION_RECOVERY_STORAGE = 'movethewheels.consolidation.unresolved.v1';
+export function decodeConsolidationRecovery(raw: string | null): ReuseRecovery | null {
+  if (!raw || new TextEncoder().encode(raw).byteLength > 200000) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (
+      typeof value !== 'object' ||
+      value === null ||
+      !('version' in value) ||
+      value.version !== 1 ||
+      !('scope' in value) ||
+      !('input' in value) ||
+      !('operation' in value) ||
+      typeof value.operation !== 'string' ||
+      ![
+        SaveConsolidationPlanDocument,
+        RecordConsolidationObservationDocument,
+        SaveConsolidationManifestDocument,
+      ].some((item) => print(item) === value.operation) ||
+      !('key' in value) ||
+      typeof value.key !== 'string' ||
+      !value.key ||
+      value.key.length > 200 ||
+      !('success' in value) ||
+      typeof value.success !== 'string' ||
+      value.success.length > 500
+    )
+      return null;
+    if (
+      typeof value.input !== 'object' ||
+      value.input === null ||
+      Array.isArray(value.input) ||
+      typeof value.scope !== 'object' ||
+      value.scope === null
+    )
+      return null;
+    const scope = value.scope;
+    if (
+      !('actorId' in scope) ||
+      typeof scope.actorId !== 'string' ||
+      !scope.actorId ||
+      !('workspaceId' in scope) ||
+      typeof scope.workspaceId !== 'string' ||
+      !scope.workspaceId ||
+      !('tenantId' in scope) ||
+      typeof scope.tenantId !== 'string' ||
+      !('organizationId' in scope) ||
+      typeof scope.organizationId !== 'string' ||
+      !scope.organizationId ||
+      !('gateway' in scope) ||
+      typeof scope.gateway !== 'string' ||
+      !('projectId' in scope) ||
+      (scope.projectId !== null && typeof scope.projectId !== 'string')
+    )
+      return null;
+    return {
+      version: 1,
+      scope: {
+        actorId: scope.actorId,
+        workspaceId: scope.workspaceId,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        gateway: scope.gateway,
+        projectId: scope.projectId,
+      },
+      operation: value.operation,
+      // The owning document is exact and input is an object; field authority remains backend-validated.
+      input: structuredClone(value.input) as Record<string, unknown>,
+      key: value.key,
+      success: value.success,
+    };
+  } catch {
+    return null;
+  }
+}
+export function encodeConsolidationRecovery(attempt: ReuseRecovery): string {
+  const raw = JSON.stringify(attempt);
+  if (!decodeConsolidationRecovery(raw))
+    throw new Error('Cannot safely retain this consolidation request. Nothing was sent.');
+  return raw;
+}

package/src/movethewheels/utils/consolidationReportHead.ts

@@ -0,0 +1,29 @@
+import {
+  ConsolidationObservationsDocument,
+  type ConsolidationObservationsQuery,
+  type MtwConsolidationReportKind,
+} from '../../generated/consolidation-operations';
+type Report = ConsolidationObservationsQuery['mtwConsolidationObservationPage']['items'][number];
+export async function findConsolidationReportHead(
+  request: <T>(
+    document: typeof ConsolidationObservationsDocument,
+    variables: Record<string, unknown>
+  ) => Promise<T>,
+  planId: string,
+  lotId: string,
+  kind: MtwConsolidationReportKind
+): Promise<Report | null> {
+  // Receipt ordering makes the first matching row the current cumulative chain head.
+  for (let offset = 0; offset < 500; offset += 25) {
+    const page = await request<ConsolidationObservationsQuery>(ConsolidationObservationsDocument, {
+      planId,
+      pagination: { limit: 25, offset },
+    });
+    const head = page.mtwConsolidationObservationPage.items.find(
+      (row) => row.lotId === lotId && row.kind === kind
+    );
+    if (head) return head;
+    if (!page.mtwConsolidationObservationPage.hasMore) return null;
+  }
+  throw new Error('History exceeds the supported review window. No report will be sent.');
+}

package/src/movethewheels/utils/freeTimeDate.ts

@@ -0,0 +1,31 @@
+export function freeTimeIso(value: string): string {
+  const parts =
+    /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/i.exec(
+      value
+    );
+  if (!parts)
+    throw new Error('Use an ISO date and time with seconds and Z or an explicit timezone offset.');
+  const year = Number(parts[1]);
+  const month = Number(parts[2]);
+  const day = Number(parts[3]);
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  if (
+    month < 1 ||
+    month > 12 ||
+    day < 1 ||
+    day > (days[month - 1] ?? 0) ||
+    Number(parts[4]) > 23 ||
+    Number(parts[5]) > 59 ||
+    Number(parts[6]) > 59
+  )
+    throw new Error(
+      'Enter a real calendar date and time; invalid dates are not moved to another day.'
+    );
+  if (!/(?:Z|[+-]\d{2}:\d{2})$/i.test(value))
+    throw new Error('Include Z or an explicit timezone offset.');
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime()))
+    throw new Error('Enter a valid time with an explicit timezone.');
+  return date.toISOString();
+}

package/src/movethewheels/utils/freightAcknowledgement.ts

@@ -0,0 +1,31 @@
+/** Validate the minimum immutable receipt identity before resolving a retained request. */
+export function matchesFreightAcknowledgement(
+  result: unknown,
+  input: Record<string, unknown>
+): boolean {
+  if (
+    typeof result !== 'object' ||
+    result === null ||
+    !('saveMtwFreightEstimate' in result) ||
+    typeof result.saveMtwFreightEstimate !== 'object' ||
+    result.saveMtwFreightEstimate === null
+  )
+    return false;
+  const receipt = result.saveMtwFreightEstimate;
+  return (
+    'id' in receipt &&
+    typeof receipt.id === 'string' &&
+    receipt.id.trim().length > 0 &&
+    'shipmentId' in receipt &&
+    receipt.shipmentId === input.shipmentId &&
+    'estimateReference' in receipt &&
+    receipt.estimateReference === input.estimateReference &&
+    'version' in receipt &&
+    Number.isInteger(input.expectedVersion) &&
+    typeof input.expectedVersion === 'number' &&
+    input.expectedVersion >= 0 &&
+    receipt.version === input.expectedVersion + 1 &&
+    'previousVersionId' in receipt &&
+    receipt.previousVersionId === input.expectedPreviousVersionId
+  );
+}