@tallyui/pos 2.0.0 → 3.0.0-next.0

package/src/pos-order/finalize.ts

@@ -1,20 +1,98 @@
-import type { ServerCapabilities } from '@tallyui/core';
-import type { Order } from '../order/types';
-import type { PosOrder, PosOrderPayment } from './types';
+import { minorUnitDigits, type ServerCapabilities, type TaxRounding } from '@tallyui/core';
+import type { Order, SentOrder } from '../order/types';
+import { DEFAULT_TAX_ROUNDING, taxLinesByRate } from '../tax/exact';
+import { outboxLogger } from '../outbox/logger';
+import { cutText, PAYLOAD_STRING_MAX, sendable } from './command';
+import type { PosOrder, PosOrderLocalWarning, PosOrderPayment } from './types';
 import { uuidv7 } from './uuidv7';
 
 export interface FinalizeOptions {
+  localWarnings?: PosOrderLocalWarning[];
   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;
+  /** Tests only: replaces uuidv7. Every id it returns must be at most 255 characters with no NUL (order.create's bound). */
   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. */
+/** A line name in a refusal message: 60 UTF-16 units of it plus '…' at most, so a cashier-facing message stays short. */
+export const MESSAGE_NAME_MAX = 61;
+
+/** The receipt shows the order as it was stored and sent (Front desk, 2026-09-29). */
+export function withSentForm(order: Order, posOrder: PosOrder): SentOrder {
+  const customer: SentOrder['customer'] = order.customer && { ...order.customer };
+  if (customer && posOrder.customer?.email === undefined) delete customer.email;
+  if (customer && posOrder.customer?.id === undefined) delete customer.id;
+  return { ...order, customer,
+    lineItems: order.lineItems.map((line, i) => ({ ...line, name: posOrder.lines[i].name })),
+    display: posOrder.display ? { ...order.display,
+      lines: order.display.lines.map((line, i) => ({ ...line,
+        discounts: line.discounts.map((discount, j) => ({ ...discount, label: posOrder.display!.lines[i].discounts[j].label })),
+      })),
+    } : order.display,
+  };
+}
+
+/** Bounds apply when the sent form is frozen; the outbox freezes older tills' stored orders before their first send. */
+export function freezeSentForm(order: PosOrder): PosOrder {
+  let changed = false;
+  const lines = order.lines.map((line) => {
+    const name = cutText(line.name, PAYLOAD_STRING_MAX);
+    changed ||= name !== line.name;
+    return { ...line, name };
+  });
+  const display = order.display && { ...order.display, lines: order.display.lines.map((line) => ({ ...line,
+    discounts: line.discounts.map((discount) => {
+      if (discount.label === undefined) return discount;
+      const label = cutText(discount.label, PAYLOAD_STRING_MAX);
+      changed ||= label !== discount.label;
+      return { ...discount, label };
+    }),
+  })) };
+  const payments = order.payments.map((payment) => {
+    if (payment.reference === undefined) return payment;
+    const reference = cutText(payment.reference, PAYLOAD_STRING_MAX);
+    changed ||= reference !== payment.reference;
+    return { ...payment, reference };
+  });
+  const customer = order.customer && { ...order.customer };
+  const localWarnings = [...(order.localWarnings ?? [])];
+  for (const [field, max] of [['email', 254], ['id', 64]] as const) {
+    if (customer && field in customer && !sendable(customer[field], max)) {
+      delete customer[field]; changed = true;
+      if (!localWarnings.some((warning) => warning.code === 'customer_omitted' && warning.field === field)) localWarnings.push({ code: 'customer_omitted', field });
+    }
+  }
+  return changed ? { ...order, lines, payments, customer, ...(display ? { display } : {}), ...(localWarnings.length ? { localWarnings } : {}) } : order;
+}
+
+/**
+ * Why a reference the till passes through without minting would fail order.create's shape check
+ * (over PAYLOAD_STRING_MAX, or a NUL), or null; `label` names it for the cashier. `useSale` also
+ * checks its options and an entered payment reference with it.
+ */
+export function referenceError(label: string, value: string | undefined): string | null {
+  const reason = referenceReason(value);
+  return reason === 'long' ? `${label} is too long (max ${PAYLOAD_STRING_MAX} characters)`
+    : reason === 'nul' ? `${label} contains a NUL character` : null;
+}
+
+/** referenceError's rule as a reason: 'long' (over PAYLOAD_STRING_MAX), 'nul', or null when finalize accepts the value. */
+export function referenceReason(value: string | undefined): 'long' | 'nul' | null {
+  if (value === undefined) return null;
+  if (value.length > PAYLOAD_STRING_MAX) return 'long';
+  return value.includes('\u0000') ? 'nul' : null;
+}
+
+/**
+ * Turns a fully paid builder Order into a pending PosOrder without mutating it. The PosOrder holds the sent form,
+ * frozen: line names and v3 discount labels are cut to PAYLOAD_STRING_MAX with NUL stripped (`cutText`), and a
+ * customer email or id the shape check would refuse is left out, so `toOrderCreateEnvelope` sends it unchanged.
+ */
 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.
@@ -41,6 +119,21 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
   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');
+  // Refused before any id is minted, so such a value never reaches the stored order or the outbox.
+  // v3 also sends each line discount's id and each tax code (as taxByRate's codes); an id is never clamped.
+  const v3 = (options.capabilities?.orderCreate ?? 1) >= 3;
+  const references: Array<[string, string | undefined]> = [['registerId', options.registerId], ['cashierRef', options.cashierRef],
+    ...order.lineItems.flatMap((line, i): Array<[string, string | undefined]> => {
+      const name = `"${cutText(line.name, MESSAGE_NAME_MAX)}"`;
+      return [line.variantId !== undefined ? [`${name}: the variant id`, line.variantId] : [`${name}: the product id`, line.productId],
+        ...(v3 ? order.display.lines[i]?.discounts ?? [] : []).map((d): [string, string] => [`${name}: the discount id`, d.discountId]),
+        ...(v3 ? line.taxLines : []).map((tax): [string, string | undefined] => [`${name}: the tax code`, tax.code])];
+    }),
+    ...order.payments.map((payment): [string, string | undefined] => [`the ${payment.method} payment's reference`, payment.reference])];
+  for (const [field, value] of references) {
+    const message = referenceError(field, value);
+    if (message) throw new Error(`finalize: ${message}`);
+  }
   const newId = options.newId ?? uuidv7;
   const id = newId();
   const lines = order.lineItems.map((line) => ({
@@ -55,6 +148,18 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
     id: newId(), method: payment.method as PosOrderPayment['method'], amountMinor: payment.amountMinor,
     ...(payment.reference !== undefined ? { reference: payment.reference } : {}),
   }));
+  // A warning naming a payment the order no longer has is dropped and logged, never thrown: this runs at sale completion.
+  const localWarnings = options.localWarnings?.flatMap((warning): PosOrderLocalWarning[] => {
+    if (warning.code !== 'payment_reference_dropped') return [{ ...warning }];
+    const index = order.payments.findIndex((payment) => payment.id === warning.paymentId);
+    if (index === -1) {
+      try {
+        outboxLogger.warn('finalize: dropped a localWarnings entry naming an unknown payment', { orderId: id, paymentId: warning.paymentId });
+      } catch { /* a failing sink must never fail the sale */ }
+      return [];
+    }
+    return [{ ...warning, paymentId: payments[index].id }];
+  });
   for (let i = payments.length - 1; i >= 0; i--) {
     const payment = payments[i];
     if (payment.method !== 'cash') continue;
@@ -66,16 +171,49 @@ export function finalizeOrder(order: Order, options: FinalizeOptions = {}): PosO
   if (payments.reduce((sum, p) => sum + p.amountMinor, 0) !== order.totalMinor) {
     throw new Error('finalize: payments do not reconcile');
   }
+  let display: PosOrder['display'];
+  let taxByRate: PosOrder['taxByRate'];
+  if ((options.capabilities?.orderCreate ?? 1) >= 3) {
+    if (order.display.lines.length !== order.lineItems.length
+      || order.display.lines.some((line, i) => line.lineId !== order.lineItems[i].id)) {
+      throw new Error('finalize: display lines do not match the order lines');
+    }
+    display = { currency: order.currency, exponent: minorUnitDigits(order.currency), ...order.display,
+      lines: order.display.lines.map((line, i) => ({
+        lineId: lines[i].id, amountMinor: line.amountMinor,
+        discounts: line.discounts.map(({ discountId, label, amountMinor }) => ({
+          discountId, ...(label !== undefined ? { label } : {}), amountMinor,
+        })),
+      })),
+    };
+    taxByRate = taxLinesByRate(order.lineItems, order.taxMinor, undefined, order.taxRounding).map(({ ratePpm, code, netMinor, amountMinor }) => ({
+      ratePpm, ...(code !== undefined ? { code } : {}), netMinor, amountMinor, grossMinor: netMinor + amountMinor,
+    }));
+    if (display.totalMinor !== order.totalMinor || display.taxMinor !== order.taxMinor
+      || display.taxInclusive !== order.pricesIncludeTax) {
+      throw new Error('finalize: display does not match the order');
+    }
+    if (taxByRate.reduce((sum, rate) => sum + rate.amountMinor, 0) !== order.taxMinor) {
+      throw new Error('finalize: tax by rate does not sum to the order tax');
+    }
+  }
+  // Frozen with the figures (#287), the default included, and never recomputed from the store's later capability:
+  // absent on the snapshot is the default the figures used; `custom` computes as the default but records itself.
+  const rounding = order.taxRounding ?? DEFAULT_TAX_ROUNDING;
+  const taxRounding: TaxRounding = rounding.granularity === 'custom' ? { granularity: 'custom' }
+    : { granularity: rounding.granularity, mode: rounding.mode };
   const now = (options.now ?? new Date()).toISOString();
-  return {
+  return freezeSentForm({
     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,
+    taxMinor: order.taxMinor, totalMinor: order.totalMinor, taxRounding,
+    ...(display && taxByRate ? { display, taxByRate } : {}),
     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 } : {}),
-  };
+    ...(localWarnings?.length ? { localWarnings } : {}),
+  });
 }

package/src/pos-order/index.ts

@@ -1,8 +1,8 @@
-export type { PosOrderSyncStatus, PosOrderLine, PosOrderPayment, PosOrder } from './types';
+export type { PosOrderSyncStatus, PosOrderLine, PosOrderPayment, PosOrderLocalWarning, PosOrderServerFailures, PosOrder } from './types';
 export { uuidv7 } from './uuidv7';
 export { finalizeOrder } from './finalize';
 export type { FinalizeOptions } from './finalize';
-export { toOrderCreateEnvelope } from './command';
+export { toOrderCreateEnvelope, UnsupportedOrderVersionError } from './command';
 export { posOrderSchema, posOrderCollection } from './schema';
 export { addPosOrderCollection, PosOrderOpenClosedError, posOrdersLogger } from './open';
 export { getDeviceId } from './device-id';

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

@@ -1,11 +1,16 @@
+import { knownWarnings } from '@tallyui/core';
 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`.
+ * The orders a cashier must look at: rejected, applied with a known warning, taken after their
+ * session closed (`lateSessionId`) or with local warnings (whatever the sync status), or pending with a `commandId` in
+ * `stuckCommandIds` (the outbox's `OutboxState.stuck`: the store keeps failing it), newest first.
+ * A warning code this till version doesn't know is not shown here (`knownWarnings`). Never changes `orders`.
  */
-export function needsAttention(orders: PosOrder[]): PosOrder[] {
+export function needsAttention(orders: PosOrder[], options: { stuckCommandIds?: readonly string[] } = {}): PosOrder[] {
   return orders.filter((order) => order.syncStatus === 'rejected'
-    || (order.syncStatus === 'applied' && !!order.warnings?.length) || order.lateSessionId !== undefined)
+    || (order.localWarnings?.length ?? 0) > 0
+    || (order.syncStatus === 'applied' && knownWarnings(order.warnings).length > 0) || order.lateSessionId !== undefined
+    || (order.syncStatus === 'pending' && options.stuckCommandIds?.includes(order.commandId) === true))
     .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
 }

package/src/pos-order/open.ts

@@ -12,18 +12,22 @@ import type { PosOrder } from './types';
 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.
+ * After this long waiting for the open, a close gives up rather than hang forever. RxDB 17.5 cancels
+ * a running migration as the database closes, and the open then rejects with
+ * `PosOrderOpenClosedError`; the run reads or writes nothing more in a store the close closes (see
+ * `openPosOrders`). The next open adds the collection without `autoMigrate` and starts and awaits the
+ * migration directly, so it migrates again: RxDB 17.5's `startMigration()` ignores the leftover status
+ * (only `migratePromise()` trusts a leftover `DONE`). It also resets that status, so the record
+ * describes the new run, and removes the run's checkpoint (RxDB bug 1). An order that run already
+ * copied is found equal and skipped, so no order is lost.
  */
 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.
+ * was called once `close()` had begun, the close cancelled its migration (RxDB 17.5), 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';
@@ -50,12 +54,14 @@ function waitWithTimeout(promise: Promise<unknown>, ms: number): Promise<boolean
 /**
  * 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.
+ * one) to the migration. `from` is whichever older version is stored, 0, 1 or 2.
  */
-async function writeOverStaleCopies(collection: RxCollection, from: RxStorageInstance<any, any, any>, to: RxStorageInstance<any, any, any>) {
+async function writeOverStaleCopies(collection: RxCollection, from: RxStorageInstance<any, any, any>, to: RxStorageInstance<any, any, any>,
+  stopIfClosing: () => void) {
   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)) {
+    stopIfClosing();
     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) })));
@@ -71,16 +77,20 @@ async function writeOverStaleCopies(collection: RxCollection, from: RxStorageIns
  * 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
+ * RxDB 17.5.0 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.
+ * collection is added without `autoMigrate` and the migration is started and awaited directly: RxDB
+ * 17.5's `startMigration()` ignores a leftover status (only `migratePromise()` trusts a leftover
+ * `DONE`), which lets a rolled-back or interrupted run migrate again and recovers its orders. The
+ * status is reset first so its record describes the new run, and a failed run's checkpoint is
+ * removed (RxDB bug 1); never an order or its storage.
  *
- * 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.
+ * A close waits for the open, up to `POS_ORDER_MIGRATION_CLOSE_WAIT_MS`, and cancels a running
+ * migration (RxDB 17.5). Called once the database's close has begun, when the close cancels its
+ * migration, 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.
  */
@@ -88,11 +98,11 @@ export async function addPosOrderCollection(db: RxDatabase, closeWaitMs = POS_OR
   // 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.
+  // RxDB 17.5.0 sets the private `closePromise` as `close()` begins (rx-database.js:447), and that
+  // close may already have read `db.onClose` (:473-476), 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
+  // idle (rx-database.js:473-476), 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) {
@@ -105,8 +115,10 @@ export async function addPosOrderCollection(db: RxDatabase, closeWaitMs = POS_OR
 }
 
 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;
+  // Set once RxDB cancels this open's migration while it runs (see `startMigration` below).
+  let cancelled = false;
+  // The backstop, after each await: `closed` is set only once every store is closed (rx-database.js:444).
+  const closing = () => cancelled || 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();
@@ -114,12 +126,22 @@ async function openPosOrders(db: RxDatabase, previous: Promise<unknown> | undefi
     stopIfClosing();
     const mustMigrate = await state.mustMigrate;
     stopIfClosing();
-    if (!mustMigrate) return collection;
+    if (!mustMigrate) {
+      // RxDB 17 blocks writes (COL25) from collection creation until its own `migrationNeeded()` read.
+      // With nothing to migrate, `startMigration()` sets and clears that block on the same memoised `mustMigrate`,
+      // as `migratePromise()` does for `autoMigrate` (rx-collection.js:939-941), so the open resolves only once writes are allowed.
+      await state.startMigration();
+      stopIfClosing();
+      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.
+    // Makes the stored status record describe this run (RUNNING, a fresh count, no leftover error):
+    // RxDB 17.5's `runMigration` overwrites only `count.total` and counts `handled` on from the stored
+    // value. It isn't what recovers a rollback (`startMigration()` ignores the status); "after a
+    // rollback to the version-N app" in open.test-helper.ts pins the record after a recovery.
     await state.updateStatus((status) => {
       // RxDB writes only what the handler changes in place.
       delete status.error;
@@ -127,6 +149,7 @@ async function openPosOrders(db: RxDatabase, previous: Promise<unknown> | undefi
       status.count = { total: 0, handled: 0, percent: 0 };
       return status;
     });
+    // RxDB bug 1, which still reproduces on 17.5.0 (repro 2026-09-29):
     // 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,
@@ -138,35 +161,46 @@ async function openPosOrders(db: RxDatabase, previous: Promise<unknown> | undefi
       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
+    // RxDB bug 2, which still reproduces on 17.5.0 (repro 2026-09-29: a batch in flight when `cancel()`
+    // is called lands after it resolves, 200 of 600 documents): a run's replication can outlive 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
+    // drops the assumed state): a stale copy wins its conflict. 17.5.0 keeps the copy and ignores the
+    // conflict (rx-migration-state.js `masterWrite` returns none); 17.4.0 and 16.21 loop 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.
+    // older-version order that has a copy is skipped in writeOverStaleCopies, so if anything ever
+    // deleted a pos_orders document, its stale copy would win (17.5.0) or RxDB would loop on it (earlier).
     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
+    // migration runs on (rx-database.js:476-485). 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`,
+    // bug 6, which still reproduces on 17.5.0, repro 2026-09-29), 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.
+    // (rx-migration-state.js:357-362), so a rejection there would be unhandled.
+    // Every call a gate lets through that returns a promise is counted until it settles, so a cancelled
+    // open (below) settles only once none of the run's calls can still reach a store the close closes.
+    let inFlight = 0;
+    let drained: (() => void) | undefined;
+    const track = (result: unknown) => {
+      if (!(result instanceof Promise)) return result;
+      inFlight++;
+      return result.finally(() => { if (--inFlight === 0) drained?.(); });
+    };
     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));
+          (closing() && (key === 'bulkWrite' || key === 'findDocumentsById') ? closed(key, args[0]) : track(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;
@@ -177,16 +211,45 @@ async function openPosOrders(db: RxDatabase, previous: Promise<unknown> | undefi
     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) => {
+      stopIfClosing();
+      // RxDB 17.5 sets `canceled` but never reads it, so a cancelled run would otherwise still
+      // create a checkpoint store and a replication after `cancel()` returned.
       const to = gate(current, () => Promise.reject(new PosOrderOpenClosedError(db.name)));
-      if (from.collectionName === collection.name) await writeOverStaleCopies(collection, from, to);
+      if (from.collectionName === collection.name) await writeOverStaleCopies(collection, from, to, stopIfClosing);
+      stopIfClosing();
       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());
+    // RxDB 17.5 hooks the database's and the collection's close to `cancel()` once the run starts
+    // (rx-migration-state.js `startMigration`), and a cancelled run stops for good: its
+    // `startMigration()` never settles. So a cancel while the run is pending settles the open:
+    // `cancelled` first makes the gates above refuse the run's later reads and writes, the open waits
+    // for the calls they already let through (a batch in flight still lands after `cancel()`, bug 2,
+    // and one landing on a store the close has closed would poison the handle, bug 6), then it
+    // rejects with `PosOrderOpenClosedError`. That covers the `db.onClose` path: the close's own
+    // handler waits for the open (up to its limit, so a give-up never hangs) before it closes storage;
+    // `cancel()`'s return does not wait for the drain. A cancel after the run has settled (the catch
+    // below closes the collection) changes nothing.
+    // This assumes 17.5's `cancel()` comes only from the close hooks. RxDB 16.x also calls it at the
+    // end of a successful run, while `running` is still true: the gates would then drop its last
+    // writes and pos_orders would never open. The wrapper depends on 17.5's `cancel()` and `startMigration()`
+    // behaviour, which changed within a minor release before, so @tallyui/pos requires rxdb ~17.5.0.
+    let running = true;
+    let onCancel!: () => void;
+    const cancelledRun = new Promise<void>((resolve) => { onCancel = resolve; });
+    const cancel = state.cancel.bind(state);
+    state.cancel = () => {
+      if (running) {
+        cancelled = true;
+        if (inFlight === 0) onCancel();
+        else drained = onCancel;
+      }
+      return cancel();
+    };
+    // Settles once the migration has: DONE, ERROR with its old storage closed, or cancelled by a close.
+    await Promise.race([state.startMigration(), cancelledRun]).finally(() => { running = false; settled.next(); });
     stopIfClosing();
     const status = (await getSingleDocument(db.internalStore, state.statusDocId))?.data as RxMigrationStatus | undefined;
     stopIfClosing();
@@ -197,7 +260,7 @@ async function openPosOrders(db: RxDatabase, previous: Promise<unknown> | undefi
     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
+    // A backstop: a read of a store the close has closed fails on SQLite with rxdb-premium bug 5's (still on 17.5.0) 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.

package/src/pos-order/schema.ts

@@ -1,5 +1,7 @@
 import { addRxPlugin, type MigrationStrategies, type RxJsonSchema } from 'rxdb';
 import { RxDBMigrationSchemaPlugin } from 'rxdb/plugins/migration-schema';
+import { DEFAULT_TAX_ROUNDING } from '../tax/exact';
+import { contentVersion } from './command';
 import type { PosOrder } from './types';
 
 /**
@@ -8,9 +10,17 @@ import type { PosOrder } from './types';
  * sale), and ADR-065's `display` and `taxByRate`, declared ahead of the job that writes them so a
  * till migrates once. Create the collection with `posOrderCollection()`, never with this schema
  * alone: RxDB refuses a version above 0 without its migration strategies.
+ * Version 3 adds an index on `sessionId` (with its `maxLength`), and the optional `sentVersion` and `downgradedFrom` (the outbox's version fallback), and changes nothing else.
+ * Version 4 adds the optional `localWarnings` and `serverFailures` (the outbox's stuck clock start, latest reason and
+ * isolation, restored when an outbox starts), and changes nothing else.
+ * Version 5 lets `sentVersion` and `downgradedFrom` be 4 (order.create version 4, #286), and changes nothing else. Its
+ * migration sets a row's missing `sentVersion` to its content version, the version any earlier attempt went out at.
+ * Like version 4 (ADR-069), it is one-way: an older build shows no orders.
+ * Version 6 adds `taxRounding`, the strategy the sale's figures were computed with (#287; never sent), and changes
+ * nothing else. Its migration sets it on every older row. It is one-way like version 5.
  */
 export const posOrderSchema: RxJsonSchema<PosOrder> = {
-  version: 2, primaryKey: 'id', type: 'object', additionalProperties: false,
+  version: 6, primaryKey: 'id', type: 'object', additionalProperties: false,
   properties: {
     id: { type: 'string', maxLength: 36 },
     commandId: { type: 'string', maxLength: 36 },
@@ -21,7 +31,7 @@ export const posOrderSchema: RxJsonSchema<PosOrder> = {
     subtotalMinor: { type: 'integer' }, discountMinor: { type: 'integer' },
     taxMinor: { type: 'integer' }, totalMinor: { type: 'integer' },
     syncStatus: { type: 'string', enum: ['pending', 'applied', 'rejected'], maxLength: 10 },
-    note: { type: 'string' }, registerId: { type: 'string' }, sessionId: { type: 'string' }, cashierRef: { type: 'string' },
+    note: { type: 'string' }, registerId: { type: 'string' }, sessionId: { type: 'string', maxLength: 36 }, cashierRef: { type: 'string' },
     lines: { type: 'array', items: {
       type: 'object', properties: {
         id: { type: 'string', maxLength: 36 }, productId: { type: 'string' }, variantId: { type: 'string' },
@@ -49,7 +59,19 @@ export const posOrderSchema: RxJsonSchema<PosOrder> = {
       required: ['code'], additionalProperties: true,
     } },
     error: { type: 'object', properties: { code: { type: 'string' }, message: { type: 'string' } }, required: ['code', 'message'] },
+    localWarnings: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+      code: { type: 'string', maxLength: 64 }, field: { type: 'string', maxLength: 16 }, paymentId: { type: 'string', maxLength: 36 },
+    }, required: ['code'] } },
+    serverFailures: { type: 'object', additionalProperties: false, properties: {
+      since: { type: 'integer', minimum: 0 }, reason: { type: 'string', maxLength: 64 }, isolated: { type: 'boolean' },
+    }, required: ['since', 'reason', 'isolated'] },
     lateSessionId: { type: 'string' },
+    taxRounding: { type: 'object', additionalProperties: false, properties: {
+      granularity: { type: 'string', enum: ['per_order', 'per_line_items', 'per_rate_group_items', 'custom'] },
+      mode: { type: 'string', enum: ['half_away_from_zero', 'half_up'] },
+    }, required: ['granularity'] },
+    sentVersion: { type: 'integer', minimum: 1, maximum: 4 },
+    downgradedFrom: { type: 'integer', minimum: 1, maximum: 4 },
     // The nested objects are closed too: loosening a schema later is free, tightening one costs a migration.
     display: { type: 'object', additionalProperties: false, properties: {
       currency: { type: 'string' }, exponent: { type: 'integer' }, taxInclusive: { type: 'boolean' },
@@ -74,8 +96,8 @@ export const posOrderSchema: RxJsonSchema<PosOrder> = {
     } },
   },
   required: ['id', 'createdAt', 'currency', 'pricesIncludeTax', 'lines', 'subtotalMinor', 'discountMinor', 'taxMinor',
-    'totalMinor', 'payments', 'customer', 'syncStatus', 'commandId', 'updatedAt'],
-  indexes: ['createdAt', 'syncStatus', ['syncStatus', 'createdAt']],
+    'totalMinor', 'payments', 'customer', 'syncStatus', 'commandId', 'updatedAt', 'taxRounding'],
+  indexes: ['createdAt', 'syncStatus', ['syncStatus', 'createdAt'], 'sessionId'],
 };
 
 /**
@@ -96,5 +118,13 @@ export function posOrderCollection(): { schema: RxJsonSchema<PosOrder>; migratio
   // addRxPlugin ignores a plugin it already has.
   addRxPlugin(RxDBMigrationSchemaPlugin);
   const identity = (doc: PosOrder) => doc;
-  return { schema: posOrderSchema, migrationStrategies: { 1: identity, 2: identity } };
+  // Every row before version 5 was built without version 4, so its content version is what any earlier attempt
+  // went out at (a downgraded row has its sentVersion already): each retry then resends those bytes (#286).
+  const recordSent = (doc: PosOrder) => { doc.sentVersion ??= contentVersion(doc); return doc; };
+  // Every row before version 6 was computed per_order + half_away_from_zero: no released build or app set another
+  // strategy (#309's `rounding` reaches a sale only through TaxProvider's props, which no app passes yet). Recording
+  // it means no older sale is ever re-rounded (#287).
+  const recordRounding = (doc: PosOrder) => { doc.taxRounding ??= { ...DEFAULT_TAX_ROUNDING }; return doc; };
+  return { schema: posOrderSchema,
+    migrationStrategies: { 1: identity, 2: identity, 3: identity, 4: identity, 5: recordSent, 6: recordRounding } };
 }