@tallyui/pos 3.6.0 → 3.7.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { Money, TaxRounding, StoreSettings, TallyConnector, SyncContext, StoreSettingsChoice, StoreSettingsChoices, ProductTraits, ProductCategory, TraitContext, OrderCreateLine, PaymentMethodKind, CommandServerRefs, CommandWarning, CommandError, ServerCapabilities, OrderCreateEnvelope, RegisterCommandType, RegisterCommandResult, VariantSummary, CommandResult, AnyCommandEnvelope, CommandEnvelope, OrderCreatePayload, RegisterCommandEnvelope } from '@tallyui/core';
+import { Money, TaxRounding, StoreSettings, TallyConnector, SyncContext, StoreSettingsChoice, StoreSettingsChoices, ProductTraits, ProductCategory, TraitContext, OrderCreateLine, PaymentMethodKind, CommandServerRefs, CommandWarning, CommandError, ServerCapabilities, OrderCreateEnvelope, RegisterCommandType, RegisterCommandResult, RegisterSessionTransitionPayload, VariantSummary, CommandResult, AnyCommandEnvelope, CommandEnvelope, OrderCreatePayload, RegisterCommandEnvelope } from '@tallyui/core';
 export { getProductStock, withStockOverlay } from '@tallyui/core';
 export { countFresh, readFresh, watchFresh } from '@tallyui/core/rxdb';
 import * as rxdb from 'rxdb';
@@ -911,27 +911,10 @@ declare class PosOrderOpenClosedError extends Error {
     constructor(databaseName: string);
 }
 /**
- * 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.
  */
 declare function addPosOrderCollection(db: RxDatabase, closeWaitMs?: number): Promise<RxCollection<PosOrder>>;
 
@@ -1072,7 +1055,7 @@ declare const denominations: Record<string, number[]>;
 /**
  * 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
@@ -1091,7 +1074,10 @@ 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;
@@ -1162,16 +1148,31 @@ interface Closure {
 }
 declare 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.
+ * @deprecated Use `addRegisterSessionCollection` to open register_sessions.
+ * Kept so old callers compile but fail at start instead of migrating on RxDB's own path.
  */
-declare function registerSessionCollection(): {
-    readonly schema: RxJsonSchema<RegisterSession>;
-    readonly localDocuments: true;
-};
+declare function registerSessionCollection(): never;
 declare const cashMovementSchema: RxJsonSchema<CashMovement>;
 declare const closureSchema: RxJsonSchema<Closure>;
 
+/** `addRegisterSessionCollection`'s logger: attach a sink to see dropped status writes during close. */
+declare const registerSessionsLogger: Logger;
+/** How long a close waits for the open; see `openMigratedCollection` for the cancellation mechanism. */
+declare const REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS = 10000;
+/** The database is closing; no session is lost. Reopen the database and call the opener again. */
+declare class RegisterSessionOpenClosedError extends Error {
+    readonly databaseName: string;
+    readonly code = "REGISTER_SESSION_OPEN_CLOSED";
+    constructor(databaseName: string);
+}
+/**
+ * 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.
+ */
+declare function addRegisterSessionCollection(db: RxDatabase, closeWaitMs?: number): Promise<RxCollection<RegisterSession>>;
+
 type RegisterHost = RxLocalDocumentMutation<any>;
 type RegisterCounters = {
     last_closure_number: number;
@@ -1255,6 +1256,11 @@ declare class RegisterSessionRequiredError extends Error {
 declare class RegisterSessionClosedError extends Error {
     constructor();
 }
+/** A stored session status outside the known set (written by a later build); its message can be shown to a cashier as it is. */
+declare class RegisterNeedsUpgradeError extends Error {
+    readonly code = "REGISTER_NEEDS_UPGRADE";
+    constructor();
+}
 /** ADR-068 6a: movement amounts must be safe integers, positive for paid_in/paid_out and zero for no_sale. */
 declare class RegisterMovementAmountError extends Error {
     constructor(type: 'paid_in' | 'paid_out' | 'no_sale', amountMinor: number);
@@ -1275,6 +1281,8 @@ declare class RegisterMovementStrandedError extends Error {
         session_id: string;
     });
 }
+/** Whether this build knows the stored session status. */
+declare function isKnownSessionStatus(status: string): boolean;
 declare const openSessionSelector: {
     readonly status: "open";
 };
@@ -1836,6 +1844,7 @@ type BuiltCommand = Pick<RegisterCommand, 'key' | 'type' | 'payload'> & {
 };
 declare function sessionOpenCommand(s: RegisterSession): BuiltCommand;
 declare function sessionTransitionCommand(s: RegisterSession & {
+    status: RegisterSessionTransitionPayload['status'];
     status_at: string;
 }): BuiltCommand;
 declare function movementCommand(m: CashMovement): BuiltCommand;
@@ -1870,7 +1879,7 @@ declare class RegisterApprovalRequiredError extends Error {
     constructor();
 }
 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;
@@ -1911,6 +1920,8 @@ interface UseRegisterSessionOptions {
 }
 declare function useRegisterSession(options: UseRegisterSessionOptions): {
     session: RegisterSession | null;
+    /** Any unknown session status in the current snapshot means the register needs upgrade. */
+    needsUpgrade: boolean;
     movements: CashMovement[];
     expected: Record<string, number>;
     salesCount: number;
@@ -1939,6 +1950,7 @@ declare 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: (input: {
             expectedFloatMinor: number | null;
@@ -2565,4 +2577,4 @@ declare function tenderVoidCollection(): {
     readonly schema: RxJsonSchema<TenderVoid>;
 };
 
-export { type Actor, type AddLineInput, type AppliedDiscount, type BackendNotFound, type BasketLine, CartError, type CashMovement, type CashMovementCollection, type CatalogueEntry, type CatalogueGridColumns, type CatalogueView, type CatalogueViewAction, type CatalogueViewState, type ChargeInput, type ChargeLine, type Closure, type ClosureCollection, type ClosureContext, type ClosureScope, type CommandTransport, type Correction, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, DEFAULT_CATALOGUE_VIEW_STATE, DISCOUNTS_UNSUPPORTED, type Discount, type DisplayLine, type DisplayTotals, type FeeLine, type FinalizeOptions, type HttpTransportOptions, type LedgerRow, type LineItem, type LineTaxLine, type LogEntry, type LogLevel, type LogSink, type Logger, MAX_TENDER_MINOR, MICROS_PER_MINOR, type Movement$1 as Movement, type MovementType, type Order, type OrderBuilder, type OrderBuilderOptions, OrderContentMismatchError, type OrderManager, type OrderManagerOptions, type OrderOutbox, type OrderOutboxOptions, type OrderTaxTotals, type OrderTransportContext, type OutboxState, PRODUCT_SORT_FIELDS, type ParkedOrderSummary, type Payment, type PaymentMethod, type PaymentTransport, type PlanLeg, type PosOrder, type PosOrderLine, type PosOrderLocalWarning, PosOrderOpenClosedError, type PosOrderPayment, type PosOrderServerFailures, type PosOrderSyncStatus, type ProductSort, type ProductSortValue, RECEIPT_SCHEMA_VERSION, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptFiscal, type ReceiptLineItem, type ReceiptRegister, type ReceiptSoftware, type RecordedFigures, RegisterApprovalRequiredError, type RegisterBucket, RegisterCloseIncompleteError, type RegisterCommand, type RegisterCommandCollection, type RegisterCounters, type RegisterDocument, type RegisterFact, type RegisterHost, RegisterIdInvalidError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, type RegisterOutbox, type RegisterOutboxOptions, type RegisterSession, RegisterSessionAlreadyOpenError, RegisterSessionClosedError, type RegisterSessionCollection, RegisterSessionRequiredError, type RegisterStore, RegisterTenderInProgressError, type Repository, type ResolveStoreSettingsOptions, SALE_SAVING, type SaleStage, type SentOrder, type ShippingLine, type SplitTab, type StoreSettingsResolution, type StoreSettingsState, TAX_ROUNDING_MIXED_NOTE, type TaxContext, type TaxLineInput, TaxProvider, type TaxProviderProps, type TaxRateMap, type TenderAction, type TenderKey, type TenderLineId, type TenderPlan, type TenderState, type TenderView, type TenderVoid, type TransportOutcome, UnsupportedOrderVersionError, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterOutboxOptions, type UseRegisterOutboxResult, type UseRegisterSessionOptions, activePlan, addEntryToCart, addPosOrderCollection, advancePerpetual, allocateOrderDiscount, appliedMinor, backToSelling, bindRegister, buildClosureDocument, buildReceiptData, buildXReportDocument, callbackSink, cashMovementSchema, catalogueEntries, catalogueViewReducer, changeMinor, clampClosureScope, closeNeedsApproval, closeSession, closureCommand, closureSchema, computeOrderTax, consoleSink, countVariance, createBackendNotFound, createHttpCommandTransport, createLogger, createOrderBuilder, createOrderManager, createOrderOutbox, createRegisterOutbox, createRepository, denominationTotal, denominations, deriveExpected, deriveSettled, ensureRegister, evenSplitShareMinor, exportCsv, finalizeOrder, findEntryByCode, formatClosureDate, getBoundRegisterId, getDeviceId, inCategory, initTenderState, initialTenderState, isServerDecimal, labelKeys, listCategories, minorToDecimal, mintClosureNumber, mintUuid, movementCommand, movementFieldError, needsAttention, nextSaleCounter, normalizeAmount, normalizeCatalogueViewState, observeRegister$, openSession, openSessionSelector, orderDraftSchema, outboxLogger, overThreshold, parkedOrderSummaries$, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, productCategories, productSortValue, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, requireOpenSession, resolveGridColumns, resolveStoreSettings, restoreOrderDraft, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sessionOpenCommand, sessionTransitionCommand, sortProducts, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, tenderVoidCollection, tenderVoidSchema, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useParkedSales, useRegisterOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure, writeOrderDraft };
+export { type Actor, type AddLineInput, type AppliedDiscount, type BackendNotFound, type BasketLine, CartError, type CashMovement, type CashMovementCollection, type CatalogueEntry, type CatalogueGridColumns, type CatalogueView, type CatalogueViewAction, type CatalogueViewState, type ChargeInput, type ChargeLine, type Closure, type ClosureCollection, type ClosureContext, type ClosureScope, type CommandTransport, type Correction, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, DEFAULT_CATALOGUE_VIEW_STATE, DISCOUNTS_UNSUPPORTED, type Discount, type DisplayLine, type DisplayTotals, type FeeLine, type FinalizeOptions, type HttpTransportOptions, type LedgerRow, type LineItem, type LineTaxLine, type LogEntry, type LogLevel, type LogSink, type Logger, MAX_TENDER_MINOR, MICROS_PER_MINOR, type Movement$1 as Movement, type MovementType, type Order, type OrderBuilder, type OrderBuilderOptions, OrderContentMismatchError, type OrderManager, type OrderManagerOptions, type OrderOutbox, type OrderOutboxOptions, type OrderTaxTotals, type OrderTransportContext, type OutboxState, PRODUCT_SORT_FIELDS, type ParkedOrderSummary, type Payment, type PaymentMethod, type PaymentTransport, type PlanLeg, type PosOrder, type PosOrderLine, type PosOrderLocalWarning, PosOrderOpenClosedError, type PosOrderPayment, type PosOrderServerFailures, type PosOrderSyncStatus, type ProductSort, type ProductSortValue, RECEIPT_SCHEMA_VERSION, REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptFiscal, type ReceiptLineItem, type ReceiptRegister, type ReceiptSoftware, type RecordedFigures, RegisterApprovalRequiredError, type RegisterBucket, RegisterCloseIncompleteError, type RegisterCommand, type RegisterCommandCollection, type RegisterCounters, type RegisterDocument, type RegisterFact, type RegisterHost, RegisterIdInvalidError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, RegisterNeedsUpgradeError, type RegisterOutbox, type RegisterOutboxOptions, type RegisterSession, RegisterSessionAlreadyOpenError, RegisterSessionClosedError, type RegisterSessionCollection, RegisterSessionOpenClosedError, RegisterSessionRequiredError, type RegisterStore, RegisterTenderInProgressError, type Repository, type ResolveStoreSettingsOptions, SALE_SAVING, type SaleStage, type SentOrder, type ShippingLine, type SplitTab, type StoreSettingsResolution, type StoreSettingsState, TAX_ROUNDING_MIXED_NOTE, type TaxContext, type TaxLineInput, TaxProvider, type TaxProviderProps, type TaxRateMap, type TenderAction, type TenderKey, type TenderLineId, type TenderPlan, type TenderState, type TenderView, type TenderVoid, type TransportOutcome, UnsupportedOrderVersionError, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterOutboxOptions, type UseRegisterOutboxResult, type UseRegisterSessionOptions, activePlan, addEntryToCart, addPosOrderCollection, addRegisterSessionCollection, advancePerpetual, allocateOrderDiscount, appliedMinor, backToSelling, bindRegister, buildClosureDocument, buildReceiptData, buildXReportDocument, callbackSink, cashMovementSchema, catalogueEntries, catalogueViewReducer, changeMinor, clampClosureScope, closeNeedsApproval, closeSession, closureCommand, closureSchema, computeOrderTax, consoleSink, countVariance, createBackendNotFound, createHttpCommandTransport, createLogger, createOrderBuilder, createOrderManager, createOrderOutbox, createRegisterOutbox, createRepository, denominationTotal, denominations, deriveExpected, deriveSettled, ensureRegister, evenSplitShareMinor, exportCsv, finalizeOrder, findEntryByCode, formatClosureDate, getBoundRegisterId, getDeviceId, inCategory, initTenderState, initialTenderState, isKnownSessionStatus, isServerDecimal, labelKeys, listCategories, minorToDecimal, mintClosureNumber, mintUuid, movementCommand, movementFieldError, needsAttention, nextSaleCounter, normalizeAmount, normalizeCatalogueViewState, observeRegister$, openSession, openSessionSelector, orderDraftSchema, outboxLogger, overThreshold, parkedOrderSummaries$, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, productCategories, productSortValue, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, registerSessionsLogger, requireOpenSession, resolveGridColumns, resolveStoreSettings, restoreOrderDraft, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sessionOpenCommand, sessionTransitionCommand, sortProducts, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, tenderVoidCollection, tenderVoidSchema, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useParkedSales, useRegisterOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure, writeOrderDraft };

package/dist/index.js

@@ -2121,7 +2121,7 @@ function posOrderCollection() {
   };
 }
 
-// src/pos-order/open.ts
+// src/rxdb/open-migrated-collection.ts
 import {
   deepEqual,
   defaultConflictHandler,
@@ -2135,16 +2135,6 @@ import {
 } from "rxdb";
 import { getOldCollectionMeta, migrateDocumentData } from "rxdb/plugins/migration-schema";
 import { Subject, takeUntil } from "rxjs";
-var posOrdersLogger = createLogger("pos-orders");
-var POS_ORDER_MIGRATION_CLOSE_WAIT_MS = 1e4;
-var PosOrderOpenClosedError = class extends Error {
-  constructor(databaseName) {
-    super(`addPosOrderCollection: database ${databaseName} closed during the open; reopen it and open pos_orders again`);
-    this.databaseName = databaseName;
-    this.name = "PosOrderOpenClosedError";
-  }
-  code = "POS_ORDER_OPEN_CLOSED";
-};
 var latestOpens = /* @__PURE__ */ new WeakMap();
 var closedUnderOpen = /* @__PURE__ */ new WeakSet();
 function waitWithTimeout(promise, ms) {
@@ -2157,35 +2147,40 @@ function waitWithTimeout(promise, ms) {
   });
 }
 async function writeOverStaleCopies(collection, from, to, stopIfClosing) {
+  const primaryKey = collection.schema.primaryPath;
   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 copies = new Map((await to.findDocumentsById(page.documents.map((doc) => doc[primaryKey]), false)).map((copy) => [copy[primaryKey], copy]));
+    const rows = await Promise.all(page.documents.filter((doc) => copies.has(doc[primaryKey]) && !doc._deleted).map(async (doc) => ({ assumedMasterState: copies.get(doc[primaryKey]), newDocumentState: await migrateDocumentData(collection, from.schema.version, doc) })));
     const stale = rows.filter((row) => row.newDocumentState && !deepEqual(row.assumedMasterState, row.newDocumentState));
     if (stale.length > 0) await handler.masterWrite(stale);
   }
 }
-async function addPosOrderCollection(db, closeWaitMs = POS_ORDER_MIGRATION_CLOSE_WAIT_MS) {
-  if (db.multiInstance) throw new Error("addPosOrderCollection: multiInstance databases are not supported (ADR-061)");
-  if (db.closed || db.closePromise) throw new PosOrderOpenClosedError(db.name);
-  const previous = latestOpens.get(db);
+async function openMigratedCollection(db, opener, closeWaitMs) {
+  const { name, label, closedError } = opener;
+  if (db.multiInstance) throw new Error(`${label}: multiInstance databases are not supported (ADR-061)`);
+  if (db.closed || db.closePromise) throw closedError(db.name);
+  const opens = latestOpens.get(db) ?? /* @__PURE__ */ new Map();
+  latestOpens.set(db, opens);
+  const previous = opens.get(name);
   if (!previous) {
-    db.onClose.push(() => waitWithTimeout(latestOpens.get(db), closeWaitMs).then((settled) => {
+    db.onClose.push(() => waitWithTimeout(latestOpens.get(db).get(name), closeWaitMs).then((settled) => {
       if (!settled) closedUnderOpen.add(db);
     }));
   }
-  const opening = openPosOrders(db, previous);
-  latestOpens.set(db, Promise.all([previous, opening.catch(() => void 0)]));
+  const opening = openCollection(db, opener, previous);
+  opens.set(name, Promise.all([previous, opening.catch(() => void 0)]));
   return opening;
 }
-async function openPosOrders(db, previous) {
+async function openCollection(db, opener, previous) {
+  const { name, creator, logger, closedError } = opener;
   let cancelled = false;
   const closing = () => cancelled || closedUnderOpen.has(db) || db.closed;
   const stopIfClosing = () => {
-    if (closing()) throw new PosOrderOpenClosedError(db.name);
+    if (closing()) throw closedError(db.name);
   };
-  const { pos_orders: collection } = await db.addCollections({ pos_orders: { ...posOrderCollection(), autoMigrate: false } });
+  const { [name]: collection } = await db.addCollections({ [name]: { ...creator(), autoMigrate: false } });
   const state = collection.getMigrationState();
   try {
     stopIfClosing();
@@ -2208,7 +2203,7 @@ async function openPosOrders(db, previous) {
     stopIfClosing();
     const checkpoint = await db.storage.createStorageInstance({
       databaseName: db.name,
-      collectionName: `rx-migration-state-meta-pos_orders-${old.version}`,
+      collectionName: `rx-migration-state-meta-${name}-${old.version}`,
       databaseInstanceToken: db.token,
       multiInstance: db.multiInstance,
       options: {},
@@ -2234,7 +2229,7 @@ async function openPosOrders(db, previous) {
     } });
     const internalStore = gate(db.internalStore, async (key, first) => {
       const ids = key === "bulkWrite" ? first.map((row) => row.document.id) : first;
-      posOrdersLogger.warn(
+      logger.warn(
         `The database closed during the migration: dropped a ${key === "bulkWrite" ? "status write" : "status read"}`,
         { database: db.name, ids }
       );
@@ -2244,7 +2239,7 @@ async function openPosOrders(db, previous) {
     const migrateStorage = state.migrateStorage.bind(state);
     state.migrateStorage = async (from, current, batchSize) => {
       stopIfClosing();
-      const to = gate(current, () => Promise.reject(new PosOrderOpenClosedError(db.name)));
+      const to = gate(current, () => Promise.reject(closedError(db.name)));
       if (from.collectionName === collection.name) await writeOverStaleCopies(collection, from, to, stopIfClosing);
       stopIfClosing();
       return migrateStorage(new Proxy(from, { get: (target, key) => {
@@ -2279,10 +2274,31 @@ async function openPosOrders(db, previous) {
     throw newRxError("DM4", { collection: collection.name, error: status?.error });
   } catch (error) {
     await collection.close();
-    throw closing() ? new PosOrderOpenClosedError(db.name) : error;
+    throw closing() ? closedError(db.name) : error;
   }
 }
 
+// src/pos-order/open.ts
+var posOrdersLogger = createLogger("pos-orders");
+var POS_ORDER_MIGRATION_CLOSE_WAIT_MS = 1e4;
+var PosOrderOpenClosedError = class extends Error {
+  constructor(databaseName) {
+    super(`addPosOrderCollection: database ${databaseName} closed during the open; reopen it and open pos_orders again`);
+    this.databaseName = databaseName;
+    this.name = "PosOrderOpenClosedError";
+  }
+  code = "POS_ORDER_OPEN_CLOSED";
+};
+function addPosOrderCollection(db, closeWaitMs = POS_ORDER_MIGRATION_CLOSE_WAIT_MS) {
+  return openMigratedCollection(db, {
+    name: "pos_orders",
+    creator: posOrderCollection,
+    label: "addPosOrderCollection",
+    logger: posOrdersLogger,
+    closedError: (name) => new PosOrderOpenClosedError(name)
+  }, closeWaitMs);
+}
+
 // src/pos-order/device-id.ts
 var processId;
 function getDeviceId(storage, key) {
@@ -2395,6 +2411,7 @@ var denominations = {
 // src/register/schemas.ts
 import { addRxPlugin as addRxPlugin2 } from "rxdb";
 import { RxDBLocalDocumentsPlugin } from "rxdb/plugins/local-documents";
+import { RxDBMigrationSchemaPlugin as RxDBMigrationSchemaPlugin2 } from "rxdb/plugins/migration-schema";
 var id = { type: "string", maxLength: 36 };
 var text = { type: "string" };
 var nullableText = { type: ["string", "null"] };
@@ -2403,7 +2420,7 @@ var nullableMinor = { type: ["integer", "null"] };
 var tenders = { type: "object", additionalProperties: minor };
 var registerSessionSchema = {
   title: "Register sessions",
-  version: 0,
+  version: 1,
   primaryKey: "id",
   type: "object",
   additionalProperties: false,
@@ -2411,7 +2428,8 @@ var registerSessionSchema = {
     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,
@@ -2435,9 +2453,16 @@ var registerSessionSchema = {
   required: ["id", "register_id", "status", "opened_at_gmt", "counted_float_minor"],
   indexes: [["register_id", "status"]]
 };
-function registerSessionCollection() {
+function registerSessionCreator() {
   addRxPlugin2(RxDBLocalDocumentsPlugin);
-  return { schema: registerSessionSchema, localDocuments: true };
+  addRxPlugin2(RxDBMigrationSchemaPlugin2);
+  return { schema: registerSessionSchema, localDocuments: true, migrationStrategies: { 1: (doc) => {
+    doc.server_session_id ??= null;
+    return doc;
+  } } };
+}
+function registerSessionCollection() {
+  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).");
 }
 var cashMovementSchema = {
   title: "Cash movements",
@@ -2521,6 +2546,27 @@ var closureSchema = {
   indexes: [["register_id"], ["session_id"]]
 };
 
+// src/register/open.ts
+var registerSessionsLogger = createLogger("register-sessions");
+var REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS = 1e4;
+var RegisterSessionOpenClosedError = class extends Error {
+  constructor(databaseName) {
+    super(`addRegisterSessionCollection: database ${databaseName} closed during the open; reopen it and open register_sessions again`);
+    this.databaseName = databaseName;
+    this.name = "RegisterSessionOpenClosedError";
+  }
+  code = "REGISTER_SESSION_OPEN_CLOSED";
+};
+function addRegisterSessionCollection(db, closeWaitMs = REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS) {
+  return openMigratedCollection(db, {
+    name: "register_sessions",
+    creator: registerSessionCreator,
+    label: "addRegisterSessionCollection",
+    logger: registerSessionsLogger,
+    closedError: (name) => new RegisterSessionOpenClosedError(name)
+  }, closeWaitMs);
+}
+
 // src/register/register-document.ts
 import { map as map4 } from "rxjs";
 var REGISTER = "register";
@@ -2760,6 +2806,13 @@ var RegisterSessionClosedError = class extends Error {
     this.name = "RegisterSessionClosedError";
   }
 };
+var RegisterNeedsUpgradeError = class extends Error {
+  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";
+  }
+};
 var RegisterMovementAmountError = class extends Error {
   constructor(type, amountMinor) {
     super(`movement_amount_invalid:${type}:${amountMinor}`);
@@ -2785,8 +2838,13 @@ var RegisterMovementStrandedError = class extends Error {
 var TRANSITIONS = {
   open: ["counting", "closed"],
   counting: ["open", "closed"],
-  closed: []
+  closed: [],
+  conflict: [],
+  superseded: []
 };
+function isKnownSessionStatus(status) {
+  return Object.hasOwn(TRANSITIONS, status);
+}
 async function readSession(sessions, id2) {
   const [stored] = await sessions.storageInstance.findDocumentsById([id2], false);
   return stored;
@@ -2798,6 +2856,7 @@ async function readClosure(closures, id2) {
 async function requireLiveSession(sessions, id2) {
   const session = await readSession(sessions, id2);
   if (!session) throw new RegisterSessionRequiredError();
+  if (!isKnownSessionStatus(session.status)) throw new RegisterNeedsUpgradeError();
   if (session.status === "closed") throw new RegisterSessionClosedError();
   return session;
 }
@@ -2875,6 +2934,7 @@ async function transition(sessions, id2, status, extra = {}) {
   if (row.status === "closed" && status === "closed") return row;
   const at2 = (/* @__PURE__ */ new Date()).toISOString();
   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}`);
@@ -3611,6 +3671,7 @@ function closureCommand(c) {
 }
 var chains = /* @__PURE__ */ new WeakMap();
 function reconcileRegisterCommands({ commands, sessions, movements, closures, host, storeKey, registerId, now, observed }) {
+  const sentStatus = (s) => s.status === "open" || s.status === "counting" || s.status === "closed";
   let registers = chains.get(commands);
   if (!registers) chains.set(commands, registers = /* @__PURE__ */ new Map());
   const run = (registers.get(registerId) ?? Promise.resolve()).then(async () => {
@@ -3625,12 +3686,12 @@ function reconcileRegisterCommands({ commands, sessions, movements, closures, ho
         readFresh(movements, { selector: { session_id: session.id } }),
         session.closure_id ? closures.storageInstance.findDocumentsById([session.closure_id], false) : Promise.resolve([])
       ]);
-      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 })]);
+      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 || !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,
@@ -3699,6 +3760,7 @@ var closedFacts = /* @__PURE__ */ new Set();
 var reservationOf = (register, storeKey, registerId) => register?.stores[storeKey]?.registers?.[registerId]?.closure_reservation;
 var unwritten = (row, closureRows) => row.status === "closed" && row.closure_id === row.id && !closureRows.some((closure) => closure.id === row.id);
 function currentSession(rows, closureRows, reservation) {
+  if (rows.some((row) => !isKnownSessionStatus(row.status))) return null;
   return (reservation && !reservation.applied ? rows.find((row) => row.id === reservation.row.session_id) : void 0) ?? rows.find((row) => row.status !== "closed") ?? rows.find((row) => unwritten(row, closureRows)) ?? null;
 }
 function ledgerRows(orders) {
@@ -3825,6 +3887,8 @@ function useRegisterSession(options) {
   const nameOf = (id2) => !id2 ? "" : id2 === actor.id ? actor.name : labels?.resolveCashierName?.(id2) ?? "";
   return {
     session,
+    /** Any unknown session status in the current snapshot means the register needs upgrade. */
+    needsUpgrade: data?.rows.some((row) => !isKnownSessionStatus(row.status)) ?? false,
     movements: entries,
     expected,
     salesCount: sales.length,
@@ -3847,6 +3911,7 @@ function useRegisterSession(options) {
        * 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) => {
         const key = registerId ?? "";
@@ -3854,6 +3919,7 @@ function useRegisterSession(options) {
         const run = (async () => {
           const { sessions: sessions2, closures: closures2, registerId: registerId2, register: register2 } = live();
           const rows = await readFresh(sessions2, { selector: { register_id: registerId2 } });
+          if (rows.some((row2) => !isKnownSessionStatus(row2.status))) throw new RegisterNeedsUpgradeError();
           if (rows.some((row2) => row2.status !== "closed")) throw new RegisterSessionAlreadyOpenError();
           const closureRows = await readFresh(closures2, { selector: { register_id: registerId2 } });
           const reservation = reservationOf(await readRegister(register2), storeKey, registerId2);
@@ -5784,14 +5850,17 @@ export {
   PRODUCT_SORT_FIELDS,
   PosOrderOpenClosedError,
   RECEIPT_SCHEMA_VERSION,
+  REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS,
   RegisterApprovalRequiredError,
   RegisterCloseIncompleteError,
   RegisterIdInvalidError,
   RegisterMovementAmountError,
   RegisterMovementReasonError,
   RegisterMovementStrandedError,
+  RegisterNeedsUpgradeError,
   RegisterSessionAlreadyOpenError,
   RegisterSessionClosedError,
+  RegisterSessionOpenClosedError,
   RegisterSessionRequiredError,
   RegisterTenderInProgressError,
   SALE_SAVING,
@@ -5801,6 +5870,7 @@ export {
   activePlan,
   addEntryToCart,
   addPosOrderCollection,
+  addRegisterSessionCollection,
   advancePerpetual,
   allocateOrderDiscount,
   appliedMinor,
@@ -5847,6 +5917,7 @@ export {
   inCategory,
   initTenderState,
   initialTenderState,
+  isKnownSessionStatus,
   isServerDecimal,
   labelKeys,
   listCategories,
@@ -5887,6 +5958,7 @@ export {
   registerFactsLogger,
   registerSessionCollection,
   registerSessionSchema,
+  registerSessionsLogger,
   requireOpenSession,
   resolveGridColumns,
   resolveStoreSettings,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/pos",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "type": "module",
   "description": "Shared POS business logic for Tally UI — tax, orders, payments, discounts, receipts",
   "main": "./dist/index.js",
@@ -27,20 +27,20 @@
     "directory": "packages/pos"
   },
   "peerDependencies": {
-    "@tallyui/core": "^3.6.0",
+    "@tallyui/core": "^3.7.0",
     "react": ">=18",
     "rxdb": "~17.5.0",
     "rxjs": ">=7"
   },
   "devDependencies": {
-    "@tallyui/core": "3.6.0",
+    "@tallyui/core": "3.7.0",
     "@types/react": ">=18",
     "react": "^19.2.4",
     "rxdb": "17.5.0",
     "rxjs": "7.8.2",
-    "@tallyui/connector-medusa": "3.6.0",
-    "@tallyui/connector-woocommerce": "3.6.0",
-    "@tallyui/database": "3.6.0"
+    "@tallyui/connector-medusa": "3.7.0",
+    "@tallyui/connector-woocommerce": "3.7.0",
+    "@tallyui/database": "3.7.0"
   },
   "scripts": {
     "build": "tsup",

package/src/index.ts

@@ -76,12 +76,13 @@ export type { PaymentTransport, TenderView, TenderLineId, TenderPlan, SplitTab,
 export { normalizeAmount, isServerDecimal, movementFieldError, deriveExpected, parseMinor, validAmount, countVariance, overThreshold, closeNeedsApproval, denominationTotal, varianceText, denominations } from './register';
 export type { MovementType, LedgerRow, Movement } from './register';
 export { registerSessionSchema, registerSessionCollection, cashMovementSchema, closureSchema } from './register';
+export { addRegisterSessionCollection, RegisterSessionOpenClosedError, registerSessionsLogger, REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS } from './register';
 export type { RegisterSession, CashMovement, Closure } from './register';
 export { registerCommandSchema, registerCommandCollection, registerCommandsLogger, sessionOpenCommand, sessionTransitionCommand, movementCommand, closureCommand, reconcileRegisterCommands } from './register';
 export type { RegisterCommand, RegisterCommandCollection } from './register';
 export { mintUuid, readRegister, ensureRegister, observeRegister$, getBoundRegisterId, readBoundRegister, bindRegister, unbindRegister, nextSaleCounter, mintClosureNumber, advancePerpetual, RegisterIdInvalidError } from './register';
 export type { RegisterHost, RegisterCounters, RegisterBucket, RegisterStore, RegisterDocument } from './register';
-export { RegisterSessionRequiredError, RegisterSessionClosedError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, openSessionSelector, requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure } from './register';
+export { RegisterSessionRequiredError, RegisterSessionClosedError, RegisterNeedsUpgradeError, isKnownSessionStatus, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, openSessionSelector, requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure } from './register';
 export type { RegisterSessionCollection, CashMovementCollection, ClosureCollection } from './register';
 export { deriveSettled, exportCsv, labelKeys, clampClosureScope, selectClosureRows } from './register';
 export type { Correction, RecordedFigures, ClosureScope } from './register';