@tallyui/pos 0.1.0 → 3.0.0-next.0

package/src/pos-order/open.ts

@@ -0,0 +1,269 @@
+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 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, 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';
+  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, 1 or 2.
+ */
+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) })));
+    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 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` 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 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.
+ */
+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 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: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) {
+    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>> {
+  // 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();
+  try {
+    stopIfClosing();
+    const mustMigrate = await state.mustMigrate;
+    stopIfClosing();
+    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();
+    // 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;
+      status.status = 'RUNNING';
+      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,
+    // 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, 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. 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 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: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, 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: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]) : 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;
+      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) => {
+      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, 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);
+    };
+    // 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();
+    // 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 (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.
+    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';
+  }
+}

package/src/pos-order/schema.ts

@@ -0,0 +1,130 @@
+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';
+
+/**
+ * Version 1 adds the optional `sessionId` (ADR-032); nothing else changed from version 0.
+ * Version 2 adds three optional fields and changes nothing else: `lateSessionId` (ADR-032, late
+ * 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: 6, primaryKey: 'id', type: 'object', additionalProperties: false,
+  properties: {
+    id: { type: 'string', maxLength: 36 },
+    commandId: { type: 'string', maxLength: 36 },
+    createdAt: { type: 'string', maxLength: 40 },
+    updatedAt: { type: 'string' },
+    currency: { type: 'string' },
+    pricesIncludeTax: { type: 'boolean' },
+    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', maxLength: 36 }, cashierRef: { type: 'string' },
+    lines: { type: 'array', items: {
+      type: 'object', properties: {
+        id: { type: 'string', maxLength: 36 }, productId: { type: 'string' }, variantId: { type: 'string' },
+        name: { type: 'string' }, sku: { type: 'string' }, quantity: { type: 'integer' },
+        unitPriceMinor: { type: 'integer' }, discountMinor: { type: 'integer' }, netMinor: { type: 'integer' },
+        taxLines: { type: 'array', items: {
+          type: 'object', properties: { code: { type: 'string' }, ratePpm: { type: 'integer' }, taxMicros: { type: 'string' } },
+          required: ['ratePpm', 'taxMicros'],
+        } },
+      },
+      required: ['id', 'productId', 'name', 'sku', 'quantity', 'unitPriceMinor', 'discountMinor', 'netMinor', 'taxLines'],
+    } },
+    payments: { type: 'array', items: {
+      type: 'object', properties: {
+        id: { type: 'string', maxLength: 36 }, method: { type: 'string', enum: ['cash', 'external'] },
+        amountMinor: { type: 'integer' }, tenderedMinor: { type: 'integer' }, changeMinor: { type: 'integer' }, reference: { type: 'string' },
+      }, required: ['id', 'method', 'amountMinor'],
+    } },
+    customer: { type: ['object', 'null'], properties: { id: { type: 'string' }, name: { type: 'string' }, email: { type: 'string' } } },
+    serverRefs: { type: 'object', properties: {
+      orderId: { type: 'string' }, displayId: { type: 'string' }, totalMinor: { type: 'integer' },
+    }, required: ['orderId', 'totalMinor'] },
+    warnings: { type: 'array', items: {
+      type: 'object', properties: { code: { type: 'string', maxLength: 64 } },
+      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' },
+      subtotalMinor: { type: 'integer' }, discountMinor: { type: 'integer' }, taxMinor: { type: 'integer' },
+      totalMinor: { type: 'integer' }, orderDiscountMinor: { type: 'integer' },
+      lines: { type: 'array', items: {
+        type: 'object', additionalProperties: false, properties: {
+          lineId: { type: 'string' }, amountMinor: { type: 'integer' },
+          discounts: { type: 'array', items: {
+            type: 'object', additionalProperties: false,
+            properties: { discountId: { type: 'string' }, label: { type: 'string' }, amountMinor: { type: 'integer' } },
+            required: ['discountId', 'amountMinor'],
+          } },
+        }, required: ['lineId', 'amountMinor', 'discounts'],
+      } },
+    }, required: ['currency', 'exponent', 'taxInclusive', 'subtotalMinor', 'discountMinor', 'taxMinor', 'totalMinor', 'orderDiscountMinor', 'lines'] },
+    taxByRate: { type: 'array', items: {
+      type: 'object', additionalProperties: false, properties: {
+        ratePpm: { type: 'integer' }, code: { type: 'string' }, label: { type: 'string' }, netMinor: { type: 'integer' },
+        amountMinor: { type: 'integer' }, grossMinor: { type: 'integer' },
+      }, required: ['ratePpm', 'netMinor', 'amountMinor', 'grossMinor'],
+    } },
+  },
+  required: ['id', 'createdAt', 'currency', 'pricesIncludeTax', 'lines', 'subtotalMinor', 'discountMinor', 'taxMinor',
+    'totalMinor', 'payments', 'customer', 'syncStatus', 'commandId', 'updatedAt', 'taxRounding'],
+  indexes: ['createdAt', 'syncStatus', ['syncStatus', 'createdAt'], 'sessionId'],
+};
+
+/**
+ * The `pos_orders` collection config, with its migration strategies. Open the collection with
+ * `addPosOrderCollection(db)`, which uses this and settles the migration safely; adding this config
+ * directly leaves RxDB's own open path. `pos_orders` holds sales not yet sent, so no step may drop a
+ * document: versions 1 and 2 only add optional fields, so every order from version 0 or 1 passes
+ * unchanged.
+ *
+ * Within one run, RxDB 16.21 keeps an order that fails the new schema's validation: with a
+ * validating storage the migration stops with DM4 and the order stays in the older version's
+ * storage; without one it is copied as is. **Across runs, RxDB's own open path can lose it**: a
+ * failed run can leave its checkpoint past that order, and the next run then removes the older
+ * version's storage without copying it. `addPosOrderCollection` resets that checkpoint, so use it
+ * (`migration.test.ts`).
+ */
+export function posOrderCollection(): { schema: RxJsonSchema<PosOrder>; migrationStrategies: MigrationStrategies } {
+  // addRxPlugin ignores a plugin it already has.
+  addRxPlugin(RxDBMigrationSchemaPlugin);
+  const identity = (doc: PosOrder) => doc;
+  // 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 } };
+}

package/src/pos-order/types.ts

@@ -0,0 +1,93 @@
+import type { CommandError, CommandServerRefs, CommandWarning, PaymentMethodKind, TaxRounding } from '@tallyui/core';
+import type { DisplayTotals } from '../order/types';
+
+export type PosOrderSyncStatus = 'pending' | 'applied' | 'rejected';
+
+export type PosOrderLocalWarning = { code: 'customer_omitted'; field: 'email' | 'id' }
+  | { code: 'payment_reference_dropped'; paymentId: string };
+/** The outbox's server-failure state for a pending order, kept so a restart restores it. */
+export interface PosOrderServerFailures {
+  /** The stuck clock's start in ms: the outbox's virtual start, which leaves out offline gaps. */
+  since: number;
+  /** The latest server-answered failure reason. */
+  reason: string;
+  /** The order failed when sent alone (as a probe or while isolated), so it is retried alone. */
+  isolated: boolean;
+}
+
+export interface PosOrderLine {
+  id: string;
+  productId: string;
+  variantId?: string;
+  name: string;
+  sku: string;
+  quantity: number;
+  unitPriceMinor: number;
+  /** Line discounts plus the allocated order-discount share, in the line's own tax mode (ADR-062). */
+  discountMinor: number;
+  netMinor: number;
+  taxLines: Array<{ code?: string; ratePpm: number; taxMicros: string }>;
+  /** This line's own tax mode; set only when it was converted from the store's (ADR-038 amendment). */
+  taxInclusive?: boolean;
+}
+
+export interface PosOrderPayment {
+  id: string;
+  method: PaymentMethodKind;
+  amountMinor: number;
+  tenderedMinor?: number;
+  changeMinor?: number;
+  reference?: string;
+}
+
+export interface PosOrder {
+  id: string;
+  createdAt: string;
+  currency: string;
+  pricesIncludeTax: boolean;
+  lines: PosOrderLine[];
+  subtotalMinor: number;
+  discountMinor: number;
+  taxMinor: number;
+  totalMinor: number;
+  payments: PosOrderPayment[];
+  customer: { id?: string; name?: string; email?: string } | null;
+  note?: string;
+  registerId?: string;
+  /**
+   * The register session the sale was taken in (ADR-032): its closure counts this order.
+   * Sent at `order.create` version 3 as the payload's `sessionId` (the stamped or late session, one field).
+   */
+  sessionId?: string;
+  /**
+   * Set only by `useSale`'s late-sale path (ADR-032): the session the sale was taken for, which
+   * refused the stamp after the money was taken. Such an order has no `sessionId`, so no closure
+   * counts it. Sent at `order.create` version 3 as the payload's `sessionId` (the stamped or late session, one field).
+   */
+  lateSessionId?: string;
+  /**
+   * The order.create version every attempt under this `commandId` goes out at: the outbox records it before the first
+   * send, and lowers it only on a downgrade (ADR-065 amendment). Absent means not sent yet (or requeued).
+   */
+  sentVersion?: 1 | 2 | 3 | 4;
+  /** The version first tried, before the downgrade (the order's audit). */
+  downgradedFrom?: 1 | 2 | 3 | 4;
+  /** ADR-065: the receipt's display figures, in integer minor units of `currency` at `exponent`. */
+  display?: DisplayTotals & { currency: string; exponent: number };
+  /** ADR-065: tax by rate, named as `taxLinesByRate` names them (`amountMinor` is the tax). */
+  taxByRate?: Array<{ ratePpm: number; code?: string; label?: string; netMinor: number; amountMinor: number; grossMinor: number }>;
+  /**
+   * The tax rounding the figures were computed with (#287), frozen at finalize; the till's own record, never sent.
+   * Version 6's migration sets the default on every older row.
+   */
+  taxRounding: TaxRounding;
+  cashierRef?: string;
+  syncStatus: PosOrderSyncStatus;
+  commandId: string;
+  serverRefs?: CommandServerRefs;
+  warnings?: CommandWarning[];
+  localWarnings?: PosOrderLocalWarning[];
+  serverFailures?: PosOrderServerFailures;
+  error?: CommandError;
+  updatedAt: string;
+}

package/src/pos-order/uuidv7.ts

@@ -0,0 +1,54 @@
+function format(ms: number, bytes: Uint8Array): string {
+  let timestamp = BigInt(ms);
+  for (let i = 5; i >= 0; i--) {
+    bytes[i] = Number(timestamp & 0xffn);
+    timestamp >>= 8n;
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function createUuidv7(options?: {
+  now?: () => number;
+  randomBytes?: (n: number) => Uint8Array;
+}): () => string {
+  let lastMs = -Infinity;
+  let lastRand = 0n;
+  return () => {
+    const randomBytes = options?.randomBytes;
+    if (!randomBytes && !globalThis.crypto?.getRandomValues) throw new Error('uuidv7: no random source');
+    let ms = Math.max((options?.now ?? Date.now)(), lastMs);
+    let rand = lastRand + 1n;
+    if (ms === lastMs && rand === 2n ** 74n) ms = lastMs + 1;
+    if (ms !== lastMs) {
+      const bytes = randomBytes ? randomBytes(16) : globalThis.crypto.getRandomValues(new Uint8Array(16));
+      rand = (BigInt(bytes[6] & 0x0f) << 8n) | BigInt(bytes[7]);
+      rand = (rand << 6n) | BigInt(bytes[8] & 0x3f);
+      for (let i = 9; i < 16; i++) rand = (rand << 8n) | BigInt(bytes[i]);
+    }
+    lastMs = ms;
+    lastRand = rand;
+    const bytes = new Uint8Array(16);
+    for (let i = 15; i >= 9; i--) {
+      bytes[i] = Number(rand & 0xffn);
+      rand >>= 8n;
+    }
+    bytes[8] = Number(rand & 0x3fn);
+    rand >>= 6n;
+    bytes[7] = Number(rand & 0xffn);
+    bytes[6] = Number(rand >> 8n);
+    return format(ms, bytes);
+  };
+}
+
+const monotonic = createUuidv7();
+
+/** RFC 9562 UUIDv7: monotonic with no arguments; stateless with an explicit timestamp or random source. */
+export function uuidv7(now?: number, randomBytes?: (n: number) => Uint8Array): string {
+  if (now === undefined && randomBytes === undefined) return monotonic();
+  const ms = now ?? Date.now();
+  if (!randomBytes && !globalThis.crypto?.getRandomValues) throw new Error('uuidv7: no random source');
+  return format(ms, randomBytes ? randomBytes(16) : globalThis.crypto.getRandomValues(new Uint8Array(16)));
+}

package/src/product/index.ts

@@ -0,0 +1,2 @@
+export { searchProducts } from './search-products';
+export { withStockOverlay, getProductStock, stockOverlay$, stockOverlayAsOf$ } from './stock';

package/src/product/search-products.ts

@@ -0,0 +1,32 @@
+import type { ProductTraits } from '@tallyui/core';
+
+/**
+ * Filters product documents by a cashier's search term, through traits, so
+ * it works the same on every backend.
+ *
+ * Every word of the term must appear in the product name, SKU or barcode
+ * (case-insensitive, any order). A term that exactly equals a barcode or SKU
+ * returns just those products, so a scanner hit is never buried among name
+ * matches. An empty term returns the input unchanged.
+ */
+export function searchProducts<Doc>(docs: Doc[], term: string, traits: ProductTraits<Doc>): Doc[] {
+  const query = term.trim().toLowerCase();
+  if (!query) return docs;
+
+  const codes = (doc: Doc) =>
+    [...new Set([
+      traits.getSku(doc), traits.getBarcode(doc),
+      ...(traits.getVariants?.(doc) ?? []).flatMap((variant) => [variant.sku, variant.barcode]),
+    ]
+      .filter((code): code is string => Boolean(code))
+      .map((code) => code.toLowerCase()))];
+
+  const exact = docs.filter((doc) => codes(doc).includes(query));
+  if (exact.length) return exact;
+
+  const words = query.split(/\s+/);
+  return docs.filter((doc) => {
+    const haystack = [traits.getName(doc).toLowerCase(), ...codes(doc)].join(' ');
+    return words.every((word) => haystack.includes(word));
+  });
+}

package/src/product/stock.ts

@@ -0,0 +1,25 @@
+import type { RxCollection } from 'rxdb';
+import { map, type Observable } from 'rxjs';
+
+import { STOCK_LEVELS_LAST_PASS } from '@tallyui/core';
+
+// The pure helpers live in core so components can use them without RxDB.
+export { withStockOverlay, getProductStock } from '@tallyui/core';
+
+/** The `stock_levels` collection as a live map of key to stock value. */
+export function stockOverlay$(collection: RxCollection): Observable<Map<string, unknown>> {
+  return collection.find().$.pipe(
+    map((rows) => new Map(rows.map((row) => [row.primary, row.get('value')] as [string, unknown]))),
+  );
+}
+
+/**
+ * When the overlay was last confirmed by a successful pass (ISO 8601), or
+ * undefined before any pass. Read from the collection's local document, so a
+ * tab or screen that does not hold the runner can show it too.
+ */
+export function stockOverlayAsOf$(collection: RxCollection): Observable<string | undefined> {
+  return collection.getLocal$<{ completedAt: string }>(STOCK_LEVELS_LAST_PASS).pipe(
+    map((doc) => doc?.get('completedAt') as string | undefined),
+  );
+}