@burdenoff/microfe-movethewheels 2026.1016.2 → 2026.1016.4

package/src/movethewheels/components/freight-cost/FreightCommercialHistory.tsx

@@ -0,0 +1,90 @@
+import type { FreightCommercialVersionQuery } from '../../../generated/freight-cost-operations';
+import { commercialSlots } from '../../utils/freightCommercial';
+import { freightLabel } from '../../utils/freightDraft';
+
+export function FreightCommercialHistory({
+  capture,
+}: {
+  capture: FreightCommercialVersionQuery['mtwFreightEstimateVersion']['commercialCapture'];
+}) {
+  if (capture === undefined)
+    return <p role="alert">Commercial context is unavailable in this reply.</p>;
+  if (capture === null) return <p>Commercial context was not captured with this version.</p>;
+  return (
+    <section className="min-w-0 space-y-4 break-words rounded border p-4">
+      <h3 className="font-semibold">
+        Recorded commercial context — schema {capture.schemaVersion}
+      </h3>
+      <p className="text-sm">
+        These are source declarations, not quote acceptance, verified authority or a complete
+        commercial checklist.
+      </p>
+      <div className="grid min-w-0 gap-3 md:grid-cols-2">
+        {commercialSlots.map((slot) => {
+          const fact = capture[slot];
+          return (
+            <article key={slot} className="space-y-2 rounded border p-3">
+              <h4 className="font-medium">
+                {freightLabel(slot)} — {freightLabel(fact.status)}
+              </h4>
+              {fact.reason && <p>{fact.reason}</p>}
+              {typeof fact.value === 'string' ? (
+                <p>{fact.value}</p>
+              ) : (
+                fact.value && (
+                  <dl>
+                    {Object.entries(fact.value)
+                      .filter(([key]) => key !== '__typename')
+                      .map(([key, value]) => (
+                        <div key={key}>
+                          <dt className="inline font-medium">{key}: </dt>
+                          <dd className="inline">
+                            {value === null || value === undefined ? 'Not recorded' : String(value)}
+                          </dd>
+                        </div>
+                      ))}
+                  </dl>
+                )
+              )}
+              {fact.provenance && (
+                <div className="text-sm">
+                  <p>
+                    Declared source {fact.provenance.sourceReference} /{' '}
+                    {fact.provenance.sourceRevision}; observed{' '}
+                    {fact.provenance.observedAt ?? 'Unknown'}.
+                  </p>
+                  {fact.provenance.evidenceLinks.map((link) => (
+                    <p key={JSON.stringify([link.fileId, link.versionId])}>
+                      Exact Files link: {link.fileId}; version {link.versionId}.
+                    </p>
+                  ))}
+                </div>
+              )}
+            </article>
+          );
+        })}
+      </div>
+      <section className="space-y-2">
+        <h4 className="font-medium">
+          Server-recorded owner context (separate from declared facts)
+        </h4>
+        <p>
+          Shipment {capture.ownerShipment.shipmentId}; revision at {capture.ownerShipment.updatedAt}
+          ; mode {capture.ownerShipment.primaryMode}.
+        </p>
+        {capture.ownerLegs.length === 0 && (
+          <p>No legs selected for this capture. This does not mean the shipment has no legs.</p>
+        )}
+        {capture.ownerLegs.map((leg) => (
+          <p key={leg.id}>
+            Leg {leg.legNumber} ({leg.id}) / {leg.mode}; revision {leg.updatedAt}; carrier{' '}
+            {leg.carrierName ?? 'Not recorded'} ({leg.carrierId ?? 'No carrier reference'}); weight{' '}
+            {leg.weightKg ?? 'Not recorded'} kg; volume {leg.volumeCbm ?? 'Not recorded'} m³;
+            equipment {leg.containerType ?? 'Not recorded'} × {leg.containerCount ?? 'Not recorded'}
+            .
+          </p>
+        ))}
+      </section>
+    </section>
+  );
+}

package/src/movethewheels/components/freight-cost/FreightDraftForm.tsx

@@ -1,4 +1,7 @@
 import { useRef, useState } from 'react';
+import type { CommercialCapture, CommercialEditorState } from '../../utils/freightCommercial';
+import { commercialCaptureInput, commercialCanonical } from '../../utils/freightCommercial';
+import { FreightCommercialEditor } from './FreightCommercialEditor';
 import type {
   MtwFreightFactsInput,
   PreviewFreightCostsQuery,
@@ -18,15 +21,22 @@ import {
 } from '../../utils/freightDraft';
 export function FreightDraftForm({
   disabled,
+  shipmentId,
   onPreview,
   onSave,
 }: {
   disabled: boolean;
+  shipmentId: string;
   onPreview: (
     facts: MtwFreightFactsInput
   ) => Promise<PreviewFreightCostsQuery['previewMtwFreightTotal']>;
-  onSave: (facts: MtwFreightFactsInput, evidence: SelectedEvidence[]) => Promise<void>;
+  onSave: (
+    facts: MtwFreightFactsInput,
+    evidence: SelectedEvidence[],
+    commercialCapture?: CommercialCapture
+  ) => Promise<void>;
 }) {
+  const [commercial, setCommercial] = useState<CommercialEditorState | null>(null);
   const [facts, setFacts] = useState(newFreightFacts);
   const [evidence, setEvidence] = useState<SelectedEvidence[]>([]);
   const [preview, setPreview] = useState<{
@@ -65,9 +75,22 @@ export function FreightDraftForm({
           return;
         }
         setError(null);
-        void onSave(structuredClone(facts), structuredClone(evidence)).catch((failure) =>
-          setError(failure instanceof Error ? failure.message : 'Unable to save this cost record.')
-        );
+        try {
+          if (commercial && commercial.reviewed !== commercialCanonical(commercial.selectedLegs))
+            throw new Error('Explicitly review the commercial leg selection before saving.');
+          const capture = commercial
+            ? commercialCaptureInput(commercial.facts, commercial.selectedLegs, evidence)
+            : undefined;
+          void onSave(structuredClone(facts), structuredClone(evidence), capture).catch((failure) =>
+            setError(
+              failure instanceof Error ? failure.message : 'Unable to save this cost record.'
+            )
+          );
+        } catch (failure) {
+          setError(
+            failure instanceof Error ? failure.message : 'Review commercial facts before saving.'
+          );
+        }
       }}
     >
       <fieldset disabled={disabled || previewing} className="space-y-5">
@@ -194,6 +217,12 @@ export function FreightDraftForm({
           )}
           <FreightFxEditor value={facts.fx} onChange={(fx) => patch({ fx })} />
         </details>
+        <FreightCommercialEditor
+          value={commercial}
+          onChange={setCommercial}
+          shipmentId={shipmentId}
+          evidence={evidence}
+        />
         <ContainerEvidencePicker
           value={evidence}
           onChange={setEvidence}

package/src/movethewheels/components/freight-cost/FreightHistory.tsx

@@ -1,10 +1,11 @@
-import type { FreightVersionQuery } from '../../../generated/freight-cost-operations';
+import { FreightCommercialHistory } from './FreightCommercialHistory';
+import type { FreightCommercialVersionQuery } from '../../../generated/freight-cost-operations';
 import { FreightTotals } from './FreightTotals';
 import { freightLabel, freightMoney } from '../../utils/freightDraft';
 export function FreightHistory({
   record,
 }: {
-  record: FreightVersionQuery['mtwFreightEstimateVersion'];
+  record: FreightCommercialVersionQuery['mtwFreightEstimateVersion'];
 }) {
   return (
     <article className="min-w-0 space-y-4 break-words rounded border p-4">
@@ -28,6 +29,7 @@ export function FreightHistory({
         Price at {record.facts.pricingAt}; recorded {record.recordedAt} by {record.createdBy} (
         {freightLabel(record.actorProvenance)}).
       </p>
+      <FreightCommercialHistory capture={record.commercialCapture} />
       <FreightTotals value={record.totals} currency={record.facts.reportingCurrency} />
       <details>
         <summary className="min-h-11 cursor-pointer font-medium">

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

@@ -0,0 +1,412 @@
+import { useEffect, useRef, useState } from 'react';
+import type {
+  CompareMtwFreightInvoiceInput,
+  InvoiceEstimatePinFragment,
+  InvoiceEstimateVersionQuery,
+  InvoiceReceiptFragment,
+  InvoiceStructuralPreviewQuery,
+  MtwFreightInvoiceFactsInput,
+} from '../../../generated/freight-invoice-operations';
+import { ContainerEvidencePicker, type SelectedEvidence } from '../ContainerEvidencePicker';
+import { Button } from '../ui';
+import { FreightCurrency, FreightSelect, FreightText } from '../freight-cost/FreightFields';
+import {
+  invoiceCanonical,
+  invoiceFactsInput,
+  matchesInvoicePreview,
+} from '../../utils/invoiceComparison';
+import { fixedFreightMinor, freightMoney } from '../../utils/freightDraft';
+import { InvoiceResults } from './InvoiceResults';
+
+export type InvoiceEstimate = InvoiceEstimateVersionQuery['mtwFreightEstimateVersion'];
+function blankFacts(): MtwFreightInvoiceFactsInput {
+  return {
+    schemaVersion: 1,
+    supplierReference: null,
+    supplierLabel: null,
+    invoiceReference: null,
+    sourceReference: '',
+    sourceRevision: '',
+    invoiceDate: null,
+    currency: { code: '', minorUnitDigits: 2 },
+    rows: [
+      {
+        id: crypto.randomUUID(),
+        description: '',
+        estimateLineId: null,
+        currency: { code: '', minorUnitDigits: 2 },
+        payerReference: null,
+        payerLabel: null,
+        quantity: null,
+        unit: null,
+        unitRateMajor: null,
+        amountMinor: null,
+        zeroReason: null,
+      },
+    ],
+  };
+}
+export function invoiceEstimatePin(estimate: InvoiceEstimate): InvoiceEstimatePinFragment {
+  return {
+    id: estimate.id,
+    estimateReference: estimate.estimateReference,
+    version: estimate.version,
+    kind: estimate.facts.kind,
+    sourceReference: estimate.facts.sourceReference,
+    sourceRevision: estimate.facts.sourceRevision,
+    quotedAt: estimate.facts.quotedAt,
+    validFrom: estimate.facts.validFrom,
+    validUntil: estimate.facts.validUntil,
+    acceptance: 'NOT_ESTABLISHED',
+  };
+}
+export function InvoiceForm({
+  estimate,
+  previous,
+  disabled,
+  canRecord,
+  onPreview,
+  onSave,
+}: {
+  estimate: InvoiceEstimate;
+  previous: InvoiceReceiptFragment | null;
+  disabled: boolean;
+  canRecord: boolean;
+  onPreview: (input: {
+    shipmentId: string;
+    estimateVersionId: string;
+    facts: MtwFreightInvoiceFactsInput;
+    evidence: { fileId: string; versionId: string }[];
+  }) => Promise<InvoiceStructuralPreviewQuery['previewMtwFreightInvoice']>;
+  onSave: (
+    input: Omit<CompareMtwFreightInvoiceInput, 'idempotencyKey'>,
+    pin: InvoiceEstimatePinFragment
+  ) => Promise<InvoiceReceiptFragment | null | undefined>;
+}) {
+  const [facts, setFacts] = useState<MtwFreightInvoiceFactsInput>(() =>
+      previous ? structuredClone(previous.facts) : blankFacts()
+    ),
+    [evidence, setEvidence] = useState<SelectedEvidence[]>([]),
+    [reason, setReason] = useState('');
+  const [preview, setPreview] = useState<{
+      body: string;
+      value: InvoiceStructuralPreviewQuery['previewMtwFreightInvoice'];
+    } | null>(null),
+    [error, setError] = useState<string | null>(null),
+    [previewing, setPreviewing] = useState(false);
+  const form = useRef<HTMLFormElement | null>(null);
+  const alive = useRef(true),
+    running = useRef(false);
+  useEffect(() => {
+    alive.current = true;
+    return () => {
+      alive.current = false;
+    };
+  }, []);
+  // The owning workbench is keyed by canonical context; no old draft is rebound to a new owner.
+  const body = invoiceCanonical({
+    facts,
+    evidence: evidence.map(({ fileId, versionId }) => ({ fileId, versionId })),
+    estimateId: estimate.id,
+  });
+  const current = preview?.body === body ? preview.value : null;
+  const patch = (v: Partial<MtwFreightInvoiceFactsInput>) => setFacts({ ...facts, ...v });
+  const changeRow = (id: string, v: Partial<MtwFreightInvoiceFactsInput['rows'][number]>) =>
+    patch({ rows: facts.rows.map((r) => (r.id === id ? { ...r, ...v } : r)) });
+  const previewNow = async () => {
+    if (running.current || disabled || !form.current?.reportValidity()) return;
+    running.current = true;
+    setPreviewing(true);
+    setError(null);
+    const original = body;
+    try {
+      const normalized = invoiceFactsInput(facts),
+        value = await onPreview({
+          shipmentId: estimate.shipmentId,
+          estimateVersionId: estimate.id,
+          facts: normalized,
+          evidence: evidence.map(({ fileId, versionId }) => ({ fileId, versionId })),
+        });
+      if (!matchesInvoicePreview(value, normalized, invoiceEstimatePin(estimate)))
+        throw new Error(
+          'The preview did not match these reported facts and exact estimate. Nothing was sent.'
+        );
+      if (alive.current) setPreview({ body: original, value });
+    } catch (failure) {
+      if (alive.current)
+        setError(
+          failure instanceof Error ? failure.message : 'Unable to preview the reported facts.'
+        );
+    } finally {
+      running.current = false;
+      if (alive.current) setPreviewing(false);
+    }
+  };
+  return (
+    <form
+      ref={form}
+      className="min-w-0 space-y-5"
+      aria-label="Manual invoice comparison"
+      onSubmit={(event) => {
+        event.preventDefault();
+        if (!current || current.recordable !== true || disabled || !canRecord || running.current)
+          return;
+        setError(null);
+        try {
+          const normalized = invoiceFactsInput(facts);
+          void onSave(
+            {
+              shipmentId: estimate.shipmentId,
+              estimateVersionId: estimate.id,
+              facts: normalized,
+              evidence: evidence.map(({ fileId, versionId }) => ({ fileId, versionId })),
+              expectedRevision: previous?.revision ?? 0,
+              expectedPreviousComparisonId: previous?.id ?? null,
+              correctionReason: previous ? reason.trim() || null : null,
+            },
+            invoiceEstimatePin(estimate)
+          ).catch(() =>
+            setError('The original request remains retained; inspect read-only recovery.')
+          );
+        } catch (failure) {
+          setError(
+            failure instanceof Error
+              ? failure.message
+              : 'Review the reported source fields. Nothing was sent.'
+          );
+        }
+      }}
+    >
+      <fieldset disabled={disabled || previewing} className="min-w-0 space-y-5">
+        <legend className="text-lg font-semibold">
+          {previous ? 'Append an immutable correction' : 'Reported supplier invoice'}
+        </legend>
+        <p>
+          Blank means unknown, never zero. This is a manual comparison, not approval or payment. No
+          FX, credits or split allocation.
+        </p>
+        <p>
+          Exact pinned {estimate.facts.kind.toLowerCase()}: {estimate.estimateReference} / version{' '}
+          {estimate.version}; {estimate.facts.title}. Source validity: {estimate.validityAtRead}.
+          Acceptance is not established.
+        </p>
+        <div className="grid min-w-0 gap-3 md:grid-cols-2">
+          <FreightText
+            label="Supplier source reference"
+            value={facts.supplierReference ?? ''}
+            disabled={!!previous}
+            onChange={(supplierReference) => patch({ supplierReference })}
+          />
+          <FreightText
+            label="Supplier label"
+            value={facts.supplierLabel ?? ''}
+            onChange={(supplierLabel) => patch({ supplierLabel })}
+          />
+          <FreightText
+            label="Invoice reference"
+            value={facts.invoiceReference ?? ''}
+            disabled={!!previous}
+            onChange={(invoiceReference) => patch({ invoiceReference })}
+          />
+          <FreightText
+            label="Invoice source reference"
+            value={facts.sourceReference}
+            required
+            onChange={(sourceReference) => patch({ sourceReference })}
+          />
+          <FreightText
+            label="Invoice source revision"
+            value={facts.sourceRevision}
+            required
+            onChange={(sourceRevision) => patch({ sourceRevision })}
+          />
+          <FreightText
+            label="Invoice source date (optional)"
+            type="date"
+            value={facts.invoiceDate ?? ''}
+            onChange={(invoiceDate) => patch({ invoiceDate: invoiceDate || null })}
+          />
+        </div>
+        <FreightCurrency
+          label="Invoice currency"
+          value={facts.currency}
+          onChange={(currency) =>
+            patch({
+              currency,
+              rows: facts.rows.map((r) => ({
+                ...r,
+                currency,
+                amountMinor: null,
+                zeroReason: null,
+              })),
+            })
+          }
+        />
+        {facts.rows.map((row, index) => (
+          <fieldset key={row.id} className="min-w-0 space-y-3 rounded border p-3">
+            <legend className="font-semibold">Reported row {index + 1}</legend>
+            <FreightText
+              label={`Row ${index + 1} description`}
+              value={row.description}
+              required
+              onChange={(description) => changeRow(row.id, { description })}
+            />
+            <FreightSelect
+              label={`Row ${index + 1} exact estimate mapping`}
+              value={row.estimateLineId ?? ''}
+              onChange={(estimateLineId) =>
+                changeRow(row.id, { estimateLineId: estimateLineId || null })
+              }
+            >
+              <option value="">Unmatched invoice row</option>
+              {estimate.facts.lines.map((line) => (
+                <option key={line.id} value={line.id}>
+                  {line.description} / {line.id} / {line.disposition}
+                </option>
+              ))}
+            </FreightSelect>
+            <div className="grid min-w-0 gap-3 md:grid-cols-2">
+              <FreightText
+                label={`Row ${index + 1} payer source reference`}
+                value={row.payerReference ?? ''}
+                onChange={(payerReference) => changeRow(row.id, { payerReference })}
+              />
+              <FreightText
+                label={`Row ${index + 1} payer label`}
+                value={row.payerLabel ?? ''}
+                onChange={(payerLabel) => changeRow(row.id, { payerLabel })}
+              />
+              <label className="block text-sm">
+                Row {index + 1} supplied amount ({row.currency.code || 'declare currency'})
+                <input
+                  key={`${row.currency.code}:${row.currency.minorUnitDigits}`}
+                  className="mt-1 min-h-11 w-full rounded border p-2"
+                  aria-label={`Row ${index + 1} supplied amount`}
+                  inputMode="decimal"
+                  defaultValue={
+                    row.amountMinor == null
+                      ? ''
+                      : freightMoney(row.amountMinor, row.currency.minorUnitDigits)
+                  }
+                  onChange={(event) => {
+                    try {
+                      changeRow(row.id, {
+                        amountMinor: fixedFreightMinor(
+                          event.target.value,
+                          row.currency.minorUnitDigits
+                        ),
+                      });
+                      event.target.setCustomValidity('');
+                    } catch (failure) {
+                      changeRow(row.id, { amountMinor: null });
+                      event.target.setCustomValidity(
+                        failure instanceof Error ? failure.message : 'Invalid sourced amount.'
+                      );
+                    }
+                  }}
+                />
+              </label>
+              <FreightText
+                label={`Row ${index + 1} zero source reason`}
+                value={row.zeroReason ?? ''}
+                onChange={(zeroReason) => changeRow(row.id, { zeroReason })}
+              />
+              <FreightText
+                label={`Row ${index + 1} supplied quantity`}
+                value={row.quantity ?? ''}
+                onChange={(quantity) => changeRow(row.id, { quantity })}
+              />
+              <FreightText
+                label={`Row ${index + 1} explicit unit`}
+                value={row.unit ?? ''}
+                onChange={(unit) => changeRow(row.id, { unit })}
+              />
+              <FreightText
+                label={`Row ${index + 1} supplied unit rate`}
+                value={row.unitRateMajor ?? ''}
+                onChange={(unitRateMajor) => changeRow(row.id, { unitRateMajor })}
+              />
+            </div>
+            <p>
+              {facts.currency.code || 'currency unknown'} / decimal places{' '}
+              {facts.currency.minorUnitDigits}. Amount stays as supplied, not quantity × rate.
+            </p>
+            <Button
+              type="button"
+              variant="outline"
+              disabled={facts.rows.length === 1}
+              onClick={() => patch({ rows: facts.rows.filter((r) => r.id !== row.id) })}
+            >
+              Remove row {index + 1}
+            </Button>
+          </fieldset>
+        ))}
+        <Button
+          type="button"
+          variant="outline"
+          disabled={facts.rows.length >= 100}
+          onClick={() =>
+            patch({
+              rows: [
+                ...facts.rows,
+                {
+                  id: crypto.randomUUID(),
+                  description: '',
+                  estimateLineId: null,
+                  currency: { ...facts.currency },
+                  payerReference: null,
+                  payerLabel: null,
+                  quantity: null,
+                  unit: null,
+                  unitRateMajor: null,
+                  amountMinor: null,
+                  zeroReason: null,
+                },
+              ],
+            })
+          }
+        >
+          Add reported row
+        </Button>
+        <ContainerEvidencePicker
+          currentOnly
+          value={evidence}
+          onChange={setEvidence}
+          description="Choose current readable ACTIVE Files versions with an integrity fingerprint. The server rechecks eligibility when recording; no binary is uploaded here."
+        />
+        {previous && (
+          <FreightText
+            label="Correction source reason"
+            value={reason}
+            required={false}
+            onChange={setReason}
+          />
+        )}
+        <div className="flex flex-wrap gap-3">
+          <Button type="button" variant="outline" onClick={() => void previewNow()}>
+            Preview reported comparison
+          </Button>
+          <Button
+            type="submit"
+            disabled={
+              !canRecord ||
+              current?.recordable !== true ||
+              !evidence.length ||
+              (!!previous && !reason.trim())
+            }
+          >
+            Record immutable comparison
+          </Button>
+        </div>
+      </fieldset>
+      {!canRecord && (
+        <p>
+          Shipment update permission is required to record; structural preview remains read-only.
+        </p>
+      )}
+      {previewing && <p role="status">Comparing the exact recorded facts…</p>}
+      {error && <p role="alert">{error}</p>}
+      {current && <InvoiceResults value={current} />}
+    </form>
+  );
+}