@burdenoff/microfe-movethewheels 2026.1016.2 → 2026.1016.4

package/src/movethewheels/utils/invoiceComparison.ts

@@ -0,0 +1,520 @@
+import { freightMoney } from './freightDraft';
+import type {
+  CompareMtwFreightInvoiceInput,
+  InvoiceEstimatePinFragment,
+  InvoiceReceiptFragment,
+  InvoiceStructuralPreviewQuery,
+  MtwFreightInvoiceFactsInput,
+} from '../../generated/freight-invoice-operations';
+
+export const INVOICE_RECOVERY_STORAGE = 'movethewheels.freight-invoice.unresolved.v1';
+export interface InvoiceScope {
+  actorId: string;
+  workspaceId: string;
+  tenantId: string | null;
+  organizationId: string;
+  projectId: string | null;
+  gateway: string;
+}
+export interface InvoiceIntent {
+  version: 1;
+  scope: InvoiceScope;
+  input: CompareMtwFreightInvoiceInput;
+  estimate: InvoiceEstimatePinFragment;
+}
+function fail(message: string): never {
+  throw new Error(message);
+}
+function object(value: unknown, allowed: readonly string[]): Record<string, unknown> {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    Object.keys(value).some((key) => !allowed.includes(key))
+  )
+    fail('Invoice fields are not supported. Nothing was sent.');
+  return Object.fromEntries(Object.entries(value));
+}
+function text(value: unknown, maximum: number): string {
+  if (typeof value !== 'string' || !value.trim() || value.trim().length > maximum)
+    fail('Complete the bounded invoice source fields. Nothing was sent.');
+  return value.trim();
+}
+function optional(value: unknown, maximum: number): string | null {
+  return value == null || value === '' ? null : text(value, maximum);
+}
+function integer(value: unknown, max: number): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > max)
+    fail('Invoice numeric convention is invalid. Nothing was sent.');
+  return value;
+}
+function currency(value: unknown) {
+  const v = object(value, ['code', 'minorUnitDigits']),
+    code = text(v.code, 3);
+  if (!/^[A-Z]{3}$/.test(code)) fail('Declare an uppercase three-letter invoice currency.');
+  return { code, minorUnitDigits: integer(v.minorUnitDigits, 4) };
+}
+export function invoiceCanonical(value: unknown): string {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean')
+    return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(invoiceCanonical).join(',') + ']';
+  if (value && typeof value === 'object') {
+    const v = Object.fromEntries(Object.entries(value)),
+      keys = Object.keys(v).filter((key) => v[key] !== undefined);
+    keys.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return (
+      '{' + keys.map((key) => JSON.stringify(key) + ':' + invoiceCanonical(v[key])).join(',') + '}'
+    );
+  }
+  return fail('Cannot safely retain this invoice intent. Nothing was sent.');
+}
+export function invoiceFactsInput(value: unknown): MtwFreightInvoiceFactsInput {
+  const v = object(value, [
+    'schemaVersion',
+    'supplierReference',
+    'supplierLabel',
+    'invoiceReference',
+    'sourceReference',
+    'sourceRevision',
+    'invoiceDate',
+    'currency',
+    'rows',
+  ]);
+  if (v.schemaVersion !== 1 || !Array.isArray(v.rows) || v.rows.length < 1 || v.rows.length > 100)
+    fail('Provide 1–100 reported invoice rows.');
+  const money = currency(v.currency),
+    date = optional(v.invoiceDate, 10);
+  if (date !== null) {
+    const d = new Date(date + 'T00:00:00.000Z');
+    if (
+      !/^\d{4}-\d{2}-\d{2}$/.test(date) ||
+      date.startsWith('0000') ||
+      !Number.isFinite(d.getTime()) ||
+      d.toISOString().slice(0, 10) !== date
+    )
+      fail('Invoice date must be an exact source date or left unknown.');
+  }
+  const rows = v.rows.map((item) => {
+    const r = object(item, [
+      'id',
+      'description',
+      'estimateLineId',
+      'currency',
+      'payerReference',
+      'payerLabel',
+      'quantity',
+      'unit',
+      'unitRateMajor',
+      'amountMinor',
+      'zeroReason',
+    ]);
+    const row = {
+      id: text(r.id, 120),
+      description: text(r.description, 1000),
+      estimateLineId: optional(r.estimateLineId, 120),
+      currency: currency(r.currency),
+      payerReference: optional(r.payerReference, 255),
+      payerLabel: optional(r.payerLabel, 255),
+      quantity: optional(r.quantity, 40),
+      unit: optional(r.unit, 255),
+      unitRateMajor: optional(r.unitRateMajor, 40),
+      amountMinor: optional(r.amountMinor, 38),
+      zeroReason: optional(r.zeroReason, 255),
+    };
+    if (invoiceCanonical(row.currency) !== invoiceCanonical(money))
+      fail('Every row must declare the same invoice currency and scale.');
+    if ((row.payerReference === null) !== (row.payerLabel === null))
+      fail('Supply both payer reference and label, or leave both unknown.');
+    for (const decimal of [row.quantity, row.unitRateMajor])
+      if (decimal !== null && !/^(0|[1-9]\d{0,19})(\.\d{1,18})?$/.test(decimal))
+        fail(
+          'Quantity and rate require nonnegative decimal strings; no credits or exponent notation.'
+        );
+    if (row.amountMinor !== null && !/^(0|[1-9]\d{0,37})$/.test(row.amountMinor))
+      fail('Amount requires a nonnegative integer minor-unit string or unknown.');
+    if (row.amountMinor === '0' && row.zeroReason === null)
+      fail('Record the source reason for an explicit zero charge.');
+    return row;
+  });
+  rows.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  if (new Set(rows.map((r) => r.id)).size !== rows.length) fail('Invoice row IDs must be unique.');
+  return {
+    schemaVersion: 1,
+    supplierReference: optional(v.supplierReference, 255),
+    supplierLabel: optional(v.supplierLabel, 255),
+    invoiceReference: optional(v.invoiceReference, 120),
+    sourceReference: text(v.sourceReference, 255),
+    sourceRevision: text(v.sourceRevision, 255),
+    invoiceDate: date,
+    currency: money,
+    rows,
+  };
+}
+export function invoiceRecordInput(value: unknown): CompareMtwFreightInvoiceInput {
+  const v = object(value, [
+    'shipmentId',
+    'estimateVersionId',
+    'facts',
+    'evidence',
+    'expectedPreviousComparisonId',
+    'expectedRevision',
+    'correctionReason',
+    'idempotencyKey',
+  ]);
+  const facts = invoiceFactsInput(v.facts);
+  if (!facts.supplierReference || !facts.invoiceReference)
+    fail('Source stable supplier and invoice references before recording.');
+  if (!Array.isArray(v.evidence) || v.evidence.length < 1 || v.evidence.length > 10)
+    fail('Select 1–10 current exact evidence versions.');
+  const evidence = v.evidence.map((item) => {
+    const r = object(item, ['fileId', 'versionId']);
+    return { fileId: text(r.fileId, 255), versionId: text(r.versionId, 255) };
+  });
+  evidence.sort((a, b) => {
+    const x = JSON.stringify([a.fileId, a.versionId]),
+      y = JSON.stringify([b.fileId, b.versionId]);
+    return x < y ? -1 : x > y ? 1 : 0;
+  });
+  if (new Set(evidence.map((e) => e.versionId)).size !== evidence.length)
+    fail('Select distinct exact evidence versions.');
+  const expectedRevision = integer(v.expectedRevision, 2147483646),
+    previous = optional(v.expectedPreviousComparisonId, 255),
+    reason = optional(v.correctionReason, 1000);
+  if (
+    (expectedRevision === 0) !== (previous === null) ||
+    (expectedRevision === 0) !== (reason === null)
+  )
+    fail('A correction needs the exact previous revision and a reason.');
+  const result = {
+    shipmentId: text(v.shipmentId, 255),
+    estimateVersionId: text(v.estimateVersionId, 255),
+    facts,
+    evidence,
+    expectedPreviousComparisonId: previous,
+    expectedRevision,
+    correctionReason: reason,
+    idempotencyKey: text(v.idempotencyKey, 120),
+  };
+  if (new TextEncoder().encode(invoiceCanonical(result)).byteLength > 131072)
+    fail('This normalized invoice request exceeds 131072 bytes.');
+  return result;
+}
+export function sameInvoiceScope(a: InvoiceScope, b: InvoiceScope | null): boolean {
+  return b !== null && invoiceCanonical(a) === invoiceCanonical(b);
+}
+export function decodeInvoiceIntent(raw: string | null): InvoiceIntent | null {
+  if (!raw || new TextEncoder().encode(raw).byteLength > 200000) return null;
+  try {
+    const v = object(JSON.parse(raw), ['version', 'scope', 'input', 'estimate']);
+    if (v.version !== 1) return null;
+    const s = object(v.scope, [
+      'actorId',
+      'workspaceId',
+      'tenantId',
+      'organizationId',
+      'projectId',
+      'gateway',
+    ]);
+    const scope = {
+      actorId: text(s.actorId, 255),
+      workspaceId: text(s.workspaceId, 255),
+      tenantId: optional(s.tenantId, 255),
+      organizationId: text(s.organizationId, 255),
+      projectId: optional(s.projectId, 255),
+      gateway: text(s.gateway, 2048),
+    };
+    const input = invoiceRecordInput(v.input),
+      e = object(v.estimate, [
+        'id',
+        'estimateReference',
+        'version',
+        'kind',
+        'sourceReference',
+        'sourceRevision',
+        'quotedAt',
+        'validFrom',
+        'validUntil',
+        'acceptance',
+      ]);
+    if (
+      (e.kind !== 'ESTIMATE' && e.kind !== 'QUOTE') ||
+      e.acceptance !== 'NOT_ESTABLISHED' ||
+      e.id !== input.estimateVersionId
+    )
+      return null;
+    const version = integer(e.version, 2147483647);
+    if (version < 1) return null;
+    const estimate: InvoiceEstimatePinFragment = {
+      id: text(e.id, 255),
+      estimateReference: text(e.estimateReference, 120),
+      version,
+      kind: e.kind,
+      sourceReference: text(e.sourceReference, 255),
+      sourceRevision: text(e.sourceRevision, 255),
+      quotedAt: optional(e.quotedAt, 32),
+      validFrom: optional(e.validFrom, 32),
+      validUntil: optional(e.validUntil, 32),
+      acceptance: e.acceptance,
+    };
+    return { version: 1, scope, input, estimate };
+  } catch {
+    return null;
+  }
+}
+export function encodeInvoiceIntent(value: InvoiceIntent): string {
+  const raw = JSON.stringify(value);
+  if (!decodeInvoiceIntent(raw))
+    fail('Cannot retain the original invoice intent. Nothing was sent.');
+  return raw;
+}
+function instant(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    Number.isFinite(new Date(value).getTime()) &&
+    new Date(value).toISOString() === value
+  );
+}
+const comparisonFlags = new Set([
+  'MATCHED',
+  'RATE_CHANGED',
+  'QUANTITY_CHANGED',
+  'AMOUNT_CHANGED',
+  'CURRENCY_CHANGED',
+  'PAYER_CHANGED',
+  'UNMATCHED_INVOICE_LINE',
+  'MISSING_EXPECTED_LINE',
+  'DUPLICATE_MATCH',
+  'EXCLUDED_CHARGE_APPEARED',
+  'UNKNOWN_COMPARISON',
+]);
+const comparisonReasons = new Set([
+  'MISSING_AMOUNT',
+  'MISSING_PAYER',
+  'MISSING_UNIT',
+  'UNIT_MISMATCH',
+  'MISSING_QUANTITY',
+  'MISSING_RATE',
+  'SCALE_MISMATCH',
+  'UNKNOWN_BASIS',
+  'UNKNOWN_DISPOSITION',
+  'INCLUDED_CHILD_BILLED_SEPARATELY',
+  'UNKNOWN_EXPECTED_CHARGE_COVERAGE',
+]);
+function enumList(value: unknown, allowed: Set<string>, nonempty = false): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length <= allowed.size &&
+    (!nonempty || value.length > 0) &&
+    value.every((v) => typeof v === 'string' && allowed.has(v)) &&
+    new Set(value).size === value.length
+  );
+}
+function outcomeMatches(
+  receipt: Pick<
+    InvoiceReceiptFragment,
+    'outcome' | 'estimateDeclaredSubtotals' | 'invoiceDeclaredSubtotals'
+  >,
+  expected: MtwFreightInvoiceFactsInput['rows']
+): boolean {
+  const o = receipt.outcome;
+  if (
+    !o ||
+    typeof o.allLinesMatched !== 'boolean' ||
+    !enumList(o.flags, comparisonFlags, true) ||
+    !Array.isArray(o.rows) ||
+    o.rows.length !== expected.length ||
+    new Set(o.rows.map((r) => r.invoiceLineId)).size !== expected.length ||
+    !Array.isArray(o.missingExpectedLineIds) ||
+    o.missingExpectedLineIds.length > 100 ||
+    o.missingExpectedLineIds.some((id) => typeof id !== 'string' || !id || id.length > 120) ||
+    new Set(o.missingExpectedLineIds).size !== o.missingExpectedLineIds.length ||
+    !Array.isArray(o.unknownExpectedCoverage) ||
+    o.unknownExpectedCoverage.length > 100
+  )
+    return false;
+  if (
+    o.rows.some(
+      (r) =>
+        !expected.some(
+          (e) => e.id === r.invoiceLineId && (e.estimateLineId ?? null) === r.estimateLineId
+        ) ||
+        !enumList(r.flags, comparisonFlags, true) ||
+        !enumList(r.reasons, comparisonReasons) ||
+        (r.deltaMinor !== null &&
+          (typeof r.deltaMinor !== 'string' || !/^(-?[1-9]\d{0,39}|0)$/.test(r.deltaMinor)))
+    )
+  )
+    return false;
+  if (
+    o.unknownExpectedCoverage.some(
+      (r) =>
+        typeof r.estimateLineId !== 'string' ||
+        !r.estimateLineId ||
+        r.estimateLineId.length > 120 ||
+        r.flag !== 'UNKNOWN_COMPARISON' ||
+        r.reason !== 'UNKNOWN_EXPECTED_CHARGE_COVERAGE'
+    )
+  )
+    return false;
+  if (
+    o.allLinesMatched &&
+    (o.flags.length !== 1 ||
+      o.flags[0] !== 'MATCHED' ||
+      o.missingExpectedLineIds.length > 0 ||
+      o.unknownExpectedCoverage.length > 0 ||
+      o.rows.some((r) => r.flags.length !== 1 || r.flags[0] !== 'MATCHED'))
+  )
+    return false;
+  if (!Array.isArray(o.comparableSubtotals) || o.comparableSubtotals.length > 100) return false;
+  const comparableRows: string[] = [];
+  for (const group of o.comparableSubtotals) {
+    currency(group.currency);
+    text(group.payerReference, 255);
+    for (const minor of [group.estimateMinor, group.invoiceMinor])
+      if (typeof minor !== 'string' || !/^(0|[1-9]\d{0,39})$/.test(minor)) return false;
+    if (
+      typeof group.deltaMinor !== 'string' ||
+      !/^(-?[1-9]\d{0,39}|0)$/.test(group.deltaMinor) ||
+      !Array.isArray(group.invoiceLineIds) ||
+      !group.invoiceLineIds.length ||
+      group.invoiceLineIds.some((id) => !expected.some((r) => r.id === id))
+    )
+      return false;
+    comparableRows.push(...group.invoiceLineIds);
+  }
+  if (new Set(comparableRows).size !== comparableRows.length) return false;
+  for (const groups of [receipt.estimateDeclaredSubtotals, receipt.invoiceDeclaredSubtotals]) {
+    if (!Array.isArray(groups) || groups.length > 100) return false;
+    for (const group of groups) {
+      currency(group.currency);
+      optional(group.payerReference, 255);
+      optional(group.payerLabel, 255);
+      if (
+        typeof group.knownAmountMinor !== 'string' ||
+        !/^(0|[1-9]\d{0,39})$/.test(group.knownAmountMinor) ||
+        (group.totalAmountMinor !== null &&
+          (typeof group.totalAmountMinor !== 'string' ||
+            !/^(0|[1-9]\d{0,39})$/.test(group.totalAmountMinor)))
+      )
+        return false;
+    }
+  }
+  return true;
+}
+/** Server owns full trusted context and fingerprint; validate visible business facts, never invent its hash. */
+export function matchesInvoiceReceipt(
+  receipt: InvoiceReceiptFragment | null | undefined,
+  intent: InvoiceIntent
+): boolean {
+  try {
+    if (
+      !receipt ||
+      typeof receipt.id !== 'string' ||
+      !/^([a-f0-9]{8}-){1}[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(receipt.id) ||
+      typeof receipt.invoiceIdentityId !== 'string' ||
+      !receipt.invoiceIdentityId ||
+      receipt.invoiceIdentityId.length > 255 ||
+      receipt.invoiceIdentityId !== receipt.invoiceIdentityId.trim() ||
+      receipt.shipmentId !== intent.input.shipmentId ||
+      receipt.idempotencyKey !== intent.input.idempotencyKey ||
+      typeof receipt.requestFingerprint !== 'string' ||
+      !/^([a-f0-9]{64})$/.test(receipt.requestFingerprint) ||
+      receipt.methodVersion !== 1 ||
+      receipt.revision !== intent.input.expectedRevision + 1 ||
+      receipt.previousComparisonId !== (intent.input.expectedPreviousComparisonId ?? null) ||
+      receipt.correctionReason !== (intent.input.correctionReason ?? null) ||
+      receipt.createdBy !== intent.scope.actorId ||
+      receipt.actorProvenance !== 'direct_human' ||
+      (receipt.onBehalfOf !== null && receipt.onBehalfOf !== intent.scope.actorId) ||
+      !instant(receipt.recordedAt)
+    )
+      return false;
+    if (
+      invoiceCanonical(receipt.estimate) !== invoiceCanonical(intent.estimate) ||
+      invoiceCanonical(invoiceFactsInput(receipt.facts)) !== invoiceCanonical(intent.input.facts)
+    )
+      return false;
+    if (!outcomeMatches(receipt, intent.input.facts.rows)) return false;
+    const requested = intent.input.evidence.map((e) => JSON.stringify([e.fileId, e.versionId]));
+    const actual = receipt.evidence.map((e) => JSON.stringify([e.fileId, e.versionId]));
+    if (
+      actual.length !== requested.length ||
+      new Set(actual).size !== actual.length ||
+      actual.some((key, index) => key !== requested[index])
+    )
+      return false;
+    return receipt.evidence.every(
+      (e) =>
+        typeof e.sha256Hash === 'string' &&
+        /^[a-f0-9]{64}$/.test(e.sha256Hash) &&
+        instant(e.checkedAt) &&
+        new Date(e.checkedAt) <= new Date(receipt.recordedAt) &&
+        new Date(receipt.recordedAt).getTime() - new Date(e.checkedAt).getTime() <= 60000
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Structural preview must match the selected exact version and current draft; it grants no save authority. */
+export function matchesInvoicePreview(
+  value: InvoiceStructuralPreviewQuery['previewMtwFreightInvoice'],
+  facts: MtwFreightInvoiceFactsInput,
+  estimate: InvoiceEstimatePinFragment
+): boolean {
+  try {
+    return (
+      !!value &&
+      value.methodVersion === 1 &&
+      typeof value.recordable === 'boolean' &&
+      Array.isArray(value.blockers) &&
+      value.blockers.length <= 4 &&
+      value.recordable === (value.blockers.length === 0) &&
+      value.blockers.every(
+        (blocker) =>
+          blocker === 'SUPPLIER_UNKNOWN' ||
+          blocker === 'INVOICE_REFERENCE_UNKNOWN' ||
+          blocker === 'EVIDENCE_REQUIRED' ||
+          blocker === 'SHIPMENT_NOT_LIVE'
+      ) &&
+      invoiceCanonical(value.estimate) === invoiceCanonical(estimate) &&
+      invoiceCanonical(invoiceFactsInput(value.facts)) ===
+        invoiceCanonical(invoiceFactsInput(facts)) &&
+      outcomeMatches(value, facts.rows)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Exact decimal display including signed differences; money never enters Number. */
+export function invoiceMoney(
+  minor: string | null | undefined,
+  currency: { code: string; minorUnitDigits: number }
+): string {
+  if (minor == null) return 'Unknown';
+  const negative = minor.startsWith('-');
+  return `${currency.code} ${negative ? '-' : ''}${freightMoney(negative ? minor.slice(1) : minor, currency.minorUnitDigits)}`;
+}
+export function invoiceRowDifference(
+  value: Pick<InvoiceReceiptFragment, 'facts' | 'outcome'>,
+  rowId: string
+): string {
+  const source = value.facts.rows.find((row) => row.id === rowId),
+    result = value.outcome.rows.find((row) => row.invoiceLineId === rowId);
+  const group = value.outcome.comparableSubtotals.find((group) =>
+    group.invoiceLineIds.includes(rowId)
+  );
+  if (
+    !source ||
+    !result ||
+    result.deltaMinor === null ||
+    !group ||
+    source.currency.code !== group.currency.code ||
+    source.currency.minorUnitDigits !== group.currency.minorUnitDigits ||
+    source.payerReference !== group.payerReference
+  )
+    return 'Not comparable';
+  return invoiceMoney(result.deltaMinor, source.currency);
+}