@tallyui/pos 2.0.0 → 3.0.0-next.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, TallyConnector, SyncContext, StoreSettingsChoice, StoreSettings, StoreSettingsChoices, ProductTraits, PaymentMethodKind, CommandServerRefs, CommandWarning, CommandError, ServerCapabilities, CommandEnvelope, OrderCreatePayload, VariantSummary, CommandResult } from '@tallyui/core';
+import { Money, TaxRounding, TallyConnector, SyncContext, StoreSettingsChoice, StoreSettings, StoreSettingsChoices, ProductTraits, PaymentMethodKind, CommandServerRefs, CommandWarning, CommandError, ServerCapabilities, OrderCreateEnvelope, RegisterCommandType, RegisterCommandResult, 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';
@@ -66,8 +66,10 @@ declare function ratePpmFromPercent(percent: number | string): number;
  * Throws RangeError unless amount and rate are safe integers and rate is non-negative.
  */
 declare function taxMicros(amountMinor: number, ratePpm: number, pricesIncludeTax: boolean): bigint;
-/** Rounds micro-minor-units to integer minor units, half away from zero. */
-declare function roundMicrosToMinor(micros: bigint): number;
+/** #287: `half_up` is Math.round's rule, Vendure's DefaultMoneyStrategy (default-money-strategy.js:19-21). */
+type RoundingMode = 'half_away_from_zero' | 'half_up';
+/** Rounds micro-minor-units to integer minor units, half away from zero unless `mode` says otherwise. */
+declare function roundMicrosToMinor(micros: bigint, mode?: RoundingMode): number;
 interface TaxLineInput {
     unitPriceMinor: number;
     quantity: number;
@@ -93,6 +95,16 @@ interface RateTaxLine {
     netMinor: number;
     amountMinor: number;
 }
+type TaxedLine = {
+    netMinor: number;
+    discountMinor?: number;
+    taxInclusive: boolean;
+    taxLines: readonly {
+        code?: string;
+        ratePpm: number;
+        taxMicros: string;
+    }[];
+};
 /**
  * Groups each line's stacked tax rates (ADR-040: each independently taxes the line's full
  * tax-free base) by `code`+`ratePpm`, floors each group's exact tax to minor units, then
@@ -100,17 +112,10 @@ interface RateTaxLine {
  * so the rates sum to exactly `orderTaxMinor`. A line's `netMinor` is in its OWN tax mode
  * (`taxInclusive`): an inclusive line's net already contains its tax, so its tax-free base is
  * `netMinor − roundMicrosToMinor(Σ its taxMicros)`; an exclusive line's base is `netMinor` as is.
- * Shared by a receipt's tax summary and a Z report's per-rate breakdown.
+ * Shared by a receipt's tax summary and a Z report's per-rate breakdown. That is `per_order`'s split; a `per_line_items` or
+ * `per_rate_group_items` order's rows are `roundedTaxByRate`'s (#287).
  */
-declare function taxLinesByRate(lines: readonly {
-    netMinor: number;
-    taxInclusive: boolean;
-    taxLines: readonly {
-        code?: string;
-        ratePpm: number;
-        taxMicros: string;
-    }[];
-}[], orderTaxMinor: number, taxLabels?: Record<number, string>): RateTaxLine[];
+declare function taxLinesByRate(lines: readonly TaxedLine[], orderTaxMinor: number, taxLabels?: Record<number, string>, rounding?: TaxRounding): RateTaxLine[];
 
 /** Tax rates as integer parts per million (19% = 190000). */
 type TaxRateMap = {
@@ -120,15 +125,24 @@ type TaxRateMap = {
 interface TaxContext {
     /** Tax rate for a tax class as integer parts per million (19% = 190000); the default class when omitted or unknown. */
     getTaxRatePpm(taxClass?: string): number;
+    /** The backend's name for that class's rate, when mapped: a `per_rate_group_items` store groups by name and value (#287). */
+    getTaxRateCode?(taxClass?: string): string | undefined;
     pricesIncludeTax: boolean;
+    /** The store's tax rounding strategy (#287); absent means `per_order`, half away from zero. */
+    rounding?: TaxRounding;
 }
 
+declare const taxLogger: Logger;
 interface TaxProviderProps {
     ratesPpm: Record<string, number>;
     pricesIncludeTax: boolean;
+    /** `ServerCapabilities.taxRounding` (#287); a change restarts an idle sale under it. */
+    rounding?: TaxRounding;
+    /** Tax class → the backend's rate name, for `per_rate_group_items`'s grouping (#287). */
+    rateCodes?: Record<string, string>;
     children: ReactNode;
 }
-declare function TaxProvider({ ratesPpm, pricesIncludeTax, children }: TaxProviderProps): react_jsx_runtime.JSX.Element;
+declare function TaxProvider({ ratesPpm, pricesIncludeTax, rounding, rateCodes, children }: TaxProviderProps): react_jsx_runtime.JSX.Element;
 declare function useTax(): TaxContext;
 
 type StoreSettingsResolution = {
@@ -162,7 +176,11 @@ declare function resolveStoreSettings(options: ResolveStoreSettingsOptions, choi
 
 /** The replication's context with the settings' opaque pricing context; the key is left out when the settings have none. */
 declare function withPricingContext(context: SyncContext, settings: StoreSettings): SyncContext;
-/** `<TaxProvider>`'s props from the same settings, so its tax inclusivity matches the connector's. */
+/**
+ * `<TaxProvider>`'s props from the same settings, so its tax inclusivity and rounding match the store's. `custom`
+ * rounding passes none, the default (#287). An explicit `rounding` prop after the spread still wins, since JSX
+ * applies props in order; so `<TaxProvider {...taxProviderProps(s)} rounding={undefined}>` wipes the store's rounding.
+ */
 declare function taxProviderProps(settings: StoreSettings): Omit<TaxProviderProps, 'children'>;
 
 type StoreSettingsState = {
@@ -187,6 +205,9 @@ type StoreSettingsState = {
  * Resolves the store settings on mount, and again when `connector` or `context` changes by
  * identity (a store switch), so memoise both; the last request wins. `loadChoice` and
  * `saveChoice` are read when a request starts, so inline functions don't trigger a re-resolve.
+ * The ready settings carry the store's `taxRounding` from the capabilities, so `taxProviderProps` passes it on (#324).
+ * The capabilities are read beside the settings, before `ready`, so each resolve emits the settings once, with the
+ * rounding already known: no later change of `settings` holds a sale.
  *
  * ```tsx
  * const store = useStoreSettings({ connector, context, loadChoice, saveChoice });
@@ -225,6 +246,8 @@ interface Order {
     note: string;
     currency: string;
     pricesIncludeTax: boolean;
+    /** The store's tax rounding strategy the figures were computed with (#287), from the sale's tax context; absent is per_order. */
+    taxRounding?: TaxRounding;
     subtotalMinor: number;
     discountMinor: number;
     taxMinor: number;
@@ -236,6 +259,12 @@ interface Order {
     createdAt: string;
     updatedAt: string;
 }
+/** An Order as it was stored and sent, whose customer id may have been left out. */
+type SentOrder = Omit<Order, 'customer'> & {
+    customer: (Omit<CustomerSummary, 'id'> & {
+        id?: string;
+    }) | null;
+};
 /**
  * Figures for showing the cart or a receipt in the store's display mode (ADR-063); never sent to the server.
  * A parked order's saved draft may carry them; they are recomputed from the lines on resume, so never authoritative.
@@ -326,6 +355,7 @@ interface AddLineInput {
         code?: string;
         ratePpm: number;
     }>;
+    taxClass?: string;
 }
 
 interface OrderBuilderOptions {
@@ -354,6 +384,29 @@ interface OrderBuilder {
 }
 declare function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder;
 
+/** A sent line; `discountMinor` is its `lines[].discountMinor` (line discounts + its order share), in its own mode. */
+type BasketLine = {
+    unitPriceMinor: number;
+    quantity: number;
+    discountMinor?: number;
+    taxInclusive: boolean;
+    taxLines: Array<{
+        code?: string;
+        ratePpm: number;
+    }>;
+};
+/**
+ * The till's settlement figures for a sent basket under a store's strategy (#287), computed exactly as a sale computes
+ * them, so a backend can score its own orders against the till (vendurepos/app#38). Each discountMinor is applied as a
+ * fixed line discount in the line's own mode.
+ */
+declare function taxFiguresForBasket(currency: string, pricesIncludeTax: boolean, lines: readonly BasketLine[], rounding?: TaxRounding): {
+    subtotalMinor: number;
+    taxMinor: number;
+    totalMinor: number;
+    taxByRate: RateTaxLine[];
+};
+
 /**
  * Splits an order discount across lines in proportion to each line's pre-order-discount amount,
  * in its own tax mode (ADR-062), with largest-remainder rounding to the minor unit.
@@ -410,6 +463,7 @@ interface ReceiptData {
         orderNumber: string;
         date: string;
         cashier?: string;
+        customer?: string;
         register?: string;
     };
     lineItems: ReceiptLineItem[];
@@ -451,7 +505,7 @@ interface ReceiptConfig {
     taxLabels?: Record<number, string>;
 }
 
-declare function buildReceiptData(order: Order, config: ReceiptConfig): ReceiptData;
+declare function buildReceiptData(order: SentOrder, config: ReceiptConfig): ReceiptData;
 
 /**
  * Filters product documents by a cashier's search term, through traits, so
@@ -474,6 +528,22 @@ declare function stockOverlay$(collection: RxCollection): Observable<Map<string,
 declare function stockOverlayAsOf$(collection: RxCollection): Observable<string | undefined>;
 
 type PosOrderSyncStatus = 'pending' | 'applied' | 'rejected';
+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. */
+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;
+}
 interface PosOrderLine {
     id: string;
     productId: string;
@@ -521,21 +591,28 @@ interface PosOrder {
     registerId?: string;
     /**
      * The register session the sale was taken in (ADR-032): its closure counts this order.
-     * Local only: `toOrderCreateEnvelope` never sends it.
+     * 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. Local only: `toOrderCreateEnvelope` never sends it.
+     * counts it. Sent at `order.create` version 3 as the payload's `sessionId` (the stamped or late session, one field).
      */
     lateSessionId?: string;
-    /** ADR-065: the receipt's display figures, in integer minor units of `currency` at `exponent`. Not written yet. */
+    /**
+     * 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). Not written yet. */
+    /** ADR-065: tax by rate, named as `taxLinesByRate` names them (`amountMinor` is the tax). */
     taxByRate?: Array<{
         ratePpm: number;
         code?: string;
@@ -544,11 +621,18 @@ interface PosOrder {
         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;
 }
@@ -557,21 +641,38 @@ interface PosOrder {
 declare function uuidv7(now?: number, randomBytes?: (n: number) => Uint8Array): string;
 
 interface FinalizeOptions {
+    localWarnings?: PosOrderLocalWarning[];
     registerId?: string;
     cashierRef?: string;
     now?: Date;
+    /** Tests only: replaces uuidv7. Every id it returns must be at most 255 characters with no NUL (order.create's bound). */
     newId?: () => string;
     /** The store's `order.create` capability (ADR-062); `undefined` is treated as 1. */
     capabilities?: ServerCapabilities;
 }
-/** Turns a fully paid builder Order into a pending PosOrder without mutating it. */
+/**
+ * Turns a fully paid builder Order into a pending PosOrder without mutating it. The PosOrder holds the sent form,
+ * frozen: line names and v3 discount labels are cut to PAYLOAD_STRING_MAX with NUL stripped (`cutText`), and a
+ * customer email or id the shape check would refuse is left out, so `toOrderCreateEnvelope` sends it unchanged.
+ */
 declare function finalizeOrder(order: Order, options?: FinalizeOptions): PosOrder;
 
+declare class UnsupportedOrderVersionError extends Error {
+    readonly needed: number;
+    readonly supported: number;
+    readonly code = "UNSUPPORTED_ORDER_VERSION";
+    constructor(needed: number, supported: number);
+}
 /**
- * Builds the ADR-038 order.create envelope for a PosOrder.
- * A discounted order is version 2 (ADR-062); a discount-free one stays version 1, byte-identical.
+ * Builds the ADR-038 order.create envelope for a PosOrder. It sends the stored order unchanged, so every resend of
+ * an order is byte-identical, and an order stored by an older till goes out exactly as that till sent it:
+ * `finalizeOrder` freezes the sent form (names and labels cut, an unsendable customer email or id left out).
+ * ADR-065's figures make version 3; otherwise a discounted order is version 2 (ADR-062), else version 1, byte-identical.
+ * A version-3 order goes as version 4 (#286) only when `maxVersion` is at least 4 and its `sentVersion` doesn't cap it.
  */
-declare function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt?: number): CommandEnvelope<OrderCreatePayload>;
+declare function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attempt?: number, options?: {
+    maxVersion?: number;
+}): OrderCreateEnvelope;
 
 /**
  * Version 1 adds the optional `sessionId` (ADR-032); nothing else changed from version 0.
@@ -579,6 +680,14 @@ declare function toOrderCreateEnvelope(order: PosOrder, deviceId: string, attemp
  * 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.
  */
 declare const posOrderSchema: RxJsonSchema<PosOrder>;
 /**
@@ -604,8 +713,9 @@ declare function posOrderCollection(): {
 declare const posOrdersLogger: Logger;
 /**
  * `addPosOrderCollection` stopped, before any further write, because its database is closing: it
- * was called once `close()` had begun, or the close stopped waiting for it (after
- * `POS_ORDER_MIGRATION_CLOSE_WAIT_MS`). No order is lost: reopen the database and call it again.
+ * was called once `close()` had begun, the close cancelled its migration (RxDB 17.5), or the close
+ * stopped waiting for it (after `POS_ORDER_MIGRATION_CLOSE_WAIT_MS`). No order is lost: reopen the
+ * database and call it again.
  */
 declare class PosOrderOpenClosedError extends Error {
     readonly databaseName: string;
@@ -618,16 +728,20 @@ declare class PosOrderOpenClosedError extends Error {
  * stopped and closes the collection, so the app can surface the error and open again; it never
  * deletes an order.
  *
- * RxDB 16.21 trusts the status its last migration stored: a leftover `ERROR` rejects
+ * RxDB 17.5.0 trusts the status its last migration stored: a leftover `ERROR` rejects
  * `migratePromise` at once while the migration keeps running (a close then interrupts it), and a
  * `DONE` left before a rollback resolves it before the older version's new orders have moved. So the
- * collection is added without `autoMigrate`, the status and a failed run's checkpoint are reset
- * (never an order or its storage), and the migration itself is awaited.
+ * collection is added without `autoMigrate` and the migration is started and awaited directly: RxDB
+ * 17.5's `startMigration()` ignores a leftover status (only `migratePromise()` trusts a leftover
+ * `DONE`), which lets a rolled-back or interrupted run migrate again and recovers its orders. The
+ * status is reset first so its record describes the new run, and a failed run's checkpoint is
+ * removed (RxDB bug 1); never an order or its storage.
  *
- * A close waits for the whole open, up to `POS_ORDER_MIGRATION_CLOSE_WAIT_MS`. Called once the
- * database's close has begun, or when the close stops waiting, it rejects with
- * `PosOrderOpenClosedError` (`code: 'POS_ORDER_OPEN_CLOSED'`) before any further write: reopen and
- * call it again. Any other rejection (DM4, a storage error) is a real failure.
+ * A close waits for the open, up to `POS_ORDER_MIGRATION_CLOSE_WAIT_MS`, and cancels a running
+ * migration (RxDB 17.5). Called once the database's close has begun, when the close cancels its
+ * migration, or when the close stops waiting, it rejects with `PosOrderOpenClosedError`
+ * (`code: 'POS_ORDER_OPEN_CLOSED'`) before any further write: reopen and call it again. Any other
+ * rejection (DM4, a storage error) is a real failure.
  *
  * `closeWaitMs` is for tests only; the first open on a database sets it for that database's close.
  */
@@ -644,10 +758,14 @@ declare function getDeviceId(storage: {
 } | null, key: string): string;
 
 /**
- * The orders a cashier must look at: rejected, applied with warnings, or taken after their session
- * closed (`lateSessionId`, whatever the sync status), newest first. Never changes `orders`.
+ * The orders a cashier must look at: rejected, applied with a known warning, taken after their
+ * session closed (`lateSessionId`) or with local warnings (whatever the sync status), or pending with a `commandId` in
+ * `stuckCommandIds` (the outbox's `OutboxState.stuck`: the store keeps failing it), newest first.
+ * A warning code this till version doesn't know is not shown here (`knownWarnings`). Never changes `orders`.
  */
-declare function needsAttention(orders: PosOrder[]): PosOrder[];
+declare function needsAttention(orders: PosOrder[], options?: {
+    stuckCommandIds?: readonly string[];
+}): PosOrder[];
 
 type SaleContent = Pick<PosOrder, 'totalMinor' | 'currency' | 'lines' | 'payments'>;
 /**
@@ -877,6 +995,7 @@ type RegisterCounters = {
  * same atomic write as its number, and `applied` once its period is in the perpetual totals.
  */
 type RegisterBucket = Partial<RegisterCounters> & {
+    commands_since?: string;
     closure_reservation?: {
         row: Closure;
         applied: boolean;
@@ -911,6 +1030,9 @@ declare function readBoundRegister(host: RegisterHost, storeKey: string): Promis
     id: string;
     name: string;
 } | null>;
+declare class RegisterIdInvalidError extends Error {
+    constructor();
+}
 declare function bindRegister(host: RegisterHost, storeKey: string, register: {
     id: string | null;
     name: string | null;
@@ -944,10 +1066,17 @@ declare class RegisterSessionRequiredError extends Error {
 declare class RegisterSessionClosedError extends Error {
     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);
+}
+declare class RegisterMovementReasonError extends Error {
+    constructor();
+}
 /**
  * The movement is recorded, on a session that closed while it was saved, and no closure is known
- * to count it, so it was kept rather than deleted. The caller must not record it again; job c's
- * server resolves stranded movements. The message can be shown to a cashier as it is.
+ * to count it, so it stays local on the till. The caller must not record it again; the server
+ * refuses it once the closure exists (ADR-068 4). The message can be shown to a cashier as it is.
  */
 declare class RegisterMovementStrandedError extends Error {
     readonly id: string;
@@ -975,9 +1104,9 @@ declare function openSession(sessions: RegisterSessionCollection, input: {
         day: number;
     };
     storeKey?: string | null;
-}): Promise<rxdb.RxDocument<RegisterSession, {}>>;
-declare const startCounting: (sessions: RegisterSessionCollection, id: string) => Promise<rxdb.RxDocument<RegisterSession, {}>>;
-declare const backToSelling: (sessions: RegisterSessionCollection, id: string) => Promise<rxdb.RxDocument<RegisterSession, {}>>;
+}): Promise<rxdb.RxDocument<RegisterSession, {}, unknown>>;
+declare const startCounting: (sessions: RegisterSessionCollection, id: string) => Promise<rxdb.RxDocument<RegisterSession, {}, unknown>>;
+declare const backToSelling: (sessions: RegisterSessionCollection, id: string) => Promise<rxdb.RxDocument<RegisterSession, {}, unknown>>;
 /**
  * Closes the session with its counted tenders (minor units); `timezone` dates a session opened
  * without a business day. `approvedBy`, the manager who approved the count, is written in the same
@@ -988,7 +1117,7 @@ declare function closeSession(sessions: RegisterSessionCollection, id: string, i
     closedBy?: string;
     approvedBy?: string;
     timezone?: string;
-}): Promise<rxdb.RxDocument<RegisterSession, {}>>;
+}): Promise<rxdb.RxDocument<RegisterSession, {}, unknown>>;
 /**
  * Records a movement on a session that is `open` or `counting`; a closed or missing one is refused.
  * A close that races the insert ends in `RegisterSessionClosedError` (removed) or
@@ -1000,14 +1129,14 @@ declare function recordMovement(sessions: RegisterSessionCollection, movements:
     amountMinor: number;
     reason: string;
     actor: string;
-}): Promise<rxdb.RxDocument<CashMovement, {}>>;
+}): Promise<rxdb.RxDocument<CashMovement, {}, unknown>>;
 /**
  * Reverses a movement with a `void` row while its session is live; repeated or concurrent calls
  * share one reversal. A close that races the writes ends in `RegisterMovementStrandedError` (kept;
  * don't void it again). Without `closures`, nothing can prove the reversal counted, so a re-read
  * that finds the session closed always ends in `RegisterMovementStrandedError`.
  */
-declare function voidMovement(sessions: RegisterSessionCollection, movements: CashMovementCollection, movementId: string, actor: string, closures?: ClosureCollection): Promise<rxdb.RxDocument<CashMovement, {}>>;
+declare function voidMovement(sessions: RegisterSessionCollection, movements: CashMovementCollection, movementId: string, actor: string, closures?: ClosureCollection): Promise<rxdb.RxDocument<CashMovement, {}, unknown>>;
 /**
  * Freezes a closed session's figures into its closure, once. The draft is reserved on the register
  * document with its number (`mintClosureNumber`), so a failed insert or a restarted till reuses the
@@ -1039,7 +1168,7 @@ declare function writeClosure({ closures, register, storeKey, session, counted,
     /** The app's version, stamped on the closure. */
     softwareVersion: string;
     timezone?: string;
-}): Promise<rxdb.RxDocument<Closure, {}>>;
+}): Promise<rxdb.RxDocument<Closure, {}, unknown>>;
 
 /**
  * Corrections layered onto a closure's recorded figures (ADR-032): late sales, late cash
@@ -1212,6 +1341,11 @@ declare function selectClosureRows(rows: readonly Closure[], scope: ClosureScope
 declare function minorToDecimal(minor: number, exponent: number): string;
 
 type Values = Record<string, unknown>;
+/**
+ * The Z report's line when a session's sales used more than one tax rounding (#287; wording approved by the Front
+ * desk, 2026-09-30). The closure template lives in the apps, so the document carries it ready to print.
+ */
+declare const TAX_ROUNDING_MIXED_NOTE = "This register's sales used more than one tax rounding method. Each sale's tax is as its receipt showed.";
 type ClosureContext = {
     store: Values;
     currency: string;
@@ -1234,6 +1368,7 @@ type ClosureContext = {
 declare function formatClosureDate(value: string | null | undefined, context: Pick<ClosureContext, 'timezone' | 'locale'>): Record<string, string>;
 declare function buildClosureDocument(row: Closure, context: ClosureContext): {
     closure: {
+        tax_rounding_note?: string | undefined;
         has_sales: boolean;
         has_perpetual: boolean;
     } & {
@@ -1344,6 +1479,7 @@ declare function buildClosureDocument(row: Closure, context: ClosureContext): {
 };
 declare function buildXReportDocument(session: RegisterSession, context: ClosureContext): {
     closure: {
+        tax_rounding_note?: string | undefined;
         has_sales: boolean;
         has_perpetual: boolean;
     } & {
@@ -1486,6 +1622,48 @@ type RegisterFact = (Human & {
 });
 declare function recordRegisterFact(fact: RegisterFact): void;
 
+declare const registerCommandsLogger: Logger;
+interface RegisterCommand {
+    key: string;
+    registerId: string;
+    seq: number;
+    commandId: string;
+    type: RegisterCommandType;
+    version: number;
+    payload: Record<string, unknown>;
+    createdAt: string;
+    syncStatus: 'pending' | 'applied' | 'rejected';
+    error?: CommandError;
+    result?: RegisterCommandResult;
+    updatedAt: string;
+}
+type RegisterCommandCollection = RxCollection<RegisterCommand>;
+declare const registerCommandSchema: RxJsonSchema<RegisterCommand>;
+declare const registerCommandCollection: () => {
+    schema: RxJsonSchema<RegisterCommand>;
+};
+type BuiltCommand = Pick<RegisterCommand, 'key' | 'type' | 'payload'> & {
+    version: 1;
+};
+declare function sessionOpenCommand(s: RegisterSession): BuiltCommand;
+declare function sessionTransitionCommand(s: RegisterSession & {
+    status_at: string;
+}): BuiltCommand;
+declare function movementCommand(m: CashMovement): BuiltCommand;
+declare function closureCommand(c: Closure): BuiltCommand;
+/** Appends missing facts in dependency order; the bytes of an existing key never change. */
+declare function reconcileRegisterCommands({ commands, sessions, movements, closures, host, storeKey, registerId, now, observed }: {
+    commands: RegisterCommandCollection;
+    sessions: RegisterSessionCollection;
+    movements: CashMovementCollection;
+    closures: ClosureCollection;
+    host: RegisterHost;
+    storeKey: string;
+    registerId: string;
+    now?: string;
+    observed?: RegisterSession[];
+}): Promise<string[]>;
+
 /** A sale is at tender, so the till can't count or close under it. Its message can be shown to a cashier as it is. */
 declare class RegisterTenderInProgressError extends Error {
     constructor();
@@ -1509,6 +1687,9 @@ interface UseRegisterSessionOptions {
     movements: CashMovementCollection | null;
     /** `closures`; `null` while it opens. */
     closures: ClosureCollection | null;
+    /** `register_commands`, created with `registerCommandCollection()`; `null` while it opens. */
+    commands?: RegisterCommandCollection | null;
+    capabilities?: ServerCapabilities;
     /** `pos_orders`: a session's sales are those whose `sessionId` is its id. */
     orders: RxCollection<PosOrder> | null;
     /** The register document's host, for the closure number and perpetual totals (`writeClosure`); `null` while it opens. */
@@ -1573,9 +1754,9 @@ declare function useRegisterSession(options: UseRegisterSessionOptions): {
         openSession: (input: {
             expectedFloatMinor: number | null;
             countedFloatMinor: number;
-        }) => Promise<rxdb.RxDocument<RegisterSession, {}>>;
-        startCounting: () => Promise<rxdb.RxDocument<RegisterSession, {}>>;
-        backToSelling: () => Promise<rxdb.RxDocument<RegisterSession, {}>>;
+        }) => Promise<rxdb.RxDocument<RegisterSession, {}, unknown>>;
+        startCounting: () => Promise<rxdb.RxDocumentBase<RegisterSession, {}, unknown> & RegisterSession & rxdb.ExtendObservables<RegisterSession> & rxdb.ExtendReactivity<RegisterSession, unknown>>;
+        backToSelling: () => Promise<rxdb.RxDocumentBase<RegisterSession, {}, unknown> & RegisterSession & rxdb.ExtendObservables<RegisterSession> & rxdb.ExtendReactivity<RegisterSession, unknown>>;
         /**
          * `counted` maps each tender to its counted minor units. An interrupted close resumes with
          * the count persisted on the session, not the one passed to the retry (WCPOS uses the retry's).
@@ -1590,13 +1771,13 @@ declare function useRegisterSession(options: UseRegisterSessionOptions): {
             counted: Record<string, number>;
             approvedBy?: string;
             approvedByName?: string;
-        }) => Promise<rxdb.RxDocument<Closure, {}>>;
+        }) => Promise<rxdb.RxDocument<Closure, {}, unknown>>;
         recordMovement: (input: {
             type: "paid_in" | "paid_out" | "no_sale";
             amountMinor: number;
             reason: string;
-        }) => Promise<rxdb.RxDocument<CashMovement, {}>>;
-        voidMovement: (id: string) => Promise<rxdb.RxDocument<CashMovement, {}>>;
+        }) => Promise<rxdb.RxDocument<CashMovement, {}, unknown>>;
+        voidMovement: (id: string) => Promise<rxdb.RxDocument<CashMovement, {}, unknown>>;
     };
 };
 
@@ -1620,7 +1801,7 @@ type SaleStage = {
     method: 'cash' | 'external';
 } | {
     kind: 'receipt';
-    order: Order;
+    order: SentOrder;
     posOrder: PosOrder;
 };
 /** TallyUI finalizeOrder's refusal below order.create v2 (c19a203), shown when the discount is applied; finalize stays the backstop. */
@@ -1668,6 +1849,8 @@ declare function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
     /** A line's discount, or the order's without a line; returns the refusal to show, or null once applied. */
     applyDiscount(lineId: string | null, discount: Discount): string | null;
     removeDiscount(id: string): void;
+    /** the picked customer reaches the server as order.create v3's customer.customerId */
+    setCustomer(customer: CustomerSummary | null): void;
     /**
      * Pins `options.session` for this tender when given, else the rendered `session` option. Pass the
      * session `useRegisterSession`'s `requireSaleSession()` returned: the rendered one can lag a session
@@ -1696,7 +1879,9 @@ declare function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
      * and `createdAt`, no new stamp and no second late-sale fact) and hands it to `onSaleCompleted`
      * again, so that must accept an order it already stored (as `useOrderOutbox.record` does). The
      * pending completion is cleared once `onSaleCompleted` resolves, or by `newSale()`. A call while
-     * another is in flight returns that call's promise, and a call on the receipt does nothing.
+     * another is in flight returns that call's promise, and a call on the receipt does nothing. While
+     * `cashierRef` or `registerId` is out of bounds (shown as `error`), a call does nothing either,
+     * unless it's the Retry of a pending completion, which was built with the options as they were.
      */
     complete: () => Promise<void>;
     /**
@@ -1734,16 +1919,22 @@ type TransportOutcome = {
     kind: 'refused';
     status: number;
     reason: string;
-} | {
+}
+/** `reason` is `network` when the store could not be reached, `timeout` when a sent request got no answer in time,
+ * else what the store answered (`status_503`, `bad_body`, ...). The order outbox counts every reason but `network`. */
+ | {
     kind: 'retry';
     reason: string;
     retryAfterMs?: number;
 };
-interface CommandTransport {
-    send(batch: CommandEnvelope<OrderCreatePayload>[]): Promise<TransportOutcome>;
+interface CommandTransport<E extends AnyCommandEnvelope = CommandEnvelope<OrderCreatePayload>> {
+    send(batch: E[]): Promise<TransportOutcome>;
 }
 interface OutboxState {
     pending: number;
+    /** The order outbox's count of `pos_orders` the store refused (`syncStatus: 'rejected'`), read with `pending`. Each
+     * stays until requeue() sends it again. The register outbox leaves it unset. */
+    rejected?: number;
     sending: boolean;
     lastRetryReason?: string;
     nextAttemptAt?: number;
@@ -1754,6 +1945,26 @@ interface OutboxState {
         status: number;
         reason: string;
     };
+    /** Set while the store (not offline) has kept failing some orders for 15 minutes, each on its own clock. Those
+     * orders stay pending and keep retrying. `orders` has each order's own entry: its `since` is when its clock
+     * would have started had there been no offline gaps (now minus its answered time; while offline, as of the
+     * moment the clock paused), and its latest `reason`. `since` is the earliest of theirs; `reason` the latest. */
+    stuck?: {
+        commandIds: string[];
+        since: number;
+        reason: string;
+        orders: {
+            commandId: string;
+            since: number;
+            reason: string;
+        }[];
+    };
+    /** Set after 3 consecutive 404 answers (counted across the outboxes sharing one BackendNotFound): the store address
+     * may be wrong, or the store's plugin isn't installed or is switched off. The outbox keeps retrying; the next answer
+     * that isn't a 404 clears it (offline changes nothing). `since` is when the first of those 404s arrived. */
+    backendMissing?: {
+        since: number;
+    };
 }
 
 interface HttpTransportOptions {
@@ -1762,17 +1973,33 @@ interface HttpTransportOptions {
     fetch?: typeof fetch;
     timeoutMs?: number;
 }
-declare function createHttpCommandTransport(options: HttpTransportOptions): CommandTransport;
+declare function createHttpCommandTransport(options: HttpTransportOptions): CommandTransport<AnyCommandEnvelope>;
+
+/** Counts consecutive 404s across every outbox given it, so a missing plugin shows once, whichever outbox meets it. */
+interface BackendNotFound {
+    /** A 404 counts; any other answer from the store clears; offline (`network`) changes nothing. */
+    record(outcome: TransportOutcome, at: number): void;
+    backendMissing$: Observable<OutboxState['backendMissing']>;
+}
+declare function createBackendNotFound(): BackendNotFound;
 
 interface OrderOutboxOptions {
     collection: RxCollection<PosOrder>;
-    transport: CommandTransport;
+    transport: CommandTransport<OrderCreateEnvelope>;
     deviceId: string;
+    getMaxOrderCreateVersion?: () => number | undefined | Promise<number | undefined>;
+    refreshCapabilities?: () => Promise<void>;
     batchSize?: number;
     initialBackoffMs?: number;
     maxBackoffMs?: number;
     random?: () => number;
     now?: () => number;
+    /** Tests only: overrides ISOLATE_AFTER_ATTEMPTS. */
+    isolateAfterAttempts?: number;
+    /** Tests only: overrides STUCK_AFTER_MS. */
+    stuckAfterMs?: number;
+    /** Counts 404s toward OutboxState.backendMissing; pass the register outbox's too, so either one's 404s show one notice. */
+    backendNotFound?: BackendNotFound;
 }
 interface OrderOutbox {
     /** Sends pending orders until empty or retrying. Concurrent calls share one run. */
@@ -1788,8 +2015,34 @@ interface OrderOutbox {
 }
 declare function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox;
 
-/** Logs a retried order found stored under another `commandId` (warn), and a content mismatch (error). */
+interface RegisterOutboxOptions {
+    collection: RxCollection<RegisterCommand>;
+    transport: CommandTransport<RegisterCommandEnvelope>;
+    deviceId: string;
+    /** Checked at the start of every run; false sends nothing. */
+    isEnabled?: () => boolean;
+    /** Runs before marking, so a crash resends; a throw is logged and marking continues. */
+    onResult?: (command: RegisterCommand, result: CommandResult) => Promise<void> | void;
+    batchSize?: number;
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+    random?: () => number;
+    now?: () => number;
+    /** Tests only: overrides STUCK_AFTER_MS. */
+    stuckAfterMs?: number;
+    /** Counts 404s toward OutboxState.backendMissing; pass the order outbox's too, so either one's 404s show one notice. */
+    backendNotFound?: BackendNotFound;
+}
+interface RegisterOutbox {
+    flush(): Promise<void>;
+    start(): void;
+    stop(): void;
+    state$: Observable<OutboxState>;
+}
+declare function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOutbox;
+
 declare const outboxLogger: Logger;
+
 interface UseOrderOutboxOptions {
     /** Which order store to use (medusapos: the backend's base URL); `null` means no store. A change reopens. */
     storeKey: string | null;
@@ -1799,9 +2052,13 @@ interface UseOrderOutboxOptions {
         close(): Promise<void>;
     }>;
     /** Builds the command transport for `storeKey` (the app's HTTP transport and auth headers). Read once per open. */
-    transport(storeKey: string): CommandTransport;
+    transport(storeKey: string): CommandTransport<OrderCreateEnvelope>;
     /** The device id sent on every command (see `getDeviceId`). A change reopens. */
     deviceId: string;
+    /** Presence is fixed when the store opens; calls use the latest function. Reopen to add or remove. */
+    getMaxOrderCreateVersion?: () => number | undefined | Promise<number | undefined>;
+    /** Presence is fixed when the store opens; calls use the latest function. Reopen to add or remove. */
+    refreshCapabilities?: () => Promise<void>;
     /** Called with `state.sending`, and with `false` on cleanup (medusapos: live-tab's `markBusy('outbox', …)`). */
     onBusy?(busy: boolean): void;
     /** Called when `open` rejects, even if the key has changed since (medusapos: reports storage worker failures). */
@@ -1837,6 +2094,9 @@ interface UseOrderOutboxResult {
      * storage can wait forever, and TallyUI deliberately doesn't bound that close (#155).
      */
     savesInFlight: number;
+    /** The command ids in `state.stuck`: pending orders the store keeps failing. Pass them to `needsAttention` and
+     * `OrdersList`. Empty when none, and before the current store is ready. */
+    stuckCommandIds: readonly string[];
 }
 /** Opens the order store for `storeKey`, runs its outbox and watches the recent orders (lifted from medusapos/app, ADR-052). */
 declare function useOrderOutbox(options: UseOrderOutboxOptions): UseOrderOutboxResult;
@@ -1987,4 +2247,4 @@ declare function planLegs(plan: TenderPlan, rowsSinceFrom: {
     };
 };
 
-export { type Actor, type AddLineInput, type AppliedDiscount, CartError, type CashMovement, type CashMovementCollection, type CatalogueEntry, type Closure, type ClosureCollection, type ClosureContext, type ClosureScope, type CommandTransport, type Correction, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, DISCOUNTS_UNSUPPORTED, type Discount, type DisplayLine, type DisplayTotals, 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 OutboxState, type ParkedOrderSummary, type Payment, type PaymentMethod, type PaymentTransport, type PlanLeg, type PosOrder, type PosOrderLine, PosOrderOpenClosedError, type PosOrderPayment, type PosOrderSyncStatus, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptLineItem, type RecordedFigures, RegisterApprovalRequiredError, type RegisterBucket, RegisterCloseIncompleteError, type RegisterCounters, type RegisterDocument, type RegisterFact, type RegisterHost, RegisterMovementStrandedError, type RegisterSession, RegisterSessionAlreadyOpenError, RegisterSessionClosedError, type RegisterSessionCollection, RegisterSessionRequiredError, type RegisterStore, RegisterTenderInProgressError, type Repository, type ResolveStoreSettingsOptions, SALE_SAVING, type SaleStage, type SplitTab, type StoreSettingsResolution, type StoreSettingsState, type TaxContext, type TaxLineInput, TaxProvider, type TaxProviderProps, type TaxRateMap, type TenderAction, type TenderKey, type TenderLineId, type TenderPlan, type TenderState, type TenderView, type TransportOutcome, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterSessionOptions, activePlan, addEntryToCart, addPosOrderCollection, advancePerpetual, allocateOrderDiscount, appliedMinor, backToSelling, bindRegister, buildClosureDocument, buildReceiptData, buildXReportDocument, callbackSink, cashMovementSchema, catalogueEntries, changeMinor, clampClosureScope, closeNeedsApproval, closeSession, closureSchema, computeOrderTax, consoleSink, countVariance, createHttpCommandTransport, createLogger, createOrderBuilder, createOrderManager, createOrderOutbox, createRepository, denominationTotal, denominations, deriveExpected, deriveSettled, ensureRegister, evenSplitShareMinor, exportCsv, finalizeOrder, findEntryByCode, formatClosureDate, getBoundRegisterId, getDeviceId, initTenderState, initialTenderState, isServerDecimal, labelKeys, minorToDecimal, mintClosureNumber, mintUuid, movementFieldError, needsAttention, nextSaleCounter, normalizeAmount, observeRegister$, openSession, openSessionSelector, outboxLogger, overThreshold, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, recordMovement, recordRegisterFact, registerFactsLogger, registerSessionCollection, registerSessionSchema, requireOpenSession, resolveStoreSettings, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, taxLinesByRate, taxMicros, taxProviderProps, tenderReducer, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure };
+export { type Actor, type AddLineInput, type AppliedDiscount, type BackendNotFound, type BasketLine, CartError, type CashMovement, type CashMovementCollection, type CatalogueEntry, type Closure, type ClosureCollection, type ClosureContext, type ClosureScope, type CommandTransport, type Correction, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, DISCOUNTS_UNSUPPORTED, type Discount, type DisplayLine, type DisplayTotals, 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 OutboxState, type ParkedOrderSummary, type Payment, type PaymentMethod, type PaymentTransport, type PlanLeg, type PosOrder, type PosOrderLine, type PosOrderLocalWarning, PosOrderOpenClosedError, type PosOrderPayment, type PosOrderServerFailures, type PosOrderSyncStatus, type RateTaxLine, type ReceiptConfig, type ReceiptData, type ReceiptLineItem, 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 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 TransportOutcome, UnsupportedOrderVersionError, type UseOrderOutboxOptions, type UseOrderOutboxResult, type UseRegisterSessionOptions, activePlan, addEntryToCart, addPosOrderCollection, advancePerpetual, allocateOrderDiscount, appliedMinor, backToSelling, bindRegister, buildClosureDocument, buildReceiptData, buildXReportDocument, callbackSink, cashMovementSchema, catalogueEntries, 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, initTenderState, initialTenderState, isServerDecimal, labelKeys, minorToDecimal, mintClosureNumber, mintUuid, movementCommand, movementFieldError, needsAttention, nextSaleCounter, normalizeAmount, observeRegister$, openSession, openSessionSelector, outboxLogger, overThreshold, parseMinor, planLegs, posOrderCollection, posOrderSchema, posOrdersLogger, quickTenderedAmounts, ratePpmFromPercent, readBoundRegister, readRegister, reconcileRegisterCommands, recordMovement, recordRegisterFact, registerCommandCollection, registerCommandSchema, registerCommandsLogger, registerFactsLogger, registerSessionCollection, registerSessionSchema, requireOpenSession, resolveStoreSettings, roundMicrosToMinor, saleLogger, sameSale, searchProducts, selectClosureRows, sessionOpenCommand, sessionTransitionCommand, stampSession, startCounting, stockOverlay$, stockOverlayAsOf$, taxFiguresForBasket, taxLinesByRate, taxLogger, taxMicros, taxProviderProps, tenderReducer, toOrderCreateEnvelope, unbindRegister, useCurrencyCode, useCurrencyFormatter, useOrderOutbox, useRegisterSession, useSale, useStoreSettings, useTax, uuidv7, validAmount, varianceText, variantPriceLabel, voidMovement, withPricingContext, writeClosure };