@tallyui/pos 2.0.0 → 3.0.0-next.0

package/src/outbox/register-outbox.ts

@@ -0,0 +1,250 @@
+import type { CommandResult, RegisterCommandEnvelope } from '@tallyui/core';
+import type { RxCollection } from 'rxdb';
+import { BehaviorSubject, type Observable, type Subscription } from 'rxjs';
+import { registerCommandsLogger, type RegisterCommand } from '../register/register-commands';
+import { countFresh, readFresh } from '../rxdb';
+import { createBackendNotFound, type BackendNotFound } from './backend-not-found';
+import { STUCK_AFTER_MS } from './order-outbox';
+import type { CommandTransport, OutboxState } from './types';
+
+export interface RegisterOutboxOptions {
+  collection: RxCollection<RegisterCommand>;
+  transport: CommandTransport<RegisterCommandEnvelope>;
+  deviceId: string;
+  /** Checked at the start of every run; false sends nothing. */
+  isEnabled?: () => boolean;
+  /** Runs before marking, so a crash resends; a throw is logged and marking continues. */
+  onResult?: (command: RegisterCommand, result: CommandResult) => Promise<void> | void;
+  batchSize?: number;
+  initialBackoffMs?: number;
+  maxBackoffMs?: number;
+  random?: () => number;
+  now?: () => number;
+  /** Tests only: overrides STUCK_AFTER_MS. */
+  stuckAfterMs?: number;
+  /** Counts 404s toward OutboxState.backendMissing; pass the order outbox's too, so either one's 404s show one notice. */
+  backendNotFound?: BackendNotFound;
+}
+export interface RegisterOutbox {
+  flush(): Promise<void>;
+  start(): void;
+  stop(): void;
+  state$: Observable<OutboxState>;
+}
+
+function plainCommand({ key, registerId, seq, commandId, type, version, payload, createdAt, syncStatus,
+  error, result, updatedAt }: RegisterCommand): RegisterCommand {
+  return structuredClone({ key, registerId, seq, commandId, type, version, payload, createdAt, syncStatus,
+    ...(error ? { error } : {}), ...(result ? { result } : {}), updatedAt });
+}
+
+export function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOutbox {
+  const { collection, transport, deviceId } = options;
+  const size = options.batchSize;
+  const batchSize = Math.max(1, Math.min(typeof size === 'number' && Number.isFinite(size) ? Math.floor(size) : 10, 10));
+  const initialBackoff = options.initialBackoffMs ?? 1000;
+  const maxBackoff = options.maxBackoffMs ?? 60000;
+  const random = options.random ?? Math.random;
+  const now = options.now ?? Date.now;
+  const state$ = new BehaviorSubject<OutboxState>({ pending: 0, sending: false });
+  const backendNotFound = options.backendNotFound ?? createBackendNotFound();
+  let missingSubscription: Subscription | undefined; // stop() lets go of the (maybe shared) tracker; start() and flush() take it up again
+  const watchBackendMissing = () => missingSubscription ??= backendNotFound.backendMissing$.subscribe((backendMissing) => {
+    if (backendMissing !== state$.value.backendMissing) state$.next({ ...state$.value, backendMissing });
+  });
+  watchBackendMissing();
+  const attempts = new Map<string, number>();
+  let backoff = initialBackoff;
+  let unauthorizedSinceAccepted = 0;
+  let running: Promise<void> | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let subscription: Subscription | undefined;
+  let stopped = false;
+  let insertedDuringRun = false;
+  let stoppedDuringRun = false;
+  const stuckAfter = options.stuckAfterMs ?? STUCK_AFTER_MS;
+  // Each command's stuck clock counts only answered time, by the order outbox's rules. It starts when a batch that
+  // sent the command fails with a failure the store answered (a `retry` other than `network`, where `timeout` counts
+  // like a 503, or `no_progress`); a running clock keeps its `since` and takes the latest reason. A `network` failure
+  // pauses every clock (`pausedAt`), and the next answer of any kind resumes them, moving `since` on by the offline
+  // gap, so `since` is now minus the answered time. A clock clears when its command is no longer pending under its
+  // commandId (applied or rejected), or when a rejected command comes ahead of it in its ledger (it is not being
+  // sent: Front desk, 2026-09-30); commands never sent have none. Nothing is isolated: a stuck command at the head
+  // of a register's ledger holds up the commands behind it, by design, since register facts apply in `seq` order.
+  // In memory only: a restart starts with no clocks, and the first answered failure after it starts them afresh
+  // (accepted: register commands are few, and a restart re-sends at once).
+  const clocks = new Map<string, { since: number; pausedAt?: number; seq: number; reason: string }>();
+  let failureSeq = 0; // numbers failures, so `stuck` can name the latest reason
+
+  function stuckState(): OutboxState['stuck'] {
+    const stuck = [...clocks].filter(([, clock]) => (clock.pausedAt ?? now()) - clock.since >= stuckAfter);
+    if (!stuck.length) return undefined;
+    return { commandIds: stuck.map(([id]) => id), since: Math.min(...stuck.map(([, clock]) => clock.since)),
+      reason: stuck.reduce((latest, entry) => (entry[1].seq > latest[1].seq ? entry : latest))[1].reason,
+      orders: stuck.map(([commandId, { since, reason }]) => ({ commandId, since, reason })) };
+  }
+  function serverFailed(commands: RegisterCommand[], reason: string) {
+    const at = now();
+    for (const { commandId } of commands) clocks.set(commandId, { since: clocks.get(commandId)?.since ?? at, seq: ++failureSeq, reason });
+  }
+
+  async function updateState(patch: Partial<OutboxState> = {}) {
+    const pending = await countFresh(collection, { syncStatus: 'pending' });
+    // Only commands in a register's sendable prefix (pending, before its first rejected command) keep a clock.
+    const sendable = new Set<string>();
+    const blocked = new Set<string>();
+    if (clocks.size) for (const command of await readFresh(collection, { selector: { syncStatus: { $in: ['pending', 'rejected'] } },
+      sort: [{ seq: 'asc' }, { key: 'asc' }] })) {
+      if (command.syncStatus === 'rejected') blocked.add(command.registerId);
+      else if (!blocked.has(command.registerId)) sendable.add(command.commandId);
+    }
+    for (const id of clocks.keys()) if (!sendable.has(id)) clocks.delete(id);
+    state$.next({ ...state$.value, ...patch, pending, stuck: stuckState() });
+  }
+  function scheduleRetry(reason: string, retryAfterMs = 0) {
+    state$.next({ ...state$.value, lastRetryReason: reason, stuck: stuckState() });
+    if (stopped) { stoppedDuringRun = true; return; }
+    const delay = Math.min(Math.max(retryAfterMs, backoff * (0.9 + 0.2 * random())), maxBackoff);
+    backoff = Math.min(backoff * 2, maxBackoff);
+    timer = setTimeout(() => { timer = undefined; flush().catch(() => {}); }, delay);
+    state$.next({ ...state$.value, sending: false, nextAttemptAt: now() + delay });
+  }
+
+  async function run() {
+    stoppedDuringRun = false;
+    while (!stopped) try {
+      await updateState({ sending: true, nextAttemptAt: undefined });
+      insertedDuringRun = false;
+      if (options.isEnabled?.() === false) return;
+      const pending = await readFresh(collection, { selector: { syncStatus: 'pending' } });
+      const registerIds = [...new Set(pending.map((command) => command.registerId))].sort();
+      let sent = false;
+      for (const registerId of registerIds) {
+        const ledger = await readFresh(collection, {
+          selector: { registerId, syncStatus: { $in: ['pending', 'rejected'] } },
+          sort: [{ seq: 'asc' }, { key: 'asc' }],
+        });
+        const commands: RegisterCommand[] = [];
+        for (const command of ledger) {
+          if (command.syncStatus === 'rejected') break;
+          commands.push(command);
+          if (commands.length >= batchSize) break;
+        }
+        if (stopped) { stoppedDuringRun = true; return; }
+        if (!commands.length) continue;
+        sent = true;
+        const batch: RegisterCommandEnvelope[] = commands.map((doc) => {
+          const attempt = (attempts.get(doc.commandId) ?? 0) + 1;
+          attempts.set(doc.commandId, attempt);
+          return { id: doc.commandId, type: doc.type, version: doc.version, payload: doc.payload,
+            createdAt: doc.createdAt, deviceId, attempt };
+        });
+        const outcome = await transport.send(batch);
+        backendNotFound.record(outcome, now());
+        const at = now();
+        if (outcome.kind === 'retry' && outcome.reason === 'network') for (const clock of clocks.values()) clock.pausedAt ??= at;
+        else for (const clock of clocks.values()) if (clock.pausedAt !== undefined) {
+          clock.since += at - clock.pausedAt;
+          clock.pausedAt = undefined;
+        }
+        if (outcome.kind === 'retry') {
+          if (outcome.reason !== 'network') serverFailed(commands, outcome.reason);
+          return scheduleRetry(outcome.reason, outcome.retryAfterMs);
+        }
+        if (outcome.kind === 'unauthorized') {
+          unauthorizedSinceAccepted++;
+          if (unauthorizedSinceAccepted < 3) return scheduleRetry('unauthorized');
+          state$.next({ ...state$.value, authRequired: true, lastRetryReason: 'unauthorized',
+            sending: false, nextAttemptAt: undefined });
+          return;
+        }
+        if (outcome.kind === 'refused') {
+          unauthorizedSinceAccepted = 0;
+          state$.next({ ...state$.value, refused: { status: outcome.status, reason: outcome.reason },
+            authRequired: false, lastRetryReason: 'refused', sending: false, nextAttemptAt: undefined });
+          return;
+        }
+        unauthorizedSinceAccepted = 0;
+        state$.next({ ...state$.value, authRequired: false, refused: undefined });
+        let progressed = false;
+        for (const command of commands) {
+          const result = outcome.results.find((entry) => entry.id === command.commandId);
+          if (!result) continue;
+          // Skip the query cache and ignore a command changed while its send was in flight.
+          const [stored] = await collection.storageInstance.findDocumentsById([command.key], false);
+          if (stored?.syncStatus !== 'pending' || stored.commandId !== command.commandId) continue;
+          const current = await collection.findOne(command.key).exec();
+          if (!current) continue;
+          const error = result.error && { code: result.error.code, message: result.error.message,
+            ...(result.error.data ? { data: result.error.data } : {}) };
+          const normalized: CommandResult = result.status === 'duplicate' && error
+            ? { id: result.id, status: 'rejected', error }
+            : { ...result, ...(error ? { error } : {}) };
+          try { await options.onResult?.(plainCommand(stored), normalized); }
+          catch (cause) { registerCommandsLogger.warn('Failed to apply register command result', { commandId: command.commandId, cause }); }
+          const updatedAt = new Date(now()).toISOString();
+          await current.incrementalModify((row) => {
+            if (row.syncStatus !== 'pending' || row.commandId !== command.commandId) return row;
+            return Object.assign(row, normalized.status === 'rejected'
+              ? { syncStatus: 'rejected', error: normalized.error, updatedAt }
+              : { syncStatus: 'applied', ...(normalized.register ? { result: normalized.register } : {}), updatedAt });
+          });
+          attempts.delete(command.commandId);
+          progressed = true;
+          await updateState();
+        }
+        if (!progressed) {
+          serverFailed(commands, 'no_progress');
+          return scheduleRetry('no_progress');
+        }
+        backoff = initialBackoff;
+        state$.next({ ...state$.value, lastRetryReason: undefined });
+      }
+      if (!sent) return;
+    } catch (error) {
+      scheduleRetry('error: ' + (error instanceof Error ? error.message : String(error)));
+      return;
+    }
+    stoppedDuringRun = true;
+  }
+
+  function flush(): Promise<void> {
+    if (running) return running;
+    stopped = false;
+    watchBackendMissing();
+    clearTimeout(timer);
+    timer = undefined;
+    running = Promise.resolve().then(run).finally(async () => {
+      try { await updateState({ sending: false }); } catch {}
+      running = undefined;
+      if ((insertedDuringRun || stoppedDuringRun) && !stopped && timer === undefined) flush().catch(() => {});
+    });
+    return running;
+  }
+  updateState().catch(() => {});
+  return {
+    state$,
+    flush,
+    start() {
+      stopped = false;
+      watchBackendMissing();
+      if (!subscription) subscription = collection.$.subscribe((event) => {
+        if (event.documentData?.syncStatus === 'pending' &&
+          (event.operation === 'INSERT' || event.operation === 'UPDATE')) {
+          insertedDuringRun = true;
+          flush().catch(() => {});
+        }
+      });
+      if (!stopped) flush().catch(() => {});
+    },
+    stop() {
+      stopped = true;
+      clearTimeout(timer);
+      timer = undefined;
+      subscription?.unsubscribe();
+      subscription = undefined;
+      missingSubscription?.unsubscribe(); missingSubscription = undefined;
+      state$.next({ ...state$.value, nextAttemptAt: undefined });
+    },
+  };
+}

package/src/outbox/types.test-d.ts

@@ -0,0 +1,22 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { AnyCommandEnvelope, CommandEnvelope, OrderCreateEnvelope, OrderCreatePayload, RegisterCommandEnvelope } from '@tallyui/core';
+import type { CommandTransport } from './types';
+
+describe('CommandTransport', () => {
+  it('defaults to order.create envelopes', () => {
+    expectTypeOf<Parameters<CommandTransport['send']>[0]>().toEqualTypeOf<CommandEnvelope<OrderCreatePayload>[]>();
+    const transport: CommandTransport = { send: async () => ({ kind: 'results', results: [] }) };
+    const batch: CommandEnvelope<OrderCreatePayload>[] = [];
+    transport.send(batch);
+  });
+
+  it('the wide transport is accepted where the order outbox wants the order transport', () => {
+    expectTypeOf<CommandTransport<AnyCommandEnvelope>>().toMatchTypeOf<CommandTransport<OrderCreateEnvelope>>();
+  });
+
+  it('the wide transport accepts register command envelopes', () => {
+    const transport: CommandTransport<AnyCommandEnvelope> = { send: async () => ({ kind: 'results', results: [] }) };
+    const batch: RegisterCommandEnvelope[] = [];
+    transport.send(batch);
+  });
+});

package/src/outbox/types.ts

@@ -1,17 +1,22 @@
-import type { CommandEnvelope, CommandResult, OrderCreatePayload } from '@tallyui/core';
+import type { AnyCommandEnvelope, CommandEnvelope, CommandResult, OrderCreatePayload } from '@tallyui/core';
 
 export type TransportOutcome =
   | { kind: 'results'; results: CommandResult[] }
   | { kind: 'unauthorized' }
   | { kind: 'refused'; status: number; reason: string }
+  /** `reason` is `network` when the store could not be reached, `timeout` when a sent request got no answer in time,
+   * else what the store answered (`status_503`, `bad_body`, ...). The order outbox counts every reason but `network`. */
   | { kind: 'retry'; reason: string; retryAfterMs?: number };
 
-export interface CommandTransport {
-  send(batch: CommandEnvelope<OrderCreatePayload>[]): Promise<TransportOutcome>;
+export interface CommandTransport<E extends AnyCommandEnvelope = CommandEnvelope<OrderCreatePayload>> {
+  send(batch: E[]): Promise<TransportOutcome>;
 }
 
 export interface OutboxState {
   pending: number;
+  /** The order outbox's count of `pos_orders` the store refused (`syncStatus: 'rejected'`), read with `pending`. Each
+   * stays until requeue() sends it again. The register outbox leaves it unset. */
+  rejected?: number;
   sending: boolean;
   lastRetryReason?: string;
   nextAttemptAt?: number;
@@ -19,4 +24,13 @@ export interface OutboxState {
   authRequired?: boolean;
   /** Set when the server refused a whole batch (HTTP 400, 403, 413, 415, 422). No order is changed; sending pauses until the next flush(). */
   refused?: { status: number; reason: string };
+  /** Set while the store (not offline) has kept failing some orders for 15 minutes, each on its own clock. Those
+   * orders stay pending and keep retrying. `orders` has each order's own entry: its `since` is when its clock
+   * would have started had there been no offline gaps (now minus its answered time; while offline, as of the
+   * moment the clock paused), and its latest `reason`. `since` is the earliest of theirs; `reason` the latest. */
+  stuck?: { commandIds: string[]; since: number; reason: string; orders: { commandId: string; since: number; reason: string }[] };
+  /** Set after 3 consecutive 404 answers (counted across the outboxes sharing one BackendNotFound): the store address
+   * may be wrong, or the store's plugin isn't installed or is switched off. The outbox keeps retrying; the next answer
+   * that isn't a 404 clears it (offline changes nothing). `since` is when the first of those 404s arrived. */
+  backendMissing?: { since: number };
 }

package/src/outbox/use-order-outbox.ts

@@ -1,14 +1,15 @@
-import { useEffect, useRef, useState } from 'react';
+import type { OrderCreateEnvelope } from '@tallyui/core';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import type { RxCollection, RxError } from 'rxdb';
-import { createLogger } from '../logging';
+import { outboxLogger } from './logger';
 import { OrderContentMismatchError, sameSale, type PosOrder } from '../pos-order';
 import { watchFresh } from '../rxdb';
 import { createOrderOutbox } from './order-outbox';
 import type { CommandTransport, OutboxState } from './types';
 
 const idle: OutboxState = { pending: 0, sending: false };
-/** Logs a retried order found stored under another `commandId` (warn), and a content mismatch (error). */
-export const outboxLogger = createLogger('outbox');
+const noneStuck: readonly string[] = [];
+export { outboxLogger } from './logger';
 
 export interface UseOrderOutboxOptions {
   /** Which order store to use (medusapos: the backend's base URL); `null` means no store. A change reopens. */
@@ -16,9 +17,13 @@ export interface UseOrderOutboxOptions {
   /** Opens the order store for `storeKey`; `close()` is called when the key or device id changes, or on unmount. */
   open(storeKey: string): Promise<{ orders: RxCollection<PosOrder>; close(): Promise<void> }>;
   /** Builds the command transport for `storeKey` (the app's HTTP transport and auth headers). Read once per open. */
-  transport(storeKey: string): CommandTransport;
+  transport(storeKey: string): CommandTransport<OrderCreateEnvelope>;
   /** The device id sent on every command (see `getDeviceId`). A change reopens. */
   deviceId: string;
+  /** Presence is fixed when the store opens; calls use the latest function. Reopen to add or remove. */
+  getMaxOrderCreateVersion?: () => number | undefined | Promise<number | undefined>;
+  /** Presence is fixed when the store opens; calls use the latest function. Reopen to add or remove. */
+  refreshCapabilities?: () => Promise<void>;
   /** Called with `state.sending`, and with `false` on cleanup (medusapos: live-tab's `markBusy('outbox', …)`). */
   onBusy?(busy: boolean): void;
   /** Called when `open` rejects, even if the key has changed since (medusapos: reports storage worker failures). */
@@ -55,6 +60,9 @@ export interface UseOrderOutboxResult {
    * storage can wait forever, and TallyUI deliberately doesn't bound that close (#155).
    */
   savesInFlight: number;
+  /** The command ids in `state.stuck`: pending orders the store keeps failing. Pass them to `needsAttention` and
+   * `OrdersList`. Empty when none, and before the current store is ready. */
+  stuckCommandIds: readonly string[];
 }
 
 /** Opens the order store for `storeKey`, runs its outbox and watches the recent orders (lifted from medusapos/app, ADR-052). */
@@ -83,7 +91,9 @@ export function useOrderOutbox(options: UseOrderOutboxOptions): UseOrderOutboxRe
     if (!storeKey) return;
     void latest.current.open(storeKey).then(async (store) => {
       if (!active) { await store.close(); return; }
-      const outbox = createOrderOutbox({ collection: store.orders, deviceId, transport: latest.current.transport(storeKey) });
+      const outbox = createOrderOutbox({ collection: store.orders, deviceId, transport: latest.current.transport(storeKey),
+        getMaxOrderCreateVersion: latest.current.getMaxOrderCreateVersion ? () => latest.current.getMaxOrderCreateVersion?.() : undefined,
+        refreshCapabilities: latest.current.refreshCapabilities ? async () => { await latest.current.refreshCapabilities?.(); } : undefined });
       current.current = { storeKey, orders: store.orders, outbox };
       const status = outbox.state$.subscribe(setState);
       // watchFresh: find().$ can leave this stale forever, hiding a new order (RxDB 16.21.1 bug 4).
@@ -107,6 +117,9 @@ export function useOrderOutbox(options: UseOrderOutboxOptions): UseOrderOutboxRe
   }, [state.sending]);
 
   const ready = current.current?.storeKey === storeKey && !!storeKey;
+  // Each state update carries a new `stuck`; the ids keep their identity while they are unchanged.
+  const stuckKey = ready ? state.stuck?.commandIds.join(',') ?? '' : '';
+  const stuckCommandIds = useMemo(() => (stuckKey ? stuckKey.split(',') : noneStuck), [stuckKey]);
   return { orders: ready ? orders : null, state: ready ? state : idle, recent: ready ? recent : [],
     async flush() {
       const opened = current.current;
@@ -117,6 +130,7 @@ export function useOrderOutbox(options: UseOrderOutboxOptions): UseOrderOutboxRe
       return opened && opened.storeKey === storeKey ? opened.outbox.requeue(orderIds) : 0;
     },
     savesInFlight: savesInFlightCount,
+    stuckCommandIds,
     async record(posOrder) {
       savesInFlight.current++;
       setSavesInFlightCount(savesInFlight.current);

package/src/pos-order/__fixtures__/order-create-v3.json

@@ -0,0 +1,97 @@
+{
+  "id": "019f6d2e-7800-7000-8000-000000000001",
+  "type": "order.create",
+  "version": 3,
+  "createdAt": "2026-09-28T10:00:00.000Z",
+  "deviceId": "device_golden",
+  "attempt": 1,
+  "payload": {
+    "clientOrderId": "019f6d2e-7800-7000-8000-000000000002",
+    "createdAt": "2026-09-28T10:00:00.000Z",
+    "currency": "EUR",
+    "pricesIncludeTax": true,
+    "lines": [
+      {
+        "clientLineId": "line_inclusive",
+        "variantId": "variant_inclusive",
+        "title": "Inclusive item",
+        "quantity": 2,
+        "unitPriceMinor": 1200,
+        "discountMinor": 203
+      },
+      {
+        "clientLineId": "line_exclusive",
+        "variantId": "variant_exclusive",
+        "title": "Exclusive item",
+        "quantity": 1,
+        "unitPriceMinor": 1000,
+        "taxInclusive": false,
+        "discountMinor": 37
+      }
+    ],
+    "payments": [
+      {
+        "clientPaymentId": "payment_cash",
+        "method": "cash",
+        "amountMinor": 3256,
+        "tenderedMinor": 4000,
+        "changeMinor": 744,
+        "reference": "cash_receipt_1"
+      }
+    ],
+    "subtotalMinor": 2794,
+    "discountMinor": 240,
+    "taxMinor": 462,
+    "totalMinor": 3256,
+    "display": {
+      "currency": "EUR",
+      "exponent": 2,
+      "taxInclusive": true,
+      "subtotalMinor": 3500,
+      "discountMinor": 244,
+      "taxMinor": 462,
+      "totalMinor": 3256,
+      "lines": [
+        {
+          "clientLineId": "line_inclusive",
+          "amountMinor": 2400,
+          "discounts": [
+            {
+              "discountId": "discount_line",
+              "label": "Line discount",
+              "amountMinor": 120
+            }
+          ]
+        },
+        {
+          "clientLineId": "line_exclusive",
+          "amountMinor": 1100,
+          "discounts": []
+        }
+      ],
+      "orderDiscountMinor": 124
+    },
+    "taxByRate": [
+      {
+        "ratePpm": 200000,
+        "code": "VAT20",
+        "netMinor": 1831,
+        "taxMinor": 366,
+        "grossMinor": 2197
+      },
+      {
+        "ratePpm": 100000,
+        "netMinor": 963,
+        "taxMinor": 96,
+        "grossMinor": 1059
+      }
+    ],
+    "customer": {
+      "email": "buyer@example.com",
+      "customerId": "cus_golden_v3"
+    },
+    "registerId": "register_golden",
+    "cashierRef": "cashier_golden",
+    "sessionId": "019f6d2e-7800-7000-8000-000000000003"
+  }
+}

package/src/pos-order/command.ts

@@ -1,22 +1,99 @@
-import type { CommandEnvelope, OrderCreatePayload } from '@tallyui/core';
-import type { PosOrder } from './types';
+import type { OrderCreateEnvelope } from '@tallyui/core';
+import { MICROS_PER_MINOR, roundMicrosToMinor, taxMicros } from '../tax/exact';
+import type { PosOrder, PosOrderLine } from './types';
+
+export class UnsupportedOrderVersionError extends Error {
+  readonly code = 'UNSUPPORTED_ORDER_VERSION';
+  constructor(readonly needed: number, readonly supported: number) {
+    super(`This sale needs order.create version ${needed}; the server supports up to ${supported}.`);
+    this.name = 'UnsupportedOrderVersionError';
+  }
+}
+
+/**
+ * `@tallyui/core/server`'s `payloadBoundErrors` bound, in UTF-16 code units (`String.length`), on
+ * every order.create string but `customer.email` (254), `customerId` (64) and `sessionId` (36).
+ */
+export const PAYLOAD_STRING_MAX = 255;
+
+/** A non-empty string of at most `max` UTF-16 units with no NUL: what order.create's shape check accepts. */
+export const sendable = (value: unknown, max: number): value is string =>
+  typeof value === 'string' && value.length > 0 && value.length <= max && !value.includes('\u0000');
+
+/**
+ * Why a customer (picked from a search, or restored from a parked order) can't go on a sale, or null: its email
+ * (over 254 units, or a NUL) or its id (over 64, or a NUL) would be refused by order.create's shape check.
+ */
+export function customerRefusal(customer: { id?: string; email?: string }): string | null {
+  return customer.email !== undefined && customer.email !== '' && !sendable(customer.email, 254) ? CUSTOMER_REFUSALS[0]
+    : customer.id !== undefined && customer.id !== '' && !sendable(customer.id, 64) ? CUSTOMER_REFUSALS[1] : null;
+}
+/** Every message `customerRefusal` returns (email, then id). */
+export const CUSTOMER_REFUSALS = (['email', 'id'] as const)
+  .map((field) => `This customer's ${field} can't be sent to the store, so they weren't added to the sale.`);
+
+/** Text with NUL stripped, and over `max` UTF-16 units cut to `max - 1` plus '…', never inside a surrogate pair. */
+export function cutText(text: string, max: number): string {
+  const clean = text.replaceAll('\u0000', '');
+  if (clean.length <= max) return clean;
+  const high = clean.charCodeAt(max - 2);
+  return `${clean.slice(0, high >= 0xd800 && high <= 0xdbff ? max - 2 : max - 1)}…`;
+}
+
+/**
+ * Version 4 (#286): a line's discount made tax-exclusive. An exclusive line's is unchanged; an inclusive line's
+ * gross discount D on its amount A becomes `net(A) − net(A − D)`, exact in millionths (net(A − D) from its stored
+ * taxLines, the tax on A − D; net(A) from `taxMicros`, as the builder taxes), rounded half away from zero.
+ */
+function netDiscountMinor(line: PosOrderLine, pricesIncludeTax: boolean): number {
+  if (!(line.taxInclusive ?? pricesIncludeTax) || line.discountMinor === 0) return line.discountMinor;
+  const ratePpm = line.taxLines.reduce((sum, tax) => sum + tax.ratePpm, 0);
+  const taxAfter = line.taxLines.reduce((sum, tax) => sum + BigInt(tax.taxMicros), 0n);
+  const taxBefore = taxMicros(line.unitPriceMinor * line.quantity, ratePpm, true);
+  return roundMicrosToMinor(BigInt(line.discountMinor) * MICROS_PER_MINOR - taxBefore + taxAfter);
+}
+
+/**
+ * The order.create version an order's stored content makes: 3 with ADR-065's figures, else 2 when its lines are
+ * discounted (ADR-062), else 1. The builder's, and pos_orders v5's migration's for a row with no `sentVersion`.
+ */
+export function contentVersion(order: Pick<PosOrder, 'display' | 'taxByRate' | 'lines'>): 1 | 2 | 3 {
+  return order.display && order.taxByRate ? 3 : order.lines.reduce((sum, line) => sum + line.discountMinor, 0) > 0 ? 2 : 1;
+}
 
 /**
- * Builds the ADR-038 order.create envelope for a PosOrder.
- * A discounted order is version 2 (ADR-062); a discount-free one stays version 1, byte-identical.
+ * Builds the ADR-038 order.create envelope for a PosOrder. It sends the stored order unchanged, so every resend of
+ * an order is byte-identical, and an order stored by an older till goes out exactly as that till sent it:
+ * `finalizeOrder` freezes the sent form (names and labels cut, an unsendable customer email or id left out).
+ * ADR-065's figures make version 3; otherwise a discounted order is version 2 (ADR-062), else version 1, byte-identical.
+ * A version-3 order goes as version 4 (#286) only when `maxVersion` is at least 4 and its `sentVersion` doesn't cap it.
  */
-export function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt = 1): CommandEnvelope<OrderCreatePayload> {
-  // The order's discount is the sum of its lines', so the payload's two always agree.
-  const discountMinor = order.lines.reduce((sum, line) => sum + line.discountMinor, 0);
+export function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt = 1,
+  options?: { maxVersion?: number }): OrderCreateEnvelope {
+  const grossMinor = order.lines.reduce((sum, line) => sum + line.discountMinor, 0);
+  const content = contentVersion(order);
+  const cap = options?.maxVersion === undefined ? order.sentVersion : Math.min(options.maxVersion, order.sentVersion ?? options.maxVersion);
+  if (grossMinor > 0 && cap !== undefined && cap < 2) throw new UnsupportedOrderVersionError(2, cap);
+  // Version 4 only when the cap allows it (the server advertises 4, and no sentVersion holds the order lower).
+  const version = (content === 3 && cap !== undefined && cap >= 4 ? 4
+    : Math.min(content, cap ?? content)) as OrderCreateEnvelope['version'];
+  const lineDiscounts = order.lines.map((line) => version === 4 ? netDiscountMinor(line, order.pricesIncludeTax) : line.discountMinor);
+  // The order's discount is the sum of its lines', on one basis, so the payload's two always agree.
+  const discountMinor = lineDiscounts.reduce((sum, discount) => sum + discount, 0);
+  const email = order.customer?.email;
+  const id = order.customer?.id;
+  // These are the pre-#222 customerId and sessionId checks, kept byte-exact so stored orders resend older tills' bytes; don't replace with sendable.
+  const customerId = typeof id === 'string' && id.length > 0 && id.length <= 64 ? id : undefined;
+  const sessionId = order.sessionId ?? order.lateSessionId;
   return {
-    id: order.commandId, type: 'order.create', version: discountMinor > 0 ? 2 : 1, createdAt: order.createdAt, deviceId, attempt,
+    id: order.commandId, type: 'order.create', version, createdAt: order.createdAt, deviceId, attempt,
     payload: {
       clientOrderId: order.id, createdAt: order.createdAt, currency: order.currency, pricesIncludeTax: order.pricesIncludeTax,
-      lines: order.lines.map((line) => ({
+      lines: order.lines.map((line, i) => ({
         clientLineId: line.id, variantId: line.variantId ?? line.productId, title: line.name,
         quantity: line.quantity, unitPriceMinor: line.unitPriceMinor,
         ...(line.taxInclusive !== undefined ? { taxInclusive: line.taxInclusive } : {}),
-        ...(line.discountMinor > 0 ? { discountMinor: line.discountMinor } : {}),
+        ...(lineDiscounts[i] > 0 ? { discountMinor: lineDiscounts[i] } : {}),
       })),
       payments: order.payments.map((payment) => ({
         clientPaymentId: payment.id, method: payment.method, amountMinor: payment.amountMinor,
@@ -27,9 +104,20 @@ export function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt
       subtotalMinor: order.subtotalMinor,
       ...(discountMinor > 0 ? { discountMinor } : {}),
       taxMinor: order.taxMinor, totalMinor: order.totalMinor,
-      customer: order.customer?.email ? { email: order.customer.email } : null,
+      ...(version >= 3 ? {
+        display: { ...order.display!, lines: order.display!.lines.map(({ lineId, amountMinor, discounts }) => ({
+          clientLineId: lineId, amountMinor, discounts,
+        })) },
+        taxByRate: order.taxByRate!.map(({ ratePpm, code, netMinor, amountMinor, grossMinor }) => ({
+          ratePpm, ...(code !== undefined ? { code } : {}), netMinor, taxMinor: amountMinor, grossMinor,
+        })),
+      } : {}),
+      customer: version >= 3
+        ? (email || customerId ? { ...(email ? { email } : {}), ...(customerId ? { customerId } : {}) } : null)
+        : (email ? { email } : null),
       ...(order.registerId !== undefined ? { registerId: order.registerId } : {}),
       ...(order.cashierRef !== undefined ? { cashierRef: order.cashierRef } : {}),
+      ...(version >= 3 && typeof sessionId === 'string' && sessionId.length > 0 && sessionId.length <= 36 ? { sessionId } : {}),
     },
   };
 }