@tallyui/pos 3.8.0 → 3.9.0

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';
 

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/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/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! };
+}

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

@@ -0,0 +1,85 @@
+import type { OrderRefundEnvelope } from '@tallyui/core';
+import { RxError } from 'rxdb';
+import type { CommandTransport } from '../outbox/types';
+import type { PosRefund, PosRefundCollection } from './pos-refund';
+import { sendOrderRefund, type OrderRefundOutcome } from './send-order-refund';
+
+export class RefundAnswerPendingError extends Error {
+  readonly code = 'REFUND_ANSWER_PENDING';
+  constructor(public readonly record: PosRefund) {
+    super("This refund's answer is still unknown. Send it again before trying a new refund attempt.");
+    this.name = 'RefundAnswerPendingError';
+  }
+}
+
+/** Online only, never queued; the record is written before the send.
+ * An applied record is final; a pending one is resent only with its own envelope
+ * (ADR-080 amendment 1). */
+export async function submitOrderRefund({ refunds, transport, envelope, now = () => new Date().toISOString() }: {
+  refunds: PosRefundCollection; transport: CommandTransport<OrderRefundEnvelope>;
+  envelope: OrderRefundEnvelope; now?: () => string;
+}): Promise<{ outcome: OrderRefundOutcome; record: PosRefund }> {
+  const id = envelope.payload.clientRefundId;
+  let doc = await refunds.findOne(id).exec();
+  if (!doc) {
+    const at = now();
+    const { orderId, sessionId, registerId } = envelope.payload;
+    try {
+      doc = await refunds.insert({
+        id, commandId: envelope.id, orderId, sessionId, registerId, envelope,
+        status: 'pending', createdAt: at, updatedAt: at,
+      });
+    } catch (error) {
+      if (!(error instanceof RxError) || error.code !== 'CONFLICT') throw error;
+      doc = (await refunds.findOne(id).exec())!;
+    }
+  }
+  let record = doc.toJSON() as PosRefund;
+  // Re-evaluate the stored state at most once after a guarded attempt write.
+  for (let pass = 0; ; pass++) {
+    if (pass === 2) throw new RefundAnswerPendingError(record);
+    if (record.status === 'applied') {
+      return { outcome: { kind: 'applied', refund: record.result!, duplicate: true }, record };
+    }
+    if (record.status === 'pending') {
+      if (record.commandId !== envelope.id) throw new RefundAnswerPendingError(record);
+      break;
+    }
+    if (record.status === 'rejected' && record.commandId === envelope.id) {
+      return { outcome: { kind: 'rejected', error: record.error! }, record };
+    }
+    if (record.status === 'unsent' && record.commandId === envelope.id) {
+      doc = await doc.incrementalModify((stored) => {
+        if (stored.status !== 'unsent' || stored.commandId !== envelope.id) return stored;
+        const { error, ...rest } = stored;
+        return { ...rest, status: 'pending', updatedAt: now() };
+      });
+      record = doc.toJSON() as PosRefund;
+      continue;
+    }
+    doc = await doc.incrementalModify((stored) => {
+      if (stored.status !== 'rejected' && stored.status !== 'unsent') return stored;
+      const { result, duplicate, error, ...rest } = stored;
+      return { ...rest, commandId: envelope.id, envelope, status: 'pending', updatedAt: now() };
+    });
+    record = doc.toJSON() as PosRefund;
+    if (record.commandId === envelope.id) break;
+  }
+  const outcome = await sendOrderRefund(transport, envelope);
+  if (outcome.kind !== 'unknown') {
+    doc = await doc.incrementalModify((stored) => {
+      if (stored.status !== 'pending' || stored.commandId !== envelope.id) return stored;
+      const updatedAt = now();
+      if (outcome.kind === 'applied') {
+        const { error, ...rest } = stored;
+        return { ...rest, status: 'applied', result: outcome.refund, duplicate: outcome.duplicate, updatedAt };
+      }
+      if (outcome.kind === 'rejected') return { ...stored, status: 'rejected', error: outcome.error, updatedAt };
+      const error = outcome.kind === 'refused'
+        ? { code: 'refused', message: outcome.reason, data: { status: outcome.status } }
+        : { code: 'unauthorized', message: 'unauthorized' };
+      return { ...stored, status: 'unsent', error, updatedAt };
+    });
+  }
+  return { outcome, record: doc.getLatest().toJSON() as PosRefund };
+}

package/src/register/expected.ts

@@ -3,12 +3,23 @@
  * 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.
+ * Refunds come from the till's applied `pos_refunds`, counted in the record's own `sessionId`
+ * (ADR-080 amendment 1), by the server's rule. WCPOS's `attributeRefunds` fallbacks (allocations,
+ * `refunded_amount`) are not ported: the store attributes each refund to a tender in `byMethod`.
  */
+import type { PosRefund } from '../refund/pos-refund';
+
+export type RefundRow = Pick<PosRefund, 'id' | 'sessionId' | 'status' | 'result'>;
+
+export function refundAmounts(refund: RefundRow): Array<[string, number]> {
+  const result = refund.result;
+  if (typeof result !== 'object' || result === null ||
+    (Object.getPrototypeOf(result) !== Object.prototype && Object.getPrototypeOf(result) !== null)) return [];
+  const byMethod = result.byMethod;
+  if (typeof byMethod !== 'object' || byMethod === null ||
+    (Object.getPrototypeOf(byMethod) !== Object.prototype && Object.getPrototypeOf(byMethod) !== null)) return [];
+  return Object.entries(byMethod).filter(([method, amount]) => method.length > 0 && Number.isSafeInteger(amount) && amount >= 0);
+}
 
 /** `session_id`, `kind`, `method_id`, `status` kept as WCPOS names them; money is TallyUI's integer-minor-units convention. */
 export type LedgerRow = {
@@ -32,7 +43,7 @@ export type Movement = {
 /**
  * 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.
+ * paid-in/paid-out movements, minus its applied refunds.
  *
  * 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.
@@ -41,10 +52,12 @@ export function deriveExpected({
   session,
   movements,
   ledgerRowsBySession,
+  refunds,
 }: {
   session: { id: string; countedFloatMinor: number };
   movements: readonly Movement[];
   ledgerRowsBySession: readonly LedgerRow[];
+  refunds?: readonly RefundRow[];
 }): Record<string, number> {
   const totals: Record<string, number> = { cash: session.countedFloatMinor };
   for (const row of ledgerRowsBySession) {
@@ -62,5 +75,9 @@ export function deriveExpected({
     if (row.type === 'paid_in') totals.cash += row.amountMinor;
     if (row.type === 'paid_out') totals.cash -= row.amountMinor;
   }
+  for (const refund of refunds ?? []) {
+    if (refund.status !== 'applied' || refund.sessionId !== session.id) continue;
+    for (const [method, amount] of refundAmounts(refund)) totals[method] = (totals[method] ?? 0) - amount;
+  }
   return totals;
 }

package/src/register/register-adoption.ts

@@ -5,6 +5,7 @@ import type { RegisterSession } from './schemas';
 import { isKnownSessionStatus, RegisterSessionRequiredError, RegisterTakeOverError, type RegisterSessionCollection } from './session-store';
 
 const chains = new WeakMap<RegisterCommandCollection, Promise<void>>();
+type SessionTarget = { commands: RegisterCommandCollection; sessions: RegisterSessionCollection; sessionId: string; now?: string };
 
 /**
  * Applied opens fill a missing resume id; refused opens make open/counting sessions conflict.
@@ -57,9 +58,11 @@ export async function adoptRegisterResults({ commands, sessions, registerId }: {
   return run;
 }
 
-export async function takeOverSession({ commands, sessions, sessionId, now }: {
-  commands: RegisterCommandCollection; sessions: RegisterSessionCollection; sessionId: string; now?: string;
+export async function takeOverSession({ commands, sessions, sessionId, now, registerContract }: SessionTarget & {
+  /** The store's register contract (`capabilities.register`); take over needs 2, and a missing value counts as below 2. */
+  registerContract?: number;
 }): Promise<void> {
+  if ((registerContract ?? 0) < 2) throw new RegisterTakeOverError('REGISTER_TAKEOVER_UNSUPPORTED');
   const run = (chains.get(commands) ?? Promise.resolve()).then(async () => {
     const [session] = await readFresh(sessions, { selector: { id: sessionId } });
     const row = await commands.findOne(`session.open:${sessionId}`).exec();
@@ -76,7 +79,7 @@ export async function takeOverSession({ commands, sessions, sessionId, now }: {
   return run;
 }
 
-async function finishAbandon({ commands, sessions, sessionId, now }: Parameters<typeof takeOverSession>[0]) {
+async function finishAbandon({ commands, sessions, sessionId, now }: SessionTarget) {
   const rows = await readFresh(commands, { selector: { 'payload.sessionId': sessionId, syncStatus: 'pending' } });
   for (const row of rows) {
     await (await commands.findOne(row.key).exec(true)).incrementalModify((doc) => doc.syncStatus !== 'pending' ? doc : ({
@@ -87,7 +90,7 @@ async function finishAbandon({ commands, sessions, sessionId, now }: Parameters<
   await (await sessions.findOne(sessionId).exec(true)).incrementalModify((doc) => doc.status === 'conflict' ? { ...doc, status: 'abandoned' } : doc);
 }
 
-export async function abandonSession(input: Parameters<typeof takeOverSession>[0]): Promise<void> {
+export async function abandonSession(input: SessionTarget): Promise<void> {
   const { commands, sessions, sessionId } = input;
   const run = (chains.get(commands) ?? Promise.resolve()).then(async () => {
     const [session] = await readFresh(sessions, { selector: { id: sessionId } });

package/src/register/schemas.ts

@@ -82,7 +82,7 @@ export interface Closure {
   counted: TenderMap;
   variance: TenderMap;
   period_sales_total_minor: number;
-  /** Always 0 until TallyUI has a refund model (ADR-032 amendment 1). */
+  /** The session's applied refunds (ADR-080 amendment 1); 0 when the app passes none. */
   period_refunds_total_minor: number;
   perpetual_sales_total_minor: number;
   perpetual_refunds_total_minor: number;