@burdenoff/microfe-movethewheels 2026.1016.3 → 2026.1016.4

package/src/movethewheels/components/freight-invoice/InvoiceResults.tsx

@@ -0,0 +1,162 @@
+import type {
+  InvoiceReceiptFragment,
+  InvoiceStructuralPreviewQuery,
+} from '../../../generated/freight-invoice-operations';
+import { freightLabel } from '../../utils/freightDraft';
+import { invoiceMoney, invoiceRowDifference } from '../../utils/invoiceComparison';
+import { reuseCard } from '../ReuseControls';
+
+type Preview = InvoiceStructuralPreviewQuery['previewMtwFreightInvoice'];
+export function InvoiceResults({ value }: { value: Preview | InvoiceReceiptFragment }) {
+  const { estimate, outcome } = value;
+  return (
+    <section className={reuseCard} aria-label="Invoice comparison results">
+      <h2 className="text-lg font-semibold">Recorded-fact comparison</h2>
+      <p>
+        Exact {estimate.kind.toLowerCase()} {estimate.estimateReference}, version {estimate.version}
+        . Source {estimate.sourceReference} / {estimate.sourceRevision}.
+      </p>
+      <p>
+        Quote date {estimate.quotedAt ?? 'Unknown'}; source validity{' '}
+        {estimate.validFrom ?? 'Unknown'} to {estimate.validUntil ?? 'Unknown'}. Acceptance is not
+        established by this comparison.
+      </p>
+      {'recordable' in value && (
+        <p role="status">
+          Structural preview only.{' '}
+          {value.recordable
+            ? 'Source structure is recordable; current permission and Files eligibility are checked when recording.'
+            : `Not recordable: ${value.blockers.map(freightLabel).join(', ')}.`}
+        </p>
+      )}
+      <p className="font-medium">
+        {outcome.allLinesMatched
+          ? 'All explicitly compared rows and expected coverage agree under this method.'
+          : 'Differences or unknown coverage remain.'}
+      </p>
+      <p>
+        This is not an all-in cost, contracted-rate audit, liability finding, invoice approval or
+        payment.
+      </p>
+      {outcome.rows.map((row, index) => (
+        <article className="min-w-0 space-y-2 rounded border p-3" key={row.invoiceLineId}>
+          <h3 className="font-medium">
+            Row {index + 1}:{' '}
+            {value.facts.rows.find((source) => source.id === row.invoiceLineId)?.description ??
+              'Reported charge'}
+          </h3>
+          <p>
+            {row.estimateLineId
+              ? 'Mapped to the selected estimate row.'
+              : 'No estimate row mapped.'}
+          </p>
+          <p>{row.flags.map(freightLabel).join(' · ')}</p>
+          {row.reasons.length > 0 && (
+            <p>Unknown reasons: {row.reasons.map(freightLabel).join(', ')}</p>
+          )}
+          <p>Comparable amount difference: {invoiceRowDifference(value, row.invoiceLineId)}</p>
+        </article>
+      ))}
+      {outcome.missingExpectedLineIds.map((id) => (
+        <p key={id}>Missing expected line: {id}. An unknown value is not treated as zero.</p>
+      ))}
+      {outcome.unknownExpectedCoverage.map((row) => (
+        <p key={row.estimateLineId}>
+          Unknown expected-charge coverage: {row.estimateLineId}. This is not a proven missing
+          charge.
+        </p>
+      ))}
+      <section className="space-y-2">
+        <h3 className="font-semibold">Comparable pairs only</h3>
+        {outcome.comparableSubtotals.length === 0 && <p>No bounded comparable subtotal.</p>}
+        {outcome.comparableSubtotals.map((group) => (
+          <p key={JSON.stringify([group.currency, group.payerReference])}>
+            Payer{' '}
+            {value.facts.rows.find((row) => row.payerReference === group.payerReference)
+              ?.payerLabel ?? group.payerReference}
+            : estimate {invoiceMoney(group.estimateMinor, group.currency)}, invoice{' '}
+            {invoiceMoney(group.invoiceMinor, group.currency)}, difference{' '}
+            {invoiceMoney(group.deltaMinor, group.currency)}. Included rows{' '}
+            {group.invoiceLineIds
+              .map(
+                (id) =>
+                  value.facts.rows.find((row) => row.id === id)?.description ?? 'Reported charge'
+              )
+              .join(', ')}
+            . Other rows are omitted.
+          </p>
+        ))}
+      </section>
+      {(
+        [
+          ['Declared estimate subtotals', value.estimateDeclaredSubtotals],
+          ['Declared invoice subtotals', value.invoiceDeclaredSubtotals],
+        ] as const
+      ).map(([label, groups]) => (
+        <section key={label} className="space-y-2">
+          <h3 className="font-semibold">{label}</h3>
+          {groups.map((group, index) => (
+            <p key={JSON.stringify([group.currency, group.payerReference, index])}>
+              Payer {group.payerLabel ?? 'Unknown'} ({group.payerReference ?? 'Unknown reference'});{' '}
+              known {invoiceMoney(group.knownAmountMinor, group.currency)}; total{' '}
+              {invoiceMoney(group.totalAmountMinor, group.currency)}.
+            </p>
+          ))}
+        </section>
+      ))}
+    </section>
+  );
+}
+export function InvoiceHistoryRecord({ record }: { record: InvoiceReceiptFragment }) {
+  return (
+    <section className="min-w-0 space-y-4 break-words">
+      <h2 className="text-lg font-semibold">Immutable comparison revision {record.revision}</h2>
+      <p>
+        Invoice {record.facts.invoiceReference}; supplier{' '}
+        {record.facts.supplierLabel ?? 'Unknown label'} ({record.facts.supplierReference}). Source{' '}
+        {record.facts.sourceReference} / {record.facts.sourceRevision}; invoice date{' '}
+        {record.facts.invoiceDate ?? 'Unknown'}.
+      </p>
+      <p>
+        Recorded {record.recordedAt} by {record.createdBy}, {freightLabel(record.actorProvenance)};
+        on behalf of {record.onBehalfOf ?? 'Not declared'}. Method {record.methodVersion}.
+      </p>
+      {record.correctionReason && (
+        <p>
+          Correction reason: {record.correctionReason}; predecessor {record.previousComparisonId}.
+        </p>
+      )}
+      <details>
+        <summary className="min-h-11 cursor-pointer font-medium">
+          Original reported rows and exact evidence
+        </summary>
+        <div className="space-y-3">
+          {record.facts.rows.map((row) => (
+            <article key={row.id} className="rounded border p-3">
+              <h3>
+                {row.description} ({row.id})
+              </h3>
+              <p>
+                Mapping {row.estimateLineId ?? 'Unmatched'}; amount{' '}
+                {invoiceMoney(row.amountMinor, row.currency)}; payer {row.payerLabel ?? 'Unknown'} (
+                {row.payerReference ?? 'Unknown reference'}).
+              </p>
+              <p>
+                Quantity {row.quantity ?? 'Unknown'} {row.unit ?? 'unknown unit'}; supplied rate{' '}
+                {row.unitRateMajor ?? 'Unknown'}. Invoice amount was not recalculated.
+              </p>
+              {row.zeroReason && <p>Zero reason: {row.zeroReason}</p>}
+            </article>
+          ))}
+          {record.evidence.map((e) => (
+            <p className="break-all" key={e.versionId}>
+              File {e.fileId}, exact version {e.versionId}; SHA256 {e.sha256Hash}; checked{' '}
+              {e.checkedAt}. Point-in-time eligibility only.
+            </p>
+          ))}
+        </div>
+      </details>
+      <InvoiceResults value={record} />
+    </section>
+  );
+}

package/src/movethewheels/hooks/useFleet.ts

@@ -42,7 +42,7 @@ export interface CreateDriverInput {
   phone?: string;
   licenseNumber?: string;
   licenseClass?: string;
-  licenseExpiry?: string;
+  licenseExpiry?: string | null;
   /** DriverStatus enum value, e.g. `AVAILABLE`, `OFF_DUTY`. */
   status?: string;
   vehicleId?: string | null;

package/src/movethewheels/hooks/useFleetIntelligence.ts

@@ -11,7 +11,11 @@ import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { executeGraphQL } from '../utils/graphqlClient';
 
 export type FleetAlertType =
-  'LICENSE_EXPIRED' | 'LICENSE_EXPIRING' | 'MAINTENANCE_OVERDUE' | 'MAINTENANCE_DUE_SOON';
+  | 'LICENSE_UNKNOWN'
+  | 'LICENSE_EXPIRED'
+  | 'LICENSE_EXPIRING'
+  | 'MAINTENANCE_OVERDUE'
+  | 'MAINTENANCE_DUE_SOON';
 export type FleetAlertSeverity = 'CRITICAL' | 'WARNING';
 export type FleetAlertSubjectType = 'VEHICLE' | 'DRIVER';
 

package/src/movethewheels/hooks/useInvoiceComparisonRecovery.ts

@@ -0,0 +1,227 @@
+import { useLayoutEffect, useRef, useState } from 'react';
+import { useActiveContext } from '@burdenoff/fe-libs/shared/providers/shell';
+import {
+  InvoiceComparisonExactDocument,
+  RecordInvoiceComparisonDocument,
+  RecoverInvoiceComparisonDocument,
+  type CompareMtwFreightInvoiceInput,
+  type InvoiceComparisonExactQuery,
+  type InvoiceEstimatePinFragment,
+  type InvoiceReceiptFragment,
+  type RecordInvoiceComparisonMutation,
+  type RecoverInvoiceComparisonQuery,
+} from '../../generated/freight-invoice-operations';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { resolveGraphqlUrl } from '../utils/graphqlClient';
+import {
+  INVOICE_RECOVERY_STORAGE,
+  decodeInvoiceIntent,
+  encodeInvoiceIntent,
+  invoiceCanonical,
+  invoiceRecordInput,
+  matchesInvoiceReceipt,
+  sameInvoiceScope,
+  type InvoiceIntent,
+  type InvoiceScope,
+} from '../utils/invoiceComparison';
+import { useConditionApi } from './useContainerCondition';
+
+function retained() {
+  try {
+    const raw = sessionStorage.getItem(INVOICE_RECOVERY_STORAGE),
+      intent = decodeInvoiceIntent(raw);
+    return { intent, blocked: raw !== null && intent === null };
+  } catch {
+    return { intent: null, blocked: true };
+  }
+}
+/** Canonical visible context only; never decode credentials or claim the full server context. */
+export function useInvoiceComparisonScope(canRead: boolean): InvoiceScope | null {
+  const owner = useMoveTheWheels(),
+    active = useActiveContext();
+  if (
+    !canRead ||
+    !owner.currentUser?.id ||
+    !owner.workspaceId ||
+    active.workspaceId !== owner.workspaceId ||
+    !active.organizationId ||
+    (owner.tenantId && active.tenantId !== owner.tenantId)
+  )
+    return null;
+  return {
+    actorId: owner.currentUser.id,
+    workspaceId: owner.workspaceId,
+    tenantId: active.tenantId,
+    organizationId: active.organizationId,
+    projectId: active.projectId,
+    gateway: resolveGraphqlUrl(owner.apiGatewayUrl),
+  };
+}
+/** One original business intent. UNKNOWN permits reads only, never a retry/new key or automatic resend. */
+export function useInvoiceComparisonRecovery(
+  scope: InvoiceScope | null,
+  allowsWrite: () => boolean
+) {
+  const request = useConditionApi('SINGLE_ATTEMPT'),
+    [initial] = useState(retained);
+  const [pending, setPending] = useState<InvoiceIntent | null>(initial.intent),
+    pendingRef = useRef(pending);
+  const [blocked, setBlocked] = useState(initial.blocked),
+    running = useRef(false);
+  const [busy, setBusy] = useState(false),
+    [revision, setRevision] = useState(0);
+  const scopeKey = invoiceCanonical(scope),
+    currentScope = useRef(scope);
+  const [feedback, setFeedback] = useState<{
+    scopeKey: string;
+    message: string;
+    error: boolean;
+  } | null>(null);
+  useLayoutEffect(() => {
+    currentScope.current = scope;
+    return () => {
+      currentScope.current = null;
+    };
+  }, [scopeKey]);
+  const tell = (message: string, error = true) => setFeedback({ scopeKey, message, error });
+  const confirm = (receipt: InvoiceReceiptFragment | null | undefined, intent: InvoiceIntent) => {
+    if (
+      !receipt ||
+      !matchesInvoiceReceipt(receipt, intent) ||
+      !sameInvoiceScope(intent.scope, currentScope.current)
+    )
+      throw new Error('UNCONFIRMED');
+    const saved = decodeInvoiceIntent(sessionStorage.getItem(INVOICE_RECOVERY_STORAGE));
+    if (!saved || invoiceCanonical(saved) !== invoiceCanonical(intent))
+      throw new Error('RETAINED_INTENT_CHANGED');
+    sessionStorage.removeItem(INVOICE_RECOVERY_STORAGE);
+    pendingRef.current = null;
+    setPending(null);
+    setBlocked(false);
+    setRevision((v) => v + 1);
+    tell('The exact immutable comparison receipt is confirmed.', false);
+    return receipt;
+  };
+  const run = async (
+    supplied: Omit<CompareMtwFreightInvoiceInput, 'idempotencyKey'>,
+    estimate: InvoiceEstimatePinFragment
+  ) => {
+    if (running.current || pendingRef.current || blocked) {
+      tell('Resolve the original request before starting another.');
+      return null;
+    }
+    if (!scope || !sameInvoiceScope(scope, currentScope.current) || !allowsWrite()) {
+      tell(
+        'Current shipment update permission and workspace context are required. Nothing was sent.'
+      );
+      return null;
+    }
+    let intent: InvoiceIntent;
+    try {
+      if (sessionStorage.getItem(INVOICE_RECOVERY_STORAGE) !== null) throw new Error('EXISTING');
+      intent = {
+        version: 1,
+        scope: structuredClone(scope),
+        input: invoiceRecordInput({ ...supplied, idempotencyKey: crypto.randomUUID() }),
+        estimate: structuredClone(estimate),
+      };
+      sessionStorage.setItem(INVOICE_RECOVERY_STORAGE, encodeInvoiceIntent(intent));
+      pendingRef.current = intent;
+      setPending(intent);
+    } catch {
+      tell(
+        'The original request could not be retained safely. Nothing was sent; reload and inspect any retained request.'
+      );
+      return null;
+    }
+    running.current = true;
+    setBusy(true);
+    setFeedback(null);
+    try {
+      // No await occurs between this final scope/permission check and the one product dispatch.
+      if (!sameInvoiceScope(intent.scope, currentScope.current) || !allowsWrite()) {
+        const saved = decodeInvoiceIntent(sessionStorage.getItem(INVOICE_RECOVERY_STORAGE));
+        if (saved && invoiceCanonical(saved) === invoiceCanonical(intent)) {
+          sessionStorage.removeItem(INVOICE_RECOVERY_STORAGE);
+          pendingRef.current = null;
+          setPending(null);
+        }
+        tell('Context or permission changed before dispatch. Nothing was sent.');
+        return null;
+      }
+      const result = await request<RecordInvoiceComparisonMutation>(
+        RecordInvoiceComparisonDocument,
+        { input: intent.input }
+      );
+      return confirm(result.compareMtwFreightInvoice, intent);
+    } catch {
+      tell(
+        'Save outcome is UNKNOWN. Keep the original intent and use read-only recovery; do not resend it.'
+      );
+      return null;
+    } finally {
+      running.current = false;
+      setBusy(false);
+    }
+  };
+  const reconcile = async () => {
+    const intent = pendingRef.current;
+    if (running.current || !intent) return null;
+    if (!sameInvoiceScope(intent.scope, currentScope.current)) {
+      tell(
+        'Return to the original account, organization, workspace and project to inspect its request.'
+      );
+      return null;
+    }
+    running.current = true;
+    setBusy(true);
+    setFeedback(null);
+    try {
+      const found = await request<RecoverInvoiceComparisonQuery>(RecoverInvoiceComparisonDocument, {
+        shipmentId: intent.input.shipmentId,
+        requestKey: intent.input.idempotencyKey,
+      });
+      const receipt = found.mtwFreightInvoiceComparisonByRequestKey;
+      if (!receipt) {
+        tell(
+          'No original-context receipt was returned. This does not prove no effect; the request stays UNKNOWN and cannot be resent.'
+        );
+        return null;
+      }
+      if (!matchesInvoiceReceipt(receipt, intent)) throw new Error('MISMATCH');
+      if (!sameInvoiceScope(intent.scope, currentScope.current)) throw new Error('CONTEXT_CHANGED');
+      const exact = await request<InvoiceComparisonExactQuery>(InvoiceComparisonExactDocument, {
+        shipmentId: intent.input.shipmentId,
+        id: receipt.id,
+      });
+      if (
+        !matchesInvoiceReceipt(exact.mtwFreightInvoiceComparison, intent) ||
+        exact.mtwFreightInvoiceComparison.requestFingerprint !== receipt.requestFingerprint ||
+        invoiceCanonical(exact.mtwFreightInvoiceComparison) !== invoiceCanonical(receipt)
+      )
+        throw new Error('MISMATCH');
+      return confirm(exact.mtwFreightInvoiceComparison, intent);
+    } catch {
+      tell(
+        'Read-only recovery could not confirm the exact original receipt. Keep the intent; no save was sent.'
+      );
+      return null;
+    } finally {
+      running.current = false;
+      setBusy(false);
+    }
+  };
+  return {
+    run,
+    reconcile,
+    busy,
+    pending,
+    blocked,
+    uncertain: pending !== null || blocked,
+    revision,
+    scopeKey,
+    canReconcile: !!pending && sameInvoiceScope(pending.scope, scope),
+    feedback: feedback?.scopeKey === scopeKey ? feedback : null,
+    refresh: () => setRevision((v) => v + 1),
+  };
+}

package/src/movethewheels/pages/DriverDetailsPage.tsx

@@ -61,6 +61,11 @@ import { useDebouncedValue } from '../hooks/useDebouncedValue';
 import { useRefetchOnLeaveEdit } from '../hooks/useRefetchOnLeaveEdit';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatCurrency, formatDate } from '../utils/formatters';
+import {
+  driverLicenseExpiryInput,
+  driverLicenseExpiryUpdate,
+  parseDriverLicenseExpiry,
+} from '../utils/driverLicenseExpiry';
 import { joinPath } from '../utils/navigation';
 import { FormError } from '../components/FormError';
 import { DocumentsCard } from '../components/DocumentsCard';
@@ -163,7 +168,7 @@ function NewDriverForm({ editId }: { editId?: string }) {
       phone: driver.phone || '',
       licenseNumber: driver.licenseNumber || '',
       licenseClass: driver.licenseType || '',
-      licenseExpiry: toDateInput(driver.licenseExpiry),
+      licenseExpiry: driverLicenseExpiryInput(driver.licenseExpiry),
       status: driver.status,
       vehicleId: driver.assignedVehicle || '',
       vehicleIds: driver.vehicleIds,
@@ -186,7 +191,9 @@ function NewDriverForm({ editId }: { editId?: string }) {
     phone: form.phone.trim() || undefined,
     licenseNumber: form.licenseNumber.trim() || undefined,
     licenseClass: form.licenseClass.trim() || undefined,
-    licenseExpiry: fromDateInput(form.licenseExpiry),
+    licenseExpiry: isEditing
+      ? driverLicenseExpiryUpdate(form.licenseExpiry, driver?.licenseExpiry)
+      : parseDriverLicenseExpiry(form.licenseExpiry),
     status: toApiDriverStatus(form.status),
     vehicleId: form.vehicleId || null,
     vehicleIds: form.vehicleIds,
@@ -417,14 +424,33 @@ function NewDriverForm({ editId }: { editId?: string }) {
                   placeholder="Class A"
                 />
               </div>
-              <div className="space-y-2">
-                <Label htmlFor="licenseExpiry">License Expiry</Label>
+              <div className="space-y-2 md:col-span-3">
+                <div className="flex items-center justify-between gap-2">
+                  <Label htmlFor="licenseExpiry">Licence expiry (UTC)</Label>
+                  {form.licenseExpiry && (
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      aria-label="Clear recorded licence expiry"
+                      onClick={() => setForm((prev) => ({ ...prev, licenseExpiry: '' }))}
+                    >
+                      Clear
+                    </Button>
+                  )}
+                </div>
                 <Input
                   id="licenseExpiry"
-                  type="date"
+                  type="datetime-local"
+                  step="0.001"
+                  aria-describedby="licenseExpiryHelp"
                   value={form.licenseExpiry}
                   onChange={(e) => setForm((prev) => ({ ...prev, licenseExpiry: e.target.value }))}
                 />
+                <p id="licenseExpiryHelp" className="text-xs text-text-secondary">
+                  Enter the recorded UTC time. Blank means expiry not recorded; clearing removes it.
+                  A recorded expiry does not certify legal driving eligibility.
+                </p>
               </div>
             </div>
             <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
@@ -765,8 +791,8 @@ export default function DriverDetailsPage() {
       }
     >
       <PagePurpose icon={<Users size={18} />}>
-        A driver&apos;s full profile — licensing, assigned vehicle, documents and HR record. Use it
-        to confirm someone is road-ready and compliant before assigning them an order or route.
+        Review the recorded licensing, assigned vehicle, documents and HR facts before assignment.
+        These records do not certify legal driving eligibility or duty-hours availability.
       </PagePurpose>
 
       <NextSteps
@@ -822,9 +848,9 @@ export default function DriverDetailsPage() {
                     {driver.licenseNumber || '—'}
                     {driver.licenseType ? ` - ${driver.licenseType}` : ''}
                   </p>
-                  <p className="text-sm text-text-secondary">
+                  <p className="text-sm text-text-secondary break-all">
                     {driver.licenseExpiry
-                      ? `Expires: ${formatDate(driver.licenseExpiry)}`
+                      ? `Recorded expiry (UTC): ${driver.licenseExpiry.toISOString()}`
                       : 'Expiry not recorded'}
                   </p>
                 </div>

package/src/movethewheels/pages/FreightEstimatePage.tsx

@@ -335,6 +335,7 @@ function FreightWorkbench({ actions }: { actions: ReturnType<typeof useFreightRe
               key={row.id}
               type="button"
               variant="outline"
+              className="h-auto w-full max-w-full justify-start whitespace-normal break-all text-left"
               onClick={() => setSelected(row.id)}
             >
               {row.facts.title} / {row.estimateReference} / version {row.version} —{' '}