@burdenoff/microfe-movethewheels 2026.1011.1 → 2026.1011.2

package/src/movethewheels/pages/ShipmentStatusAuthorityPage.tsx

@@ -0,0 +1,639 @@
+import { useState } from 'react';
+import { ClipboardList } from 'lucide-react';
+import { PermissionProvider, usePermissions } from '@burdenoff/fe-libs/shared/providers/shell';
+import { PageLayout } from '../components/PageLayout';
+import { Button, Input, Label, Textarea } from '../components/ui';
+import { reuseCard, reuseSelect, ReuseState } from '../components/ReuseControls';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import {
+  useShipmentStatusCommand,
+  useShipmentStatusQuery,
+} from '../hooks/useShipmentStatusAuthority';
+import {
+  shipmentSourceInput,
+  sourceStatusAcknowledged,
+  manualStatusAcknowledged,
+  statusDecisionReason,
+  type ShipmentSourceDraft,
+} from '../utils/shipmentStatusDraft';
+import {
+  StatusAuthorityShipmentsDocument,
+  StatusAuthorityDetailDocument,
+  StatusAuthoritySourcesDocument,
+  StatusAuthorityConfigureDocument,
+  StatusAuthorityManualDocument,
+} from '../../generated/shipment-status-authority-operations';
+import type {
+  StatusAuthorityShipmentsQuery,
+  StatusAuthorityDetailQuery,
+  StatusAuthoritySourcesQuery,
+  StatusAuthorityConfigureMutation,
+  StatusAuthorityManualMutation,
+  ShipmentStatus,
+} from '../../generated/shipment-status-authority-operations';
+
+const LIMIT = 20;
+const STATUSES: ShipmentStatus[] = [
+  'PLANNED',
+  'PICKED_UP',
+  'IN_TRANSIT',
+  'DELIVERED',
+  'FAILED',
+  'RETURNED',
+];
+const EMPTY_SOURCE: ShipmentSourceDraft = {
+  integrationId: '',
+  basisTrackingEventId: '',
+  maxSourceAgeSeconds: '',
+  maxFutureSkewSeconds: '',
+  reason: '',
+};
+function label(value: string | null | undefined) {
+  return value ? value.toLowerCase().replaceAll('_', ' ') : 'Not recorded';
+}
+function time(value: string | null | undefined) {
+  if (!value) return 'Not recorded';
+  const parsed = new Date(value);
+  return Number.isFinite(parsed.getTime()) ? parsed.toLocaleString() : 'Unverified time';
+}
+function Pager({
+  offset,
+  length,
+  busy,
+  change,
+}: {
+  offset: number;
+  length: number | undefined;
+  busy: boolean;
+  change: (offset: number) => void;
+}) {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button
+        variant="outline"
+        disabled={busy || offset === 0}
+        onClick={() => change(Math.max(0, offset - LIMIT))}
+      >
+        Previous page
+      </Button>
+      <span>{length === undefined ? 'Page unavailable' : `${length} records on this page`}</span>
+      <Button
+        variant="outline"
+        disabled={busy || length !== LIMIT || offset >= 9980}
+        onClick={() => change(offset + LIMIT)}
+      >
+        Next page
+      </Button>
+    </div>
+  );
+}
+
+export default function ShipmentStatusAuthorityPage() {
+  const { workspaceId, tenantId, currentUser, apiGatewayUrl } = useMoveTheWheels();
+  return (
+    <PageLayout
+      title="Shipment status authority"
+      subtitle="Keep recorded status separate from incoming tracking evidence."
+      icon={<ClipboardList aria-hidden="true" />}
+    >
+      <PermissionProvider scopeId={workspaceId ?? null} gateway="workspace">
+        <StatusWorkbench key={`${workspaceId}:${tenantId}:${currentUser?.id}:${apiGatewayUrl}`} />
+      </PermissionProvider>
+    </PageLayout>
+  );
+}
+
+function StatusWorkbench() {
+  const permissions = usePermissions();
+  const [offset, setOffset] = useState(0);
+  const [selected, setSelected] = useState('');
+  const [search, setSearch] = useState('');
+  const [filter, setFilter] = useState('');
+  const shipments = useShipmentStatusQuery<StatusAuthorityShipmentsQuery>(
+    StatusAuthorityShipmentsDocument,
+    permissions.hasPermission('shipment:read')
+      ? { filter: { search: filter || undefined }, pagination: { limit: LIMIT, offset } }
+      : null
+  );
+  return (
+    <div className="space-y-6">
+      <p>
+        Incoming evidence can be accepted while its status change is held. A recorded software
+        status is not physical proof of delivery.
+      </p>
+      <ReuseState loading={permissions.isLoading} error={permissions.error?.message ?? null} />
+      {!permissions.isLoading && !permissions.hasPermission('shipment:read') && (
+        <p role="status">Shipment read permission is required.</p>
+      )}
+      {permissions.hasPermission('shipment:read') && (
+        <section className={reuseCard} aria-label="Shipment selection">
+          <form
+            className="flex flex-wrap gap-3"
+            onSubmit={(event) => {
+              event.preventDefault();
+              setFilter(search.trim());
+              setOffset(0);
+              setSelected('');
+            }}
+          >
+            <Label htmlFor="status-search">Shipment search</Label>
+            <Input
+              id="status-search"
+              value={search}
+              onChange={(event) => setSearch(event.target.value)}
+              maxLength={200}
+            />
+            <Button type="submit">Search shipments</Button>
+          </form>
+          <ReuseState loading={shipments.loading} error={shipments.error} />
+          <label className="block">
+            Shipment
+            <select
+              className={reuseSelect}
+              value={selected}
+              disabled={shipments.loading || !shipments.data}
+              onChange={(event) => setSelected(event.target.value)}
+            >
+              <option value="">Choose a shipment</option>
+              {shipments.data?.shipments.map((shipment) => (
+                <option key={shipment.id} value={shipment.id}>
+                  {shipment.shipmentNumber} · {label(shipment.status)}
+                </option>
+              ))}
+            </select>
+          </label>
+          {shipments.data?.shipments.length === 0 && <p>No shipments on this page.</p>}
+          <Pager
+            offset={offset}
+            length={shipments.data?.shipments.length}
+            busy={shipments.loading}
+            change={(next) => {
+              setOffset(next);
+              setSelected('');
+            }}
+          />
+        </section>
+      )}
+      {selected && permissions.hasPermission('shipment:read') && (
+        <StatusDetail
+          key={selected}
+          id={selected}
+          canUpdate={permissions.hasPermission('shipment:update')}
+          canReadSources={permissions.hasPermission('integration:read')}
+        />
+      )}
+    </div>
+  );
+}
+
+function StatusDetail({
+  id,
+  canUpdate,
+  canReadSources,
+}: {
+  id: string;
+  canUpdate: boolean;
+  canReadSources: boolean;
+}) {
+  const [refresh, setRefresh] = useState(0);
+  const [offset, setOffset] = useState(0);
+  const [sourceOffset, setSourceOffset] = useState(0);
+  const [evidenceOffset, setEvidenceOffset] = useState(0);
+  const action = useShipmentStatusCommand();
+  const detail = useShipmentStatusQuery<StatusAuthorityDetailQuery>(
+    StatusAuthorityDetailDocument,
+    {
+      id,
+      pagination: { limit: LIMIT, offset },
+      evidencePagination: { limit: LIMIT, offset: evidenceOffset },
+    },
+    refresh + action.revision
+  );
+  const sources = useShipmentStatusQuery<StatusAuthoritySourcesQuery>(
+    StatusAuthoritySourcesDocument,
+    canUpdate && canReadSources ? { pagination: { limit: LIMIT, offset: sourceOffset } } : null
+  );
+  const shipment = detail.data?.shipment;
+  // Forms stay mounted during refresh, so a stale response never erases operator input.
+  const [source, setSource] = useState<ShipmentSourceDraft>(EMPTY_SOURCE);
+  const [manualStatus, setManualStatus] = useState<ShipmentStatus | ''>('');
+  const [manualReason, setManualReason] = useState('');
+  const [formRevision, setFormRevision] = useState<number | null>(null);
+  const [formError, setFormError] = useState<string | null>(null);
+  const [reviewed, setReviewed] = useState(false);
+  const [requiredRefresh, setRequiredRefresh] = useState(0);
+  const freshReviewAvailable =
+    refresh >= requiredRefresh && !!shipment && !detail.loading && !detail.error;
+  const stale =
+    formRevision !== null && shipment != null && formRevision !== shipment.statusRevision;
+  const uncertain = action.feedback?.kind === 'UNKNOWN';
+  const blocked =
+    action.busy ||
+    detail.loading ||
+    !shipment ||
+    formRevision === null ||
+    stale ||
+    uncertain ||
+    !freshReviewAvailable;
+  const basis =
+    shipment?.trackingEvents.filter(
+      (event) =>
+        event.sourceIntegrationId === source.integrationId &&
+        event.sourceTimestampProvenance === 'PROVIDER_TIME_VALIDATED' &&
+        event.providerEventTime &&
+        event.eventType !== 'CREATED'
+    ) ?? [];
+  const changeSource = (field: keyof ShipmentSourceDraft, value: string) =>
+    setSource((current) => ({ ...current, [field]: value }));
+  return (
+    <div className="space-y-6">
+      <section className={reuseCard} aria-label="Recorded shipment status">
+        <div className="flex flex-wrap justify-between gap-3">
+          <h2 className="font-semibold">Recorded status</h2>
+          <Button
+            variant="outline"
+            disabled={detail.loading || action.busy}
+            onClick={() => {
+              setReviewed(false);
+              setRefresh((value) => value + 1);
+            }}
+          >
+            Refresh recorded status
+          </Button>
+        </div>
+        <ReuseState loading={detail.loading} error={detail.error} />
+        {shipment === null && <p>Shipment unavailable in this workspace.</p>}
+        {shipment && (
+          <dl className="grid gap-3 sm:grid-cols-2 break-words">
+            <div>
+              <dt>Shipment</dt>
+              <dd>{shipment.shipmentNumber}</dd>
+            </div>
+            <div>
+              <dt>Status</dt>
+              <dd>{label(shipment.status)}</dd>
+            </div>
+            <div>
+              <dt>Status revision</dt>
+              <dd>{shipment.statusRevision}</dd>
+            </div>
+            <div>
+              <dt>Authority</dt>
+              <dd>{label(shipment.statusAuthority)}</dd>
+            </div>
+            <div>
+              <dt>Chosen integration</dt>
+              <dd className="break-all">{shipment.designatedIntegrationId ?? 'None selected'}</dd>
+            </div>
+            <div>
+              <dt>Basis source time</dt>
+              <dd>{time(shipment.statusBasisSourceTime)}</dd>
+            </div>
+            <div>
+              <dt>Maximum source age</dt>
+              <dd>
+                {shipment.maxSourceAgeSeconds === null
+                  ? 'No active source policy'
+                  : `${shipment.maxSourceAgeSeconds} seconds`}
+              </dd>
+            </div>
+            <div>
+              <dt>Allowed future skew</dt>
+              <dd>
+                {shipment.maxFutureSkewSeconds === null
+                  ? 'No active source policy'
+                  : `${shipment.maxFutureSkewSeconds} seconds`}
+              </dd>
+            </div>
+          </dl>
+        )}
+      </section>
+      {action.feedback && <p role="status">{action.feedback.message}</p>}
+      {formError && <p role="alert">{formError}</p>}
+      {!canUpdate && (
+        <p role="status">
+          Read-only access. Shipment update permission is required to choose a source or record a
+          correction.
+        </p>
+      )}
+      {canUpdate && (
+        <section className={reuseCard} aria-label="Status decisions">
+          <p>
+            Review the current status, then explicitly use its revision for a new decision. Clock
+            limits are your policy, not carrier certification.
+          </p>
+          {stale && (
+            <p role="alert">
+              Status changed since this form opened. Your input is preserved. Review the current
+              recorded status before applying.
+            </p>
+          )}
+          {!uncertain && (
+            <Button
+              variant="outline"
+              disabled={!freshReviewAvailable || action.busy}
+              onClick={() => {
+                if (shipment) {
+                  setFormRevision(shipment.statusRevision);
+                  setFormError(null);
+                  action.beginSeparateAction();
+                }
+              }}
+            >
+              Use reviewed revision {shipment?.statusRevision ?? '—'}
+            </Button>
+          )}
+          {uncertain && (
+            <div className="space-y-3">
+              <label className="flex items-start gap-2">
+                <input
+                  type="checkbox"
+                  disabled={!freshReviewAvailable}
+                  checked={reviewed}
+                  onChange={(event) => setReviewed(event.target.checked)}
+                />
+                I reviewed the refreshed recorded status and decision history.
+              </label>
+              <Button
+                variant="outline"
+                disabled={!reviewed || !freshReviewAvailable || action.busy}
+                onClick={() => {
+                  if (shipment) {
+                    setSource(EMPTY_SOURCE);
+                    setManualStatus('');
+                    setManualReason('');
+                    setFormRevision(shipment.statusRevision);
+                    setFormError(null);
+                    setReviewed(false);
+                    action.beginSeparateAction();
+                  }
+                }}
+              >
+                Begin a separate new action
+              </Button>
+            </div>
+          )}
+          <form
+            className="space-y-3"
+            onSubmit={async (event) => {
+              event.preventDefault();
+              setFormError(null);
+              if (blocked || formRevision === null || !shipment) return;
+              try {
+                const input = shipmentSourceInput(source, formRevision);
+                const result = await action.run<StatusAuthorityConfigureMutation>(
+                  StatusAuthorityConfigureDocument,
+                  { id, input },
+                  (data) =>
+                    sourceStatusAcknowledged(data.configureShipmentStatusSource, {
+                      id,
+                      epoch: shipment.statusAuthorityEpoch,
+                      input,
+                      basis: basis.find((event) => event.id === input.basisTrackingEventId),
+                    })
+                );
+                if (result) setFormRevision(null);
+                else {
+                  setReviewed(false);
+                  setRequiredRefresh(refresh + 1);
+                }
+              } catch (failure) {
+                setFormError(
+                  failure instanceof Error ? failure.message : 'Review the source policy.'
+                );
+              }
+            }}
+          >
+            <fieldset disabled={blocked || !canReadSources} className="space-y-3">
+              <legend className="font-semibold">Choose a status source</legend>
+              {!canReadSources && (
+                <p>Integration read permission is required for source selection.</p>
+              )}
+              <ReuseState loading={sources.loading} error={sources.error} />
+              <label className="block">
+                Integration
+                <select
+                  className={reuseSelect}
+                  value={source.integrationId}
+                  onChange={(event) => {
+                    changeSource('integrationId', event.target.value);
+                    changeSource('basisTrackingEventId', '');
+                  }}
+                >
+                  <option value="">Choose an integration</option>
+                  {sources.data?.integrations
+                    .filter((integration) => integration.status === 'ACTIVE')
+                    .map((integration) => (
+                      <option key={integration.id} value={integration.id}>
+                        {integration.name} · {integration.provider}
+                      </option>
+                    ))}
+                </select>
+              </label>
+              <label className="block">
+                Recorded basis event
+                <select
+                  className={reuseSelect}
+                  value={source.basisTrackingEventId}
+                  onChange={(event) => changeSource('basisTrackingEventId', event.target.value)}
+                >
+                  <option value="">Choose an existing basis event</option>
+                  {basis.map((event) => (
+                    <option key={event.id} value={event.id}>
+                      {label(event.eventType)} · {time(event.providerEventTime)} · {event.id}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <p>
+                This page lists evidence from the selected source with validated provider time. The
+                server checks its recorded receipt, source and clock window before applying.
+              </p>
+              <Label htmlFor="status-source-age">Maximum source age (seconds)</Label>
+              <Input
+                id="status-source-age"
+                inputMode="numeric"
+                value={source.maxSourceAgeSeconds}
+                onChange={(event) => changeSource('maxSourceAgeSeconds', event.target.value)}
+              />
+              <Label htmlFor="status-source-skew">Allowed future skew (seconds)</Label>
+              <Input
+                id="status-source-skew"
+                inputMode="numeric"
+                value={source.maxFutureSkewSeconds}
+                onChange={(event) => changeSource('maxFutureSkewSeconds', event.target.value)}
+              />
+              <Label htmlFor="status-source-reason">Source choice reason</Label>
+              <Textarea
+                id="status-source-reason"
+                maxLength={1000}
+                value={source.reason}
+                onChange={(event) => changeSource('reason', event.target.value)}
+              />
+              <Button type="submit">Apply source choice</Button>
+            </fieldset>
+          </form>
+          {canReadSources && (
+            <Pager
+              offset={sourceOffset}
+              length={sources.data?.integrations.length}
+              busy={sources.loading || action.busy}
+              change={(next) => {
+                setSourceOffset(next);
+                changeSource('integrationId', '');
+                changeSource('basisTrackingEventId', '');
+              }}
+            />
+          )}
+          <form
+            className="space-y-3"
+            onSubmit={async (event) => {
+              event.preventDefault();
+              setFormError(null);
+              if (blocked || formRevision === null || !shipment) return;
+              try {
+                if (!manualStatus) throw new Error('Choose a recorded status for this correction.');
+                const result = await action.run<StatusAuthorityManualMutation>(
+                  StatusAuthorityManualDocument,
+                  {
+                    id,
+                    input: {
+                      status: manualStatus,
+                      expectedStatusRevision: formRevision,
+                      statusReason: statusDecisionReason(manualReason),
+                    },
+                  },
+                  (data) =>
+                    manualStatusAcknowledged(data.updateShipment, {
+                      id,
+                      revision: formRevision,
+                      epoch: shipment.statusAuthorityEpoch,
+                      status: manualStatus,
+                    })
+                );
+                if (result) setFormRevision(null);
+                else {
+                  setReviewed(false);
+                  setRequiredRefresh(refresh + 1);
+                }
+              } catch (failure) {
+                setFormError(failure instanceof Error ? failure.message : 'Review the correction.');
+              }
+            }}
+          >
+            <fieldset disabled={blocked} className="space-y-3">
+              <legend className="font-semibold">Record a manual correction</legend>
+              <p>
+                A manual correction puts automatic tracking projection on hold. Existing evidence
+                remains unchanged.
+              </p>
+              <label className="block">
+                Recorded status
+                <select
+                  className={reuseSelect}
+                  value={manualStatus}
+                  onChange={(event) => {
+                    const selectedStatus = STATUSES.find((status) => status === event.target.value);
+                    setManualStatus(selectedStatus ?? '');
+                  }}
+                >
+                  <option value="">Choose a status</option>
+                  {STATUSES.map((status) => (
+                    <option key={status} value={status}>
+                      {label(status)}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <Label htmlFor="status-manual-reason">Correction reason</Label>
+              <Textarea
+                id="status-manual-reason"
+                value={manualReason}
+                maxLength={1000}
+                onChange={(event) => setManualReason(event.target.value)}
+              />
+              <Button type="submit">Record correction and hold</Button>
+            </fieldset>
+          </form>
+        </section>
+      )}
+      <section className={reuseCard} aria-label="Shipment status decision history">
+        <h2 className="font-semibold">Decision history</h2>
+        {detail.data?.shipmentStatusDecisions.length === 0 && (
+          <p>
+            No recorded status decisions on this page. Legacy evidence may have no decision ledger.
+          </p>
+        )}
+        <div className="space-y-3">
+          {detail.data?.shipmentStatusDecisions.map((decision) => (
+            <article key={decision.id} className="border rounded-md p-3 break-words">
+              <p>
+                {label(decision.origin)} · {label(decision.outcome)}
+                {decision.heldReason ? `: ${label(decision.heldReason)}` : ''}
+              </p>
+              <p>
+                {label(decision.priorStatus)} → {label(decision.resultStatus)} · revision{' '}
+                {decision.observedRevision} → {decision.resultRevision}
+              </p>
+              <p>{time(decision.recordedAt)}</p>
+              {decision.reason && <p>{decision.reason}</p>}
+              {decision.trackingEventId && (
+                <p className="break-all">Evidence: {decision.trackingEventId}</p>
+              )}
+              {decision.proofId && <p className="break-all">Delivery proof: {decision.proofId}</p>}
+              {decision.configuredIntegrationId && (
+                <p className="break-all">
+                  Chosen integration for this decision: {decision.configuredIntegrationId}
+                </p>
+              )}
+              {decision.configuredMaxSourceAgeSeconds !== null && (
+                <p>
+                  Source age limit for this decision: {decision.configuredMaxSourceAgeSeconds}{' '}
+                  seconds
+                </p>
+              )}
+              {decision.configuredMaxFutureSkewSeconds !== null && (
+                <p>
+                  Future skew limit for this decision: {decision.configuredMaxFutureSkewSeconds}{' '}
+                  seconds
+                </p>
+              )}
+            </article>
+          ))}
+        </div>
+        <Pager
+          offset={offset}
+          length={detail.data?.shipmentStatusDecisions.length}
+          busy={detail.loading || action.busy}
+          change={(next) => {
+            setOffset(next);
+          }}
+        />
+      </section>
+      <section className={reuseCard} aria-label="Recorded tracking evidence">
+        <h2 className="font-semibold">Tracking evidence</h2>
+        <div className="space-y-3">
+          {shipment?.trackingEvents.map((event) => (
+            <article key={event.id} className="border rounded-md p-3 break-words">
+              <p>
+                {label(event.eventType)} · {label(event.sourceTimestampProvenance)}
+              </p>
+              <p>Provider time: {time(event.providerEventTime)}</p>
+              <p>Received: {time(event.serverReceivedAt)}</p>
+              <p className="break-all">Evidence: {event.id}</p>
+            </article>
+          ))}
+        </div>
+        <Pager
+          offset={evidenceOffset}
+          length={shipment?.trackingEvents.length}
+          busy={detail.loading || action.busy}
+          change={(next) => {
+            setEvidenceOffset(next);
+            changeSource('basisTrackingEventId', '');
+          }}
+        />
+      </section>
+    </div>
+  );
+}

package/src/movethewheels/pages/TrackingEventQualityPage.tsx

@@ -168,6 +168,16 @@ function QualityWorkbench() {
                         {outcome.errorCode && (
                           <p>Reason: {outcome.errorCode.replaceAll('_', ' ').toLowerCase()}</p>
                         )}
+                        {(outcome.status === 'ACCEPTED' || outcome.status === 'DUPLICATE') && (
+                          <p>
+                            Status decision:{' '}
+                            {outcome.projection?.status === 'APPLIED'
+                              ? 'Applied to the recorded shipment status'
+                              : outcome.projection?.status === 'HELD'
+                                ? `Held — ${outcome.projection.heldReason?.replaceAll('_', ' ').toLowerCase()}`
+                                : 'No status decision recorded in this legacy result'}
+                          </p>
+                        )}
                         {outcome.status === 'CONFLICT' && (
                           <p>The earlier receipt stays unchanged; this update adds no event.</p>
                         )}
@@ -198,8 +208,9 @@ function QualityWorkbench() {
         <QualityShipment key={shipmentId} id={shipmentId} onClose={() => setShipmentId(null)} />
       )}
       <p className="text-sm text-text-secondary">
-        These results describe recorded ingestion, not physical shipment truth. Ordering, late
-        updates and provider corrections need separate policies.
+        These results describe recorded ingestion, not physical shipment truth. The chosen-source
+        clock policy and manual corrections control recorded shipment status. Provider corrections
+        and replay need separate reviewed policies.
       </p>
     </div>
   );