@burdenoff/microfe-movethewheels 2026.1016.2 → 2026.1016.3

package/src/movethewheels/hooks/useFreightRecoveryAction.ts

@@ -5,6 +5,7 @@ import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { matchesFreightAcknowledgement } from '../utils/freightAcknowledgement';
 import {
   SaveFreightCostsDocument,
+  SaveFreightCommercialCostsDocument,
   type SaveFreightCostsMutation,
 } from '../../generated/freight-cost-operations';
 import {
@@ -18,7 +19,7 @@ import {
   encodeFreightRecovery,
   FREIGHT_RECOVERY_STORAGE,
 } from '../utils/freightRecovery';
-const documents = [SaveFreightCostsDocument];
+const documents = [SaveFreightCostsDocument, SaveFreightCommercialCostsDocument];
 function loadRecovery(): { attempt: ReuseRecovery | null; blocked: boolean } {
   try {
     const raw = sessionStorage.getItem(FREIGHT_RECOVERY_STORAGE);

package/src/movethewheels/pages/FreightEstimatePage.tsx

@@ -13,16 +13,18 @@ import {
   FreightShipmentsDocument,
   FreightShipmentDocument,
   FreightHistoryDocument,
-  FreightVersionDocument,
+  FreightCommercialVersionDocument,
   PreviewFreightCostsDocument,
   SaveFreightCostsDocument,
+  SaveFreightCommercialCostsDocument,
   type FreightShipmentsQuery,
   type FreightShipmentQuery,
   type FreightHistoryQuery,
-  type FreightVersionQuery,
+  type FreightCommercialVersionQuery,
   type MtwFreightFactsInput,
   type PreviewFreightCostsQuery,
 } from '../../generated/freight-cost-operations';
+import type { CommercialCapture } from '../utils/freightCommercial';
 import type { SelectedEvidence } from '../components/ContainerEvidencePicker';
 export default function FreightEstimatePage() {
   const actions = useFreightRecoveryAction();
@@ -93,8 +95,8 @@ function FreightWorkbench({ actions }: { actions: ReturnType<typeof useFreightRe
       : null,
     actions.revision
   );
-  const exact = useConditionQuery<FreightVersionQuery>(
-    FreightVersionDocument,
+  const exact = useConditionQuery<FreightCommercialVersionQuery>(
+    FreightCommercialVersionDocument,
     historyTarget && selected ? { shipmentId: historyTarget.shipmentId, id: selected } : null,
     actions.revision
   );
@@ -112,7 +114,11 @@ function FreightWorkbench({ actions }: { actions: ReturnType<typeof useFreightRe
     })) ?? [];
   if (shipment && !options.some((row) => row.id === shipment.id))
     options.unshift({ id: shipment.id, label: `${shipment.label} — selected outside this page` });
-  const save = async (facts: MtwFreightFactsInput, evidence: SelectedEvidence[]) => {
+  const save = async (
+    facts: MtwFreightFactsInput,
+    evidence: SelectedEvidence[],
+    commercialCapture?: CommercialCapture
+  ) => {
     if (preflight.current || paused) return;
     if (!draft) throw new Error('Review the shipment and current cost history first.');
     preflight.current = true;
@@ -139,8 +145,8 @@ function FreightWorkbench({ actions }: { actions: ReturnType<typeof useFreightRe
         evidence.map(({ fileId, versionId }) => ({ fileId, versionId }))
       );
       const result = await actions.run(
-        SaveFreightCostsDocument,
-        input,
+        commercialCapture ? SaveFreightCommercialCostsDocument : SaveFreightCostsDocument,
+        commercialCapture ? { ...input, commercialCapture } : input,
         'Sourced cost version recorded.'
       );
       if (result && active.current) {
@@ -250,6 +256,7 @@ function FreightWorkbench({ actions }: { actions: ReturnType<typeof useFreightRe
       {draft && !changed && !mismatch && (
         <FreightDraftForm
           key={draft.generation}
+          shipmentId={draft.shipmentId}
           disabled={
             paused || current.loading || latest.loading || !!current.error || !!latest.error
           }

package/src/movethewheels/utils/freightAcknowledgement.ts

@@ -1,3 +1,4 @@
+import { matchesCommercialCapture } from './freightCommercial';
 /** Validate the minimum immutable receipt identity before resolving a retained request. */
 export function matchesFreightAcknowledgement(
   result: unknown,
@@ -26,6 +27,7 @@ export function matchesFreightAcknowledgement(
     input.expectedVersion >= 0 &&
     receipt.version === input.expectedVersion + 1 &&
     'previousVersionId' in receipt &&
-    receipt.previousVersionId === input.expectedPreviousVersionId
+    receipt.previousVersionId === input.expectedPreviousVersionId &&
+    (input.commercialCapture == null || matchesCommercialCapture(receipt, input))
   );
 }

package/src/movethewheels/utils/freightCommercial.ts

@@ -0,0 +1,388 @@
+import type {
+  MtwFreightCommercialCaptureInput,
+  MtwFreightCommercialLocationFactInput,
+  MtwFreightCommercialStatus,
+  MtwFreightCommercialProvenanceInput,
+  FreightCommercialLegsQuery,
+} from '../../generated/freight-cost-operations';
+
+export const commercialSlots = [
+  'origin',
+  'destination',
+  'carrier',
+  'service',
+  'cargo',
+  'weight',
+  'volume',
+  'equipment',
+] as const;
+export type CommercialSlot = (typeof commercialSlots)[number];
+export type CommercialLeg = NonNullable<FreightCommercialLegsQuery['shipment']>['legs'][number];
+export type CommercialCapture = MtwFreightCommercialCaptureInput;
+export const unrecordedCommercialReason = 'Not recorded for this cost version';
+export interface CommercialFactDraft {
+  status: MtwFreightCommercialStatus;
+  reason: string;
+  label: string;
+  reference: string;
+  description: string;
+  kind: string;
+  jurisdiction: string;
+  amount: string;
+  unit: string;
+  zeroReason: string;
+  count: string;
+  sourceReference: string;
+  sourceRevision: string;
+  observedAt: string;
+  evidenceLinks: { fileId: string; versionId: string }[];
+}
+export type CommercialDraft = Record<CommercialSlot, CommercialFactDraft>;
+export interface CommercialEditorState {
+  facts: CommercialDraft;
+  selectedLegs: CommercialCapture['selectedLegs'];
+  reviewed: string | null;
+}
+export function newCommercialEditor(): CommercialEditorState {
+  return { facts: newCommercialDraft(), selectedLegs: [], reviewed: null };
+}
+export function newCommercialFact(
+  status: MtwFreightCommercialStatus = 'UNKNOWN'
+): CommercialFactDraft {
+  return {
+    status,
+    reason: status === 'UNKNOWN' ? unrecordedCommercialReason : '',
+    label: '',
+    reference: '',
+    description: '',
+    kind: '',
+    jurisdiction: '',
+    amount: '',
+    unit: '',
+    zeroReason: '',
+    count: '',
+    sourceReference: '',
+    sourceRevision: '',
+    observedAt: '',
+    evidenceLinks: [],
+  };
+}
+export function newCommercialDraft(): CommercialDraft {
+  return {
+    origin: newCommercialFact(),
+    destination: newCommercialFact(),
+    carrier: newCommercialFact(),
+    service: newCommercialFact(),
+    cargo: newCommercialFact(),
+    weight: newCommercialFact(),
+    volume: newCommercialFact(),
+    equipment: newCommercialFact(),
+  };
+}
+function text(value: string, limit: number, label: string): string {
+  const result = value.trim();
+  if (!result || result.length > limit) throw new Error(`${label}: enter 1–${limit} characters.`);
+  return result;
+}
+function instant(value: string): string {
+  if (
+    !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value) ||
+    new Date(value).toISOString() !== value ||
+    Date.parse(value) > Date.now()
+  )
+    throw new Error('Use a valid observed time no later than now.');
+  return value;
+}
+function decimal(value: string, zeroReason: string) {
+  if (!/^(0|[1-9][0-9]{0,17})(\.[0-9]{0,5}[1-9])?$/.test(value))
+    throw new Error(
+      'Use a canonical nonnegative decimal: up to 18 integer and 6 fractional digits, no exponent or trailing fractional zero.'
+    );
+  if (value === '0') return text(zeroReason, 255, 'Recorded zero reason');
+  if (zeroReason.trim()) throw new Error('A zero reason belongs only to an amount of zero.');
+  return null;
+}
+function provenance(
+  row: CommercialFactDraft,
+  evidence: { fileId: string; versionId: string }[]
+): MtwFreightCommercialProvenanceInput {
+  const links = row.evidenceLinks;
+  if (
+    links.length < 1 ||
+    links.length > 2 ||
+    new Set(links.map((link) => JSON.stringify([link.fileId, link.versionId]))).size !==
+      links.length ||
+    links.some(
+      (link) =>
+        !evidence.some((item) => item.fileId === link.fileId && item.versionId === link.versionId)
+    )
+  )
+    throw new Error(
+      'Choose 1–2 distinct exact evidence versions already selected for this cost record.'
+    );
+  return {
+    sourceReference: text(row.sourceReference, 255, 'Fact source'),
+    sourceRevision: text(row.sourceRevision, 255, 'Fact source revision'),
+    observedAt: row.observedAt ? instant(row.observedAt) : null,
+    evidenceLinks: [...links]
+      .sort((a, b) =>
+        JSON.stringify([a.fileId, a.versionId]) < JSON.stringify([b.fileId, b.versionId])
+          ? -1
+          : JSON.stringify([a.fileId, a.versionId]) > JSON.stringify([b.fileId, b.versionId])
+            ? 1
+            : 0
+      )
+      .map((link) => ({ ...link })),
+  };
+}
+/** No source values are inferred from the owner snapshot or other fact slots. */
+export function commercialCaptureInput(
+  draft: CommercialDraft,
+  pins: CommercialCapture['selectedLegs'],
+  evidence: { fileId: string; versionId: string }[]
+): CommercialCapture {
+  const common = (key: CommercialSlot) => {
+    const row = draft[key];
+    if (row.status === 'UNKNOWN')
+      return {
+        status: row.status,
+        value: null,
+        reason: text(row.reason, 255, key),
+        provenance: null,
+      };
+    if (row.status !== 'SOURCED' && row.status !== 'NOT_APPLICABLE')
+      throw new Error('Choose a supported commercial fact status.');
+    return {
+      status: row.status,
+      value: null,
+      reason: row.status === 'NOT_APPLICABLE' ? text(row.reason, 255, key) : null,
+      provenance: provenance(row, evidence),
+    };
+  };
+  const location = (key: 'origin' | 'destination'): MtwFreightCommercialLocationFactInput => {
+    const base = common(key),
+      row = draft[key];
+    if (base.status !== 'SOURCED') return base;
+    if (
+      row.kind !== 'ADDRESS_LABEL' &&
+      row.kind !== 'PORT_LABEL' &&
+      row.kind !== 'TERMINAL_LABEL' &&
+      row.kind !== 'POSTCODE_LABEL' &&
+      row.kind !== 'CUSTOM_LABEL'
+    )
+      throw new Error('Choose a location label kind.');
+    return {
+      ...base,
+      value: {
+        kind: row.kind,
+        label: text(row.label, 255, key),
+        jurisdictionLabel: row.jurisdiction.trim()
+          ? text(row.jurisdiction, 120, 'Jurisdiction label')
+          : null,
+      },
+    };
+  };
+  const weight = common('weight'),
+    volume = common('volume'),
+    carrier = common('carrier'),
+    service = common('service'),
+    cargo = common('cargo'),
+    equipment = common('equipment');
+  const w = draft.weight,
+    v = draft.volume;
+  if (w.status === 'SOURCED' && w.unit !== 'KG' && w.unit !== 'TONNE' && w.unit !== 'LB')
+    throw new Error('Choose a recorded weight unit.');
+  if (v.status === 'SOURCED' && v.unit !== 'M3' && v.unit !== 'FT3')
+    throw new Error('Choose a recorded volume unit.');
+  if (
+    draft.equipment.status === 'SOURCED' &&
+    (!/^[1-9][0-9]{0,5}$/.test(draft.equipment.count) || Number(draft.equipment.count) > 100000)
+  )
+    throw new Error('Equipment count must be an integer from 1 to 100000.');
+  if (pins.length > 16 || new Set(pins.map((pin) => pin.id)).size !== pins.length)
+    throw new Error('Select at most 16 distinct reviewed legs.');
+  const selectedLegs = pins
+    .map((pin) => ({ id: text(pin.id, 200, 'Leg ID'), expectedUpdatedAt: pin.expectedUpdatedAt }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const result: CommercialCapture = {
+    schemaVersion: 1,
+    selectedLegs,
+    origin: location('origin'),
+    destination: location('destination'),
+    carrier:
+      carrier.status === 'SOURCED'
+        ? {
+            ...carrier,
+            value: {
+              reference: text(draft.carrier.reference, 120, 'Carrier reference'),
+              label: text(draft.carrier.label, 255, 'Carrier label'),
+            },
+          }
+        : carrier,
+    service:
+      service.status === 'SOURCED'
+        ? { ...service, value: text(draft.service.label, 120, 'Service') }
+        : service,
+    cargo:
+      cargo.status === 'SOURCED'
+        ? {
+            ...cargo,
+            value: {
+              classificationLabel: text(draft.cargo.label, 120, 'Cargo classification'),
+              description: text(draft.cargo.description, 500, 'Cargo description'),
+            },
+          }
+        : cargo,
+    weight:
+      weight.status === 'SOURCED'
+        ? {
+            ...weight,
+            value: {
+              amount: w.amount,
+              unit: w.unit === 'KG' ? 'KG' : w.unit === 'TONNE' ? 'TONNE' : 'LB',
+              zeroReason: decimal(w.amount, w.zeroReason),
+            },
+          }
+        : weight,
+    volume:
+      volume.status === 'SOURCED'
+        ? {
+            ...volume,
+            value: {
+              amount: v.amount,
+              unit: v.unit === 'M3' ? 'M3' : 'FT3',
+              zeroReason: decimal(v.amount, v.zeroReason),
+            },
+          }
+        : volume,
+    equipment:
+      equipment.status === 'SOURCED'
+        ? {
+            ...equipment,
+            value: {
+              typeLabel: text(draft.equipment.label, 120, 'Equipment type'),
+              count: Number(draft.equipment.count),
+            },
+          }
+        : equipment,
+  };
+  if (new TextEncoder().encode(JSON.stringify(result)).byteLength > 32768)
+    throw new Error('Commercial capture exceeds 32768 bytes. Shorten facts before saving.');
+  return result;
+}
+
+export function commercialPinsMatch(
+  pins: CommercialCapture['selectedLegs'],
+  legs: CommercialLeg[],
+  shipmentId: string
+): boolean {
+  return (
+    pins.length <= 16 &&
+    new Set(pins.map((pin) => pin.id)).size === pins.length &&
+    pins.every((pin) =>
+      legs.some(
+        (leg) =>
+          leg.id === pin.id &&
+          leg.shipmentId === shipmentId &&
+          leg.updatedAt === pin.expectedUpdatedAt
+      )
+    )
+  );
+}
+
+/** Compare typed GraphQL output with the canonical input without trusting __typename or key order. */
+export function commercialCanonical(value: unknown): string {
+  function ordered(v: unknown): unknown {
+    if (Array.isArray(v)) return v.map(ordered);
+    if (v && typeof v === 'object')
+      return Object.fromEntries(
+        Object.entries(v)
+          .filter(([key]) => key !== '__typename')
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([key, item]) => [key, ordered(item)])
+      );
+    return v;
+  }
+  return JSON.stringify(ordered(value));
+}
+export function matchesCommercialCapture(
+  receipt: unknown,
+  input: Record<string, unknown>
+): boolean {
+  if (
+    !receipt ||
+    typeof receipt !== 'object' ||
+    !('commercialCapture' in receipt) ||
+    !receipt.commercialCapture ||
+    typeof receipt.commercialCapture !== 'object'
+  )
+    return false;
+  const capture = receipt.commercialCapture;
+  if (
+    !input.commercialCapture ||
+    typeof input.commercialCapture !== 'object' ||
+    !('selectedLegs' in input.commercialCapture) ||
+    !Array.isArray(input.commercialCapture.selectedLegs) ||
+    !('ownerShipment' in capture) ||
+    !capture.ownerShipment ||
+    typeof capture.ownerShipment !== 'object' ||
+    !('shipmentId' in capture.ownerShipment) ||
+    capture.ownerShipment.shipmentId !== input.shipmentId ||
+    !('updatedAt' in capture.ownerShipment) ||
+    capture.ownerShipment.updatedAt !== input.expectedShipmentUpdatedAt ||
+    !('primaryMode' in capture.ownerShipment) ||
+    typeof capture.ownerShipment.primaryMode !== 'string' ||
+    !['AIR', 'OCEAN', 'RAIL', 'ROAD'].includes(capture.ownerShipment.primaryMode) ||
+    !('ownerLegs' in capture) ||
+    !Array.isArray(capture.ownerLegs)
+  )
+    return false;
+  const declared = Object.fromEntries(
+    Object.entries(capture).filter(([key]) => key !== 'ownerShipment' && key !== 'ownerLegs')
+  );
+  if (commercialCanonical(declared) !== commercialCanonical(input.commercialCapture)) return false;
+  const pins = input.commercialCapture.selectedLegs;
+  const ownerLegs = capture.ownerLegs;
+  return (
+    ownerLegs.length === pins.length &&
+    pins.every(
+      (pin) =>
+        pin &&
+        typeof pin === 'object' &&
+        'id' in pin &&
+        'expectedUpdatedAt' in pin &&
+        ownerLegs.some(
+          (leg: unknown) =>
+            leg &&
+            typeof leg === 'object' &&
+            'id' in leg &&
+            leg.id === pin.id &&
+            'updatedAt' in leg &&
+            leg.updatedAt === pin.expectedUpdatedAt &&
+            'legNumber' in leg &&
+            typeof leg.legNumber === 'number' &&
+            Number.isInteger(leg.legNumber) &&
+            leg.legNumber > 0 &&
+            'mode' in leg &&
+            typeof leg.mode === 'string' &&
+            ['AIR', 'OCEAN', 'RAIL', 'ROAD'].includes(leg.mode) &&
+            ['carrierId', 'carrierName'].every(
+              (key) =>
+                key in leg &&
+                (Reflect.get(leg, key) === null || typeof Reflect.get(leg, key) === 'string')
+            ) &&
+            ['weightKg', 'volumeCbm', 'containerCount'].every(
+              (key) =>
+                key in leg &&
+                (Reflect.get(leg, key) === null ||
+                  (typeof Reflect.get(leg, key) === 'number' &&
+                    Number.isFinite(Reflect.get(leg, key))))
+            ) &&
+            'containerType' in leg &&
+            (leg.containerType === null ||
+              (typeof leg.containerType === 'string' &&
+                ['FCL_20FT', 'FCL_40FT', 'FCL_40FT_HC', 'LCL'].includes(leg.containerType)))
+        )
+    )
+  );
+}

package/src/movethewheels/utils/freightRecovery.ts

@@ -1,5 +1,8 @@
 import { print } from 'graphql';
-import { SaveFreightCostsDocument } from '../../generated/freight-cost-operations';
+import {
+  SaveFreightCostsDocument,
+  SaveFreightCommercialCostsDocument,
+} from '../../generated/freight-cost-operations';
 import type { ReuseRecovery } from './reuseRecovery';
 export const FREIGHT_RECOVERY_STORAGE = 'movethewheels.freight.unresolved.v1';
 export function decodeFreightRecovery(raw: string | null): ReuseRecovery | null {
@@ -14,7 +17,8 @@ export function decodeFreightRecovery(raw: string | null): ReuseRecovery | null
       !('scope' in value) ||
       !('input' in value) ||
       !('operation' in value) ||
-      value.operation !== print(SaveFreightCostsDocument) ||
+      (value.operation !== print(SaveFreightCostsDocument) &&
+        value.operation !== print(SaveFreightCommercialCostsDocument)) ||
       !('key' in value) ||
       typeof value.key !== 'string' ||
       !value.key ||