@tallyui/pos 3.5.3 → 3.7.0

package/src/pos-order/open.ts

@@ -1,10 +1,6 @@
-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 type { RxCollection, RxDatabase } from 'rxdb';
 import { createLogger } from '../logging';
+import { openMigratedCollection } from '../rxdb/open-migrated-collection';
 import { posOrderCollection } from './schema';
 import type { PosOrder } from './types';
 
@@ -15,7 +11,7 @@ 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
+ * `openMigratedCollection`). 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
@@ -37,233 +33,13 @@ export class PosOrderOpenClosedError extends Error {
   }
 }
 
-/** 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.
+ * Adds `pos_orders` to `db` and resolves once no order of an older version is left to migrate.
+ * On DM4 it rejects after the migration has stopped and closes the collection. It rejects with
+ * `PosOrderOpenClosedError` when the database is closing. `closeWaitMs` is for tests only.
+ * See `openMigratedCollection` for the migration and close mechanism.
  */
-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;
-  }
+export function addPosOrderCollection(db: RxDatabase, closeWaitMs = POS_ORDER_MIGRATION_CLOSE_WAIT_MS): Promise<RxCollection<PosOrder>> {
+  return openMigratedCollection<PosOrder>(db, { name: 'pos_orders', creator: posOrderCollection, label: 'addPosOrderCollection',
+    logger: posOrdersLogger, closedError: (name) => new PosOrderOpenClosedError(name) }, closeWaitMs);
 }

package/src/receipt/build-receipt-data.ts

@@ -1,6 +1,7 @@
 import type { Discount, SentOrder } from '../order/types';
 import { roundMicrosToMinor, taxLinesByRate } from '../tax/exact';
 import type { ReceiptConfig, ReceiptData } from './types';
+import { RECEIPT_SCHEMA_VERSION } from './types';
 
 export function buildReceiptData(order: SentOrder, config: ReceiptConfig): ReceiptData {
   // Drops the shared helper's `netMinor` (the Z report's own use): the receipt's tax summary
@@ -29,6 +30,14 @@ export function buildReceiptData(order: SentOrder, config: ReceiptConfig): Recei
   const customer = order.customer?.name || order.customer?.email;
 
   return {
+    schemaVersion: RECEIPT_SCHEMA_VERSION,
+    software: {
+      name: 'WCPOS', plugin_version: '', app_version: '', app_build: '', platform: '', ...config.software,
+    },
+    register: { id: config.register ?? '', name: config.registerName ?? '' },
+    fiscal: {
+      document_type: 'sale', is_reprint: false, reprint_count: 0, qr_payload: '', ...config.fiscal,
+    },
     header: {
       storeName: config.storeName,
       storeAddress: config.storeAddress,

package/src/receipt/index.ts

@@ -1,2 +1,3 @@
 export { buildReceiptData } from './build-receipt-data';
-export type { ReceiptData, ReceiptLineItem, ReceiptConfig } from './types';
+export { RECEIPT_SCHEMA_VERSION } from './types';
+export type { ReceiptData, ReceiptLineItem, ReceiptConfig, ReceiptSoftware, ReceiptRegister, ReceiptFiscal } from './types';

package/src/receipt/types.ts

@@ -1,3 +1,18 @@
+/** WCPOS receipt data schema version these blocks follow (wiki: fiscal groundwork, receipt identity and QR §2). */
+export const RECEIPT_SCHEMA_VERSION = '1.4.0';
+
+/** 1.4 `software`: which software produced the receipt. */
+export interface ReceiptSoftware { name: string; plugin_version: string; app_version: string; app_build: string; platform: string }
+/** 1.4 `register`: `{ id: '', name: '' }` when there is none. */
+export interface ReceiptRegister { id: string; name: string }
+/** 1.4 `fiscal` identity fields a till can know. Sale time, zone and counter come with the per-register sale counter (#475). */
+export interface ReceiptFiscal {
+  document_type: 'sale' | 'refund' | 'void' | 'cancellation' | 'closure' | 'x_report';
+  is_reprint: boolean;
+  reprint_count: number;
+  qr_payload: string;
+}
+
 export interface ReceiptLineItem {
   name: string;
   sku: string;
@@ -11,6 +26,10 @@ export interface ReceiptLineItem {
 }
 
 export interface ReceiptData {
+  schemaVersion: string;
+  software: ReceiptSoftware;
+  register: ReceiptRegister;
+  fiscal: ReceiptFiscal;
   header: {
     storeName: string;
     storeAddress?: string;
@@ -47,5 +66,8 @@ export interface ReceiptConfig {
   storeAddress?: string;
   cashier?: string;
   register?: string;
+  registerName?: string;
+  software?: Partial<ReceiptSoftware>;
+  fiscal?: Partial<ReceiptFiscal>;
   taxLabels?: Record<number, string>;
 }

package/src/register/index.ts

@@ -5,6 +5,7 @@ export type { LedgerRow, Movement } from './expected';
 export { parseMinor, validAmount, countVariance, overThreshold, closeNeedsApproval, denominationTotal, varianceText } from './register-count.helpers';
 export { denominations } from './register-count.denominations';
 export { registerSessionSchema, registerSessionCollection, cashMovementSchema, closureSchema } from './schemas';
+export { addRegisterSessionCollection, RegisterSessionOpenClosedError, registerSessionsLogger, REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS } from './open';
 export type { RegisterSession, CashMovement, Closure } from './schemas';
 export {
   mintUuid, readRegister, ensureRegister, observeRegister$, getBoundRegisterId, readBoundRegister, bindRegister,
@@ -12,7 +13,7 @@ export {
 } from './register-document';
 export type { RegisterHost, RegisterCounters, RegisterBucket, RegisterStore, RegisterDocument } from './register-document';
 export {
-  RegisterSessionRequiredError, RegisterSessionClosedError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, openSessionSelector,
+  RegisterSessionRequiredError, RegisterSessionClosedError, RegisterNeedsUpgradeError, isKnownSessionStatus, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, openSessionSelector,
   requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure,
 } from './session-store';
 export type { RegisterSessionCollection, CashMovementCollection, ClosureCollection } from './session-store';

package/src/register/open.ts

@@ -0,0 +1,30 @@
+import type { RxCollection, RxDatabase } from 'rxdb';
+import { createLogger } from '../logging';
+import { openMigratedCollection } from '../rxdb/open-migrated-collection';
+import { registerSessionCreator, type RegisterSession } from './schemas';
+
+/** `addRegisterSessionCollection`'s logger: attach a sink to see dropped status writes during close. */
+export const registerSessionsLogger = createLogger('register-sessions');
+
+/** How long a close waits for the open; see `openMigratedCollection` for the cancellation mechanism. */
+export const REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS = 10_000;
+
+/** The database is closing; no session is lost. Reopen the database and call the opener again. */
+export class RegisterSessionOpenClosedError extends Error {
+  readonly code = 'REGISTER_SESSION_OPEN_CLOSED';
+  constructor(readonly databaseName: string) {
+    super(`addRegisterSessionCollection: database ${databaseName} closed during the open; reopen it and open register_sessions again`);
+    this.name = 'RegisterSessionOpenClosedError';
+  }
+}
+
+/**
+ * Adds `register_sessions` and resolves once no older session is left to migrate; the register
+ * document, a local document, is kept. On DM4 it rejects after migration stops and closes the collection.
+ * A closing database rejects with `RegisterSessionOpenClosedError`; `closeWaitMs` is for tests only.
+ * See `openMigratedCollection` for the migration and close mechanism.
+ */
+export function addRegisterSessionCollection(db: RxDatabase, closeWaitMs = REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS): Promise<RxCollection<RegisterSession>> {
+  return openMigratedCollection<RegisterSession>(db, { name: 'register_sessions', creator: registerSessionCreator,
+    label: 'addRegisterSessionCollection', logger: registerSessionsLogger, closedError: (name) => new RegisterSessionOpenClosedError(name) }, closeWaitMs);
+}

package/src/register/register-commands.ts

@@ -51,7 +51,7 @@ export function sessionOpenCommand(s: RegisterSession): BuiltCommand {
   } satisfies RegisterSessionOpenPayload };
 }
 
-export function sessionTransitionCommand(s: RegisterSession & { status_at: string }): BuiltCommand {
+export function sessionTransitionCommand(s: RegisterSession & { status: RegisterSessionTransitionPayload['status']; status_at: string }): BuiltCommand {
   return { key: `session.transition:${s.id}:${s.status}:${s.status_at}`, type: 'register.session.transition', version: 1, payload: {
     sessionId: s.id, status: s.status, at: s.status_at,
     ...(s.status !== 'closed' || s.counted == null ? {} : { counted: s.counted }),
@@ -92,6 +92,8 @@ export function reconcileRegisterCommands({ commands, sessions, movements, closu
   commands: RegisterCommandCollection; sessions: RegisterSessionCollection; movements: CashMovementCollection;
   closures: ClosureCollection; host: RegisterHost; storeKey: string; registerId: string; now?: string; observed?: RegisterSession[];
 }): Promise<string[]> {
+  // `conflict` and `superseded` are local states derived from the store's answers (ADR-078 decision 9), never sent as a transition.
+  const sentStatus = (s: RegisterSession): s is RegisterSession & { status: RegisterSessionTransitionPayload['status'] } => s.status === 'open' || s.status === 'counting' || s.status === 'closed';
   let registers = chains.get(commands);
   if (!registers) chains.set(commands, registers = new Map());
   const run = (registers.get(registerId) ?? Promise.resolve()).then(async () => {
@@ -113,10 +115,10 @@ export function reconcileRegisterCommands({ commands, sessions, movements, closu
       ]);
       const events = (observed ?? []).filter((row) => row.id === session.id && !transitioned.has(session.id)
         && row.status !== session.status && row.status !== 'closed')
-        .flatMap((row) => row.status_at == null ? [] : [sessionTransitionCommand({ ...row, status_at: row.status_at })]);
+        .flatMap((row) => row.status_at == null || !sentStatus(row) ? [] : [sessionTransitionCommand({ ...row, status_at: row.status_at })]);
       events.push(...entries.filter((entry) => entry.type !== 'void').map(movementCommand),
         ...entries.filter((entry) => entry.type === 'void').map(movementCommand));
-      if (session.status_at != null) events.push(sessionTransitionCommand({ ...session, status_at: session.status_at }));
+      if (session.status_at != null && sentStatus(session)) events.push(sessionTransitionCommand({ ...session, status_at: session.status_at }));
       return { session, number: closureRows[0]?.number, built: [sessionOpenCommand(session), ...events,
         ...closureRows.map((closure) => closureCommand(closure))] };
     }));

package/src/register/register-document.ts

@@ -3,7 +3,7 @@
  * (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`.
  *
  * The host is whatever carries local documents: `register_sessions`, created with
- * `registerSessionCollection` (a Tally database has no database-level local documents). WCPOS
+ * `addRegisterSessionCollection` (a Tally database has no database-level local documents). WCPOS
  * keys its buckets by site UUID plus a numeric WooCommerce store id; TallyUI keys them by one
  * neutral `storeKey` the app derives (for example the connector id plus the base URL). WCPOS's
  * module-level snapshots (`getRegisterSnapshot`, `getRegisterId`, `getCurrentBoundRegisterId`)

package/src/register/schemas.ts

@@ -1,7 +1,7 @@
 /**
  * The register's local collections (ADR-032): sessions, cash movements and closures. Port
  * provenance (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`, where they are at versions 1, 0
- * and 1; each starts at version 0 here.
+ * and 1; sessions are at version 1 here (ADR-078), movements and closures at version 0.
  *
  * All three are local only, like `pos_orders`: the app creates them and never replicates them
  * (a replicated collection must never take local writes, #53). WCPOS's outbox fields
@@ -13,8 +13,9 @@
  * by method) holds integers. People (`opened_by`, `created_by`, ...) are the backend's user id
  * as a string, since not every backend's is a number.
  */
-import { addRxPlugin, type JsonSchema, type RxJsonSchema } from 'rxdb';
+import { addRxPlugin, type JsonSchema, type RxCollectionCreator, type RxJsonSchema } from 'rxdb';
 import { RxDBLocalDocumentsPlugin } from 'rxdb/plugins/local-documents';
+import { RxDBMigrationSchemaPlugin } from 'rxdb/plugins/migration-schema';
 
 type TenderMap = Record<string, number>;
 
@@ -23,7 +24,10 @@ export interface RegisterSession {
   register_id: string;
   /** The app's neutral store key (see `bindRegister`). */
   store_key?: string | null;
-  status: 'open' | 'counting' | 'closed';
+  /** Stored status is an open string so a later local state costs no migration (ADR-078 decision 9); the union names today's states. */
+  status: 'open' | 'counting' | 'closed' | 'conflict' | 'superseded';
+  /** The store session this local id was resumed as (ADR-078 decision 2), never the session that superseded it; null until a resume. */
+  server_session_id?: string | null;
   /** The store's day the session opened, `yyyy-MM-dd`. */
   business_day?: string;
   opened_at_gmt: string;
@@ -103,10 +107,11 @@ const nullableMinor: JsonSchema = { type: ['integer', 'null'] };
 const tenders: JsonSchema = { type: 'object', additionalProperties: minor };
 
 export const registerSessionSchema: RxJsonSchema<RegisterSession> = {
-  title: 'Register sessions', version: 0, primaryKey: 'id', type: 'object', additionalProperties: false,
+  title: 'Register sessions', version: 1, primaryKey: 'id', type: 'object', additionalProperties: false,
   properties: {
     id, register_id: id, store_key: nullableText,
-    status: { type: 'string', enum: ['open', 'counting', 'closed'], maxLength: 8 },
+    status: { type: 'string', maxLength: 20 },
+    server_session_id: { ...nullableText, default: null },
     business_day: { type: 'string', maxLength: 10 },
     opened_at_gmt: text, opened_by: nullableText,
     expected_float_minor: nullableMinor, counted_float_minor: minor, opening_variance_minor: nullableMinor,
@@ -126,13 +131,26 @@ export const registerSessionSchema: RxJsonSchema<RegisterSession> = {
 };
 
 /**
- * Create `register_sessions` with this: the register document (`register-document.ts`) is a
- * local document on this collection, since a Tally database has no database-level ones.
+ * Internal: used by `addRegisterSessionCollection` and tests on a database that never held an older version.
+ * The register document (`register-document.ts`) is a local document on this collection.
  */
-export function registerSessionCollection() {
+export function registerSessionCreator(): RxCollectionCreator<RegisterSession> {
   // addRxPlugin ignores a plugin it already has.
   addRxPlugin(RxDBLocalDocumentsPlugin);
-  return { schema: registerSessionSchema, localDocuments: true } as const;
+  addRxPlugin(RxDBMigrationSchemaPlugin);
+  return { schema: registerSessionSchema, localDocuments: true, migrationStrategies: { 1: (doc) => {
+    // Every migrated row gets the field, the same shape a new row gets from the schema default.
+    doc.server_session_id ??= null;
+    return doc;
+  } } };
+}
+
+/**
+ * @deprecated Use `addRegisterSessionCollection` to open register_sessions.
+ * Kept so old callers compile but fail at start instead of migrating on RxDB's own path.
+ */
+export function registerSessionCollection(): never {
+  throw new Error('registerSessionCollection() is gone: open register_sessions with await addRegisterSessionCollection(db). Adding it with addCollections would run RxDB\'s own migration of schema version 1, which can lose sessions (ADR-078, #371).');
 }
 
 export const cashMovementSchema: RxJsonSchema<CashMovement> = {

package/src/register/session-store.ts

@@ -40,6 +40,15 @@ export class RegisterSessionClosedError extends Error {
   }
 }
 
+/** A stored session status outside the known set (written by a later build); its message can be shown to a cashier as it is. */
+export class RegisterNeedsUpgradeError extends Error {
+  readonly code = 'REGISTER_NEEDS_UPGRADE';
+  constructor() {
+    super('This till has register data from a newer version of the app. Update the app to continue.');
+    this.name = 'RegisterNeedsUpgradeError';
+  }
+}
+
 /** ADR-068 6a: movement amounts must be safe integers, positive for paid_in/paid_out and zero for no_sale. */
 export class RegisterMovementAmountError extends Error {
   constructor(type: 'paid_in' | 'paid_out' | 'no_sale', amountMinor: number) {
@@ -71,13 +80,21 @@ export class RegisterMovementStrandedError extends Error {
   }
 }
 
-/** Every move a session may make. Nothing leaves `closed`; everything else is refused. */
+/** Every move a session may make. Nothing leaves `closed`; everything else is refused.
+ * No cashier move leaves `conflict` or `superseded`; the store's answers set them (ADR-078). */
 const TRANSITIONS: Record<RegisterSession['status'], readonly RegisterSession['status'][]> = {
   open: ['counting', 'closed'],
   counting: ['open', 'closed'],
   closed: [],
+  conflict: [],
+  superseded: [],
 };
 
+/** Whether this build knows the stored session status. */
+export function isKnownSessionStatus(status: string): boolean {
+  return Object.hasOwn(TRANSITIONS, status);
+}
+
 /**
  * The session as stored, by primary key, not a cached `findOne(id)`: a status write that skips that
  * query (a server sync) can't leave a live-session check stale (docs/rxdb/query-cache-reads.md). A
@@ -97,6 +114,7 @@ async function readClosure(closures: ClosureCollection | undefined, id: string)
 async function requireLiveSession(sessions: RegisterSessionCollection, id: string) {
   const session = await readSession(sessions, id);
   if (!session) throw new RegisterSessionRequiredError();
+  if (!isKnownSessionStatus(session.status)) throw new RegisterNeedsUpgradeError();
   if (session.status === 'closed') throw new RegisterSessionClosedError();
   return session;
 }
@@ -247,6 +265,7 @@ async function transition(
   const at = new Date().toISOString();
   // The guard runs again on the latest document, so a racing write can't slip past it.
   return row.incrementalModify((doc) => {
+    if (!isKnownSessionStatus(doc.status)) throw new RegisterNeedsUpgradeError();
     if (doc.status === 'closed' && status === 'closed') return doc;
     if (doc.status === 'closed') throw new RegisterSessionClosedError();
     if (!TRANSITIONS[doc.status].includes(status)) throw new Error(`invalid_session_transition:${doc.status}->${status}`);

package/src/register/use-register-session.ts

@@ -75,7 +75,7 @@ const subscribeClosing = (listener: () => void) => {
 const closedFacts = new Set<string>();
 
 export interface UseRegisterSessionOptions {
-  /** `register_sessions`, created with `registerSessionCollection()`; `null` while it opens. */
+  /** `register_sessions`, created with `addRegisterSessionCollection`; `null` while it opens. */
   sessions: RegisterSessionCollection | null;
   /** `cash_movements`; `null` while it opens. */
   movements: CashMovementCollection | null;
@@ -128,9 +128,10 @@ const unwritten = (row: RegisterSession, closureRows: readonly { id: string }[])
 /**
  * The session for this register: first the one an unapplied closure reservation names (its close
  * was interrupted after the number was reserved, perhaps after its row was written), so it can
- * finish; then the open or counting one; then a closed one whose closure row was never written.
+ * finish; then the open or counting one; then a closed one whose closure row was never written; null if any status is unknown.
  */
 function currentSession(rows: RegisterSession[], closureRows: Closure[], reservation: Reservation) {
+  if (rows.some((row) => !store.isKnownSessionStatus(row.status))) return null;
   return (reservation && !reservation.applied ? rows.find((row) => row.id === reservation.row.session_id) : undefined)
     ?? rows.find((row) => row.status !== 'closed')
     ?? rows.find((row) => unwritten(row, closureRows))
@@ -281,6 +282,8 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
 
   return {
     session,
+    /** Any unknown session status in the current snapshot means the register needs upgrade. */
+    needsUpgrade: data?.rows.some((row) => !store.isKnownSessionStatus(row.status)) ?? false,
     movements: entries,
     expected,
     salesCount: sales.length,
@@ -304,6 +307,7 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
        * Refuses with `RegisterSessionAlreadyOpenError` while the register has a live session or
        * another open is running (in any hook instance), and with `RegisterCloseIncompleteError`
        * while an earlier close hasn't finished: a new session would lock the till behind it.
+       * An unknown stored status refuses with `RegisterNeedsUpgradeError`.
        */
       openSession: async (input: { expectedFloatMinor: number | null; countedFloatMinor: number }) => {
         // A double tap: the second call sees the first's promise, set before its first await.
@@ -313,6 +317,7 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
           const { sessions, closures, registerId, register } = live();
           // The storage, not the rendered snapshot or a cached query, which can lag a new write.
           const rows = await readFresh(sessions, { selector: { register_id: registerId } });
+          if (rows.some((row) => !store.isKnownSessionStatus(row.status))) throw new store.RegisterNeedsUpgradeError();
           if (rows.some((row) => row.status !== 'closed')) throw new RegisterSessionAlreadyOpenError();
           // Closure rows before the reservation: a close reserves, then inserts its row, then applies the
           // reservation, so a close landing between the two reads is still caught by one of them.