@burdenoff/microfe-movethewheels 2026.930.5 → 2026.1010.1

package/src/movethewheels/utils/reuseRecovery.ts

@@ -0,0 +1,151 @@
+import { Kind, parse, print, type DocumentNode } from 'graphql';
+import { resolveGraphqlUrl } from './graphqlClient';
+
+export const REUSE_RECOVERY_STORAGE = 'movethewheels.empty-reuse.unresolved.v1';
+const MAX_BYTES = 200_000;
+const operations = new Set([
+  'RecordReturnInstruction',
+  'RecordReuseProposal',
+  'RecordReuseApproval',
+  'AcceptReuseReservation',
+  'TerminateReuseReservation',
+]);
+export interface ReuseRecoveryScope {
+  actorId: string;
+  workspaceId: string;
+  tenantId: string;
+  organizationId: string;
+  gateway: string;
+  projectId: string | null;
+}
+export interface ReuseRecovery {
+  version: 1;
+  scope: ReuseRecoveryScope;
+  operation: string;
+  input: Record<string, unknown>;
+  key: string;
+  success: string;
+}
+function object(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Claims are context comparison metadata only; the gateway remains the authentication authority. */
+export function reuseRecoveryScope(
+  actorId: string | undefined,
+  workspaceId: string | undefined,
+  tenantId: string | undefined,
+  gateway: string | undefined,
+  workspaceToken: string | undefined
+): ReuseRecoveryScope | null {
+  if (!actorId || !workspaceId || !workspaceToken) return null;
+  try {
+    const encoded = workspaceToken.split('.')[1];
+    const claims: unknown = JSON.parse(atob(encoded.replace(/-/g, '+').replace(/_/g, '/')));
+    if (
+      !object(claims) ||
+      claims.sub !== actorId ||
+      claims.workspaceId !== workspaceId ||
+      typeof claims.organizationId !== 'string' ||
+      !claims.organizationId ||
+      !Object.hasOwn(claims, 'projectId')
+    )
+      return null;
+    const project = claims.projectId;
+    if (project !== null && project !== undefined && typeof project !== 'string') return null;
+    return {
+      actorId,
+      workspaceId,
+      tenantId: tenantId ?? '',
+      organizationId: claims.organizationId,
+      gateway: resolveGraphqlUrl(gateway),
+      projectId: project ?? null,
+    };
+  } catch {
+    return null;
+  }
+}
+/** Stable across token renewal; changing an owner/project context resets unsent forms. */
+export function reuseRecoveryContextKey(scope: ReuseRecoveryScope | null): string {
+  return JSON.stringify(scope);
+}
+export function sameReuseRecoveryScope(
+  a: ReuseRecoveryScope,
+  b: ReuseRecoveryScope | null
+): boolean {
+  return (
+    b !== null &&
+    a.actorId === b.actorId &&
+    a.workspaceId === b.workspaceId &&
+    a.tenantId === b.tenantId &&
+    a.organizationId === b.organizationId &&
+    a.gateway === b.gateway &&
+    a.projectId === b.projectId
+  );
+}
+export function decodeReuseRecovery(
+  raw: string | null,
+  documents: readonly DocumentNode[]
+): ReuseRecovery | null {
+  if (!raw || new TextEncoder().encode(raw).byteLength > MAX_BYTES) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (!object(value) || value.version !== 1 || !object(value.scope) || !object(value.input))
+      return null;
+    const scope = value.scope;
+    if (
+      typeof scope.actorId !== 'string' ||
+      typeof scope.workspaceId !== 'string' ||
+      typeof scope.tenantId !== 'string' ||
+      typeof scope.organizationId !== 'string' ||
+      typeof scope.gateway !== 'string' ||
+      !scope.actorId ||
+      !scope.workspaceId ||
+      (scope.projectId !== null && typeof scope.projectId !== 'string')
+    )
+      return null;
+    if (typeof value.operation !== 'string' || !documents.some((d) => print(d) === value.operation))
+      return null;
+    const definitions = parse(value.operation).definitions;
+    const op = definitions.find((d) => d.kind === Kind.OPERATION_DEFINITION);
+    if (
+      !op ||
+      op.kind !== Kind.OPERATION_DEFINITION ||
+      op.operation !== 'mutation' ||
+      !op.name ||
+      !operations.has(op.name.value)
+    )
+      return null;
+    if (
+      typeof value.key !== 'string' ||
+      !value.key ||
+      value.key.length > 200 ||
+      typeof value.success !== 'string' ||
+      value.success.length > 500
+    )
+      return null;
+    // Storage is untrusted. Only the current owning operation document may be executed.
+    return {
+      version: 1,
+      scope: {
+        actorId: scope.actorId,
+        workspaceId: scope.workspaceId,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        gateway: scope.gateway,
+        projectId: scope.projectId,
+      },
+      operation: value.operation,
+      input: value.input,
+      key: value.key,
+      success: value.success,
+    };
+  } catch {
+    return null;
+  }
+}
+export function encodeReuseRecovery(value: ReuseRecovery): string {
+  const text = JSON.stringify(value);
+  if (new TextEncoder().encode(text).byteLength > MAX_BYTES)
+    throw new Error('This request is too large to retain safely.');
+  return text;
+}

package/src/movethewheels/utils/stockBindingForm.ts

@@ -0,0 +1,209 @@
+import type {
+  RecordMtwStockBindingAssessmentInput,
+  StockSourceContextFragment,
+  StockAssessmentFragment,
+} from '../../generated/stock-binding-operations';
+import { freeTimeIso } from './freeTimeDate';
+import type { SelectedEvidence } from '../components/ContainerEvidencePicker';
+
+export interface StockDraftPin {
+  inventoryItemId: string;
+  expectedCargoItemId: string;
+  expectedWarehouseId: string;
+  expectedLocationId: string | null;
+  expectedCompositionEpoch: number;
+  expectedInventoryUpdatedAt: string;
+  expectedCargoUpdatedAt: string;
+  expectedWarehouseUpdatedAt: string;
+  expectedLocationUpdatedAt: string | null;
+  expectedPreviousAssessmentId: string | null;
+  expectedVersion: number;
+  label: string;
+}
+export type StockFactDraft = Pick<
+  RecordMtwStockBindingAssessmentInput,
+  'effectiveAt' | 'facts' | 'evidence'
+>;
+export function stockContextLabel(row: StockSourceContextFragment): string {
+  return `${row.warehouse?.name ?? 'Warehouse unavailable'} (${row.warehouse?.code ?? 'unknown code'}) / ${row.cargoItem?.name ?? 'Cargo unavailable'} (${row.cargoItem?.sku ?? 'unknown SKU'}) / ${row.locationId === null ? 'Unbinned' : (row.location?.locationCode ?? 'Bin unavailable')}`;
+}
+export function stockDraftPin(
+  row: StockSourceContextFragment,
+  predecessor: StockAssessmentFragment | null
+): StockDraftPin {
+  if (
+    !row.cargoItem ||
+    !row.warehouse ||
+    row.cargoItem.id !== row.cargoItemId ||
+    row.warehouse.id !== row.warehouseId ||
+    (row.locationId === null
+      ? row.location != null
+      : !row.location ||
+        row.location.id !== row.locationId ||
+        row.location.warehouseId !== row.warehouseId)
+  )
+    throw new Error(
+      'This stock line is missing a current owner. Refresh and review it before recording.'
+    );
+  if (
+    !Number.isInteger(row.compositionEpoch) ||
+    row.compositionEpoch < 0 ||
+    row.compositionEpoch > 2147483647
+  )
+    throw new Error(
+      'The current continuity revision is unavailable. Refresh and review this stock line.'
+    );
+  if (predecessor && predecessor.inventoryItemId !== row.id)
+    throw new Error('The previous assessment belongs to another stock line.');
+  return {
+    inventoryItemId: row.id,
+    expectedCompositionEpoch: row.compositionEpoch,
+    expectedCargoItemId: row.cargoItemId,
+    expectedWarehouseId: row.warehouseId,
+    expectedLocationId: row.locationId ?? null,
+    expectedInventoryUpdatedAt: row.updatedAt,
+    expectedCargoUpdatedAt: row.cargoItem.updatedAt,
+    expectedWarehouseUpdatedAt: row.warehouse.updatedAt,
+    expectedLocationUpdatedAt: row.location?.updatedAt ?? null,
+    expectedPreviousAssessmentId: predecessor?.id ?? null,
+    expectedVersion: predecessor?.version ?? 0,
+    label: stockContextLabel(row),
+  };
+}
+export function stockContextMatches(
+  pin: StockDraftPin,
+  row: StockSourceContextFragment | null | undefined,
+  predecessor: StockAssessmentFragment | null
+): boolean {
+  if (!row) return false;
+  try {
+    const current = stockDraftPin(row, predecessor);
+    // current contains only the declared pin keys; UI-only generation metadata is excluded.
+    return Object.entries(current).every(
+      ([name, value]) => name === 'label' || pin[name as keyof StockDraftPin] === value
+    );
+  } catch {
+    return false;
+  }
+}
+export function inputForStockDraft(
+  draft: StockFactDraft,
+  pin: StockDraftPin,
+  row: StockSourceContextFragment | null | undefined,
+  predecessor: StockAssessmentFragment | null
+): Omit<RecordMtwStockBindingAssessmentInput, 'idempotencyKey'> {
+  if (!stockContextMatches(pin, row, predecessor))
+    throw new Error(
+      'This stock line or its recorded history changed. Refresh and review a new draft.'
+    );
+  return {
+    inventoryItemId: pin.inventoryItemId,
+    expectedCompositionEpoch: pin.expectedCompositionEpoch,
+    expectedCargoItemId: pin.expectedCargoItemId,
+    expectedWarehouseId: pin.expectedWarehouseId,
+    expectedLocationId: pin.expectedLocationId,
+    expectedInventoryUpdatedAt: pin.expectedInventoryUpdatedAt,
+    expectedCargoUpdatedAt: pin.expectedCargoUpdatedAt,
+    expectedWarehouseUpdatedAt: pin.expectedWarehouseUpdatedAt,
+    expectedLocationUpdatedAt: pin.expectedLocationUpdatedAt,
+    expectedPreviousAssessmentId: pin.expectedPreviousAssessmentId,
+    expectedVersion: pin.expectedVersion,
+    ...draft,
+  };
+}
+function optionalText(data: FormData, name: string, max = 255): string | null {
+  const value = data.get(name);
+  if (value === null || value === '') return null;
+  if (typeof value !== 'string') throw new Error('Enter text source facts.');
+  const text = value.trim();
+  if (!text) return null;
+  if (text.length > max) throw new Error(`${name} exceeds ${max} characters.`);
+  return text;
+}
+function optionalDate(data: FormData, name: string): string | null {
+  const text = optionalText(data, name);
+  return text === null ? null : freeTimeIso(text);
+}
+function choice<T extends string>(data: FormData, name: string, allowed: readonly T[]): T {
+  const selected = allowed.find((value) => value === data.get(name));
+  if (!selected) throw new Error(`Choose a declared ${name}.`);
+  return selected;
+}
+export function readStockFactDraft(data: FormData, evidence: SelectedEvidence[]): StockFactDraft {
+  const validityPolicy = choice(data, 'validityPolicy', [
+    'UNKNOWN',
+    'TIME_BOUNDED',
+    'NO_REQUIRED_EXPIRY',
+  ] as const);
+  const from = optionalDate(data, 'validityFrom'),
+    until = optionalDate(data, 'validityUntil');
+  if (
+    (validityPolicy === 'NO_REQUIRED_EXPIRY' && until !== null) ||
+    (from && until && Date.parse(from) >= Date.parse(until))
+  )
+    throw new Error('Source validity cutoff or chronology contradicts its declaration.');
+  const lotPresent = choice(data, 'lotPresent', ['UNKNOWN', 'REPORTED'] as const) === 'REPORTED';
+  const expiryPolicy = lotPresent
+    ? choice(data, 'expiryPolicy', ['UNKNOWN', 'TIME_BOUNDED', 'NO_REQUIRED_EXPIRY'] as const)
+    : 'UNKNOWN';
+  const expiresAt = optionalDate(data, 'expiresAt');
+  if (lotPresent && expiryPolicy === 'NO_REQUIRED_EXPIRY' && expiresAt !== null)
+    throw new Error('No-required-expiry lot cannot have a cutoff.');
+  if (!evidence.length || evidence.length > 10)
+    throw new Error('Choose 1–10 exact evidence versions from shared Files.');
+  return {
+    effectiveAt: freeTimeIso(optionalText(data, 'effectiveAt') ?? ''),
+    evidence: evidence.map(({ fileId, versionId }) => ({ fileId, versionId })),
+    facts: {
+      scope: choice(data, 'scope', ['UNKNOWN', 'WHOLE_LINE', 'UNSUPPORTED_MIXED_LOT'] as const),
+      source: {
+        reference: optionalText(data, 'sourceReference'),
+        revision: optionalText(data, 'sourceRevision', 120),
+      },
+      countUnit:
+        choice(data, 'unitPresent', ['UNKNOWN', 'COUNT_UNIT'] as const) === 'COUNT_UNIT'
+          ? {
+              kind: 'COUNT_UNIT',
+              reference: optionalText(data, 'unitReference'),
+              revision: optionalText(data, 'unitRevision', 120),
+            }
+          : null,
+      scanMapping: {
+        reportedItemLabel: optionalText(data, 'itemLabel'),
+        reportedBinLabel: optionalText(data, 'binLabel'),
+        mappingReference: optionalText(data, 'mappingReference'),
+        mappingRevision: optionalText(data, 'mappingRevision', 120),
+      },
+      declaredLotPolicy: choice(data, 'lotPolicy', [
+        'UNKNOWN',
+        'REQUIRED',
+        'NOT_REQUIRED',
+      ] as const),
+      lot: lotPresent
+        ? {
+            reference: optionalText(data, 'lotReference'),
+            revision: optionalText(data, 'lotRevision', 120),
+            declaredDisposition: choice(data, 'lotDisposition', [
+              'UNKNOWN',
+              'RELEASED',
+              'HELD',
+              'EXPIRED',
+            ] as const),
+            expiry: {
+              policy: expiryPolicy,
+              expiresAt,
+              sourceReference: optionalText(data, 'expiryReference'),
+              sourceRevision: optionalText(data, 'expiryRevision', 120),
+            },
+          }
+        : null,
+      sourceValidity: {
+        policy: validityPolicy,
+        from,
+        until,
+        sourceReference: optionalText(data, 'validityReference'),
+        sourceRevision: optionalText(data, 'validityRevision', 120),
+      },
+    },
+  };
+}

package/src/movethewheels/utils/stockBindingLabels.ts

@@ -0,0 +1,41 @@
+export function stockCompletenessLabel(status: string): string {
+  if (status === 'SOURCE_FACTS_ONLY') return 'Reported facts';
+  if (status === 'INCOMPLETE') return 'Missing facts';
+  if (status === 'UNSUPPORTED_MIXED_LOT') return 'Mixed lots need separate handling';
+  return 'Unknown';
+}
+export function stockFactLabel(value: string | null | undefined): string {
+  if (!value || value === 'UNKNOWN') return 'Unknown';
+  if (value === 'NO_REQUIRED_EXPIRY') return 'Source reports no required expiry';
+  if (value === 'COUNT_UNIT') return 'Explicit count unit';
+  if (value === 'UNSUPPORTED_MIXED_LOT') return 'Mixed lots need separate handling';
+  const text = value.toLowerCase().replaceAll('_', ' ');
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+export function stockMissingFactLabel(value: string): string {
+  const text = value
+    .toLowerCase()
+    .replaceAll('_', ' ')
+    .replace(/^declared /, 'Reported ')
+    .replace(/ unknown$/, ' is unknown');
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+export function stockContinuityLabel(
+  assessment: { inventoryItemId: string; capturedCompositionEpoch?: number | null },
+  current?: { id: string; compositionEpoch: number } | null
+): string {
+  if (assessment.capturedCompositionEpoch == null) return 'Continuity revision not recorded.';
+  const captured = `Recorded continuity revision: ${assessment.capturedCompositionEpoch}.`;
+  if (
+    !current ||
+    current.id !== assessment.inventoryItemId ||
+    !Number.isInteger(current.compositionEpoch) ||
+    current.compositionEpoch < 0 ||
+    current.compositionEpoch > 2147483647
+  )
+    return `${captured} Current comparison unavailable.`;
+  return current.compositionEpoch === assessment.capturedCompositionEpoch
+    ? `${captured} Matches the displayed stock revision.`
+    : `${captured} Stock context changed since this record.`;
+}

package/src/movethewheels/utils/stockObservationForm.ts

@@ -0,0 +1,73 @@
+import type { RecordMtwStockObservationInput } from '../../generated/stock-observation-operations';
+
+function text(form: FormData, name: string, max: number, required = false): string | null {
+  const value = form.get(name);
+  if (typeof value !== 'string') throw new Error('Reported field is missing.');
+  const normalized = value.trim();
+  if (normalized.length > max || (required && !normalized))
+    throw new Error('Check the reported field length.');
+  return normalized || null;
+}
+/** Blank remains unknown, explicit zero remains zero; no inferred stock adjustment. */
+export function reportedCount(value: string): number | null {
+  const clean = value.trim();
+  if (!clean) return null;
+  if (!/^\d+$/.test(clean)) throw new Error('Reported count must be a whole number or blank.');
+  const count = Number(clean);
+  if (!Number.isSafeInteger(count) || count > 2147483647)
+    throw new Error('Reported count is outside the supported range.');
+  return count;
+}
+function reportedInstant(value: string): string | null {
+  if (!value) return null;
+  const time = new Date(value);
+  if (!Number.isFinite(time.getTime()) || time.getTime() > Date.now())
+    throw new Error('Reported observation time must be valid and no later than now.');
+  return time.toISOString();
+}
+export function stockObservationInput(
+  inventoryItemId: string,
+  form: FormData
+): Omit<RecordMtwStockObservationInput, 'idempotencyKey'> {
+  const kind = text(form, 'kind', 40, true);
+  const scope = text(form, 'countScope', 40, true);
+  if (
+    kind !== 'COUNT_DISCREPANCY' &&
+    kind !== 'DAMAGE' &&
+    kind !== 'IDENTITY_UNCERTAIN' &&
+    kind !== 'OTHER'
+  )
+    throw new Error('Choose a supported issue.');
+  if (scope !== 'WHOLE_LINE' && scope !== 'UNKNOWN')
+    throw new Error('Choose a supported count scope.');
+  const fileId = text(form, 'fileId', 255),
+    versionId = text(form, 'versionId', 255);
+  if (!!fileId !== !!versionId)
+    throw new Error('Enter both exact file and version references, or leave both blank.');
+  const unitReference = text(form, 'unitReference', 255),
+    unitRevision = text(form, 'unitRevision', 255);
+  const sourceReference = text(form, 'sourceReference', 255),
+    sourceRevision = text(form, 'sourceRevision', 255);
+  const countUnit = form.get('countUnit');
+  if (countUnit !== 'COUNT_UNIT' && countUnit !== 'UNKNOWN')
+    throw new Error('Choose a supported reported unit.');
+  if (countUnit === 'UNKNOWN' && (unitReference || unitRevision))
+    throw new Error('Select count unit before supplying its references.');
+  return {
+    inventoryItemId,
+    kind,
+    countScope: scope,
+    observedCount: reportedCount(text(form, 'observedCount', 32) ?? ''),
+    reportedCountUnit:
+      countUnit === 'COUNT_UNIT'
+        ? { kind: 'COUNT_UNIT', reference: unitReference, revision: unitRevision }
+        : null,
+    source:
+      sourceReference || sourceRevision
+        ? { reference: sourceReference, revision: sourceRevision }
+        : null,
+    reportedObservedAt: reportedInstant(text(form, 'reportedObservedAt', 50) ?? ''),
+    reason: text(form, 'reason', 1000, true) ?? '',
+    evidenceDeclarations: fileId && versionId ? [{ fileId, versionId }] : [],
+  };
+}

package/src/movethewheels/utils/tripDraftContext.ts

@@ -0,0 +1,61 @@
+import type { RecordMtwTripUtilizationReportInput } from '../../generated/trip-utilization-operations';
+import type { TripReportDraft } from './tripUtilizationForm';
+export interface TripDraftContext {
+  routeId: string;
+  routeUpdatedAt: string;
+  vehicleId: string;
+  vehicleUpdatedAt: string;
+  routeName: string;
+  vehicleNumber: string;
+}
+interface RouteContext {
+  id: string;
+  updatedAt: string;
+  vehicleId?: string | null;
+}
+interface VehicleContext {
+  id: string;
+  updatedAt: string;
+}
+export function tripRouteStillMatches(
+  pin: TripDraftContext,
+  route: RouteContext | null | undefined
+): boolean {
+  return (
+    !!route &&
+    route.id === pin.routeId &&
+    route.updatedAt === pin.routeUpdatedAt &&
+    route.vehicleId === pin.vehicleId
+  );
+}
+export function tripContextStillMatches(
+  pin: TripDraftContext,
+  route: RouteContext | null | undefined,
+  vehicle: VehicleContext | null | undefined
+): boolean {
+  return (
+    tripRouteStillMatches(pin, route) &&
+    !!vehicle &&
+    vehicle.id === pin.vehicleId &&
+    vehicle.updatedAt === pin.vehicleUpdatedAt
+  );
+}
+/** Fresh reads verify captured intent; they never replace the vehicle or revisions entered against. */
+export function inputForTripDraft(
+  draft: TripReportDraft,
+  pin: TripDraftContext,
+  route: RouteContext | null | undefined,
+  vehicle: VehicleContext | null | undefined
+): Omit<RecordMtwTripUtilizationReportInput, 'idempotencyKey'> {
+  if (!tripContextStillMatches(pin, route, vehicle))
+    throw new Error(
+      'Route assignment or revision changed since this draft began. Refresh context, review the route and vehicle, and start a new report; the entered measurements will not be reassigned automatically.'
+    );
+  return {
+    ...draft,
+    routeId: pin.routeId,
+    vehicleId: pin.vehicleId,
+    expectedRouteUpdatedAt: pin.routeUpdatedAt,
+    expectedVehicleUpdatedAt: pin.vehicleUpdatedAt,
+  };
+}

package/src/movethewheels/utils/tripUtilizationForm.ts

@@ -0,0 +1,105 @@
+import type {
+  RecordMtwTripUtilizationReportInput,
+  MtwTripUtilizationBasis,
+  MtwTripUtilizationCoverage,
+} from '../../generated/trip-utilization-operations';
+import type { SelectedEvidence } from '../components/ContainerEvidencePicker';
+import { freeTimeIso } from './freeTimeDate';
+import { reuseText } from './reuseForm';
+export type TripReportDraft = Omit<
+  RecordMtwTripUtilizationReportInput,
+  'routeId' | 'vehicleId' | 'expectedRouteUpdatedAt' | 'expectedVehicleUpdatedAt' | 'idempotencyKey'
+>;
+export function tripQuantity(text: string, maximum: number, positive = false): number | null {
+  if (!text.trim()) return null;
+  if (!/^(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(text.trim()))
+    throw new Error('Enter a nonnegative measurement, or leave it blank for UNKNOWN.');
+  const number = Number(text);
+  if (
+    !Number.isFinite(number) ||
+    number > maximum ||
+    (number === 0 && /[1-9]/.test(text.trim().split(/[eE]/)[0] ?? '')) ||
+    (positive ? number <= 0 : number < 0)
+  )
+    throw new Error(
+      `Measurement must be ${positive ? 'positive' : 'nonnegative'}, finite and no greater than ${maximum}.`
+    );
+  return number;
+}
+function choice<T extends string>(text: string, choices: readonly T[], label: string): T {
+  const found = choices.find((item) => item === text);
+  if (!found) throw new Error(`Choose ${label}.`);
+  return found;
+}
+export function readTripDraft(
+  values: FormData,
+  ids: string[],
+  basis: MtwTripUtilizationBasis,
+  coverage: MtwTripUtilizationCoverage,
+  evidence: SelectedEvidence[]
+): TripReportDraft {
+  if (!evidence.length) throw new Error('Select exact readable evidence versions for the report.');
+  const intervalFrom = freeTimeIso(reuseText(values, 'intervalFrom'));
+  const intervalUntil = freeTimeIso(reuseText(values, 'intervalUntil'));
+  if (intervalFrom > intervalUntil)
+    throw new Error('The report interval must end at or after its start.');
+  const segments = ids.map((segmentId, index) => {
+    const text = (field: string) => reuseText(values, `${segmentId}.${field}`);
+    const observed = text('observedAt');
+    const observedAt = observed ? freeTimeIso(observed) : null;
+    if (
+      basis === 'OBSERVED' &&
+      (!observedAt || observedAt < intervalFrom || observedAt > intervalUntil)
+    )
+      throw new Error(
+        `Segment ${index + 1}: observation time must be within the reported interval.`
+      );
+    return {
+      segmentId,
+      sequence: index + 1,
+      loadedState: choice(
+        text('loadedState'),
+        ['EMPTY', 'LOADED', 'UNKNOWN'] as const,
+        'explicit load state'
+      ),
+      distanceKm: tripQuantity(text('distanceKm'), 10000000),
+      payloadKg: tripQuantity(text('payloadKg'), 1000000000),
+      payloadCapacityKg: tripQuantity(text('payloadCapacityKg'), 1000000000, true),
+      cubeM3: tripQuantity(text('cubeM3'), 1000000000),
+      cubeCapacityM3: tripQuantity(text('cubeCapacityM3'), 1000000000, true),
+      source: {
+        reference: text('reference'),
+        revision: text('revision'),
+        observedAt,
+        distanceBasis: choice(
+          text('distanceBasis'),
+          basis === 'OBSERVED'
+            ? (['MEASURED'] as const)
+            : (['PROVIDER_ESTIMATE', 'OPERATOR_ESTIMATE'] as const),
+          'distance source basis'
+        ),
+        loadBasis: choice(
+          text('loadBasis'),
+          basis === 'OBSERVED'
+            ? (['MEASURED'] as const)
+            : (['MEASURED', 'SOURCE_CONFIRMED_PLAN'] as const),
+          'load source basis'
+        ),
+        capacityBasis: choice(
+          text('capacityBasis'),
+          ['RATED', 'MEASURED'] as const,
+          'capacity source basis'
+        ),
+      },
+    };
+  });
+  return {
+    tripId: reuseText(values, 'tripReference'),
+    basis,
+    declaredCoverage: coverage,
+    intervalFrom,
+    intervalUntil,
+    segments,
+    evidence: evidence.map(({ fileId, versionId }) => ({ fileId, versionId })),
+  };
+}

package/src/operations/condition/container-condition.graphql

@@ -0,0 +1,41 @@
+fragment ConditionEvidence on MtwContainerEvidence { fileId versionId sha256Hash checkedAt }
+fragment InspectionSummary on MtwContainerInspection {
+  id containerId inspectedAt inspectorActorId templateVersion examinationScheme nextExaminationAt acepReference
+  cargoCategory suitability cscPlateVersionId examinationVersionId defectCount severeDefectCount resolvedDefectIds evidence { ...ConditionEvidence }
+}
+fragment HoldSummary on MtwContainerHold {
+  id containerId inspectionId reason heldAt status version defectIds releasedAt updatedAt evidence { ...ConditionEvidence }
+}
+fragment QualificationSummary on MtwInspectorQualification {
+  id subjectActorId issuerName credentialReference validFrom validUntil scopes status version
+  verifierActorId reviewedAt issuerConfirmationReference reviewNote revokedAt revocationReason
+  evidence { ...ConditionEvidence } reviewEvidence { ...ConditionEvidence }
+}
+query ConditionContainers($pagination: MtwContainerPagination) {
+  mtwContainerPage(pagination: $pagination) { items { id containerNumber equipmentType } hasMore nextOffset }
+}
+query ConditionInspections($containerId: ID!, $pagination: MtwContainerPagination) {
+  mtwContainerInspectionPage(containerId: $containerId, pagination: $pagination) { items { ...InspectionSummary } hasMore nextOffset }
+}
+query ConditionHolds($containerId: ID!, $pagination: MtwContainerPagination) {
+  mtwContainerHoldPage(containerId: $containerId, pagination: $pagination) { items { ...HoldSummary } hasMore nextOffset }
+}
+query ConditionDefects($inspectionId: ID!, $pagination: MtwContainerPagination) {
+  mtwContainerDefectPage(inspectionId: $inspectionId, pagination: $pagination) { items { id code severity details } hasMore nextOffset }
+}
+query ConditionRepairs($holdId: ID!, $pagination: MtwContainerPagination) {
+  mtwContainerRepairPage(holdId: $holdId, pagination: $pagination) { items { id completedAt workDescription defectIds evidence { ...ConditionEvidence } } hasMore nextOffset }
+}
+query ConditionReleases($containerId: ID!, $pagination: MtwContainerPagination) {
+  mtwContainerReleaseDecisionPage(containerId: $containerId, pagination: $pagination) { items { id holdId inspectionId qualificationId resolutionReview decidedAt evidence { ...ConditionEvidence } } hasMore nextOffset }
+}
+query ConditionQualifications($pagination: MtwContainerPagination) {
+  mtwContainerQualificationPage(pagination: $pagination) { items { ...QualificationSummary } hasMore nextOffset }
+}
+mutation RecordInspection($input: RecordMtwContainerInspectionInput!) { recordMtwContainerInspection(input: $input) { ...InspectionSummary } }
+mutation CreateConditionHold($input: HoldMtwContainerInput!) { holdMtwContainer(input: $input) { ...HoldSummary } }
+mutation RecordConditionRepair($input: RecordMtwContainerRepairInput!) { recordMtwContainerRepair(input: $input) { id } }
+mutation SubmitInspectorQualification($input: SubmitMtwInspectorQualificationInput!) { submitMtwInspectorQualification(input: $input) { ...QualificationSummary } }
+mutation ReviewInspectorQualification($input: VerifyMtwInspectorQualificationInput!) { verifyMtwInspectorQualification(input: $input) { ...QualificationSummary } }
+mutation RevokeInspectorQualification($input: RevokeMtwInspectorQualificationInput!) { revokeMtwInspectorQualification(input: $input) { ...QualificationSummary } }
+mutation ReleaseConditionHold($input: ReleaseMtwContainerHoldInput!) { releaseMtwContainerHold(input: $input) { id decidedAt } }