@tallyui/pos 3.7.1 → 3.9.0

package/package.json

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

package/src/index.ts

@@ -29,10 +29,11 @@ export { createOrderBuilder, createOrderManager, allocateOrderDiscount, taxFigur
 export { orderDraftSchema, writeOrderDraft, restoreOrderDraft, parkedOrderSummaries$ } from './order';
 export { useParkedSales } from './order';
 export type { BasketLine } from './order';
-export type { OrderBuilder, OrderBuilderOptions } from './order';
+export type { OrderBuilder, OrderBuilderOptions, OrderCouponContext } from './order';
 export type { OrderManager, OrderManagerOptions, ParkedOrderSummary } from './order';
 export type {
   Order,
+  OrderCoupon,
   SentOrder,
   LineItem,
   LineTaxLine,
@@ -69,6 +70,7 @@ export type { RegisterOutboxOptions, RegisterOutbox, UseRegisterOutboxOptions, U
 export { createBackendNotFound } from './outbox/backend-not-found';
 export type { BackendNotFound } from './outbox/backend-not-found';
 export type { HttpTransportOptions, OrderOutboxOptions, OrderOutbox, TransportOutcome, CommandTransport, OrderTransportContext, OutboxState, UseOrderOutboxOptions, UseOrderOutboxResult } from './outbox';
+export { sendOrderRefund, type OrderRefundOutcome, posRefundSchema, posRefundCollection, submitOrderRefund, RefundAnswerPendingError, type PosRefund, type PosRefundStatus, type PosRefundCollection } from './refund';
 export { tenderReducer, initTenderState, initialTenderState, appliedMinor, changeMinor, quickTenderedAmounts, evenSplitShareMinor, activePlan, planLegs, MAX_TENDER_MINOR, tenderVoidSchema, tenderVoidCollection } from './tender';
 export type { PaymentTransport, TenderView, TenderLineId, TenderPlan, SplitTab, TenderState, TenderKey, TenderAction, PlanLeg, TenderVoid } from './tender';
 
@@ -78,11 +80,11 @@ export type { MovementType, LedgerRow, Movement } from './register';
 export { registerSessionSchema, registerSessionCollection, cashMovementSchema, closureSchema } from './register';
 export { addRegisterSessionCollection, RegisterSessionOpenClosedError, registerSessionsLogger, REGISTER_SESSION_MIGRATION_CLOSE_WAIT_MS } from './register';
 export type { RegisterSession, CashMovement, Closure } from './register';
-export { registerCommandSchema, registerCommandCollection, registerCommandsLogger, sessionOpenCommand, sessionTransitionCommand, movementCommand, closureCommand, reconcileRegisterCommands } from './register';
+export { registerCommandSchema, registerCommandCollection, registerCommandsLogger, sessionOpenCommand, sessionTransitionCommand, movementCommand, closureCommand, reconcileRegisterCommands, adoptRegisterResults, takeOverSession, abandonSession } from './register';
 export type { RegisterCommand, RegisterCommandCollection } from './register';
 export { mintUuid, readRegister, ensureRegister, observeRegister$, getBoundRegisterId, readBoundRegister, bindRegister, unbindRegister, nextSaleCounter, mintClosureNumber, advancePerpetual, RegisterIdInvalidError } from './register';
 export type { RegisterHost, RegisterCounters, RegisterBucket, RegisterStore, RegisterDocument } from './register';
-export { RegisterSessionRequiredError, RegisterSessionClosedError, RegisterNeedsUpgradeError, isKnownSessionStatus, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, openSessionSelector, requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure } from './register';
+export { RegisterSessionRequiredError, RegisterSessionClosedError, RegisterNeedsUpgradeError, RegisterSessionConflictError, RegisterTakeOverError, isKnownSessionStatus, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, openSessionSelector, requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure } from './register';
 export type { RegisterSessionCollection, CashMovementCollection, ClosureCollection } from './register';
 export { deriveSettled, exportCsv, labelKeys, clampClosureScope, selectClosureRows } from './register';
 export type { Correction, RecordedFigures, ClosureScope } from './register';

package/src/order/index.ts

@@ -2,13 +2,14 @@ export { createOrderBuilder } from './order-builder';
 export { taxFiguresForBasket } from './tax-figures';
 export type { BasketLine } from './tax-figures';
 export { allocateOrderDiscount } from './allocate-order-discount';
-export type { OrderBuilder, OrderBuilderOptions } from './order-builder';
+export type { OrderBuilder, OrderBuilderOptions, OrderCouponContext } from './order-builder';
 export { createOrderManager } from './order-manager';
 export { orderDraftSchema, writeOrderDraft, restoreOrderDraft, parkedOrderSummaries$ } from './order-drafts';
 export { useParkedSales } from './use-parked-sales';
 export type { OrderManager, OrderManagerOptions, ParkedOrderSummary } from './order-manager';
 export type {
   Order,
+  OrderCoupon,
   SentOrder,
   LineItem,
   LineTaxLine,

package/src/order/order-builder.ts

@@ -1,10 +1,10 @@
 import { BehaviorSubject, type Observable } from 'rxjs';
-import { resolvePrice, woocommerceTax, type ProductTraits, type TaxRounding } from '@tallyui/core';
+import { resolvePrice, woocommerceTax, type woocommerceCoupons, type ProductTraits, type TaxRounding } from '@tallyui/core';
 import type { TaxContext } from '../tax/types';
 import { taxMicros, roundMicrosToMinor, roundedTaxByRate } from '../tax/exact';
 import { taxLogger } from '../tax/tax-provider';
 import { allocateOrderDiscount } from './allocate-order-discount';
-import { woocommerceLine, woocommerceTotals } from './woocommerce-tax';
+import { woocommerceLine, woocommerceTotals, woocommerceCouponReplay } from './woocommerce-tax';
 import type {
   Order,
   LineItem,
@@ -62,10 +62,17 @@ export function assertDisplayResidue(residue: number, convertedLines: number, co
   if (Math.abs(residue) > bound) throw new Error(`Display residue ${residue} exceeds its bound of ${bound} (ADR-063)`);
 }
 
+export interface OrderCouponContext {
+  configs: ReadonlyMap<string, woocommerceCoupons.CouponDiscountConfig>;
+  productCategories: ReadonlyMap<number, { id: number }[]>;
+  calcDiscountsSequentially: boolean;
+}
+
 export interface OrderBuilderOptions {
   currency: string;
   taxContext: TaxContext;
   id?: string;
+  couponContext?: OrderCouponContext;
 }
 
 export interface OrderBuilder {
@@ -89,12 +96,14 @@ export interface OrderBuilder {
   removePayment(paymentId: string): void;
   setCustomer(customer: CustomerSummary | null): void;
   setNote(note: string): void;
+  /** Replaces the coupon codes with their trimmed, lower-case, deduplicated list. */
+  setCoupons(codes: readonly string[]): void;
   clear(): void;
   getSnapshot(): Order;
 }
 
 export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
-  const { taxContext } = options;
+  const { taxContext, couponContext } = options;
   const currency = options.currency.toUpperCase();
   const orderId = options.id ?? uid();
   const woo = taxContext.rounding?.granularity === 'woocommerce' && taxContext.getTaxRates ? taxContext.rounding : undefined;
@@ -113,6 +122,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
   let payments: Payment[] = [];
   let customer: CustomerSummary | null = null;
   let note = '';
+  let couponCodes: string[] = [];
   const now = new Date().toISOString();
 
   const subject = new BehaviorSubject<Order>(buildOrder());
@@ -186,7 +196,10 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       return { ...d, amountMinor };
     });
     const shares = allocateOrderDiscount(lineAmounts, recalcedOrderDiscounts.reduce((sum, d) => sum + d.amountMinor, 0));
-    const lines = lineItems.map((li, index) => recalculateLine(li, shares[index]));
+    const displaySourceLines = lineItems.map((li, index) => recalculateLine(li, shares[index]));
+    const replay = woo && couponCodes.length ? woocommerceCouponReplay(displaySourceLines, couponCodes, couponContext!,
+      taxContext.getTaxRates!, currency, woo.roundAtSubtotal, taxContext.pricesIncludeTax) : undefined;
+    const lines = replay?.lines ?? displaySourceLines;
 
     if (woo) shipping = shipping.map((charge) => ({ ...charge, ...recalculateCharge(charge.id, charge, true) }));
     const wooTotals = woo ? woocommerceTotals(lines, fees, shipping, currency, woo.roundAtSubtotal, taxContext.pricesIncludeTax) : undefined;
@@ -206,7 +219,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     // from the settlement total, so every sum is exact; the rounding residue goes to the converted lines' amounts,
     // never to a discount or an unconverted line.
     const taxInclusive = taxContext.pricesIncludeTax;
-    const figures = lines.map((li) => {
+    const figures = displaySourceLines.map((li) => {
       // A negative-priced (return) line shows what settlement charges for it (recalculateLine caps it at 0 today),
       // with no rows: its capped "discounts" are the negative gross cancelled, not money off.
       const returned = li.unitPriceMinor < 0;
@@ -221,8 +234,11 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     });
     const displayLines = figures.map((f) => f.line);
     const orderDiscountDisplay = figures.reduce((sum, f) => sum + f.shareMinor, 0);
+    const displayCoupons = replay?.coupons.map(({ code, discountMinor, discountTaxMinor }) =>
+      ({ code, amountMinor: discountMinor + (taxInclusive ? discountTaxMinor : 0) }));
     const displayDiscount = displayLines.reduce(
-      (sum, line) => line.discounts.reduce((lineSum, d) => lineSum + d.amountMinor, sum), orderDiscountDisplay);
+      (sum, line) => line.discounts.reduce((lineSum, d) => lineSum + d.amountMinor, sum), orderDiscountDisplay)
+      + (displayCoupons?.reduce((sum, row) => sum + row.amountMinor, 0) ?? 0);
     const chargeRows = (items: ChargeLine[]) => items.map(({ id, name, amountMinor, netMinor, totalMinor }) =>
       ({ id, name, amountMinor: woo ? taxInclusive ? totalMinor! : netMinor : amountMinor }));
     const displayFees = chargeRows(fees), displayShipping = chargeRows(shipping);
@@ -237,9 +253,9 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       if (charge) displaySubtotal -= residue;
       residue = displaySubtotal - displayLines.reduce((sum, line) => sum + line.amountMinor, 0);
     }
-    const converted = lines.flatMap((li, index) => li.taxInclusive === taxInclusive ? [] : [index]);
-    const conversions = converted.reduce((count, index) => count + [lines[index].netMinor, lines[index].orderDiscountMinor,
-      ...lines[index].discounts.map((d) => d.amountMinor)].filter((x) => x !== 0).length, 0);
+    const converted = displaySourceLines.flatMap((li, index) => li.taxInclusive === taxInclusive ? [] : [index]);
+    const conversions = converted.reduce((count, index) => count + [displaySourceLines[index].netMinor, displaySourceLines[index].orderDiscountMinor,
+      ...displaySourceLines[index].discounts.map((d) => d.amountMinor)].filter((x) => x !== 0).length, 0);
     assertDisplayResidue(residue, converted.length, conversions);
     // Largest converted remaining first (ties to the earlier line). A negative residue takes a line down to its rows
     // and share at most, then moves on: six 2-cent inclusive lines can owe −3 with no line above 2. The spill is a
@@ -268,6 +284,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     const display = {
       taxInclusive, subtotalMinor: displaySubtotal, discountMinor: displayDiscount, taxMinor, totalMinor,
       lines: displayLines, orderDiscountMinor: orderDiscountDisplay,
+      ...(displayCoupons ? { coupons: displayCoupons } : {}),
       ...(fees.length ? { fees: displayFees } : {}),
       ...(shipping.length ? { shipping: displayShipping } : {}),
     };
@@ -279,6 +296,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       id: orderId,
       status: 'draft',
       lineItems: lines,
+      ...(replay ? { coupons: replay.coupons } : {}),
       ...(fees.length ? { fees: [...fees] } : {}),
       ...(shipping.length ? { shipping: [...shipping] } : {}),
       discounts: recalcedOrderDiscounts,
@@ -540,6 +558,19 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       emit();
     },
 
+    setCoupons(codes) {
+      const normalized = [...new Set(codes.map((code) => code.trim().toLowerCase()))];
+      if (normalized.length && !couponContext) throw new Error('Coupon context is required');
+      for (const code of normalized) {
+        const config = couponContext!.configs.get(code);
+        if (!config) throw new RangeError(`Unknown coupon ${code}`);
+        // Lines do not carry their regular price yet, so sale lines cannot be identified.
+        if (config.exclude_sale_items) throw new RangeError(`Coupon ${code} excludes sale items`);
+      }
+      couponCodes = normalized;
+      emit();
+    },
+
     clear() {
       lineItems = [];
       fees = [];
@@ -548,6 +579,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       payments = [];
       customer = null;
       note = '';
+      couponCodes = [];
       emit();
     },
 

package/src/order/order-drafts.ts

@@ -33,9 +33,11 @@ export interface ParkedOrderSummary {
 }
 
 export async function writeOrderDraft(drafts: RxCollection, snapshot: Order): Promise<string> {
+  // Coupons are not persisted until ADR-077 step (d2).
+  const { coupons: _coupons, ...draft } = snapshot;
   await drafts.upsert({
     id: snapshot.id,
-    data: JSON.stringify(snapshot),
+    data: JSON.stringify(draft),
     customerName: snapshot.customer?.name ?? '',
     itemCount: snapshot.lineItems.length,
     total: snapshot.totalMinor,

package/src/order/types.ts

@@ -1,5 +1,11 @@
 import type { Money, TaxRounding } from '@tallyui/core';
 
+export interface OrderCoupon {
+  code: string; // lower-case code
+  discountMinor: number; // WooCommerce coupon discount, ex tax, in integer minor units
+  discountTaxMinor: number; // its tax, in integer minor units
+}
+
 export interface Order {
   id: string;
   status: 'draft' | 'parked' | 'saved' | 'completed';
@@ -7,6 +13,8 @@ export interface Order {
   fees?: FeeLine[];
   shipping?: ShippingLine[];
   discounts: AppliedDiscount[];
+  /** Present only after coupon replay; discountMinor excludes coupons, which are carried here. */
+  coupons?: OrderCoupon[];
   payments: Payment[];
   customer: CustomerSummary | null;
   note: string;
@@ -37,12 +45,14 @@ export type SentOrder = Omit<Order, 'customer'> & { customer: (Omit<CustomerSumm
 export interface DisplayTotals {
   taxInclusive: boolean;      // = order.pricesIncludeTax
   subtotalMinor: number;      // product lines before discounts, excluding fees and shipping (ADR-075)
-  discountMinor: number;      // Σ lines' discount rows + orderDiscountMinor, in the display mode; >= 0
+  discountMinor: number;      // Σ lines' discount rows + orderDiscountMinor + coupon rows, in the display mode; >= 0
   taxMinor: number;           // = order.taxMinor (added when exclusive, included when inclusive)
   totalMinor: number;         // = order.totalMinor
   lines: DisplayLine[];       // in lineItems order; Σ amountMinor = subtotalMinor
   fees?: Array<{ id: string; name: string; amountMinor: number }>;
   shipping?: Array<{ id: string; name: string; amountMinor: number }>;
+  /** Present exactly when Order.coupons is. */
+  coupons?: Array<{ code: string; amountMinor: number }>;
   orderDiscountMinor: number; // the order discounts as one row, not allocated: Σ each line's share, converted on its own
 }
 

package/src/order/woocommerce-tax.ts

@@ -1,7 +1,8 @@
-import { minorUnitDigits, woocommerceTax } from '@tallyui/core';
-import type { WooRate } from '../tax/types';
+import { minorUnitDigits, woocommerceTax, woocommerceCoupons } from '@tallyui/core';
+import type { TaxContext, WooRate } from '../tax/types';
 import type { RateTaxLine } from '../tax/exact';
-import type { ChargeLine, LineItem, LineTaxLine } from './types';
+import type { ChargeLine, LineItem, LineTaxLine, OrderCoupon } from './types';
+import type { OrderCouponContext } from './order-builder';
 
 /** ADR-076: all WooCommerce float arithmetic stays here; only integer money leaves this module. */
 export function woocommerceLine(amountMinor: number, rates: readonly WooRate[], inclusive: boolean, currency: string,
@@ -19,13 +20,69 @@ export function woocommerceLine(amountMinor: number, rates: readonly WooRate[],
     return { code: rate.code, rateId: rate.id, compound: rate.compound, ratePpm: Math.round(Number(rate.rate) * 10000),
       taxMicros: String(Math.round(tax.total * factor * 1e6)) };
   });
-  const tax = result.taxes.reduce((sum, rate) => sum + (roundAtSubtotal ? rate.total
+  return lineAmounts(net, result.taxes, taxLines, dp, roundAtSubtotal, pricesIncludeTax);
+}
+
+function lineAmounts(net: number, taxes: { total: number }[], taxLines: LineTaxLine[], dp: number,
+  roundAtSubtotal: boolean, pricesIncludeTax: boolean) {
+  const factor = 10 ** dp;
+  const tax = taxes.reduce((sum, rate) => sum + (roundAtSubtotal ? rate.total
     : woocommerceTax.roundTaxTotal(rate.total, dp, pricesIncludeTax)), 0);
   return { netMinor: Math.round(woocommerceTax.roundHalfUp(net, dp) * factor), netMicros: String(Math.round(net * factor * 1e6)),
     totalMinor: Math.round(woocommerceTax.roundHalfUp(net + tax, dp) * factor), taxLines,
     taxMicros: taxLines.reduce((sum, rate) => sum + BigInt(rate.taxMicros), 0n).toString() };
 }
 
+/** Replays coupons on the manually discounted net lines; only integer money leaves this boundary (ADR-076). */
+export function woocommerceCouponReplay(lines: readonly LineItem[], codes: readonly string[], context: OrderCouponContext,
+  getTaxRates: NonNullable<TaxContext['getTaxRates']>, currency: string, roundAtSubtotal: boolean,
+  pricesIncludeTax: boolean): { lines: LineItem[]; coupons: OrderCoupon[] } {
+  const dp = minorUnitDigits(currency), factor = 10 ** dp;
+  const inputLines = lines.filter((line) => line.unitPriceMinor >= 0);
+  const lineItems: woocommerceCoupons.LineItemInput[] = inputLines.map((line) => {
+    const productId = Number(line.productId), variationId = Number(line.variantId);
+    const net = (Number(line.netMicros) / (factor * 1e6)).toFixed(6);
+    const taxes = line.taxLines.map((tax) => {
+      const amount = (Number(tax.taxMicros) / (factor * 1e6)).toFixed(6);
+      return { id: tax.rateId, subtotal: amount, total: amount };
+    });
+    const tax = taxes.reduce((sum, row) => sum + Number(row.total), 0).toFixed(6);
+    return {
+      product_id: !line.custom && Number.isSafeInteger(productId) && productId >= 0 ? productId : 0,
+      ...(Number.isSafeInteger(variationId) && variationId >= 0 ? { variation_id: variationId } : {}),
+      quantity: line.quantity, tax_class: line.taxClass ?? '',
+      ...(line.taxStatus === 'none' ? { tax_status: 'none' } : {}),
+      subtotal: net, total: net, taxes, subtotal_tax: tax, total_tax: tax,
+    };
+  });
+  const taxRates = new Map<string, woocommerceCoupons.RecalculateInput['taxRates'][number]>();
+  for (const line of inputLines) for (const rate of getTaxRates(line.taxClass)) {
+    const taxClass = woocommerceTax.normalizeTaxClass(line.taxClass);
+    taxRates.set(JSON.stringify([rate.id, taxClass]), { id: rate.id, rate: rate.rate, compound: rate.compound,
+      order: rate.priority, priority: rate.priority, class: taxClass });
+  }
+  const result = woocommerceCoupons.recalculateCoupons({
+    lineItems, couponLines: codes.map((code) => ({ code })),
+    couponConfigs: new Map(codes.map((code) => [code, context.configs.get(code)!])),
+    pricesIncludeTax, calcDiscountsSequentially: context.calcDiscountsSequentially,
+    productCategories: new Map(context.productCategories), taxRates: [...taxRates.values()],
+    taxRoundAtSubtotal: roundAtSubtotal, dp,
+  });
+  let index = 0;
+  return {
+    lines: lines.map((line) => {
+      if (line.unitPriceMinor < 0) return line;
+      const item = result.lineItems[index++];
+      const taxes = line.taxLines.map((tax) => ({ total: Number(item.taxes?.find((row) => row.id === tax.rateId)?.total ?? '0') }));
+      const taxLines = line.taxLines.map((tax, index) => ({ ...tax, taxMicros: String(Math.round(taxes[index].total * factor * 1e6)) }));
+      return { ...line, ...lineAmounts(Number(item.total), taxes, taxLines, dp, roundAtSubtotal, pricesIncludeTax) };
+    }),
+    coupons: result.couponLines.map((coupon, index) => ({ code: codes[index],
+      discountMinor: Math.round(woocommerceTax.roundHalfUp(Number(coupon.discount), dp) * factor),
+      discountTaxMinor: Math.round(woocommerceTax.roundHalfUp(Number(coupon.discount_tax), dp) * factor) })),
+  };
+}
+
 /** calculateOrderTotals: products round conditionally, fees stay raw, shipping always rounds per item. */
 export function woocommerceTotals(lines: readonly LineItem[], fees: readonly ChargeLine[], shipping: readonly ChargeLine[],
   currency: string, roundAtSubtotal: boolean, inclusive: boolean) {

package/src/outbox/register-outbox.ts

@@ -2,6 +2,7 @@ import type { CommandResult, RegisterCommandEnvelope } from '@tallyui/core';
 import type { RxCollection } from 'rxdb';
 import { BehaviorSubject, type Observable, type Subscription } from 'rxjs';
 import { registerCommandsLogger, type RegisterCommand } from '../register/register-commands';
+import type { RegisterSessionCollection } from '../register/session-store';
 import { countFresh, readFresh } from '../rxdb';
 import { createBackendNotFound, type BackendNotFound } from './backend-not-found';
 import { STUCK_AFTER_MS } from './order-outbox';
@@ -12,6 +13,9 @@ export const NON_BLOCKING_REJECTIONS: ReadonlySet<string> = new Set(['register_s
 
 export interface RegisterOutboxOptions {
   collection: RxCollection<RegisterCommand>;
+  /** The till's `register_sessions`. With it, a refused open (`register_session_already_open`) stops blocking its register
+   * once its session is `abandoned` (ADR-078 decision 9). Without it, that refusal always blocks. */
+  sessions?: RegisterSessionCollection;
   transport: CommandTransport<RegisterCommandEnvelope>;
   deviceId: string;
   /** Checked at the start of every run; false sends nothing. */
@@ -42,7 +46,7 @@ function plainCommand({ key, registerId, seq, commandId, type, version, payload,
 }
 
 export function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOutbox {
-  const { collection, transport, deviceId } = options;
+  const { collection, sessions, transport, deviceId } = options;
   const size = options.batchSize;
   const batchSize = Math.max(1, Math.min(typeof size === 'number' && Number.isFinite(size) ? Math.floor(size) : 10, 10));
   const initialBackoff = options.initialBackoffMs ?? 1000;
@@ -62,6 +66,7 @@ export function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOu
   let running: Promise<void> | undefined;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let subscription: Subscription | undefined;
+  let sessionsSubscription: Subscription | undefined;
   let stopped = false;
   let insertedDuringRun = false;
   let stoppedDuringRun = false;
@@ -92,7 +97,15 @@ export function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOu
     for (const { commandId } of commands) clocks.set(commandId, { ...(clocks.get(commandId) ?? { since: at, firstFailedAt: at }), seq: ++failureSeq, reason });
   }
 
+  function isNonBlocking(command: RegisterCommand, abandoned: ReadonlySet<string>): boolean {
+    return NON_BLOCKING_REJECTIONS.has(command.error?.code ?? '') ||
+      (command.error?.code === 'register_session_already_open' &&
+        typeof command.payload.sessionId === 'string' && abandoned.has(command.payload.sessionId));
+  }
+
   async function updateState(patch: Partial<OutboxState> = {}) {
+    const abandoned = new Set(sessions && clocks.size
+      ? (await readFresh(sessions, { selector: { status: 'abandoned' } })).map((session) => session.id) : []);
     const pending = await countFresh(collection, { syncStatus: 'pending' });
     // Only commands in a register's sendable prefix (pending, before its first rejected command) keep a clock.
     const sendable = new Set<string>();
@@ -100,7 +113,7 @@ export function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOu
     if (clocks.size) for (const command of await readFresh(collection, { selector: { syncStatus: { $in: ['pending', 'rejected'] } },
       sort: [{ seq: 'asc' }, { key: 'asc' }] })) {
       if (command.syncStatus === 'rejected') {
-        if (!NON_BLOCKING_REJECTIONS.has(command.error?.code ?? '')) blocked.add(command.registerId);
+        if (!isNonBlocking(command, abandoned)) blocked.add(command.registerId);
       } else if (!blocked.has(command.registerId)) sendable.add(command.commandId);
     }
     for (const id of clocks.keys()) if (!sendable.has(id)) clocks.delete(id);
@@ -123,6 +136,8 @@ export function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOu
       if (options.isEnabled?.() === false) return;
       const pending = await readFresh(collection, { selector: { syncStatus: 'pending' } });
       const registerIds = [...new Set(pending.map((command) => command.registerId))].sort();
+      const abandoned = new Set(sessions
+        ? (await readFresh(sessions, { selector: { status: 'abandoned' } })).map((session) => session.id) : []);
       let sent = false;
       for (const registerId of registerIds) {
         const ledger = await readFresh(collection, {
@@ -131,7 +146,7 @@ export function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOu
         });
         const commands: RegisterCommand[] = [];
         for (const command of ledger) {
-          if (command.syncStatus === 'rejected' && NON_BLOCKING_REJECTIONS.has(command.error?.code ?? '')) continue;
+          if (command.syncStatus === 'rejected' && isNonBlocking(command, abandoned)) continue;
           if (command.syncStatus === 'rejected') break;
           commands.push(command);
           if (command.type === 'register.session.open' || commands.length >= batchSize) break;
@@ -241,6 +256,12 @@ export function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOu
           flush().catch(() => {});
         }
       });
+      if (sessions && !sessionsSubscription) sessionsSubscription = sessions.$.subscribe((event) => {
+        if (event.documentData?.status === 'abandoned') {
+          insertedDuringRun = true;
+          flush().catch(() => {});
+        }
+      });
       if (!stopped) flush().catch(() => {});
     },
     stop() {
@@ -249,6 +270,8 @@ export function createRegisterOutbox(options: RegisterOutboxOptions): RegisterOu
       timer = undefined;
       subscription?.unsubscribe();
       subscription = undefined;
+      sessionsSubscription?.unsubscribe();
+      sessionsSubscription = undefined;
       missingSubscription?.unsubscribe(); missingSubscription = undefined;
       state$.next({ ...state$.value, nextAttemptAt: undefined });
     },

package/src/outbox/types.test-d.ts

@@ -1,6 +1,7 @@
 import { describe, expectTypeOf, it } from 'vitest';
 import type { AnyCommandEnvelope, CommandEnvelope, OrderCreateEnvelope, OrderCreatePayload, RegisterCommandEnvelope } from '@tallyui/core';
 import type { CommandTransport } from './types';
+import { sendOrderRefund } from '../refund';
 
 describe('CommandTransport', () => {
   it('defaults to order.create envelopes', () => {
@@ -14,6 +15,10 @@ describe('CommandTransport', () => {
     expectTypeOf<CommandTransport<AnyCommandEnvelope>>().toMatchTypeOf<CommandTransport<OrderCreateEnvelope>>();
   });
 
+  it('the wide transport is accepted where sendOrderRefund wants the refund transport', () => {
+    expectTypeOf<CommandTransport<AnyCommandEnvelope>>().toMatchTypeOf<Parameters<typeof sendOrderRefund>[0]>();
+  });
+
   it('the wide transport accepts register command envelopes', () => {
     const transport: CommandTransport<AnyCommandEnvelope> = { send: async () => ({ kind: 'results', results: [] }) };
     const batch: RegisterCommandEnvelope[] = [];

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

@@ -1,6 +1,7 @@
 import type { RegisterCommandEnvelope } from '@tallyui/core';
 import { useEffect, useRef, useState } from 'react';
 import type { RegisterCommandCollection } from '../register/register-commands';
+import type { RegisterSessionCollection } from '../register/session-store';
 import { createRegisterOutbox, type RegisterOutboxOptions } from './register-outbox';
 import type { CommandTransport, OutboxState } from './types';
 
@@ -9,6 +10,8 @@ const idle: OutboxState = { pending: 0, sending: false };
 export interface UseRegisterOutboxOptions {
   /** `register_commands` (see `registerCommandCollection()`); `null` while it opens or when there's no store. A new collection (a store switch) restarts the outbox. */
   commands: RegisterCommandCollection | null;
+  /** The till's `register_sessions`; abandoned sessions unblock refused opens. A new collection restarts the outbox. */
+  sessions?: RegisterSessionCollection | null;
   /** Builds the transport; called when the outbox is created: on each new collection or device id (twice under React StrictMode's double effect, which stops the first outbox). */
   transport(): CommandTransport<RegisterCommandEnvelope>;
   /** The device id sent on every command. A change restarts the outbox. */
@@ -27,7 +30,7 @@ export interface UseRegisterOutboxResult {
 }
 
 export function useRegisterOutbox(options: UseRegisterOutboxOptions): UseRegisterOutboxResult {
-  const { commands, deviceId } = options;
+  const { commands, sessions, deviceId } = options;
   const latest = useRef(options);
   latest.current = options;
   const current = useRef<{ commands: RegisterCommandCollection; deviceId: string; outbox: ReturnType<typeof createRegisterOutbox> } | null>(null);
@@ -37,6 +40,7 @@ export function useRegisterOutbox(options: UseRegisterOutboxOptions): UseRegiste
     setState(idle);
     if (!commands) return;
     const outbox = createRegisterOutbox({ collection: commands, deviceId, transport: latest.current.transport(),
+      sessions: sessions ?? undefined,
       isEnabled: latest.current.isEnabled ? () => latest.current.isEnabled?.() ?? true : undefined,
       onResult: latest.current.onResult ? async (command, result) => { await latest.current.onResult?.(command, result); } : undefined,
       backendNotFound: latest.current.backendNotFound });
@@ -44,7 +48,7 @@ export function useRegisterOutbox(options: UseRegisterOutboxOptions): UseRegiste
     const status = outbox.state$.subscribe(setState);
     outbox.start();
     return () => { outbox.stop(); status.unsubscribe(); current.current = null; setState(idle); };
-  }, [commands, deviceId]);
+  }, [commands, sessions, deviceId]);
 
   const opened = current.current;
   return { state: opened?.commands === commands && opened.deviceId === deviceId ? state : idle,

package/src/refund/index.ts

@@ -0,0 +1,3 @@
+export { sendOrderRefund, type OrderRefundOutcome } from './send-order-refund';
+export { posRefundSchema, posRefundCollection, type PosRefund, type PosRefundStatus, type PosRefundCollection } from './pos-refund';
+export { submitOrderRefund, RefundAnswerPendingError } from './submit-order-refund';

package/src/refund/pos-refund.ts

@@ -0,0 +1,35 @@
+import type { CommandError, OrderRefundEnvelope, OrderRefundResult } from '@tallyui/core';
+import type { RxCollection, RxJsonSchema } from 'rxdb';
+
+export type PosRefundStatus = 'pending' | 'applied' | 'rejected' | 'unsent';
+export interface PosRefund {
+  id: string; commandId: string; orderId: string; sessionId: string; registerId: string;
+  envelope: OrderRefundEnvelope;
+  status: PosRefundStatus;
+  result?: OrderRefundResult;
+  duplicate?: boolean;
+  error?: CommandError;
+  createdAt: string; updatedAt: string;
+}
+export type PosRefundCollection = RxCollection<PosRefund>;
+
+export const posRefundSchema: RxJsonSchema<PosRefund> = {
+  title: 'POS refunds', version: 0, primaryKey: 'id', type: 'object', additionalProperties: false,
+  properties: {
+    id: { type: 'string', maxLength: 64 }, commandId: { type: 'string', maxLength: 64 },
+    orderId: { type: 'string', maxLength: 64 }, sessionId: { type: 'string', maxLength: 64 },
+    registerId: { type: 'string', maxLength: 64 },
+    envelope: { type: 'object', additionalProperties: true },
+    status: { type: 'string', enum: ['pending', 'applied', 'rejected', 'unsent'], maxLength: 10 },
+    result: { type: 'object', additionalProperties: true }, duplicate: { type: 'boolean' },
+    error: { type: 'object', properties: {
+      code: { type: 'string' }, message: { type: 'string' }, data: { type: 'object', additionalProperties: true },
+    }, required: ['code', 'message'], additionalProperties: false },
+    createdAt: { type: 'string' }, updatedAt: { type: 'string' },
+  },
+  required: ['id', 'commandId', 'orderId', 'sessionId', 'registerId', 'envelope', 'status', 'createdAt', 'updatedAt'],
+  indexes: [['sessionId']],
+};
+/** Local-only, never replicated (ADR-080 amendment 1).
+ * Added with addCollections like cash_movements. */
+export const posRefundCollection = () => ({ schema: posRefundSchema });

package/src/refund/send-order-refund.ts

@@ -0,0 +1,43 @@
+import type { CommandError, OrderRefundEnvelope, OrderRefundResult } from '@tallyui/core';
+import { parseCommandResult } from '@tallyui/core/server';
+import type { CommandTransport } from '../outbox/types';
+
+export type OrderRefundOutcome =
+  | { kind: 'applied'; refund: OrderRefundResult; duplicate: boolean }
+  | { kind: 'rejected'; error: CommandError }
+  | { kind: 'unknown'; reason: string; retryAfterMs?: number }
+  | { kind: 'refused'; status: number; reason: string }
+  | { kind: 'unauthorized' };
+
+/** Online only, never queued (ADR-080). On unknown, resend the same envelope (same id).
+ * After rejected, a new attempt needs a new id. Refused and unauthorized mean the store did not take the batch. */
+export async function sendOrderRefund(
+  transport: CommandTransport<OrderRefundEnvelope>, envelope: OrderRefundEnvelope,
+): Promise<OrderRefundOutcome> {
+  let outcome;
+  try {
+    outcome = await transport.send([envelope]);
+  } catch {
+    return { kind: 'unknown', reason: 'transport_error' };
+  }
+  if (outcome.kind === 'retry') {
+    return {
+      kind: 'unknown', reason: outcome.reason,
+      ...(outcome.retryAfterMs !== undefined ? { retryAfterMs: outcome.retryAfterMs } : {}),
+    };
+  }
+  if (outcome.kind === 'refused' || outcome.kind === 'unauthorized') return outcome;
+  const matches = outcome.results.filter((result) => result.id === envelope.id);
+  if (matches.length !== 1) return { kind: 'unknown', reason: 'missing_result' };
+  let result;
+  try {
+    result = parseCommandResult(matches[0]);
+  } catch {
+    return { kind: 'unknown', reason: 'bad_result' };
+  }
+  if (result.status === 'applied' || result.status === 'duplicate') {
+    if (!result.refund) return { kind: 'unknown', reason: 'bad_result' };
+    return { kind: 'applied', refund: result.refund, duplicate: result.status === 'duplicate' };
+  }
+  return { kind: 'rejected', error: result.error! };
+}