@tallyui/pos 0.1.0 → 2.0.0

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

@@ -0,0 +1,161 @@
+import { useEffect, useRef, useState } from 'react';
+import type { RxCollection, RxError } from 'rxdb';
+import { createLogger } from '../logging';
+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');
+
+export interface UseOrderOutboxOptions {
+  /** Which order store to use (medusapos: the backend's base URL); `null` means no store. A change reopens. */
+  storeKey: string | null;
+  /** 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;
+  /** The device id sent on every command (see `getDeviceId`). A change reopens. */
+  deviceId: string;
+  /** 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). */
+  onOpenError?(error: unknown): void;
+}
+
+export interface UseOrderOutboxResult {
+  /** The open orders collection, or `null` until the current store is ready. */
+  orders: RxCollection<PosOrder> | null;
+  /** The outbox state, or idle until the current store is ready. */
+  state: OutboxState;
+  /** The newest 50 orders, newest first; empty until the current store is ready. */
+  recent: PosOrder[];
+  /**
+   * Stores a finalized order, then flushes. Throws the opening error, or "Orders are not ready.", before the store is ready.
+   * Recording an order whose `id` is already stored, not deleted, with the same money-bearing content (`sameSale`;
+   * a retried `complete()`) counts as stored, never overwrites it, and still flushes, whatever the stored `commandId`
+   * (a requeue mints a new one; the difference is logged at warn). Other content rejects with `OrderContentMismatchError`.
+   */
+  record(posOrder: PosOrder): Promise<void>;
+  /**
+   * Whether the current store holds this order `id`, not deleted, with the same money-bearing content (`sameSale`),
+   * whatever its `commandId`. A primary-key read on the storage instance, past RxDB's query cache. False before the
+   * store is ready; a content mismatch is false and logged at error.
+   */
+  isStored(order: PosOrder): Promise<boolean>;
+  /** Sends pending orders; does nothing before the current store is ready. */
+  flush(): Promise<void>;
+  /** Moves rejected orders back to pending (see `OrderOutbox.requeue`); resolves to 0 before the current store is ready. */
+  requeue(orderIds?: string[]): Promise<number>;
+  /**
+   * The count of `record()` calls not yet settled (resolved or rejected). An app holds sign-out
+   * (closing the store) while this is above 0, because a close that lands under a write stuck in
+   * storage can wait forever, and TallyUI deliberately doesn't bound that close (#155).
+   */
+  savesInFlight: number;
+}
+
+/** Opens the order store for `storeKey`, runs its outbox and watches the recent orders (lifted from medusapos/app, ADR-052). */
+export function useOrderOutbox(options: UseOrderOutboxOptions): UseOrderOutboxResult {
+  const { storeKey, deviceId } = options;
+  const latest = useRef(options);
+  latest.current = options;
+  const current = useRef<{
+    storeKey: string; orders: RxCollection<PosOrder>; outbox: ReturnType<typeof createOrderOutbox>;
+  } | null>(null);
+  const openingError = useRef<unknown>(null);
+  // Order ids already logged for a content mismatch (see `isStored`), for the hook's lifetime: a hung
+  // save's poll re-asks isStored every few seconds, and a mismatch shouldn't get a fresh error each time.
+  const loggedMismatches = useRef(new Set<string>());
+  const [orders, setOrders] = useState<RxCollection<PosOrder> | null>(null);
+  const [state, setState] = useState<OutboxState>(idle);
+  const [recent, setRecent] = useState<PosOrder[]>([]);
+  const savesInFlight = useRef(0);
+  const [savesInFlightCount, setSavesInFlightCount] = useState(0);
+
+  useEffect(() => {
+    let active = true;
+    let dispose: (() => void) | undefined;
+    openingError.current = null;
+    setOrders(null); setState(idle); setRecent([]);
+    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) });
+      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).
+      const history = watchFresh(store.orders, { sort: [{ createdAt: 'desc' }], limit: 50 }).subscribe(setRecent);
+      dispose = () => {
+        outbox.stop(); status.unsubscribe(); history.unsubscribe();
+        void store.close();
+      };
+      setOrders(store.orders);
+      outbox.start();
+    }).catch((error: unknown) => {
+      if (active) openingError.current = error;
+      latest.current.onOpenError?.(error);
+    });
+    return () => { active = false; current.current = null; dispose?.(); };
+  }, [storeKey, deviceId]);
+
+  useEffect(() => {
+    latest.current.onBusy?.(state.sending);
+    return () => latest.current.onBusy?.(false);
+  }, [state.sending]);
+
+  const ready = current.current?.storeKey === storeKey && !!storeKey;
+  return { orders: ready ? orders : null, state: ready ? state : idle, recent: ready ? recent : [],
+    async flush() {
+      const opened = current.current;
+      if (opened && opened.storeKey === storeKey) await opened.outbox.flush();
+    },
+    async requeue(orderIds) {
+      const opened = current.current;
+      return opened && opened.storeKey === storeKey ? opened.outbox.requeue(orderIds) : 0;
+    },
+    savesInFlight: savesInFlightCount,
+    async record(posOrder) {
+      savesInFlight.current++;
+      setSavesInFlightCount(savesInFlight.current);
+      try {
+        const opened = current.current;
+        if (!opened || opened.storeKey !== storeKey) throw openingError.current ?? new Error('Orders are not ready.');
+        try {
+          await opened.orders.insert(posOrder);
+        } catch (error) {
+          // useSale's retry hands over the order a failed save already stored (complete() is idempotent,
+          // ADR-052). RxDB 16's insert throws RxError code 'CONFLICT' for an existing primary key, with the
+          // stored document in `parameters.writeError.documentInDb`. The same id and content means it is stored, even
+          // under another commandId: a requeue mints one, and requiring it stuck the tender on Retry (medusapos #79).
+          const stored = (error as RxError)?.code === 'CONFLICT' ? (error as RxError).parameters.writeError : undefined;
+          const inDb = stored?.status === 409 ? stored.documentInDb : undefined;
+          if (!inDb || inDb._deleted) throw error;
+          if (!sameSale(inDb, posOrder)) throw new OrderContentMismatchError(posOrder.id);
+          if (inDb.commandId !== posOrder.commandId) {
+            outboxLogger.warn('Recorded an order stored under another commandId', { orderId: posOrder.id,
+              storedCommandId: inDb.commandId, recordedCommandId: posOrder.commandId });
+          }
+        }
+        if (current.current === opened) void opened.outbox.flush();
+      } finally {
+        savesInFlight.current--;
+        setSavesInFlightCount(savesInFlight.current);
+      }
+    },
+    async isStored(order) {
+      const opened = current.current;
+      if (!opened || opened.storeKey !== storeKey) return false;
+      const [stored] = await opened.orders.storageInstance.findDocumentsById([order.id], false);
+      if (!stored || stored._deleted) return false;
+      if (sameSale(stored, order)) return true;
+      if (!loggedMismatches.current.has(order.id)) {
+        loggedMismatches.current.add(order.id);
+        outboxLogger.error('A stored order has this id with different content', { orderId: order.id });
+      }
+      return false;
+    },
+  };
+}

package/src/pos-order/command.ts

@@ -0,0 +1,35 @@
+import type { CommandEnvelope, OrderCreatePayload } from '@tallyui/core';
+import type { PosOrder } from './types';
+
+/**
+ * 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.
+ */
+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);
+  return {
+    id: order.commandId, type: 'order.create', version: discountMinor > 0 ? 2 : 1, createdAt: order.createdAt, deviceId, attempt,
+    payload: {
+      clientOrderId: order.id, createdAt: order.createdAt, currency: order.currency, pricesIncludeTax: order.pricesIncludeTax,
+      lines: order.lines.map((line) => ({
+        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 } : {}),
+      })),
+      payments: order.payments.map((payment) => ({
+        clientPaymentId: payment.id, method: payment.method, amountMinor: payment.amountMinor,
+        ...(payment.tenderedMinor !== undefined ? { tenderedMinor: payment.tenderedMinor } : {}),
+        ...(payment.changeMinor !== undefined ? { changeMinor: payment.changeMinor } : {}),
+        ...(payment.reference !== undefined ? { reference: payment.reference } : {}),
+      })),
+      subtotalMinor: order.subtotalMinor,
+      ...(discountMinor > 0 ? { discountMinor } : {}),
+      taxMinor: order.taxMinor, totalMinor: order.totalMinor,
+      customer: order.customer?.email ? { email: order.customer.email } : null,
+      ...(order.registerId !== undefined ? { registerId: order.registerId } : {}),
+      ...(order.cashierRef !== undefined ? { cashierRef: order.cashierRef } : {}),
+    },
+  };
+}

package/src/pos-order/device-id.ts

@@ -0,0 +1,23 @@
+import { uuidv7 } from './uuidv7';
+
+/** The device id used when no storage is available, shared by every caller in this process. */
+let processId: string | undefined;
+
+/**
+ * Returns this device's id (a UUIDv7), stored under `key` in `storage` (web storage, or an app's
+ * equivalent) and minted on first use; medusapos passes `'medusapos.register_id'`. With no storage,
+ * or one that throws on read or write, it falls back to one id per process.
+ */
+export function getDeviceId(storage: { getItem(key: string): string | null; setItem(key: string, value: string): void } | null,
+  key: string): string {
+  try {
+    if (storage) {
+      const existing = storage.getItem(key);
+      if (existing) return existing;
+      const id = uuidv7();
+      storage.setItem(key, id);
+      return id;
+    }
+  } catch { /* Use the process id when web storage is unavailable. */ }
+  return processId ??= uuidv7();
+}

package/src/pos-order/finalize.ts

@@ -0,0 +1,81 @@
+import type { ServerCapabilities } from '@tallyui/core';
+import type { Order } from '../order/types';
+import type { PosOrder, PosOrderPayment } from './types';
+import { uuidv7 } from './uuidv7';
+
+export interface FinalizeOptions {
+  registerId?: string;
+  // No `sessionId`: `stampSession` is the only way to set a sale's session, because it checks the
+  // session is live. Tests and migrations that need a stamped order spread `{ ...order, sessionId }`.
+  cashierRef?: string;
+  now?: Date;
+  newId?: () => string;
+  /** The store's `order.create` capability (ADR-062); `undefined` is treated as 1. */
+  capabilities?: ServerCapabilities;
+}
+
+/** Turns a fully paid builder Order into a pending PosOrder without mutating it. */
+export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosOrder {
+  if (!order.lineItems.length) throw new Error('finalize: no lines');
+  // Defence in depth: the builder already clamps every discount to >= 0, so this should never fire.
+  if (order.discountMinor < 0
+    || order.lineItems.some((line) => line.discountMinor < 0)
+    || order.discounts.some((d) => d.amountMinor < 0)) {
+    throw new Error('finalize: negative discount');
+  }
+  // An old plugin would reject or mis-apply a version-2 payload; this guard rejects a discount only when the store can't take it yet (ADR-062).
+  // Checked as "any non-zero" rather than "> 0": defence in depth, since the builder already clamps every
+  // discount to >= 0, so a negative amountMinor should never reach here.
+  const hasDiscount = order.discountMinor !== 0
+    || order.lineItems.some((line) => line.discountMinor !== 0)
+    || order.discounts.some((d) => d.amountMinor !== 0);
+  if (hasDiscount && (options.capabilities?.orderCreate ?? 1) < 2) {
+    throw new Error('finalize: discounts are not supported by the server yet (order.create v2)');
+  }
+  for (const payment of order.payments) {
+    if (payment.method !== 'cash' && payment.method !== 'external') {
+      throw new Error(`finalize: unsupported payment method ${payment.method}`);
+    }
+  }
+  if (order.paidMinor < order.totalMinor) throw new Error('finalize: underpaid');
+  let change = order.paidMinor - order.totalMinor;
+  const cash = order.payments.reduce((sum, p) => sum + (p.method === 'cash' ? p.amountMinor : 0), 0);
+  if (change > cash) throw new Error('finalize: change exceeds cash');
+  const newId = options.newId ?? uuidv7;
+  const id = newId();
+  const lines = order.lineItems.map((line) => ({
+    id: newId(), productId: line.productId,
+    ...(line.variantId !== undefined ? { variantId: line.variantId } : {}),
+    name: line.name, sku: line.sku, quantity: line.quantity, unitPriceMinor: line.unitPriceMinor,
+    discountMinor: line.discountMinor, netMinor: line.netMinor,
+    taxLines: line.taxLines.map((tax) => ({ ...tax })),
+    ...(line.priceTaxModeConverted ? { taxInclusive: line.taxInclusive } : {}),
+  }));
+  const payments: PosOrderPayment[] = order.payments.map((payment) => ({
+    id: newId(), method: payment.method as PosOrderPayment['method'], amountMinor: payment.amountMinor,
+    ...(payment.reference !== undefined ? { reference: payment.reference } : {}),
+  }));
+  for (let i = payments.length - 1; i >= 0; i--) {
+    const payment = payments[i];
+    if (payment.method !== 'cash') continue;
+    payment.tenderedMinor = payment.amountMinor;
+    payment.changeMinor = Math.min(change, payment.tenderedMinor);
+    payment.amountMinor -= payment.changeMinor;
+    change -= payment.changeMinor;
+  }
+  if (payments.reduce((sum, p) => sum + p.amountMinor, 0) !== order.totalMinor) {
+    throw new Error('finalize: payments do not reconcile');
+  }
+  const now = (options.now ?? new Date()).toISOString();
+  return {
+    id, createdAt: now, updatedAt: now, commandId: newId(), syncStatus: 'pending',
+    currency: order.currency, pricesIncludeTax: order.pricesIncludeTax, lines, payments,
+    subtotalMinor: order.subtotalMinor, discountMinor: order.discountMinor,
+    taxMinor: order.taxMinor, totalMinor: order.totalMinor,
+    customer: order.customer ? { id: order.customer.id, name: order.customer.name,
+      ...(order.customer.email !== undefined ? { email: order.customer.email } : {}) } : null,
+    ...(order.note ? { note: order.note } : {}),
+    ...(options.registerId !== undefined ? { registerId: options.registerId } : {}),
+    ...(options.cashierRef !== undefined ? { cashierRef: options.cashierRef } : {}),
+  };
+}

package/src/pos-order/index.ts

@@ -0,0 +1,10 @@
+export type { PosOrderSyncStatus, PosOrderLine, PosOrderPayment, PosOrder } from './types';
+export { uuidv7 } from './uuidv7';
+export { finalizeOrder } from './finalize';
+export type { FinalizeOptions } from './finalize';
+export { toOrderCreateEnvelope } from './command';
+export { posOrderSchema, posOrderCollection } from './schema';
+export { addPosOrderCollection, PosOrderOpenClosedError, posOrdersLogger } from './open';
+export { getDeviceId } from './device-id';
+export { needsAttention } from './needs-attention';
+export { sameSale, OrderContentMismatchError } from './same-sale';

package/src/pos-order/needs-attention.ts

@@ -0,0 +1,11 @@
+import type { PosOrder } from './types';
+
+/**
+ * The orders a cashier must look at: rejected, applied with warnings, or taken after their session
+ * closed (`lateSessionId`, whatever the sync status), newest first. Never changes `orders`.
+ */
+export function needsAttention(orders: PosOrder[]): PosOrder[] {
+  return orders.filter((order) => order.syncStatus === 'rejected'
+    || (order.syncStatus === 'applied' && !!order.warnings?.length) || order.lateSessionId !== undefined)
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}

package/src/pos-order/open.ts

@@ -0,0 +1,206 @@
+import {
+  deepEqual, defaultConflictHandler, getChangedDocumentsSince, getRxReplicationMetaInstanceSchema, getSingleDocument, hasEncryption, newRxError,
+  overwritable, rxStorageInstanceToReplicationHandler, type RxCollection, type RxDatabase, type RxStorageInstance,
+} from 'rxdb';
+import { getOldCollectionMeta, migrateDocumentData, type RxMigrationStatus } from 'rxdb/plugins/migration-schema';
+import { Subject, takeUntil } from 'rxjs';
+import { createLogger } from '../logging';
+import { posOrderCollection } from './schema';
+import type { PosOrder } from './types';
+
+/** `addPosOrderCollection`'s logger: attach a sink to see, for example, the status writes a closing open dropped. */
+export const posOrdersLogger = createLogger('pos-orders');
+
+/**
+ * After this long waiting for a stuck migration, a close gives up rather than hang forever. The
+ * migration is left running, but it reads or writes nothing more in a store the close closes (see
+ * `openPosOrders`). The next open finds the leftover status, resets it and the
+ * checkpoint (as any DM4 does), and migrates again. An order that run already copied is found
+ * equal and skipped, so the worst case is an `ERROR` status on the next open, never a lost order.
+ */
+export const POS_ORDER_MIGRATION_CLOSE_WAIT_MS = 10_000;
+
+/**
+ * `addPosOrderCollection` stopped, before any further write, because its database is closing: it
+ * was called once `close()` had begun, or the close stopped waiting for it (after
+ * `POS_ORDER_MIGRATION_CLOSE_WAIT_MS`). No order is lost: reopen the database and call it again.
+ */
+export class PosOrderOpenClosedError extends Error {
+  readonly code = 'POS_ORDER_OPEN_CLOSED';
+  constructor(readonly databaseName: string) {
+    super(`addPosOrderCollection: database ${databaseName} closed during the open; reopen it and open pos_orders again`);
+    this.name = 'PosOrderOpenClosedError';
+  }
+}
+
+/** Every open per database so far, settled or not: one promise, so a close waits for all of them
+ * across DM4 retries with one handler, and a new open's reset waits for every earlier migration. */
+const latestOpens = new WeakMap<RxDatabase, Promise<unknown>>();
+/** Databases whose close stopped waiting (the limit passed), so storage is closing under the open. */
+const closedUnderOpen = new WeakSet<RxDatabase>();
+
+/** Resolves true once `promise` settles, or false after `ms`. */
+function waitWithTimeout(promise: Promise<unknown>, ms: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), ms);
+    promise.finally(() => { clearTimeout(timer); resolve(true); });
+  });
+}
+
+/**
+ * Writes each order of the stored older version over its differing copy in the current version,
+ * through the same write RxDB's migration makes, and leaves orders without a copy (and any deleted
+ * one) to the migration. `from` is whichever older version is stored, 0 or 1.
+ */
+async function writeOverStaleCopies(collection: RxCollection, from: RxStorageInstance<any, any, any>, to: RxStorageInstance<any, any, any>) {
+  const handler = rxStorageInstanceToReplicationHandler(to, defaultConflictHandler, collection.database.token, true);
+  for (let page = await getChangedDocumentsSince(from, 200); page.documents.length > 0;
+    page = await getChangedDocumentsSince(from, 200, page.checkpoint)) {
+    const copies = new Map((await to.findDocumentsById(page.documents.map((doc) => doc.id), false)).map((copy) => [copy.id, copy]));
+    const rows = await Promise.all(page.documents.filter((doc) => copies.has(doc.id) && !doc._deleted).map(async (doc) =>
+      ({ assumedMasterState: copies.get(doc.id), newDocumentState: await migrateDocumentData(collection, from.schema.version, doc) })));
+    const stale = rows.filter((row) => row.newDocumentState && !deepEqual(row.assumedMasterState, row.newDocumentState));
+    // A write error (an older state the current version refuses) stops the run with DM4, as RxDB's own write does.
+    if (stale.length > 0) await handler.masterWrite(stale);
+  }
+}
+
+/**
+ * Adds `pos_orders` to `db` and resolves once no order of an older version is left to migrate. The one
+ * sanctioned way to open it (ADR-032 amendment 2). On DM4 it rejects after the migration has
+ * stopped and closes the collection, so the app can surface the error and open again; it never
+ * deletes an order.
+ *
+ * RxDB 16.21 trusts the status its last migration stored: a leftover `ERROR` rejects
+ * `migratePromise` at once while the migration keeps running (a close then interrupts it), and a
+ * `DONE` left before a rollback resolves it before the older version's new orders have moved. So the
+ * collection is added without `autoMigrate`, the status and a failed run's checkpoint are reset
+ * (never an order or its storage), and the migration itself is awaited.
+ *
+ * A close waits for the whole open, up to `POS_ORDER_MIGRATION_CLOSE_WAIT_MS`. Called once the
+ * database's close has begun, or when the close stops waiting, it rejects with
+ * `PosOrderOpenClosedError` (`code: 'POS_ORDER_OPEN_CLOSED'`) before any further write: reopen and
+ * call it again. Any other rejection (DM4, a storage error) is a real failure.
+ *
+ * `closeWaitMs` is for tests only; the first open on a database sets it for that database's close.
+ */
+export async function addPosOrderCollection(db: RxDatabase, closeWaitMs = POS_ORDER_MIGRATION_CLOSE_WAIT_MS): Promise<RxCollection<PosOrder>> {
+  // The reset below runs before RxDB elects which tab migrates, so a second tab could reset a
+  // migration another tab is running. TallyUI is single-instance (ADR-061).
+  if (db.multiInstance) throw new Error('addPosOrderCollection: multiInstance databases are not supported (ADR-061)');
+  // RxDB 16.21.1 sets the private `closePromise` as `close()` begins (rx-database.js:356), and that
+  // close may already have read `db.onClose` (:381), so it would not wait for this open.
+  if (db.closed || (db as unknown as { closePromise: unknown }).closePromise) throw new PosOrderOpenClosedError(db.name);
+  // Registered before the first await. RxDB's close reads `db.onClose` once, when the database is
+  // idle (rx-database.js:381), and creating or removing a store doesn't keep it busy: a handler
+  // added after an await missed that close, which then closed storage under the open (2026-09-27).
+  const previous = latestOpens.get(db);
+  if (!previous) {
+    db.onClose.push(() => waitWithTimeout(latestOpens.get(db)!, closeWaitMs)
+      .then((settled) => { if (!settled) closedUnderOpen.add(db); }));
+  }
+  const opening = openPosOrders(db, previous);
+  latestOpens.set(db, Promise.all([previous, opening.catch(() => undefined)]));
+  return opening;
+}
+
+async function openPosOrders(db: RxDatabase, previous: Promise<unknown> | undefined): Promise<RxCollection<PosOrder>> {
+  // The backstop, after each await: `closed` is set only once every store is closed (rx-database.js:353).
+  const closing = () => closedUnderOpen.has(db) || db.closed;
+  const stopIfClosing = () => { if (closing()) throw new PosOrderOpenClosedError(db.name); };
+  const { pos_orders: collection } = await db.addCollections({ pos_orders: { ...posOrderCollection(), autoMigrate: false } });
+  const state = collection.getMigrationState();
+  try {
+    stopIfClosing();
+    const mustMigrate = await state.mustMigrate;
+    stopIfClosing();
+    if (!mustMigrate) return collection;
+    // Never reset a still-settling earlier attempt's checkpoint out from under it: each new
+    // migration on this database starts only once the one before it has fully settled.
+    await previous;
+    stopIfClosing();
+    // Older-version orders exist (their collection record is there), so any stored status is a past run's.
+    await state.updateStatus((status) => {
+      // RxDB writes only what the handler changes in place.
+      delete status.error;
+      status.status = 'RUNNING';
+      status.count = { total: 0, handled: 0, percent: 0 };
+      return status;
+    });
+    // A failed run leaves its checkpoint, which can be past an order it never copied (a queued
+    // batch that finds its docs taken by a failed one still stores its checkpoint). The next run
+    // would skip that order, then remove its storage. So every run starts from the first order,
+    // as RxDB's own first run does; an order already copied is found equal and skipped.
+    const old = (await state.oldCollectionMeta)!.data.schema;
+    stopIfClosing();
+    const checkpoint = await db.storage.createStorageInstance({ databaseName: db.name, collectionName: `rx-migration-state-meta-pos_orders-${old.version}`,
+      databaseInstanceToken: db.token, multiInstance: db.multiInstance, options: {}, password: db.password,
+      schema: getRxReplicationMetaInstanceSchema(old, hasEncryption(old)), devMode: overwritable.isDevMode() });
+    await (closing() ? checkpoint.close() : checkpoint.remove());
+    stopIfClosing();
+    // RxDB bug 2: `cancel()` stops `this.replicationState`, which `migrateStorage` never sets, so each
+    // run's replication outlives the run. It wakes only on the stored older version's change stream (one
+    // shared across instances, as on memory storage), then writes its checkpoint into the store a later
+    // run removed (an unhandled `removed already`) and its conflicts into the older version. So that
+    // stream ends once the run has settled. And RxDB never overwrites a copy in the current version (it
+    // drops the assumed state): a stale copy wins its conflict, or 16.21 loops on it. Yet a copy is only
+    // ever an earlier older-version state (the collection opens only once the older version is gone), so
+    // the newer state goes first. A rare exception: after a rollback, an older build's one-time carry-over
+    // (for example medusapos's Dexie import, run again from a leftover Dexie database, after a failed
+    // removal or from an old tab) can bulk-insert an older state of order A into an empty older version
+    // while the current version holds A as sent. This overwrite then makes A pending again, and it is sent
+    // twice; the server's commandId idempotency is what stops a double charge. Also, a deleted
+    // older-version order that has a copy is skipped in writeOverStaleCopies, so RxDB would still
+    // loop on it if anything ever deleted a pos_orders document.
+    const settled = new Subject<void>();
+    // Once the close stops waiting it closes this version's store and the internal store while RxDB's
+    // migration runs on (rx-database.js:381-385). A write called on a closed SQLite instance throws
+    // inside its transaction and poisons every later write on the handle until restart (rxdb-premium
+    // bug 6), while its close waits for a write called before it (sqlite-storage-instance.js `close`,
+    // openWriteCount$; reproduced). So from the moment the close gives up, before it closes any store,
+    // the run's reads and writes of those two stores stop here. A refused one of this version rejects
+    // the run's push, which RxDB catches as a replication error (upstream.js:372), so the run ends in
+    // ERROR. Status writes are dropped instead: RxDB never awaits the per-order ones
+    // (rx-migration-state.js:274-278), so a rejection there would be unhandled.
+    const gate = <T extends object>(target: T, closed: (key: 'bulkWrite' | 'findDocumentsById', first: any[]) => Promise<unknown>): T =>
+      new Proxy(target, { get: (t, key) => {
+        const value = Reflect.get(t, key);
+        return typeof value !== 'function' ? value : (...args: any[]) =>
+          (closing() && (key === 'bulkWrite' || key === 'findDocumentsById') ? closed(key, args[0]) : value.apply(t, args));
+      } });
+    const internalStore = gate(db.internalStore, async (key, first) => {
+      const ids = key === 'bulkWrite' ? first.map((row: { document: { id: string } }) => row.document.id) : first;
+      posOrdersLogger.warn(`The database closed during the migration: dropped a ${key === 'bulkWrite' ? 'status write' : 'status read'}`,
+        { database: db.name, ids });
+      return key === 'bulkWrite' ? { error: [] } : [];
+    });
+    state.database = new Proxy(db, { get: (target, key) => (key === 'internalStore' ? internalStore : Reflect.get(target, key)) });
+    const migrateStorage = state.migrateStorage.bind(state);
+    state.migrateStorage = async (from, current, batchSize) => {
+      const to = gate(current, () => Promise.reject(new PosOrderOpenClosedError(db.name)));
+      if (from.collectionName === collection.name) await writeOverStaleCopies(collection, from, to);
+      return migrateStorage(new Proxy(from, { get: (target, key) => {
+        const value = key === 'changeStream' ? () => target.changeStream().pipe(takeUntil(settled)) : Reflect.get(target, key);
+        return typeof value === 'function' ? value.bind(target) : value;
+      } }), to, batchSize);
+    };
+    // Settles once the migration has: DONE, or ERROR with its old storage closed. RxDB's close
+    // does not stop a migration, so a close waits for it rather than closing storage under it.
+    await state.startMigration().finally(() => settled.next());
+    stopIfClosing();
+    const status = (await getSingleDocument(db.internalStore, state.statusDocId))?.data as RxMigrationStatus | undefined;
+    stopIfClosing();
+    // RxDB deletes the older version's collection record only after every order has moved.
+    const oldMeta = status?.status === 'DONE' ? await getOldCollectionMeta(state) : undefined;
+    stopIfClosing();
+    if (status?.status === 'DONE' && !oldMeta) return collection;
+    throw newRxError('DM4', { collection: collection.name, error: status?.error });
+  } catch (error) {
+    await collection.close();
+    // A backstop: a read of a store the close has closed fails on SQLite with rxdb-premium bug 5's raw
+    // `ReferenceError: context is not defined`. The internal store's reads are locked runs, which the
+    // close's idle waits cover (rx-storage-helper.js:486), and no test reaches this; but once the close
+    // has given up, any failure means the open was closed under, so it gets the coded error.
+    throw closing() ? new PosOrderOpenClosedError(db.name) : error;
+  }
+}

package/src/pos-order/same-sale.ts

@@ -0,0 +1,26 @@
+import type { PosOrder } from './types';
+
+type SaleContent = Pick<PosOrder, 'totalMinor' | 'currency' | 'lines' | 'payments'>;
+
+/**
+ * Whether two orders carry the same money-bearing content: `totalMinor` and `currency`; each line's
+ * `id`, `quantity` and `netMinor`, in order; each payment's `method` and `amountMinor`, in order.
+ * An order `id` is minted once per sale (`finalizeOrder`), so the same `id` with other content is a defect.
+ */
+export function sameSale(stored: SaleContent, retried: SaleContent): boolean {
+  return stored.totalMinor === retried.totalMinor && stored.currency === retried.currency
+    && stored.lines.length === retried.lines.length
+    && stored.lines.every((line, i) => { const other = retried.lines[i];
+      return line.id === other.id && line.quantity === other.quantity && line.netMinor === other.netMinor; })
+    && stored.payments.length === retried.payments.length
+    && stored.payments.every((payment, i) => payment.method === retried.payments[i].method
+      && payment.amountMinor === retried.payments[i].amountMinor);
+}
+
+/** A stored order has this order's `id` but other money-bearing content (see `sameSale`): never treated as stored. */
+export class OrderContentMismatchError extends Error {
+  constructor(readonly orderId: string) {
+    super(`Order ${orderId} is already stored with different content`);
+    this.name = 'OrderContentMismatchError';
+  }
+}