@burdenoff/microfe-movethewheels 2026.930.5 → 2026.1010.1

package/src/movethewheels/components/consolidation/ConsolidationHistory.tsx

@@ -0,0 +1,159 @@
+import type {
+  ConsolidationObservationsQuery,
+  ConsolidationManifestQuery,
+  ConsolidationPlanQuery,
+} from '../../../generated/consolidation-operations';
+import { ProcedureTime as Time } from '../logistics-procedure/ProcedureFields';
+import { ConsolidationSummary } from './ConsolidationSummary';
+export function ConsolidationPlanHistory({
+  plan,
+}: {
+  plan: ConsolidationPlanQuery['mtwConsolidationPlan'];
+}) {
+  return (
+    <section className="space-y-3 rounded-lg border p-4">
+      <h3>
+        {plan.planReference} · version {plan.version} · {plan.facts.hubName}
+      </h3>
+      <p>
+        Effective <Time value={plan.facts.effectiveAt} /> · recorded{' '}
+        <Time value={plan.recordedAt} />
+      </p>
+      <p>
+        Captured shipment {plan.sourceCapture.shipmentNumber}; booking{' '}
+        {plan.sourceCapture.bookingReference ?? 'Unknown'}
+      </p>
+      {plan.facts.lots.map((lot) => (
+        <article key={lot.id} className="break-words border-t pt-2">
+          <h4>
+            {lot.supplierReference} · {lot.lotReference} · {lot.consignmentReference}
+          </h4>
+          <p>
+            Planned {lot.plannedQuantity ?? 'Unknown'} / available{' '}
+            {lot.reportedAvailableQuantity ?? 'Unknown'} {lot.unitReference ?? '(unit unknown)'}
+          </p>
+          <p>
+            Basis: {lot.quantityBasis.toLowerCase().replaceAll('_', ' ')}; unit revision{' '}
+            {lot.unitRevision ?? 'Unknown'}; balance revision {lot.balanceRevision ?? 'Unknown'}
+          </p>
+          <p>
+            Source {lot.source.reference ?? 'Unknown'} / {lot.source.revision ?? 'Unknown'}
+          </p>
+        </article>
+      ))}
+      <details>
+        <summary>Captured source and audit references</summary>
+        <p className="break-all">
+          {plan.id}; predecessor {plan.previousVersionId ?? 'None'}
+        </p>
+        <p>
+          Hub source {plan.facts.hubSource.reference ?? 'Unknown'} /{' '}
+          {plan.facts.hubSource.revision ?? 'Unknown'}
+        </p>
+        <p>
+          Context source {plan.facts.contextSource.reference ?? 'Unknown'} /{' '}
+          {plan.facts.contextSource.revision ?? 'Unknown'}
+        </p>
+        <p>
+          Mode {plan.facts.mode ?? 'Unknown'}; carrier {plan.facts.carrierReference ?? 'Unknown'};
+          declared booking {plan.facts.bookingReference ?? 'Unknown'}
+        </p>
+        <p>
+          Cutoff <Time value={plan.facts.cutoffAt} />; timezone {plan.facts.timezone ?? 'Unknown'};
+          jurisdiction {plan.facts.jurisdictionReference ?? 'Unknown'}
+        </p>
+        <p>
+          Recorded by {plan.createdBy} · {plan.actorProvenance}; on behalf of{' '}
+          {plan.onBehalfOf ?? 'Not supplied'}
+        </p>
+        {plan.evidence.map((row) => (
+          <p className="break-all" key={JSON.stringify([row.fileId, row.versionId])}>
+            {row.fileId} / {row.versionId} · checked <Time value={row.checkedAt} />
+          </p>
+        ))}
+      </details>
+    </section>
+  );
+}
+export function ConsolidationReportHistory({
+  rows,
+  labels,
+}: {
+  rows: ConsolidationObservationsQuery['mtwConsolidationObservationPage']['items'];
+  labels: Record<string, string>;
+}) {
+  return (
+    <section className="space-y-3">
+      <h3 className="font-semibold">Append-only report history</h3>
+      {rows.map((row) => (
+        <article key={row.id} className="min-w-0 space-y-1 rounded-lg border p-3">
+          <h4>
+            {labels[row.lotId] ?? 'Captured lot'} ·{' '}
+            {row.kind === 'ISSUE'
+              ? 'Unresolved reported issue'
+              : row.kind === 'RECEIPT_REPORT'
+                ? 'Receipt total'
+                : 'Stuffing total'}{' '}
+            · version {row.version}
+          </h4>
+          <p>
+            {row.kind === 'ISSUE'
+              ? row.issueReference
+              : (row.reportedQuantity ?? 'Unknown quantity')}{' '}
+            {row.unitReference ?? '(unit unknown)'}
+          </p>
+          <p className="break-words">{row.reason}</p>
+          <p>
+            Observed <Time value={row.reportedObservedAt} /> · recorded{' '}
+            <Time value={row.recordedAt} /> · receipt sequence {row.receiptSequence}
+          </p>
+          <details>
+            <summary>Source and original attribution</summary>
+            <p>
+              {row.source.reference ?? 'Unknown'} / {row.source.revision ?? 'Unknown'}
+            </p>
+            <p className="break-all">
+              {row.id}; predecessor {row.previousVersionId ?? 'None'}; recorded by {row.createdBy} ·{' '}
+              {row.actorProvenance}; on behalf of {row.onBehalfOf ?? 'Not supplied'}
+            </p>
+            {row.evidence.map((e) => (
+              <p className="break-all" key={JSON.stringify([e.fileId, e.versionId])}>
+                Checked evidence {e.fileId} / {e.versionId}
+              </p>
+            ))}
+            {row.evidenceDeclarations.map((e) => (
+              <p className="break-all" key={JSON.stringify([e.fileId, e.versionId])}>
+                Unverified declaration {e.fileId} / {e.versionId}
+              </p>
+            ))}
+          </details>
+        </article>
+      ))}
+    </section>
+  );
+}
+export function ConsolidationManifestHistory({
+  manifest,
+  labels,
+}: {
+  manifest: ConsolidationManifestQuery['mtwConsolidationManifest'];
+  labels: Record<string, string>;
+}) {
+  return (
+    <section className="space-y-3 rounded-lg border p-4">
+      <h3>Immutable manifest record · version {manifest.version}</h3>
+      <p>
+        Recorded <Time value={manifest.recordedAt} /> · by {manifest.createdBy} ·{' '}
+        {manifest.actorProvenance}
+      </p>
+      <ConsolidationSummary snapshot={manifest.snapshot} labels={labels} />
+      <details>
+        <summary>Exact historical references</summary>
+        <p className="break-all">
+          {manifest.id}; predecessor {manifest.previousVersionId ?? 'None'}; plan {manifest.planId};
+          recorded on behalf of {manifest.onBehalfOf ?? 'Not supplied'}
+        </p>
+      </details>
+    </section>
+  );
+}

package/src/movethewheels/components/consolidation/ConsolidationLotEditor.tsx

@@ -0,0 +1,144 @@
+import type { MtwConsolidationLotInput } from '../../../generated/consolidation-operations';
+import {
+  ProcedureField as Field,
+  ProcedureGroup as Group,
+} from '../logistics-procedure/ProcedureFields';
+import { reuseSelect } from '../ReuseControls';
+export function ConsolidationLotEditor({
+  lot,
+  onChange,
+}: {
+  lot: MtwConsolidationLotInput;
+  onChange: (lot: MtwConsolidationLotInput) => void;
+}) {
+  const set = (key: keyof MtwConsolidationLotInput, value: string) =>
+    onChange({ ...lot, [key]: value || null });
+  return (
+    <Group title="Supplier lot">
+      <div className="grid gap-3 sm:grid-cols-2">
+        {(
+          ['supplierReference', 'lotReference', 'consignmentReference', 'sourceRevision'] as const
+        ).map((key) => (
+          <Field
+            key={key}
+            label={
+              {
+                supplierReference: 'Supplier reference',
+                lotReference: 'Lot reference',
+                consignmentReference: 'Consignment reference',
+                sourceRevision: 'Lot source revision',
+              }[key]
+            }
+            value={lot[key]}
+            onChange={(value) => set(key, value)}
+          />
+        ))}
+      </div>
+      <label className="block">
+        Quantity basis
+        <select
+          className={reuseSelect}
+          value={lot.quantityBasis}
+          onChange={(event) =>
+            onChange({
+              ...lot,
+              quantityBasis:
+                event.target.value === 'SOURCE_DECLARATION'
+                  ? 'SOURCE_DECLARATION'
+                  : event.target.value === 'HUB_REPORT'
+                    ? 'HUB_REPORT'
+                    : 'UNKNOWN',
+            })
+          }
+        >
+          <option value="UNKNOWN">Unknown</option>
+          <option value="SOURCE_DECLARATION">Supplier declaration</option>
+          <option value="HUB_REPORT">Reported at hub</option>
+        </select>
+      </label>
+      <p>
+        Blank quantities are unknown. Zero means an explicitly reported zero. No unit conversion is
+        inferred.
+      </p>
+      <div className="grid gap-3 sm:grid-cols-2">
+        {(
+          [
+            'unitReference',
+            'unitRevision',
+            'balanceRevision',
+            'plannedQuantity',
+            'reportedAvailableQuantity',
+          ] as const
+        ).map((key) => (
+          <Field
+            key={key}
+            required={false}
+            label={
+              {
+                unitReference: 'Reported count unit',
+                unitRevision: 'Unit source revision',
+                balanceRevision: 'Balance source revision',
+                plannedQuantity: 'Planned quantity',
+                reportedAvailableQuantity: 'Reported available quantity',
+              }[key]
+            }
+            value={lot[key] ?? ''}
+            onChange={(value) => set(key, value)}
+          />
+        ))}
+      </div>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <Field
+          required={false}
+          label="Quantity source reference"
+          value={lot.source.reference ?? ''}
+          onChange={(value) =>
+            onChange({ ...lot, source: { ...lot.source, reference: value || null } })
+          }
+        />
+        <Field
+          required={false}
+          label="Quantity source revision"
+          value={lot.source.revision ?? ''}
+          onChange={(value) =>
+            onChange({ ...lot, source: { ...lot.source, revision: value || null } })
+          }
+        />
+      </div>
+      <details>
+        <summary>Mass, volume and transport context</summary>
+        <div className="grid gap-3 sm:grid-cols-2">
+          {(
+            [
+              'grossKg',
+              'cubeM3',
+              'originReference',
+              'destinationReference',
+              'importerReference',
+              'transportReference',
+              'documentReference',
+            ] as const
+          ).map((key) => (
+            <Field
+              key={key}
+              required={false}
+              label={
+                {
+                  grossKg: 'Reported gross mass (kg)',
+                  cubeM3: 'Reported volume (m³)',
+                  originReference: 'Origin reference',
+                  destinationReference: 'Destination reference',
+                  importerReference: 'Importer reference',
+                  transportReference: 'Transport reference',
+                  documentReference: 'Document reference',
+                }[key]
+              }
+              value={lot[key] ?? ''}
+              onChange={(value) => set(key, value)}
+            />
+          ))}
+        </div>
+      </details>
+    </Group>
+  );
+}

package/src/movethewheels/components/consolidation/ConsolidationManifestWorkbench.tsx

@@ -0,0 +1,168 @@
+import { useEffect, useRef, useState } from 'react';
+import {
+  ConsolidationObservationsDocument,
+  ConsolidationPreviewDocument,
+  ConsolidationManifestsDocument,
+  ConsolidationManifestDocument,
+  SaveConsolidationManifestDocument,
+  type ConsolidationObservationsQuery,
+  type ConsolidationPreviewQuery,
+  type ConsolidationManifestsQuery,
+  type ConsolidationManifestQuery,
+  type ConsolidationPlanQuery,
+} from '../../../generated/consolidation-operations';
+import { useConditionApi, useConditionQuery } from '../../hooks/useContainerCondition';
+import type { useConsolidationAction } from '../../hooks/useConsolidationAction';
+import { assertConsolidationPredecessor } from '../../utils/consolidationPins';
+import { ConsolidationSummary } from './ConsolidationSummary';
+import { ConsolidationManifestHistory } from './ConsolidationHistory';
+import { Button } from '../ui';
+import { ReusePager, ReuseState, reuseCard } from '../ReuseControls';
+export function ConsolidationManifestWorkbench({
+  plan,
+  actions,
+  labels,
+}: {
+  plan: ConsolidationPlanQuery['mtwConsolidationPlan'];
+  actions: ReturnType<typeof useConsolidationAction>;
+  labels: Record<string, string>;
+}) {
+  const request = useConditionApi(),
+    active = useRef(true);
+  useEffect(() => {
+    active.current = true;
+    return () => {
+      active.current = false;
+    };
+  }, []);
+  const [preview, setPreview] = useState<{
+      snapshot: ConsolidationPreviewQuery['previewMtwConsolidationManifest'];
+      previous: { id: string; version: number } | null;
+    } | null>(null),
+    [checking, setChecking] = useState(false),
+    [error, setError] = useState<string | null>(null),
+    [offset, setOffset] = useState(0),
+    [selected, setSelected] = useState('');
+  const history = useConditionQuery<ConsolidationManifestsQuery>(
+      ConsolidationManifestsDocument,
+      { planId: plan.id, pagination: { limit: 10, offset } },
+      actions.revision
+    ),
+    exact = useConditionQuery<ConsolidationManifestQuery>(
+      ConsolidationManifestDocument,
+      selected ? { planId: plan.id, id: selected } : null,
+      actions.revision
+    ),
+    paused = checking || actions.busy || actions.uncertain;
+  const current = async () => {
+    const [observations, manifests] = await Promise.all([
+      request<ConsolidationObservationsQuery>(ConsolidationObservationsDocument, {
+        planId: plan.id,
+        pagination: { limit: 1, offset: 0 },
+      }),
+      request<ConsolidationManifestsQuery>(ConsolidationManifestsDocument, {
+        planId: plan.id,
+        pagination: { limit: 1, offset: 0 },
+      }),
+    ]);
+    return {
+      sequence: observations.mtwConsolidationObservationPage.items[0]?.receiptSequence ?? 0,
+      previous: manifests.mtwConsolidationManifestPage.items[0] ?? null,
+    };
+  };
+  const review = async () => {
+    if (paused) return;
+    setChecking(true);
+    setError(null);
+    try {
+      const pins = await current();
+      const result = await request<ConsolidationPreviewQuery>(ConsolidationPreviewDocument, {
+        planId: plan.id,
+        expectedObservationSequence: pins.sequence,
+      });
+      if (active.current)
+        setPreview({ snapshot: result.previewMtwConsolidationManifest, previous: pins.previous });
+    } catch (f) {
+      setError(f instanceof Error ? f.message : 'Unable to preview.');
+    } finally {
+      setChecking(false);
+    }
+  };
+  const save = async () => {
+    if (!preview || paused) return;
+    setChecking(true);
+    setError(null);
+    try {
+      const pins = await current();
+      if (!active.current) throw new Error('Context changed. Nothing was sent.');
+      if (pins.sequence !== preview.snapshot.observationSequence)
+        throw new Error('New reports were received. Review a fresh preview before recording.');
+      assertConsolidationPredecessor(preview.previous, pins.previous);
+      const result = await actions.run(
+        SaveConsolidationManifestDocument,
+        {
+          planId: plan.id,
+          expectedObservationSequence: preview.snapshot.observationSequence,
+          expectedPreviousVersionId: preview.previous?.id ?? null,
+          expectedVersion: preview.previous?.version ?? 0,
+        },
+        'Immutable manifest record saved.'
+      );
+      if (result) {
+        setPreview(null);
+        setOffset(0);
+      }
+    } catch (f) {
+      setError(f instanceof Error ? f.message : 'Unable to record manifest.');
+    } finally {
+      setChecking(false);
+    }
+  };
+  return (
+    <section className={reuseCard}>
+      <h2 className="text-lg font-semibold">Review and record a manifest</h2>
+      <p>
+        Each record captures the reported quantities at one receipt sequence. Historical records
+        retain their original reports and time; later corrections do not rewrite them.
+      </p>
+      <Button disabled={paused} variant="outline" onClick={() => void review()}>
+        Load current reconciliation preview
+      </Button>
+      {preview && (
+        <>
+          <ConsolidationSummary snapshot={preview.snapshot} labels={labels} />
+          <Button disabled={paused} onClick={() => void save()}>
+            Record this manifest snapshot
+          </Button>
+        </>
+      )}
+      {error && <p role="alert">{error}</p>}
+      <ReuseState loading={history.loading} error={history.error} />
+      <div className="flex flex-wrap gap-2">
+        {history.data?.mtwConsolidationManifestPage.items.map((row) => (
+          <Button
+            key={row.id}
+            disabled={paused}
+            variant="outline"
+            onClick={() => setSelected(row.id)}
+          >
+            Version {row.version} · receipt sequence {row.observationSequence}
+          </Button>
+        ))}
+      </div>
+      <ReusePager
+        offset={offset}
+        page={history.data?.mtwConsolidationManifestPage}
+        busy={paused}
+        onChange={setOffset}
+      />
+      <ReuseState loading={exact.loading} error={exact.error} />
+      {exact.data && (
+        <ConsolidationManifestHistory
+          manifest={exact.data.mtwConsolidationManifest}
+          labels={labels}
+        />
+      )}
+    </section>
+  );
+}

package/src/movethewheels/components/consolidation/ConsolidationPlanForm.tsx

@@ -0,0 +1,185 @@
+import { useState } from 'react';
+import type {
+  SaveMtwConsolidationPlanInput,
+  MtwConsolidationLotInput,
+} from '../../../generated/consolidation-operations';
+import { ContainerEvidencePicker, type SelectedEvidence } from '../ContainerEvidencePicker';
+import {
+  ProcedureField as Field,
+  ProcedureGroup as Group,
+} from '../logistics-procedure/ProcedureFields';
+import {
+  consolidationInstant,
+  consolidationQuantity,
+  nullableText,
+} from '../../utils/consolidationInput';
+import { ConsolidationLotEditor } from './ConsolidationLotEditor';
+import { emptyConsolidationLot } from '../../utils/consolidationLot';
+import { Button } from '../ui';
+export type ConsolidationPlanPin = Omit<
+  SaveMtwConsolidationPlanInput,
+  'facts' | 'evidence' | 'idempotencyKey'
+>;
+export function ConsolidationPlanForm({
+  pin,
+  busy,
+  onSave,
+}: {
+  pin: ConsolidationPlanPin;
+  busy: boolean;
+  onSave: (input: Omit<SaveMtwConsolidationPlanInput, 'idempotencyKey'>) => Promise<void>;
+}) {
+  const [hubName, setHubName] = useState(''),
+    [hubReference, setHubReference] = useState(''),
+    [hubSource, setHubSource] = useState(''),
+    [hubRevision, setHubRevision] = useState(''),
+    [effective, setEffective] = useState(''),
+    [lots, setLots] = useState<MtwConsolidationLotInput[]>(() => [emptyConsolidationLot()]),
+    [evidence, setEvidence] = useState<SelectedEvidence[]>([]),
+    [error, setError] = useState<string | null>(null);
+  const [context, setContext] = useState({
+    mode: '',
+    carrierReference: '',
+    bookingReference: '',
+    cutoffAt: '',
+    timezone: '',
+    jurisdictionReference: '',
+    reference: '',
+    revision: '',
+  });
+  return (
+    <form
+      className="space-y-4"
+      onSubmit={(event) => {
+        event.preventDefault();
+        if (busy) return;
+        setError(null);
+        void (async () => {
+          if (evidence.length < 1 || evidence.length > 10)
+            throw new Error('Choose one to ten exact evidence versions.');
+          const normalized = lots.map((lot) => ({
+            ...lot,
+            plannedQuantity: consolidationQuantity(lot.plannedQuantity ?? ''),
+            reportedAvailableQuantity: consolidationQuantity(lot.reportedAvailableQuantity ?? ''),
+            grossKg: consolidationQuantity(lot.grossKg ?? ''),
+            cubeM3: consolidationQuantity(lot.cubeM3 ?? ''),
+          }));
+          await onSave({
+            ...pin,
+            facts: {
+              hubName: hubName.trim(),
+              hubReference: hubReference.trim(),
+              hubSource: {
+                reference: nullableText(hubSource),
+                revision: nullableText(hubRevision),
+              },
+              effectiveAt: consolidationInstant(effective),
+              lots: normalized,
+              mode: nullableText(context.mode),
+              carrierReference: nullableText(context.carrierReference),
+              bookingReference: nullableText(context.bookingReference),
+              cutoffAt: context.cutoffAt ? consolidationInstant(context.cutoffAt) : null,
+              timezone: nullableText(context.timezone),
+              jurisdictionReference: nullableText(context.jurisdictionReference),
+              contextSource: {
+                reference: nullableText(context.reference),
+                revision: nullableText(context.revision),
+              },
+            },
+            evidence: evidence.map(({ fileId, versionId }) => ({ fileId, versionId })),
+          });
+        })().catch((f) => setError(f instanceof Error ? f.message : 'Unable to record plan.'));
+      }}
+    >
+      <fieldset disabled={busy} className="space-y-4">
+        <Group title="One named hub">
+          <Field label="Hub name" value={hubName} onChange={setHubName} />
+          <Field label="Hub reference" value={hubReference} onChange={setHubReference} />
+          <Field label="Hub source reference" value={hubSource} onChange={setHubSource} />
+          <Field label="Hub source revision" value={hubRevision} onChange={setHubRevision} />
+          <Field
+            label="Effective from (local time)"
+            type="datetime-local"
+            value={effective}
+            onChange={setEffective}
+          />
+          <p>Times are saved as UTC. A future plan does not make its reports effective now.</p>
+        </Group>
+        <p>
+          A new plan version starts separate receipt and stuffing histories. Earlier reports remain
+          attached to their original plan.
+        </p>
+        {lots.map((lot, index) => (
+          <section key={lot.id} className="space-y-2">
+            <ConsolidationLotEditor
+              lot={lot}
+              onChange={(value) =>
+                setLots((rows) => rows.map((row, i) => (i === index ? value : row)))
+              }
+            />
+            <Button
+              type="button"
+              variant="outline"
+              disabled={lots.length === 1}
+              onClick={() => setLots((rows) => rows.filter((_, i) => i !== index))}
+            >
+              Remove lot {index + 1}
+            </Button>
+          </section>
+        ))}
+        <Button
+          type="button"
+          variant="outline"
+          disabled={lots.length >= 20}
+          onClick={() => setLots((rows) => [...rows, emptyConsolidationLot()])}
+        >
+          Add supplier lot ({lots.length}/20)
+        </Button>
+        <details>
+          <summary>Lane, cutoff and document context</summary>
+          <Group title="Declared context">
+            {(
+              [
+                'mode',
+                'carrierReference',
+                'bookingReference',
+                'cutoffAt',
+                'timezone',
+                'jurisdictionReference',
+                'reference',
+                'revision',
+              ] as const
+            ).map((key) => (
+              <Field
+                key={key}
+                required={false}
+                label={
+                  {
+                    mode: 'Transport mode',
+                    carrierReference: 'Carrier reference',
+                    bookingReference: 'Booking reference',
+                    cutoffAt: 'Cutoff (local time)',
+                    timezone: 'Reported timezone',
+                    jurisdictionReference: 'Jurisdiction reference',
+                    reference: 'Context source reference',
+                    revision: 'Context source revision',
+                  }[key]
+                }
+                type={key === 'cutoffAt' ? 'datetime-local' : 'text'}
+                value={context[key]}
+                onChange={(value) => setContext((row) => ({ ...row, [key]: value }))}
+              />
+            ))}
+          </Group>
+        </details>
+        <ContainerEvidencePicker
+          value={evidence}
+          onChange={setEvidence}
+          description="Choose exact readable Files versions supporting these declarations. This does not verify physical stock or approvals."
+        />
+        {error && <p role="alert">{error}</p>}
+        <Button type="submit">Record plan version</Button>
+      </fieldset>
+    </form>
+  );
+}