@tallyui/pos 0.1.0 → 3.0.0-next.0

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { MangoQuery, RxCollection } from 'rxdb';
+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';
+import { MangoQuery, RxCollection, RxJsonSchema, MigrationStrategies, RxDatabase, RxLocalDocumentMutation } from 'rxdb';
+import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
-import { ProductTraits } from '@tallyui/core';
 
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 interface LogEntry {
@@ -44,42 +48,178 @@ interface CallbackSinkOptions {
 }
 declare function callbackSink(options: CallbackSinkOptions): LogSink;
 
-declare function formatCurrency(amount: number, currencyCode: string, locale?: string): string;
-
 interface CurrencyProviderProps {
     currencyCode: string;
     locale?: string;
     children: ReactNode;
 }
 declare function CurrencyProvider({ currencyCode, locale, children }: CurrencyProviderProps): react_jsx_runtime.JSX.Element;
-declare function useCurrencyFormatter(): (amount: number) => string;
+declare function useCurrencyFormatter(): (money: Money) => string;
+declare function useCurrencyCode(): string;
 
-interface TaxResult {
-    priceExclTax: number;
-    priceInclTax: number;
-    taxAmount: number;
+/** Micro-minor-units per minor unit. */
+declare const MICROS_PER_MINOR = 1000000n;
+/** Converts a plain decimal percentage with at most four fractional digits to safe integer ppm. */
+declare function ratePpmFromPercent(percent: number | string): number;
+/**
+ * Exact exclusive tax, or inclusive tax rounded half away from zero to a micro-minor-unit.
+ * Throws RangeError unless amount and rate are safe integers and rate is non-negative.
+ */
+declare function taxMicros(amountMinor: number, ratePpm: number, pricesIncludeTax: boolean): bigint;
+/** #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;
+    ratePpm: number;
 }
+interface OrderTaxTotals {
+    subtotalMinor: number;
+    taxMinor: number;
+    totalMinor: number;
+    lineTaxMicros: bigint[];
+}
+/**
+ * Sums tax on each unit price × quantity and rounds once for the order.
+ * Exclusive: total = subtotal + tax. Inclusive: subtotal = total − tax.
+ * Empty orders return zeros and an empty lineTaxMicros.
+ * Throws RangeError for unsafe integer inputs or totals, negative rates, or quantity < 1.
+ */
+declare function computeOrderTax(lines: TaxLineInput[], pricesIncludeTax: boolean): OrderTaxTotals;
+interface RateTaxLine {
+    label: string;
+    code?: string;
+    ratePpm: number;
+    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
+ * distributes `orderTaxMinor` minus that floor sum by largest remainder (ties to the higher rate)
+ * 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. 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 TaxedLine[], orderTaxMinor: number, taxLabels?: Record<number, string>, rounding?: TaxRounding): RateTaxLine[];
+
+/** Tax rates as integer parts per million (19% = 190000). */
 type TaxRateMap = {
     default: number;
     [taxClass: string]: number;
 };
 interface TaxContext {
-    getTaxRate(taxClass?: string): number;
+    /** 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 function addTax(priceExclTax: number, rate: number): number;
-declare function extractTax(priceInclTax: number, rate: number): number;
-declare function calculateTax(price: number, rate: number, pricesIncludeTax: boolean): TaxResult;
-
+declare const taxLogger: Logger;
 interface TaxProviderProps {
-    rates: Record<string, number>;
+    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({ rates, 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 = {
+    status: 'ready';
+    settings: StoreSettings;
+    choice?: StoreSettingsChoice;
+} | {
+    status: 'choose';
+    choices: StoreSettingsChoices;
+    initial?: StoreSettingsChoice;
+} | {
+    status: 'unsupported';
+};
+interface ResolveStoreSettingsOptions {
+    connector: TallyConnector;
+    context: SyncContext;
+    /** The app's stored choice for this store (its own settings; TallyUI never stores it). */
+    loadChoice: () => StoreSettingsChoice | undefined | Promise<StoreSettingsChoice | undefined>;
+    saveChoice: (choice: StoreSettingsChoice) => void | Promise<void>;
+    /** A save that throws after a successful resolve: the pick is asked again next launch. */
+    onSaveError?: (error: unknown) => void;
+}
+/**
+ * Reads the store settings with the app's choice (TV4). A `choice` argument (a new pick from
+ * the choice screen) wins over the stored one and is saved only once it resolves; a stored
+ * choice is never re-saved. `choice_required` (including a stale stored choice) gives
+ * `choose`, with the tried choice narrowed to what's offered as `initial`, so the screen
+ * pre-selects what still matches. Any other error, `failed` included, is rethrown unchanged.
+ */
+declare function resolveStoreSettings(options: ResolveStoreSettingsOptions, choice?: StoreSettingsChoice): Promise<StoreSettingsResolution>;
+
+/** 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 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 = {
+    state: 'loading';
+} | {
+    state: 'ready';
+    settings: StoreSettings;
+    choice?: StoreSettingsChoice;
+} | {
+    state: 'choose';
+    choices: StoreSettingsChoices;
+    initial?: StoreSettingsChoice;
+    choose: (choice: StoreSettingsChoice) => void;
+} | {
+    state: 'error';
+    error: unknown;
+    retry: () => void;
+} | {
+    state: 'unsupported';
+};
+/**
+ * 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 });
+ * if (store.state === 'choose')
+ *   return <StoreSettingsChoiceScreen choices={store.choices} initial={store.initial} onSubmit={store.choose} />;
+ * if (store.state !== 'ready') return <Loading />; // or an error with store.retry, or the app's own config when unsupported
+ * const syncContext = withPricingContext(context, store.settings); // for the replication
+ * return <TaxProvider {...taxProviderProps(store.settings)}>{children}</TaxProvider>;
+ * ```
+ */
+declare function useStoreSettings(options: ResolveStoreSettingsOptions): StoreSettingsState;
+
 interface Repository<T> {
     findById$(id: string): Observable<T | null>;
     findAll$(query?: MangoQuery<T>): Observable<T[]>;
@@ -104,16 +244,50 @@ interface Order {
     payments: Payment[];
     customer: CustomerSummary | null;
     note: string;
-    subtotal: number;
-    discountTotal: number;
-    taxTotal: number;
-    total: number;
-    balanceDue: number;
-    changeDue: number;
     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;
+    totalMinor: number;
+    display: DisplayTotals;
+    paidMinor: number;
+    balanceDueMinor: number;
+    changeDueMinor: number;
     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.
+ */
+interface DisplayTotals {
+    taxInclusive: boolean;
+    subtotalMinor: number;
+    discountMinor: number;
+    taxMinor: number;
+    totalMinor: number;
+    lines: DisplayLine[];
+    orderDiscountMinor: number;
+}
+/** One line in the display mode (ADR-063): before any discount, with its own discounts as sub-rows. */
+interface DisplayLine {
+    lineId: string;
+    amountMinor: number;
+    discounts: {
+        discountId: string;
+        label?: string;
+        amountMinor: number;
+    }[];
+}
 interface LineItem {
     id: string;
     productId: string;
@@ -121,13 +295,22 @@ interface LineItem {
     name: string;
     sku: string;
     imageUrl?: string;
-    price: number;
+    unitPriceMinor: number;
     quantity: number;
-    taxRate: number;
-    taxAmount: number;
+    taxLines: LineTaxLine[];
     discounts: AppliedDiscount[];
-    discountAmount: number;
-    lineTotal: number;
+    discountMinor: number;
+    orderDiscountMinor: number;
+    netMinor: number;
+    taxMicros: string;
+    taxInclusive: boolean;
+    /** Set only when the price's tax mode differs from the order's; named price mode → order mode. */
+    priceTaxModeConverted?: 'inclusive-to-exclusive' | 'exclusive-to-inclusive';
+}
+interface LineTaxLine {
+    code?: string;
+    ratePpm: number;
+    taxMicros: string;
 }
 interface Discount {
     type: 'percentage' | 'fixed';
@@ -137,12 +320,14 @@ interface Discount {
 }
 interface AppliedDiscount extends Discount {
     id: string;
-    amount: number;
+    amountMinor: number;
 }
 interface Payment {
     id: string;
     method: string;
-    amount: number;
+    amountMinor: number;
+    tenderedMinor?: number;
+    changeMinor?: number;
     reference?: string;
 }
 interface CustomerSummary {
@@ -156,6 +341,22 @@ interface PaymentMethod {
     icon?: string;
     requiresReference?: boolean;
 }
+interface AddLineInput {
+    productId: string;
+    variantId?: string;
+    name: string;
+    sku?: string;
+    imageUrl?: string;
+    unitPrice: Money & {
+        taxInclusive?: boolean;
+    };
+    quantity?: number;
+    taxRates?: Array<{
+        code?: string;
+        ratePpm: number;
+    }>;
+    taxClass?: string;
+}
 
 interface OrderBuilderOptions {
     currency: string;
@@ -168,6 +369,7 @@ interface OrderBuilder {
         variantId?: string;
         quantity?: number;
     }): string;
+    addLine(input: AddLineInput): string;
     updateQuantity(lineId: string, quantity: number): void;
     removeItem(lineId: string): void;
     applyLineDiscount(lineId: string, discount: Discount): void;
@@ -182,11 +384,46 @@ 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.
+ *
+ * - The shares sum exactly to `totalMinor`, and no share exceeds its line's amount.
+ * - Leftover units go to the largest remainders; ties go to the earlier line, so the result is deterministic.
+ * - A line with a zero or negative amount gets 0.
+ *
+ * Throws RangeError unless every input is a safe integer and 0 ≤ totalMinor ≤ Σ positive amounts.
+ */
+declare function allocateOrderDiscount(lineAmountsMinor: readonly number[], totalMinor: number): number[];
+
 interface ParkedOrderSummary {
     id: string;
     customerName?: string;
     itemCount: number;
-    total: number;
+    totalMinor: number;
     parkedAt: string;
     source: 'local' | 'server';
 }
@@ -209,8 +446,15 @@ interface ReceiptLineItem {
     name: string;
     sku: string;
     quantity: number;
-    unitPrice: number;
-    lineTotal: number;
+    unitPriceMinor: number;
+    /** After every discount, including the line's order share, in the order's mode. Not the figure to print above the subtotal: use displayAmountMinor. */
+    lineTotalMinor: number;
+    discountMinor?: number;
+    displayAmountMinor: number;
+    displayDiscounts: {
+        label: string;
+        amountMinor: number;
+    }[];
 }
 interface ReceiptData {
     header: {
@@ -219,30 +463,34 @@ interface ReceiptData {
         orderNumber: string;
         date: string;
         cashier?: string;
+        customer?: string;
         register?: string;
     };
     lineItems: ReceiptLineItem[];
     discounts: {
         label: string;
-        amount: number;
+        amountMinor: number;
     }[];
+    orderDiscountMinor: number;
     totals: {
-        subtotal: number;
-        discountTotal: number;
+        taxInclusive: boolean;
+        subtotalMinor: number;
+        discountMinor: number;
         taxLines: {
             label: string;
-            rate: number;
-            amount: number;
+            code?: string;
+            ratePpm: number;
+            amountMinor: number;
         }[];
-        taxTotal: number;
-        total: number;
+        taxMinor: number;
+        totalMinor: number;
     };
     payments: {
         method: string;
-        amount: number;
+        amountMinor: number;
         reference?: string;
     }[];
-    changeDue: number;
+    changeDueMinor: number;
     footer: {
         note?: string;
         barcode?: string;
@@ -257,6 +505,1746 @@ 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
+ * it works the same on every backend.
+ *
+ * Every word of the term must appear in the product name, SKU or barcode
+ * (case-insensitive, any order). A term that exactly equals a barcode or SKU
+ * returns just those products, so a scanner hit is never buried among name
+ * matches. An empty term returns the input unchanged.
+ */
+declare function searchProducts<Doc>(docs: Doc[], term: string, traits: ProductTraits<Doc>): Doc[];
+
+/** The `stock_levels` collection as a live map of key to stock value. */
+declare function stockOverlay$(collection: RxCollection): Observable<Map<string, unknown>>;
+/**
+ * When the overlay was last confirmed by a successful pass (ISO 8601), or
+ * undefined before any pass. Read from the collection's local document, so a
+ * tab or screen that does not hold the runner can show it too.
+ */
+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;
+    variantId?: string;
+    name: string;
+    sku: string;
+    quantity: number;
+    unitPriceMinor: number;
+    /** Line discounts plus the allocated order-discount share, in the line's own tax mode (ADR-062). */
+    discountMinor: number;
+    netMinor: number;
+    taxLines: Array<{
+        code?: string;
+        ratePpm: number;
+        taxMicros: string;
+    }>;
+    /** This line's own tax mode; set only when it was converted from the store's (ADR-038 amendment). */
+    taxInclusive?: boolean;
+}
+interface PosOrderPayment {
+    id: string;
+    method: PaymentMethodKind;
+    amountMinor: number;
+    tenderedMinor?: number;
+    changeMinor?: number;
+    reference?: string;
+}
+interface PosOrder {
+    id: string;
+    createdAt: string;
+    currency: string;
+    pricesIncludeTax: boolean;
+    lines: PosOrderLine[];
+    subtotalMinor: number;
+    discountMinor: number;
+    taxMinor: number;
+    totalMinor: number;
+    payments: PosOrderPayment[];
+    customer: {
+        id?: string;
+        name?: string;
+        email?: string;
+    } | null;
+    note?: string;
+    registerId?: string;
+    /**
+     * The register session the sale was taken in (ADR-032): its closure counts this order.
+     * Sent at `order.create` version 3 as the payload's `sessionId` (the stamped or late session, one field).
+     */
+    sessionId?: string;
+    /**
+     * Set only by `useSale`'s late-sale path (ADR-032): the session the sale was taken for, which
+     * refused the stamp after the money was taken. Such an order has no `sessionId`, so no closure
+     * counts it. Sent at `order.create` version 3 as the payload's `sessionId` (the stamped or late session, one field).
+     */
+    lateSessionId?: string;
+    /**
+     * The order.create version every attempt under this `commandId` goes out at: the outbox records it before the first
+     * send, and lowers it only on a downgrade (ADR-065 amendment). Absent means not sent yet (or requeued).
+     */
+    sentVersion?: 1 | 2 | 3 | 4;
+    /** The version first tried, before the downgrade (the order's audit). */
+    downgradedFrom?: 1 | 2 | 3 | 4;
+    /** ADR-065: the receipt's display figures, in integer minor units of `currency` at `exponent`. */
+    display?: DisplayTotals & {
+        currency: string;
+        exponent: number;
+    };
+    /** ADR-065: tax by rate, named as `taxLinesByRate` names them (`amountMinor` is the tax). */
+    taxByRate?: Array<{
+        ratePpm: number;
+        code?: string;
+        label?: string;
+        netMinor: number;
+        amountMinor: number;
+        grossMinor: number;
+    }>;
+    /**
+     * The tax rounding the figures were computed with (#287), frozen at finalize; the till's own record, never sent.
+     * Version 6's migration sets the default on every older row.
+     */
+    taxRounding: TaxRounding;
+    cashierRef?: string;
+    syncStatus: PosOrderSyncStatus;
+    commandId: string;
+    serverRefs?: CommandServerRefs;
+    warnings?: CommandWarning[];
+    localWarnings?: PosOrderLocalWarning[];
+    serverFailures?: PosOrderServerFailures;
+    error?: CommandError;
+    updatedAt: string;
+}
+
+/** RFC 9562 UUIDv7: monotonic with no arguments; stateless with an explicit timestamp or random source. */
+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. 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. 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, options?: {
+    maxVersion?: number;
+}): OrderCreateEnvelope;
+
+/**
+ * Version 1 adds the optional `sessionId` (ADR-032); nothing else changed from version 0.
+ * Version 2 adds three optional fields and changes nothing else: `lateSessionId` (ADR-032, late
+ * sale), and ADR-065's `display` and `taxByRate`, declared ahead of the job that writes them so a
+ * till migrates once. Create the collection with `posOrderCollection()`, never with this schema
+ * alone: RxDB refuses a version above 0 without its migration strategies.
+ * Version 3 adds an index on `sessionId` (with its `maxLength`), and the optional `sentVersion` and `downgradedFrom` (the outbox's version fallback), and changes nothing else.
+ * Version 4 adds the optional `localWarnings` and `serverFailures` (the outbox's stuck clock start, latest reason and
+ * isolation, restored when an outbox starts), and changes nothing else.
+ * Version 5 lets `sentVersion` and `downgradedFrom` be 4 (order.create version 4, #286), and changes nothing else. Its
+ * migration sets a row's missing `sentVersion` to its content version, the version any earlier attempt went out at.
+ * Like version 4 (ADR-069), it is one-way: an older build shows no orders.
+ * Version 6 adds `taxRounding`, the strategy the sale's figures were computed with (#287; never sent), and changes
+ * nothing else. Its migration sets it on every older row. It is one-way like version 5.
+ */
+declare const posOrderSchema: RxJsonSchema<PosOrder>;
+/**
+ * The `pos_orders` collection config, with its migration strategies. Open the collection with
+ * `addPosOrderCollection(db)`, which uses this and settles the migration safely; adding this config
+ * directly leaves RxDB's own open path. `pos_orders` holds sales not yet sent, so no step may drop a
+ * document: versions 1 and 2 only add optional fields, so every order from version 0 or 1 passes
+ * unchanged.
+ *
+ * Within one run, RxDB 16.21 keeps an order that fails the new schema's validation: with a
+ * validating storage the migration stops with DM4 and the order stays in the older version's
+ * storage; without one it is copied as is. **Across runs, RxDB's own open path can lose it**: a
+ * failed run can leave its checkpoint past that order, and the next run then removes the older
+ * version's storage without copying it. `addPosOrderCollection` resets that checkpoint, so use it
+ * (`migration.test.ts`).
+ */
+declare function posOrderCollection(): {
+    schema: RxJsonSchema<PosOrder>;
+    migrationStrategies: MigrationStrategies;
+};
+
+/** `addPosOrderCollection`'s logger: attach a sink to see, for example, the status writes a closing open dropped. */
+declare const posOrdersLogger: Logger;
+/**
+ * `addPosOrderCollection` stopped, before any further write, because its database is closing: it
+ * was called once `close()` had begun, the close cancelled its migration (RxDB 17.5), or the close
+ * stopped waiting for it (after `POS_ORDER_MIGRATION_CLOSE_WAIT_MS`). No order is lost: reopen the
+ * database and call it again.
+ */
+declare class PosOrderOpenClosedError extends Error {
+    readonly databaseName: string;
+    readonly code = "POS_ORDER_OPEN_CLOSED";
+    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.
+ */
+declare function addPosOrderCollection(db: RxDatabase, closeWaitMs?: number): Promise<RxCollection<PosOrder>>;
+
+/**
+ * Returns this device's id (a UUIDv7), stored under `key` in `storage` (web storage, or an app's
+ * equivalent) and minted on first use; medusapos passes `'medusapos.register_id'`. With no storage,
+ * or one that throws on read or write, it falls back to one id per process.
+ */
+declare function getDeviceId(storage: {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+} | null, key: string): string;
+
+/**
+ * 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[], options?: {
+    stuckCommandIds?: readonly string[];
+}): PosOrder[];
+
+type SaleContent = Pick<PosOrder, 'totalMinor' | 'currency' | 'lines' | 'payments'>;
+/**
+ * Whether two orders carry the same money-bearing content: `totalMinor` and `currency`; each line's
+ * `id`, `quantity` and `netMinor`, in order; each payment's `method` and `amountMinor`, in order.
+ * An order `id` is minted once per sale (`finalizeOrder`), so the same `id` with other content is a defect.
+ */
+declare function sameSale(stored: SaleContent, retried: SaleContent): boolean;
+/** A stored order has this order's `id` but other money-bearing content (see `sameSale`): never treated as stored. */
+declare class OrderContentMismatchError extends Error {
+    readonly orderId: string;
+    constructor(orderId: string);
+}
+
+type MovementType = 'paid_in' | 'paid_out' | 'no_sale';
+declare function normalizeAmount(raw: string): string;
+/** Whether the server's `decimal()` would accept this string. */
+declare function isServerDecimal(value: string): boolean;
+/**
+ * The field the server would name in its 400, or null when it would accept the movement.
+ * A no sale carries no amount — the sheet sends '0' — but still needs a reason.
+ */
+declare function movementFieldError(input: {
+    type: MovementType;
+    amount: string;
+    reason: string;
+}): 'amount' | 'reason' | null;
+
+/**
+ * What the register should hold at close, per tender method: the session's cash float plus
+ * captured payments and cash movements — never what the cashier counts. Port provenance
+ * (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`.
+ *
+ * **Refund attribution is deferred.** WCPOS's `attributeRefunds` debits a session's drawer for
+ * refunds processed against its captured payments (by stamped session, then by a legacy
+ * `refunded_amount` fallback). TallyUI has no refund model yet (ADR-032 amendment 1), so
+ * `deriveExpected` covers only the float, the session's captured payment rows, and its
+ * paid-in/paid-out cash movements under WCPOS's void rules.
+ */
+/** `session_id`, `kind`, `method_id`, `status` kept as WCPOS names them; money is TallyUI's integer-minor-units convention. */
+type LedgerRow = {
+    session_id?: string | null;
+    kind: string;
+    method_id: string;
+    status: string;
+    amountMinor: number;
+};
+/** `type`, `voids` and `voided_by` are kept as WCPOS names them: neutral across backends. */
+type Movement$1 = {
+    id: string;
+    session_id: string;
+    type: string;
+    amountMinor: number;
+    voided_by?: string | null;
+    voids?: string | null;
+};
+/**
+ * Expected totals per tender method: the counted float, plus every captured ledger row for the
+ * session (grouped under `cash` for cash rows, else `method_id`), plus its non-voided
+ * paid-in/paid-out movements.
+ *
+ * A movement is excluded when its own `voided_by` is set, or when a `type: 'void'` row's
+ * `voids` names its id; the `void` row itself carries no amount of its own.
+ */
+declare function deriveExpected({ session, movements, ledgerRowsBySession, }: {
+    session: {
+        id: string;
+        countedFloatMinor: number;
+    };
+    movements: readonly Movement$1[];
+    ledgerRowsBySession: readonly LedgerRow[];
+}): Record<string, number>;
+
+/**
+ * The pure maths behind a register count: variance against the expected float, a display
+ * string for it, and the denomination arithmetic the counting keypad uses. Port provenance
+ * (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`.
+ *
+ * Money here is TallyUI's convention: integer minor units. Everywhere WCPOS assumed two
+ * decimals, these take the currency's `exponent` instead — 0 for JPY, 3 for KWD — except
+ * `validAmount`, which like WCPOS still takes the cashier's typed text.
+ */
+/**
+ * Parses a decimal string the cashier typed into integer minor units at `exponent` decimal
+ * places, without rounding. Returns `NaN` when the string carries more precision than the
+ * currency allows, so a safe-integer check on the result also rejects it.
+ */
+declare function parseMinor(text: string, exponent: number): number;
+declare const validAmount: (value: string, exponent: number) => boolean;
+/** Counted minus expected, both already in minor units. */
+declare const countVariance: (countedMinor: number, expectedMinor: number) => number;
+/** Whether the variance exceeds the store's configured threshold (minor units; none means never). */
+declare const overThreshold: (variance: number, thresholdMinor?: number | null) => boolean;
+/**
+ * Whether a close's cash count needs a manager's approval: its cash variance against the expected
+ * cash is over the threshold. The one definition `RegisterCount` and `useRegisterSession`'s
+ * `closeSession` gate share (ADR-032).
+ */
+declare const closeNeedsApproval: (countedCashMinor: number, expectedCashMinor: number, thresholdMinor?: number | null) => boolean;
+/** Sums denomination face values (already minor units) by piece count. */
+declare const denominationTotal: (pieces: Record<number, number>) => number;
+/**
+ * The variance line under the count: exact, short or over. `format` takes a major-unit
+ * amount, as an app's currency formatter expects, so `exponent` converts `variance` back for
+ * it; `t` supplies the translated words for the `register.exact`/`register.short`/
+ * `register.over` keys. Both are the app's own — neutral here.
+ *
+ * The direction lives in the word, not a sign (the Front desk, 2026-09-28): a signed amount
+ * next to "short" read as a double negative, so the amount here is always its absolute value.
+ */
+declare function varianceText(variance: number, exponent: number, format: (value: number) => string, t: (key: string) => string): string;
+
+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.
+ *
+ * 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
+ * (`sync_status`, attempts, next time, error) and closures' server and receipt fields are gone;
+ * sending sessions to a server is registers job c.
+ *
+ * Money is integer minor units: WCPOS's decimal strings become `*_minor` integers (`amountMinor`
+ * on a movement, matching `Movement`), and a tender map (`counted`, `expected`, `variance`, keyed
+ * 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.
+ */
+
+type TenderMap = Record<string, number>;
+interface RegisterSession {
+    id: string;
+    register_id: string;
+    /** The app's neutral store key (see `bindRegister`). */
+    store_key?: string | null;
+    status: 'open' | 'counting' | 'closed';
+    /** The store's day the session opened, `yyyy-MM-dd`. */
+    business_day?: string;
+    opened_at_gmt: string;
+    opened_by?: string | null;
+    expected_float_minor?: number | null;
+    counted_float_minor: number;
+    opening_variance_minor?: number | null;
+    counting_started_at_gmt?: string | null;
+    closed_at_gmt?: string | null;
+    closed_by?: string | null;
+    approval_required?: boolean;
+    approved_by?: string | null;
+    counted?: TenderMap | null;
+    closure_id?: string | null;
+    /** The last local transition, kept for a server to acknowledge (job c). */
+    pending_status?: string | null;
+    server_status?: string | null;
+    status_at?: string | null;
+    approver_token?: string | null;
+    /** A server's expected figures; cleared before every money action (`requireOpenSession`). */
+    server_expected?: TenderMap | null;
+    server_sales_count?: number | null;
+}
+interface CashMovement {
+    id: string;
+    session_id: string;
+    type: 'paid_in' | 'paid_out' | 'no_sale' | 'void';
+    amountMinor: number;
+    reason: string;
+    created_at_gmt: string;
+    created_by?: string | null;
+    /** On a `void` row: the movement it reverses. */
+    voids?: string | null;
+    /** On a reversed movement: its `void` row. */
+    voided_by?: string | null;
+}
+interface Closure {
+    id: string;
+    session_id: string;
+    register_id: string;
+    store_key?: string | null;
+    business_day?: string;
+    closed_by?: string | null;
+    corrections_count?: number;
+    number: number;
+    opened_at: string;
+    closed_at: string;
+    till_expected: TenderMap;
+    expected: TenderMap;
+    counted: TenderMap;
+    variance: TenderMap;
+    period_sales_total_minor: number;
+    /** Always 0 until TallyUI has a refund model (ADR-032 amendment 1). */
+    period_refunds_total_minor: number;
+    perpetual_sales_total_minor: number;
+    perpetual_refunds_total_minor: number;
+    /** This session's orders still waiting for the outbox, and their payments' total. */
+    unsynced_count: number;
+    unsynced_total_minor: number;
+    software_version: string;
+    breakdowns: Record<string, unknown>;
+    order_ids: string[];
+    movement_ids: string[];
+    server_closure_id?: string | null;
+    printed_at?: string | null;
+    print_count: number;
+    number_retried?: boolean;
+}
+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.
+ */
+declare function registerSessionCollection(): {
+    readonly schema: RxJsonSchema<RegisterSession>;
+    readonly localDocuments: true;
+};
+declare const cashMovementSchema: RxJsonSchema<CashMovement>;
+declare const closureSchema: RxJsonSchema<Closure>;
+
+type RegisterHost = RxLocalDocumentMutation<any>;
+type RegisterCounters = {
+    last_closure_number: number;
+    perpetual_sales_total_minor: number;
+    perpetual_refunds_total_minor: number;
+    counters_started_at?: string | null;
+};
+/**
+ * One register's counters, plus the closure being written: the draft is reserved here, in the
+ * 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;
+    };
+    /** Closure ids the orphan-stamp sweep has already checked (ADR-032, the #158 follow-ups): a
+     *  local-document field, so bounding the sweep needs no schema bump. */
+    swept_closure_ids?: string[];
+};
+interface RegisterStore {
+    sale_counter: number;
+    registers?: Record<string, RegisterBucket>;
+    /** The register (drawer) this till is bound to in this store. */
+    register_id?: string | null;
+    register_name?: string | null;
+}
+interface RegisterDocument {
+    id: string;
+    name: string;
+    /** The caller's platform, for example `'ios'` or `'web'`. */
+    platform: string;
+    created_at: string;
+    /** Keyed by `storeKey`. */
+    stores: Record<string, RegisterStore>;
+}
+declare function mintUuid(): string;
+declare function readRegister(host: RegisterHost): Promise<RegisterDocument | null>;
+/** Reads the register document, minting it on first use; concurrent callers get the same one. */
+declare function ensureRegister(host: RegisterHost, platform: string): Promise<RegisterDocument>;
+declare function observeRegister$(host: RegisterHost): rxjs.Observable<RegisterDocument | null>;
+declare function getBoundRegisterId(register: RegisterDocument | null, storeKey: string): string | null;
+declare function readBoundRegister(host: RegisterHost, storeKey: string): Promise<{
+    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;
+}): Promise<void>;
+declare function unbindRegister(host: RegisterHost, storeKey: string): Promise<void>;
+declare function nextSaleCounter(host: RegisterHost, storeKey: string): Promise<number>;
+/**
+ * Mints the register's next closure number. Given the closure draft, it reserves the draft with
+ * its number and perpetual totals in the same atomic write, and a retry of the same draft gets the
+ * same number back. A different draft is refused while an earlier one is reserved but not yet
+ * applied (`closure_write_incomplete`).
+ */
+declare function mintClosureNumber(host: RegisterHost, storeKey: string, registerId: string, closure?: Closure): Promise<number>;
+/**
+ * Adds a closed period to the register's perpetual totals. With `closureId`, it applies that
+ * reserved closure once: the totals become the reservation's, and a repeat does nothing.
+ */
+declare function advancePerpetual(host: RegisterHost, storeKey: string, registerId: string, period: {
+    salesMinor: number;
+    refundsMinor: number;
+    closureId?: string;
+}): Promise<void>;
+
+type RegisterSessionCollection = RxCollection<RegisterSession>;
+type CashMovementCollection = RxCollection<CashMovement>;
+type ClosureCollection = RxCollection<Closure>;
+declare class RegisterSessionRequiredError extends Error {
+    constructor();
+}
+/** The session is closed, and a closed session is final: there's no server yet to refuse writes to it. */
+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 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;
+    readonly session_id: string;
+    constructor(movement: {
+        id: string;
+        session_id: string;
+    });
+}
+declare const openSessionSelector: {
+    readonly status: "open";
+};
+/** The open session's id before a money action, or `RegisterSessionRequiredError`; `null` when sessions are off. */
+declare function requireOpenSession(sessions: RegisterSessionCollection | undefined, registerId: string | null, enabled: boolean): Promise<string | null>;
+declare function stampSession(order: PosOrder, sessionId: string, sessions: RegisterSessionCollection): Promise<PosOrder>;
+declare function openSession(sessions: RegisterSessionCollection, input: {
+    registerId: string;
+    expectedFloatMinor: number | null;
+    countedFloatMinor: number;
+    openedBy: string;
+    /** The store's day, not the device's UTC day. */
+    businessDay: {
+        year: number;
+        month: number;
+        day: number;
+    };
+    storeKey?: string | null;
+}): 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
+ * write as the close, and a repeat close keeps the first close's approver as it keeps its count.
+ */
+declare function closeSession(sessions: RegisterSessionCollection, id: string, input: {
+    counted: Record<string, number>;
+    closedBy?: string;
+    approvedBy?: string;
+    timezone?: string;
+}): 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
+ * `RegisterMovementStrandedError` (kept; don't record it again).
+ */
+declare function recordMovement(sessions: RegisterSessionCollection, movements: CashMovementCollection, closures: ClosureCollection, input: {
+    sessionId: string;
+    type: 'paid_in' | 'paid_out' | 'no_sale';
+    amountMinor: number;
+    reason: string;
+    actor: string;
+}): 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, {}, 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
+ * same snapshot and number, and its period reaches the perpetual totals exactly once.
+ * Only a closed session (`closed` with `closed_at_gmt`) has a closure, and a closed session is
+ * final, so its existing closure is returned as it was frozen. Orders the server rejected still
+ * count in the drawer, because the cash was taken.
+ */
+declare function writeClosure({ closures, register, storeKey, session, counted, otherTenders, movements, orders, tillExpected, labels, resolveCashierName, softwareVersion, timezone, }: {
+    closures: ClosureCollection;
+    /** The register document's host (`register_sessions`). */
+    register: RegisterHost;
+    storeKey: string;
+    session: RegisterSession;
+    /** Counted cash, minor units. */
+    counted: number;
+    otherTenders: Record<string, number>;
+    movements: readonly CashMovement[];
+    /** Any `pos_orders`; only those whose `sessionId` is this session's are counted. */
+    orders: readonly PosOrder[];
+    tillExpected?: Record<string, number>;
+    labels?: {
+        register_name: string;
+        closed_by_name: string;
+        opened_by_name?: string;
+        approved_by_name?: string;
+    };
+    resolveCashierName?: (id: string) => string;
+    /** The app's version, stamped on the closure. */
+    softwareVersion: string;
+    timezone?: string;
+}): Promise<rxdb.RxDocument<Closure, {}, unknown>>;
+
+/**
+ * Corrections layered onto a closure's recorded figures (ADR-032): late sales, late cash
+ * movements and recounts, applied in order and deduplicated by id. Port provenance (ADR-032
+ * amendment 1): WCPOS `next` `3b5331b5c` `settled-figures.ts`. Money is TallyUI's integer
+ * minor-units convention: WCPOS's four-decimal-string arithmetic becomes direct integer
+ * arithmetic on a2's `*_minor` fields and tender maps.
+ */
+
+type Correction = {
+    id: number;
+    type: 'late_sale' | 'late_movement' | 'recount';
+    created_at: string;
+    actor: {
+        id: string;
+        name: string;
+    };
+    approver: {
+        id: string;
+        name: string;
+    } | null;
+    reason: string;
+    figures: {
+        expected_delta?: Record<string, number>;
+        cash_delta?: number;
+        sales_delta?: number;
+        refunds_delta?: number;
+        counted?: Record<string, number>;
+        variance?: Record<string, number>;
+    };
+};
+type RecordedFigures = Pick<Closure, 'expected' | 'counted' | 'variance' | 'period_sales_total_minor' | 'period_refunds_total_minor' | 'perpetual_sales_total_minor' | 'perpetual_refunds_total_minor'>;
+/**
+ * Folds `corrections` onto `recorded`, ordered by `created_at` then `id`, deduplicated by `id`.
+ * A `recount` replaces the supplied tenders in `counted`; a `late_movement` adds its signed
+ * `cash_delta` to expected cash; a `late_sale` adds its `expected_delta` tenders to expected and
+ * its `sales_delta`/`refunds_delta` to both the period and perpetual totals. Variance is
+ * recomputed for every tender named by expected or counted, once any correction applies.
+ * `touched` names every field, or `field.tender`, whose settled value differs from `recorded`.
+ */
+declare function deriveSettled(recorded: RecordedFigures, corrections: readonly Correction[]): {
+    settled: {
+        expected: {
+            [x: string]: number;
+        };
+        counted: {
+            [x: string]: number;
+        };
+        variance: {
+            [x: string]: number;
+        };
+        period_sales_total_minor: number;
+        period_refunds_total_minor: number;
+        perpetual_sales_total_minor: number;
+        perpetual_refunds_total_minor: number;
+    };
+    touched: Set<string>;
+};
+
+declare function exportCsv(rows: readonly Closure[], exponent: number, t: (key: string) => string, names?: Record<string, string>, storeName?: string): string;
+
+declare const labelKeys: {
+    x_report: string;
+    closure: string;
+    opened: string;
+    closed: string;
+    approver: string;
+    opening_float: string;
+    expected: string;
+    counted: string;
+    variance: string;
+    tenders: string;
+    tender: string;
+    cash_movements: string;
+    time: string;
+    type: string;
+    amount: string;
+    reason: string;
+    sales: string;
+    period_sales: string;
+    period_refunds: string;
+    transactions: string;
+    refunds: string;
+    payment_method: string;
+    cashiers: string;
+    tax_rates: string;
+    tax_rate: string;
+    net: string;
+    tax: string;
+    gross: string;
+    perpetual_totals: string;
+    perpetual_sales: string;
+    perpetual_refunds: string;
+    unsynced_sales: string;
+    short: string;
+    over: string;
+    exact: string;
+    voided: string;
+    paid_in: string;
+    paid_out: string;
+    no_sale: string;
+    void: string;
+    copy: string;
+};
+
+type ClosureScope = {
+    from: string;
+    to: string;
+    registerId: string;
+    storeKey?: string;
+    cashier?: string;
+};
+/** Clamps a requested scope's `from`/`to` to `today` and to `historyDays` before it. */
+declare function clampClosureScope(scope: ClosureScope, today: string, historyDays?: number): ClosureScope;
+/**
+ * Rows within `scope`, newest business day first, then newest `closed_at`. A row with no
+ * `business_day` (a legacy or remote row) gets one from `opened_at` in `timezone`, reusing a2's
+ * `businessDayOf` rather than duplicating it. Register and cashier are optional filters; the
+ * store is not — a row's `store_key` must equal `scope.storeKey` (both `null` when neither is
+ * set), as WCPOS always compared `store_id`.
+ */
+declare function selectClosureRows(rows: readonly Closure[], scope: ClosureScope, timezone: string): {
+    business_day: string;
+    id: string;
+    session_id: string;
+    register_id: string;
+    store_key?: string | null;
+    closed_by?: string | null;
+    corrections_count?: number;
+    number: number;
+    opened_at: string;
+    closed_at: string;
+    till_expected: {
+        [x: string]: number;
+    };
+    expected: {
+        [x: string]: number;
+    };
+    counted: {
+        [x: string]: number;
+    };
+    variance: {
+        [x: string]: number;
+    };
+    period_sales_total_minor: number;
+    period_refunds_total_minor: number;
+    perpetual_sales_total_minor: number;
+    perpetual_refunds_total_minor: number;
+    unsynced_count: number;
+    unsynced_total_minor: number;
+    software_version: string;
+    breakdowns: Record<string, unknown>;
+    order_ids: string[];
+    movement_ids: string[];
+    server_closure_id?: string | null;
+    printed_at?: string | null;
+    print_count: number;
+    number_retried?: boolean;
+}[];
+
+/**
+ * Minor-unit money formatting shared across the register package (moved out of `export-csv.ts` so
+ * `closure-document.ts` reuses the same implementation instead of duplicating it).
+ */
+/**
+ * `minor` as a fixed-point decimal string with exactly `exponent` places: `-50` at exponent 2 is
+ * `'-0.50'`, `1250` is `'12.50'`, and at exponent 0, `1500` is `'1500'`. Integer maths only —
+ * sign, `Math.trunc`, and the remainder padded to `exponent` digits — no `toFixed` on floats.
+ */
+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;
+    timezone: string;
+    locale: string;
+    printedAt: string;
+    /** Minor-unit decimal places for every money field the envelope carries. */
+    exponent: number;
+    formatMoney: (value: string) => string;
+    i18n: Record<string, string>;
+    /** Overrides an X-report's `server_expected` tender map, in minor units. */
+    expected?: Record<string, number>;
+    /**
+     * `buildXReportDocument`'s own breakdowns merge only (unlike `buildClosureDocument`'s frozen
+     * `Closure.breakdowns`): its money fields are still expected as decimal strings, not minor
+     * units. Job c's X-report caller, once it exists, converts them before passing this in.
+     */
+    breakdowns?: Values;
+};
+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;
+    } & {
+        breakdowns: Values;
+        store_id: string | null | undefined;
+        till_expected: Record<string, string>;
+        expected: Record<string, string>;
+        counted: Record<string, string>;
+        variance: Record<string, string>;
+        period_sales_total: string;
+        period_refunds_total: string;
+        perpetual_sales_total: string;
+        perpetual_refunds_total: string;
+        unsynced_total: string;
+        id: string;
+        session_id: string;
+        register_id: string;
+        business_day?: string;
+        closed_by?: string | null;
+        corrections_count?: number;
+        number: number;
+        opened_at: string;
+        closed_at: string;
+        unsynced_count: number;
+        software_version: string;
+        order_ids: string[];
+        movement_ids: string[];
+        server_closure_id?: string | null;
+        printed_at?: string | null;
+        print_count: number;
+        number_retried?: boolean;
+    } & {
+        opened_at_gmt: unknown;
+        opened_by: {} | null;
+        closed_by: {} | null;
+        approved_by: {} | null;
+        closed_at_gmt: unknown;
+        opened_at: Record<string, string>;
+        closed_at: Record<string, string>;
+        tenders: ({
+            name: string;
+            label: {};
+            expected: string;
+            counted: string;
+            variance: string;
+            has_variance: boolean;
+            variance_label: string;
+            variance_absolute_display: string;
+        } & Record<"counted_display" | "expected_display" | "variance_display", string>)[];
+        breakdowns: {
+            labels: Values;
+            payment_methods: ({
+                name: {};
+            } & Record<`${string}_display`, string>)[];
+            tax_rates: ({
+                name: {};
+            } & Record<`${string}_display`, string>)[];
+            opening_float: Values & Record<"counted_display" | "expected_display" | "variance_display", string>;
+            movements: {
+                created_at: Record<string, string>;
+                type_label: string;
+                voided: boolean;
+                id: string;
+                reason: string;
+                amount_display: string;
+            }[];
+            cashiers: Values[];
+        };
+        period_sales_total_display: string;
+        period_refunds_total_display: string;
+        perpetual_sales_total_display: string;
+        perpetual_refunds_total_display: string;
+        unsynced_total_display: string;
+    };
+    store: Values;
+    register: {
+        id: unknown;
+        name: {};
+    };
+    software: {
+        name: string;
+        plugin_version: {};
+    };
+    order: {
+        currency: string;
+        printed: Record<string, string>;
+    };
+    fiscal: {
+        immutable_id: string;
+        hash: string;
+        qr_payload: string;
+        tax_agency_code: string;
+        signature_excerpt: string;
+        document_label: string;
+        sequence: null;
+        signed_at: null;
+        extra_fields: never[];
+        document_type: string;
+        receipt_number: string;
+        is_sale_document: boolean;
+        is_refund_document: boolean;
+        is_closure_document: boolean;
+        is_x_report: boolean;
+        is_reprint: boolean;
+        reprint_count: number;
+    };
+    i18n: Record<string, string>;
+};
+declare function buildXReportDocument(session: RegisterSession, context: ClosureContext): {
+    closure: {
+        tax_rounding_note?: string | undefined;
+        has_sales: boolean;
+        has_perpetual: boolean;
+    } & {
+        id: string;
+        register_id: string;
+        store_id: string | null | undefined;
+        opened_at: string;
+        expected: Record<string, string>;
+        counted: Record<string, string>;
+        variance: Record<string, string>;
+        breakdowns: {
+            opening_float: {
+                expected: string | undefined;
+                counted: string | undefined;
+                variance: string | undefined;
+            };
+        };
+    } & {
+        opened_at_gmt: unknown;
+        opened_by: {} | null;
+        closed_by: {} | null;
+        approved_by: {} | null;
+        closed_at_gmt: unknown;
+        opened_at: Record<string, string>;
+        closed_at: Record<string, string>;
+        tenders: ({
+            name: string;
+            label: {};
+            expected: string;
+            counted: string;
+            variance: string;
+            has_variance: boolean;
+            variance_label: string;
+            variance_absolute_display: string;
+        } & Record<"counted_display" | "expected_display" | "variance_display", string>)[];
+        breakdowns: {
+            labels: Values;
+            payment_methods: ({
+                name: {};
+            } & Record<`${string}_display`, string>)[];
+            tax_rates: ({
+                name: {};
+            } & Record<`${string}_display`, string>)[];
+            opening_float: Values & Record<"counted_display" | "expected_display" | "variance_display", string>;
+            movements: {
+                created_at: Record<string, string>;
+                type_label: string;
+                voided: boolean;
+                id: string;
+                reason: string;
+                amount_display: string;
+            }[];
+            cashiers: Values[];
+        };
+        period_sales_total_display: string;
+        period_refunds_total_display: string;
+        perpetual_sales_total_display: string;
+        perpetual_refunds_total_display: string;
+        unsynced_total_display: string;
+    };
+    store: Values;
+    register: {
+        id: unknown;
+        name: {};
+    };
+    software: {
+        name: string;
+        plugin_version: {};
+    };
+    order: {
+        currency: string;
+        printed: Record<string, string>;
+    };
+    fiscal: {
+        immutable_id: string;
+        hash: string;
+        qr_payload: string;
+        tax_agency_code: string;
+        signature_excerpt: string;
+        document_label: string;
+        sequence: null;
+        signed_at: null;
+        extra_fields: never[];
+        document_type: string;
+        receipt_number: string;
+        is_sale_document: boolean;
+        is_refund_document: boolean;
+        is_closure_document: boolean;
+        is_x_report: boolean;
+        is_reprint: boolean;
+        reprint_count: number;
+    };
+    i18n: Record<string, string>;
+};
+
+/** The register-session logging scope; the app attaches its own sinks (console, remote, toast). */
+declare const registerFactsLogger: Logger;
+type Actor = {
+    id: string;
+    name: string;
+};
+type Pair = {
+    sessionId: string | undefined;
+    registerId: string | null | undefined;
+};
+type Human = Pair & {
+    actor: Actor;
+};
+type Movement = Pair & {
+    movementId: string;
+    movementType: CashMovement['type'];
+    amount: number;
+};
+type SimpleKind = 'counting-started' | 'counting-abandoned' | 'approval-refused' | 'x-report-dispatched' | 'drawer-dispatched';
+type RegisterFact = (Human & {
+    kind: 'session-opened';
+    amount: number;
+    variance: RegisterSession['opening_variance_minor'];
+}) | (Human & {
+    kind: SimpleKind;
+}) | (Human & {
+    kind: 'session-closed';
+    closureId: string;
+} & Pick<Closure, 'number' | 'counted' | 'variance'>) | (Human & Movement & {
+    kind: 'movement-recorded';
+}) | (Human & Movement & {
+    kind: 'movement-voided';
+    voids: string;
+}) | (Human & {
+    kind: 'approval-granted';
+    approvedBy: string | null;
+}) | (Human & {
+    kind: 'variance-over-threshold';
+    variance: number;
+    threshold: number | undefined;
+}) | (Pair & {
+    kind: 'late-sale';
+    orderId: string;
+    actor?: Actor;
+});
+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();
+}
+/** The register already has an `open` or `counting` session, or an open is in flight. Its message can be shown to a cashier as it is. */
+declare class RegisterSessionAlreadyOpenError extends Error {
+    constructor();
+}
+/** An earlier session's close didn't finish (its closure is unwritten or unapplied); close it first. Its message can be shown to a cashier as it is. */
+declare class RegisterCloseIncompleteError extends Error {
+    constructor();
+}
+/** The count is over `varianceThreshold` and the close carries no `approvedBy`. Its message is `RegisterCount`'s refusal copy, so it can be shown to a cashier as it is. */
+declare class RegisterApprovalRequiredError extends Error {
+    constructor();
+}
+interface UseRegisterSessionOptions {
+    /** `register_sessions`, created with `registerSessionCollection()`; `null` while it opens. */
+    sessions: RegisterSessionCollection | null;
+    /** `cash_movements`; `null` while it opens. */
+    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. */
+    register: RegisterHost | null;
+    /** The app's neutral store key (see `bindRegister`). */
+    storeKey: string;
+    /** The register (drawer) this till is bound to, or `null` when it isn't bound. */
+    registerId: string | null;
+    /** The store uses register sessions; `false` turns everything off, as WCPOS's `sessionsOn`. */
+    enabled: boolean;
+    /** The signed-in cashier, for the facts and `opened_by`/`closed_by`. */
+    actor: Actor;
+    /** The store's IANA zone, or `'device'`: the business day a session opens on. */
+    timezone: string;
+    /** The app's version, stamped on the closure. */
+    softwareVersion: string;
+    /** A sale is at tender (`sale.stage.kind === 'tender'`): counting and closing refuse. */
+    tenderInProgress: boolean;
+    /** The count variance, in minor units, over which the app asks for approval. */
+    varianceThreshold?: number;
+    /** `'HH:mm'` on the device's clock; an open session after it is `overdue`. */
+    expectedCloseTime?: string;
+    /** The cashier may not see expected figures while counting. */
+    blind?: boolean;
+    /** The closure's register name, and a person id's display name. */
+    labels?: {
+        registerName?: string;
+        resolveCashierName?: (id: string) => string;
+    };
+}
+declare function useRegisterSession(options: UseRegisterSessionOptions): {
+    session: RegisterSession | null;
+    movements: CashMovement[];
+    expected: Record<string, number>;
+    salesCount: number;
+    overdue: boolean;
+    /** A `closeSession` for this register is in flight, in any hook instance: the session can already be stored `closed` while its closure isn't written yet. */
+    closing: boolean;
+    lastClosure: Closure;
+    lastClosed: RegisterSession;
+    varianceThreshold: number | undefined;
+    enabled: boolean;
+    blind: boolean;
+    /** Pass straight to useSale's `session` option: `complete()` then stamps through `stampSession`. */
+    saleSession: {
+        id: string;
+        sessions: RegisterSessionCollection;
+    } | undefined;
+    /** The open session's id, `null` when sessions are off, else `RegisterSessionRequiredError`. Call it when tender starts and before a card terminal captures. */
+    requireOpen: () => Promise<string | null>;
+    /** `requireOpen()`, returning `{ id, sessions }`: pass it to useSale's `startTender`, which pins it (the rendered `saleSession` can lag). */
+    requireSaleSession: () => Promise<{
+        id: string;
+        sessions: RegisterSessionCollection;
+    } | null>;
+    actions: {
+        /**
+         * 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.
+         */
+        openSession: (input: {
+            expectedFloatMinor: number | null;
+            countedFloatMinor: number;
+        }) => 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).
+         * Over `varianceThreshold` (`closeNeedsApproval`, as `RegisterCount`), a close without
+         * `approvedBy` throws `RegisterApprovalRequiredError` before any write, blind or not; a
+         * resumed close (the stored session already closed) isn't gated again. `approvedBy` reaches the Z
+         * (`breakdowns.approved_by`), and `approvedByName` its `approved_by_name`.
+         * One close per register runs at a time, in any hook instance: a call while one is in flight joins
+         * it, getting its closure or error, and its own `counted`, `approvedBy` and `approvedByName` are ignored.
+         */
+        closeSession: (input: {
+            counted: Record<string, number>;
+            approvedBy?: string;
+            approvedByName?: string;
+        }) => Promise<rxdb.RxDocument<Closure, {}, unknown>>;
+        recordMovement: (input: {
+            type: "paid_in" | "paid_out" | "no_sale";
+            amountMinor: number;
+            reason: string;
+        }) => Promise<rxdb.RxDocument<CashMovement, {}, unknown>>;
+        voidMovement: (id: string) => Promise<rxdb.RxDocument<CashMovement, {}, unknown>>;
+    };
+};
+
+type CatalogueEntry<Doc> = {
+    product: Doc;
+    variant: VariantSummary;
+};
+/** Every variant of every product, in product order then variant order. */
+declare function catalogueEntries<Doc>(products: Doc[], traits: ProductTraits<Doc>): CatalogueEntry<Doc>[];
+/** Barcode-then-SKU lookup across all products. */
+declare function findEntryByCode<Doc>(entries: CatalogueEntry<Doc>[], code: string): CatalogueEntry<Doc> | undefined;
+/** Display the resolved price in the requested currency. */
+declare function variantPriceLabel(variant: VariantSummary, currency: string, locale?: string): string | undefined;
+
+/** Logs a throw from onSaleCompleted for a confirmed pending completion newSale() has abandoned (Continue): nothing else would ever surface it. */
+declare const saleLogger: Logger;
+type SaleStage = {
+    kind: 'cart';
+} | {
+    kind: 'tender';
+    method: 'cash' | 'external';
+} | {
+    kind: 'receipt';
+    order: SentOrder;
+    posOrder: PosOrder;
+};
+/** TallyUI finalizeOrder's refusal below order.create v2 (c19a203), shown when the discount is applied; finalize stays the backstop. */
+declare const DISCOUNTS_UNSUPPORTED = "finalize: discounts are not supported by the server yet (order.create v2)";
+/** Every sale change refuses with this while a completion is pending (see `complete()`). */
+declare const SALE_SAVING = "This sale is being saved. Retry to finish it.";
+/** Call under a `TaxProvider`: its tax context and the settings' currency price every sale. */
+declare function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
+    registerId: string;
+    cashierRef: string;
+    capabilities?: ServerCapabilities;
+    /**
+     * When set, `complete()` stamps the finalized order with this session before `onSaleCompleted`.
+     * `complete()` runs after the money is taken, so a refused stamp (the session closed or went
+     * missing) never stops the sale: it goes on to `onSaleCompleted` and the receipt with
+     * `lateSessionId` instead of `sessionId`, and a `late-sale` register fact is recorded (ADR-032).
+     * The session stamped is the one in force when the tender started (`startTender`), pinned for that
+     * tender: this option going undefined mid-tender (the session closed) doesn't skip the stamp. A
+     * tender that pinned none, with a session here at `complete()`, stamps it and logs a warning.
+     */
+    session?: {
+        id: string;
+        sessions: RegisterSessionCollection;
+    };
+    onSaleCompleted?: (posOrder: PosOrder) => Promise<void> | void;
+    /**
+     * Asked after `onSaleCompleted` throws, or on a `newSale()` refused mid-save: whether that order is confirmed stored
+     * (medusapos: `useOrderOutbox`'s `isStored`). Only a true answer sets `canContinue`; without it, a failed save offers Retry only.
+     */
+    isStored?: (posOrder: PosOrder) => Promise<boolean>;
+    /** Tests only: overrides HUNG_SAVE_CHECK_MS, so a test can shrink the hung-save poll's interval. */
+    hungSaveCheckMs?: number;
+}): {
+    order: Order;
+    stage: SaleStage;
+    error: string | null;
+    idle: boolean;
+    /** A completion is pending (see `complete()`): the sale is locked, and the UI offers Retry. */
+    saving: boolean;
+    /** The failed save's order is confirmed stored (see `isStored`): the UI also offers Continue (`continueSale()`). */
+    canContinue: boolean;
+    add(entry: CatalogueEntry<any>, traits: ProductTraits<any>): void;
+    setQuantity(lineId: string, quantity: number): void;
+    remove(lineId: string): void;
+    /** 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
+     * opened just before (#170 race). A repeat call mid-tender keeps the first pin.
+     */
+    startTender(method: "cash" | "external", options?: {
+        session?: {
+            id: string;
+            sessions: RegisterSessionCollection;
+        };
+    }): void;
+    setTender: (tender: {
+        method: "cash" | "external";
+        amountMinor: number;
+        reference?: string;
+    } | null) => void;
+    cancelTender(): void;
+    /**
+     * Finalizes the tender, stamps the session (see `session`), hands the order to `onSaleCompleted`,
+     * then shows the receipt. `saving` turns true and the sale locks (every change sets SALE_SAVING)
+     * from this call's entry, not only once the order is built; a refused finalize unlocks it again,
+     * with the refusal's error. Idempotent for one tender attempt (DECISIONS, ADR-052): once the order
+     * is built, that order is the sale, kept as the pending completion, because `onSaleCompleted` may
+     * already have stored it before failing. If `onSaleCompleted` throws, the error is set and the tender stays;
+     * calling `complete()` again reuses the pending completion exactly (the same `id`, `commandId`
+     * 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. 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>;
+    /**
+     * Starts a new, empty sale. Refused with SALE_SAVING, changing nothing, while a save is still
+     * building or stamping (nothing yet to ask `isStored` about), and while a pending completion
+     * exists and isn't confirmed stored — the ways out are Retry (`complete()`) or Continue, once
+     * `canContinue` (the Front desk, 2026-09-27; #149 review). So an app that doesn't pass `isStored`
+     * gets Retry only after a failed save. A refusal while a save is still delivering its order asks
+     * `isStored` afresh, so a hung save whose order is stored can still offer Continue. Past those, it
+     * abandons a confirmed pending completion (never handed to `onSaleCompleted` again: it's stored; a
+     * save still in flight carries on in the background, a throw logged at error) and starts the new
+     * sale outright — from the receipt, or an idle cart, there's nothing pending to abandon. Abandoning
+     * clears the screen, never the record (the Front desk, 2026-09-25). `newSale()` never deletes,
+     * updates or requeues `pos_orders` itself.
+     */
+    newSale(): void;
+    /**
+     * Continue after a failed save whose order is confirmed stored (`canContinue`): exactly `newSale()`.
+     * The order stays pending in the outbox, which will send it; it isn't handed to `onSaleCompleted` again, and
+     * its receipt is not shown. Otherwise does nothing.
+     */
+    continueSale(): void;
+};
+
+declare class CartError extends Error {
+}
+declare function addEntryToCart<Doc>(builder: OrderBuilder, entry: CatalogueEntry<Doc>, traits: ProductTraits<Doc>, currency: string): string;
+
+type TransportOutcome = {
+    kind: 'results';
+    results: CommandResult[];
+} | {
+    kind: 'unauthorized';
+} | {
+    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<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;
+    /** Set after 3 consecutive 401s; the app should ask the cashier to sign in, then call flush(). */
+    authRequired?: boolean;
+    /** Set when the server refused a whole batch (HTTP 400, 403, 413, 415, 422). No order is changed; sending pauses until the next flush(). */
+    refused?: {
+        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 {
+    baseUrl: string;
+    getHeaders: () => Record<string, string> | Promise<Record<string, string>>;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+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<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. */
+    flush(): Promise<void>;
+    /** Moves rejected orders (all, or those whose id is listed) back to pending with a new commandId, then flushes.
+     * Orders rejected with idempotency_mismatch are left for reconciliation. Resolves to the number requeued. */
+    requeue(orderIds?: string[]): Promise<number>;
+    /** Watches for pending orders and sends them. */
+    start(): void;
+    /** Stops watching and retrying. */
+    stop(): void;
+    state$: Observable<OutboxState>;
+}
+declare function createOrderOutbox(options: OrderOutboxOptions): OrderOutbox;
+
+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;
+    /** Opens the order store for `storeKey`; `close()` is called when the key or device id changes, or on unmount. */
+    open(storeKey: string): Promise<{
+        orders: RxCollection<PosOrder>;
+        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<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). */
+    onOpenError?(error: unknown): void;
+}
+interface UseOrderOutboxResult {
+    /** The open orders collection, or `null` until the current store is ready. */
+    orders: RxCollection<PosOrder> | null;
+    /** The outbox state, or idle until the current store is ready. */
+    state: OutboxState;
+    /** The newest 50 orders, newest first; empty until the current store is ready. */
+    recent: PosOrder[];
+    /**
+     * Stores a finalized order, then flushes. Throws the opening error, or "Orders are not ready.", before the store is ready.
+     * Recording an order whose `id` is already stored, not deleted, with the same money-bearing content (`sameSale`;
+     * a retried `complete()`) counts as stored, never overwrites it, and still flushes, whatever the stored `commandId`
+     * (a requeue mints a new one; the difference is logged at warn). Other content rejects with `OrderContentMismatchError`.
+     */
+    record(posOrder: PosOrder): Promise<void>;
+    /**
+     * Whether the current store holds this order `id`, not deleted, with the same money-bearing content (`sameSale`),
+     * whatever its `commandId`. A primary-key read on the storage instance, past RxDB's query cache. False before the
+     * store is ready; a content mismatch is false and logged at error.
+     */
+    isStored(order: PosOrder): Promise<boolean>;
+    /** Sends pending orders; does nothing before the current store is ready. */
+    flush(): Promise<void>;
+    /** Moves rejected orders back to pending (see `OrderOutbox.requeue`); resolves to 0 before the current store is ready. */
+    requeue(orderIds?: string[]): Promise<number>;
+    /**
+     * The count of `record()` calls not yet settled (resolved or rejected). An app holds sign-out
+     * (closing the store) while this is above 0, because a close that lands under a write stuck in
+     * 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;
+
+/** The transport a payment terminal is reached over: hardware-neutral, not tied to any backend. */
+type PaymentTransport = 'bluetooth' | 'usb' | 'network' | 'tap_to_pay';
+type TenderView = 'select' | 'amount' | 'cancel';
+type TenderLineId = string | number;
+type TenderPlan = {
+    kind: 'even';
+    ways: number;
+    from: number;
+} | {
+    kind: 'fixed';
+    firstMinor: number;
+    title: string | null;
+    from: number;
+} | {
+    kind: 'items';
+    lineIds: TenderLineId[];
+    firstMinor: number;
+    ways: number;
+    from: number;
+};
+type SplitTab = 'even' | 'amount' | 'percent' | 'item';
+interface TenderState {
+    view: TenderView;
+    /** Method id being tendered; null in the 'select' and 'cancel' views. */
+    methodId: string | null;
+    readerId: string | null;
+    transport: PaymentTransport | null;
+    /** Keypad entry in minor units. */
+    entryMinor: number;
+    /** False until the cashier has touched the keypad since the entry was pre-filled. */
+    entryDirty: boolean;
+    plan: TenderPlan | null;
+    splitView: boolean;
+    splitTab: SplitTab;
+    pickedLineIds: TenderLineId[];
+    linesPaidBy: Record<TenderLineId, string[]>;
+}
+/** '0'..'9' plus the two edit keys. There is deliberately no decimal key: digits shift in from the right. */
+type TenderKey = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'clear' | 'backspace';
+type TenderAction = {
+    type: 'pick-method';
+    methodId: string;
+    prefillMinor: number;
+    readerId: string | null;
+    transport?: PaymentTransport | null;
+} | {
+    type: 'pick-transport';
+    transport: PaymentTransport;
+} | {
+    type: 'pick-reader';
+    readerId: string | null;
+} | {
+    type: 'tender-started';
+} | {
+    type: 'key';
+    key: TenderKey;
+} | {
+    type: 'set-entry';
+    minor: number;
+} | {
+    type: 'back';
+} | {
+    type: 'tender-recorded';
+    rowsSinceFrom: {
+        title: string;
+        amountMinor: number;
+    }[];
+    /** The order's balance once this row counts, so the next leg can be pre-typed. */
+    balanceMinor: number;
+} | {
+    type: 'open-split';
+} | {
+    type: 'close-split';
+} | {
+    type: 'set-split-tab';
+    tab: SplitTab;
+} | {
+    type: 'toggle-split-line';
+    lineId: TenderLineId;
+} | {
+    type: 'set-plan';
+    plan: TenderPlan;
+    balanceMinor: number;
+} | {
+    type: 'clear-plan';
+    balanceMinor: number;
+} | {
+    type: 'arm-custom';
+} | {
+    type: 'request-cancel';
+} | {
+    type: 'reset';
+};
+/** $9,999,999.99 at two decimals — a till will never legitimately take more, and it stops a stuck key running the display off the screen. */
+declare const MAX_TENDER_MINOR = 999999999;
+declare const initialTenderState: TenderState;
+/**
+ * Reducer init. An order whose method the checkout store already holds — a URL seed, or a
+ * tab the cashier is coming back to — reopens its keypad prefilled with the balance, exactly
+ * as a tap on that tile would. Everything else starts from scratch.
+ */
+declare function initTenderState({ methodId, balanceMinor, }: {
+    methodId: string | null;
+    balanceMinor: number;
+}): TenderState;
+declare function tenderReducer(state: TenderState, action: TenderAction): TenderState;
+/**
+ * What the leg applies to the order. Cash may be tendered above the balance;
+ * the excess is change, never an overpayment on the order.
+ */
+declare function appliedMinor(entryMinor: number, balanceMinor: number): number;
+/** Change handed back. Zero for any tender whose method cannot give change. */
+declare function changeMinor(entryMinor: number, appliedAmountMinor: number, givesChange: boolean): number;
+/**
+ * Quick tendered amounts under a cash keypad: the balance itself, then the next
+ * whole 5, 10 and 50 above it. Deduped, ascending, never below the balance.
+ * The caller supplies those major-unit steps already scaled to minor units.
+ */
+declare function quickTenderedAmounts(balanceMinor: number, stepsMinor: readonly number[]): number[];
+/**
+ * Even split shares. Returns the next tender's share, rounded half-up to the
+ * minor unit; the last leg remains whatever balance is left.
+ */
+declare function evenSplitShareMinor(balanceMinor: number, ways: number): number;
+/** Completion is derived from payment rows, never an extra counter in the reducer. */
+declare function activePlan(plan: TenderPlan | null, taken: number, balanceMinor: number): TenderPlan | null;
+interface PlanLeg {
+    minor: number;
+    state: 'done' | 'now' | 'todo' | 'rest';
+    title?: string;
+}
+/** Label pieces stay untranslated here; the flow supplies localized copy and item names. */
+declare function planLegs(plan: TenderPlan, rowsSinceFrom: {
+    minor: number;
+    title: string;
+}[], balanceMinor: number): {
+    legs: PlanLeg[];
+    thisPaymentMinor: number;
+    label: {
+        n: number;
+        ways: number;
+        rest: boolean;
+        title: string | null;
+    };
+};
 
-export { type AppliedDiscount, CurrencyProvider, type CurrencyProviderProps, type CustomerSummary, type Discount, type LineItem, type LogEntry, type LogLevel, type LogSink, type Logger, type Order, type OrderBuilder, type OrderBuilderOptions, type OrderManager, type OrderManagerOptions, type ParkedOrderSummary, type Payment, type PaymentMethod, type ReceiptConfig, type ReceiptData, type ReceiptLineItem, type Repository, type TaxContext, TaxProvider, type TaxProviderProps, type TaxRateMap, type TaxResult, addTax, buildReceiptData, calculateTax, callbackSink, consoleSink, createLogger, createOrderBuilder, createOrderManager, createRepository, extractTax, formatCurrency, useCurrencyFormatter, useTax };
+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 };