@tallyui/pos 2.0.0 → 3.0.0-next.0

package/src/pos-order/types.ts

@@ -1,8 +1,20 @@
-import type { CommandError, CommandServerRefs, CommandWarning, PaymentMethodKind } from '@tallyui/core';
+import type { CommandError, CommandServerRefs, CommandWarning, PaymentMethodKind, TaxRounding } from '@tallyui/core';
 import type { DisplayTotals } from '../order/types';
 
 export type PosOrderSyncStatus = 'pending' | 'applied' | 'rejected';
 
+export 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. */
+export 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;
+}
+
 export interface PosOrderLine {
   id: string;
   productId: string;
@@ -44,24 +56,38 @@ export interface PosOrder {
   registerId?: string;
   /**
    * The register session the sale was taken in (ADR-032): its closure counts this order.
-   * Local only: `toOrderCreateEnvelope` never sends it.
+   * Sent at `order.create` version 3 as the payload's `sessionId` (the stamped or late session, one field).
    */
   sessionId?: string;
   /**
    * Set only by `useSale`'s late-sale path (ADR-032): the session the sale was taken for, which
    * refused the stamp after the money was taken. Such an order has no `sessionId`, so no closure
-   * counts it. Local only: `toOrderCreateEnvelope` never sends it.
+   * counts it. Sent at `order.create` version 3 as the payload's `sessionId` (the stamped or late session, one field).
    */
   lateSessionId?: string;
-  /** ADR-065: the receipt's display figures, in integer minor units of `currency` at `exponent`. Not written yet. */
+  /**
+   * The order.create version every attempt under this `commandId` goes out at: the outbox records it before the first
+   * send, and lowers it only on a downgrade (ADR-065 amendment). Absent means not sent yet (or requeued).
+   */
+  sentVersion?: 1 | 2 | 3 | 4;
+  /** The version first tried, before the downgrade (the order's audit). */
+  downgradedFrom?: 1 | 2 | 3 | 4;
+  /** ADR-065: the receipt's display figures, in integer minor units of `currency` at `exponent`. */
   display?: DisplayTotals & { currency: string; exponent: number };
-  /** ADR-065: tax by rate, named as `taxLinesByRate` names them (`amountMinor` is the tax). Not written yet. */
+  /** ADR-065: tax by rate, named as `taxLinesByRate` names them (`amountMinor` is the tax). */
   taxByRate?: Array<{ ratePpm: number; code?: string; 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;
 }

package/src/product/search-products.ts

@@ -14,9 +14,12 @@ export function searchProducts<Doc>(docs: Doc[], term: string, traits: ProductTr
   if (!query) return docs;
 
   const codes = (doc: Doc) =>
-    [traits.getSku(doc), traits.getBarcode(doc)]
+    [...new Set([
+      traits.getSku(doc), traits.getBarcode(doc),
+      ...(traits.getVariants?.(doc) ?? []).flatMap((variant) => [variant.sku, variant.barcode]),
+    ]
       .filter((code): code is string => Boolean(code))
-      .map((code) => code.toLowerCase());
+      .map((code) => code.toLowerCase()))];
 
   const exact = docs.filter((doc) => codes(doc).includes(query));
   if (exact.length) return exact;

package/src/receipt/build-receipt-data.ts

@@ -1,11 +1,11 @@
-import type { Discount, Order } from '../order/types';
+import type { Discount, SentOrder } from '../order/types';
 import { roundMicrosToMinor, taxLinesByRate } from '../tax/exact';
 import type { ReceiptConfig, ReceiptData } from './types';
 
-export function buildReceiptData(order: Order, config: ReceiptConfig): ReceiptData {
+export function buildReceiptData(order: SentOrder, config: ReceiptConfig): ReceiptData {
   // Drops the shared helper's `netMinor` (the Z report's own use): the receipt's tax summary
   // never showed it, and an exact-shape test elsewhere in this package pins that.
-  const taxLines = taxLinesByRate(order.lineItems, order.taxMinor, config.taxLabels).map(
+  const taxLines = taxLinesByRate(order.lineItems, order.taxMinor, config.taxLabels, order.taxRounding).map(
     ({ label, code, ratePpm, amountMinor }) => ({ label, code, ratePpm, amountMinor }),
   );
 
@@ -21,6 +21,7 @@ export function buildReceiptData(order: Order, config: ReceiptConfig): ReceiptDa
     return li.taxInclusive ? li.netMinor - share : li.netMinor + share;
   });
   const label = (d: Discount) => d.label ?? d.couponCode ?? `${d.type} discount`;
+  const customer = order.customer?.name || order.customer?.email;
 
   return {
     header: {
@@ -29,6 +30,7 @@ export function buildReceiptData(order: Order, config: ReceiptConfig): ReceiptDa
       orderNumber: order.id,
       date: order.createdAt,
       cashier: config.cashier,
+      ...(customer ? { customer } : {}),
       register: config.register,
     },
     lineItems: order.lineItems.map((li, index) => ({

package/src/receipt/types.ts

@@ -17,6 +17,7 @@ export interface ReceiptData {
     orderNumber: string;
     date: string;
     cashier?: string;
+    customer?: string;
     register?: string;
   };
   lineItems: ReceiptLineItem[];

package/src/register/closure-document.ts

@@ -17,6 +17,12 @@ import { minorToDecimal } from './money';
 import type { Closure, RegisterSession } from './schemas';
 
 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.
+ */
+export 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.";
 /** `writeClosure`'s own `breakdowns.movements` shape (session-store.ts): every entry carries at
  * least a string `id` and `reason`, so callers can read them without a cast. */
 type BreakdownMovement = Values & { id: string; reason: string };
@@ -171,6 +177,7 @@ function envelope<R extends Values>(row: R, context: ClosureContext, xreport = f
       ...Object.fromEntries(
         ['payment_methods', 'tax_rates', 'movements'].map((key) => [`has_${key}`, Object.keys((breakdowns[key] as Values) ?? {}).length > 0]),
       ),
+      ...(breakdowns.tax_rounding_mixed === true ? { tax_rounding_note: TAX_ROUNDING_MIXED_NOTE } : {}),
       ...money(row, ['period_sales_total', 'period_refunds_total', 'perpetual_sales_total', 'perpetual_refunds_total', 'unsynced_total']),
       opened_at_gmt: row.opened_at,
       opened_by: breakdowns.opened_by ?? null,

package/src/register/index.ts

@@ -8,11 +8,11 @@ export { registerSessionSchema, registerSessionCollection, cashMovementSchema, c
 export type { RegisterSession, CashMovement, Closure } from './schemas';
 export {
   mintUuid, readRegister, ensureRegister, observeRegister$, getBoundRegisterId, readBoundRegister, bindRegister,
-  unbindRegister, nextSaleCounter, mintClosureNumber, advancePerpetual,
+  unbindRegister, nextSaleCounter, mintClosureNumber, advancePerpetual, RegisterIdInvalidError,
 } from './register-document';
 export type { RegisterHost, RegisterCounters, RegisterBucket, RegisterStore, RegisterDocument } from './register-document';
 export {
-  RegisterSessionRequiredError, RegisterSessionClosedError, RegisterMovementStrandedError, openSessionSelector,
+  RegisterSessionRequiredError, RegisterSessionClosedError, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, openSessionSelector,
   requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure,
 } from './session-store';
 export type { RegisterSessionCollection, CashMovementCollection, ClosureCollection } from './session-store';
@@ -23,8 +23,10 @@ export { labelKeys } from './document-labels';
 export { clampClosureScope, selectClosureRows } from './closure-rows';
 export type { ClosureScope } from './closure-rows';
 export { minorToDecimal } from './money';
-export { formatClosureDate, buildClosureDocument, buildXReportDocument } from './closure-document';
+export { formatClosureDate, buildClosureDocument, buildXReportDocument, TAX_ROUNDING_MIXED_NOTE } from './closure-document';
 export type { ClosureContext } from './closure-document';
 export { registerFactsLogger, recordRegisterFact, type Actor, type RegisterFact } from './facts';
 export { useRegisterSession, RegisterTenderInProgressError, RegisterSessionAlreadyOpenError, RegisterCloseIncompleteError, RegisterApprovalRequiredError } from './use-register-session';
 export type { UseRegisterSessionOptions } from './use-register-session';
+export { registerCommandSchema, registerCommandCollection, registerCommandsLogger, sessionOpenCommand, sessionTransitionCommand, movementCommand, closureCommand, reconcileRegisterCommands } from './register-commands';
+export type { RegisterCommand, RegisterCommandCollection } from './register-commands';

package/src/register/movement-input.ts

@@ -13,7 +13,7 @@
  */
 const SERVER_DECIMAL = /^\d+(?:\.\d+)?$/;
 const MAX_INTEGER_DIGITS = 15;
-const MAX_REASON_LENGTH = 500;
+export const MAX_REASON_LENGTH = 500;
 
 export type MovementType = 'paid_in' | 'paid_out' | 'no_sale';
 

package/src/register/register-commands.ts

@@ -0,0 +1,147 @@
+import type { RxCollection, RxError, RxJsonSchema } from 'rxdb';
+import type {
+  CommandError, RegisterCommandType, RegisterCommandResult, RegisterSessionOpenPayload, RegisterSessionTransitionPayload,
+  RegisterMovementRecordPayload, RegisterMovementVoidPayload, RegisterClosureSubmitPayload,
+} from '@tallyui/core';
+import { createLogger } from '../logging';
+import { uuidv7 } from '../pos-order/uuidv7';
+import { readFresh } from '../rxdb';
+import { markCommandsSince, type RegisterHost } from './register-document';
+import type { CashMovement, Closure, RegisterSession } from './schemas';
+import type { CashMovementCollection, ClosureCollection, RegisterSessionCollection } from './session-store';
+
+export const registerCommandsLogger = createLogger('register-commands');
+
+export 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;
+}
+export type RegisterCommandCollection = RxCollection<RegisterCommand>;
+
+export const registerCommandSchema: RxJsonSchema<RegisterCommand> = {
+  title: 'Register commands', version: 0, primaryKey: 'key', type: 'object', additionalProperties: false,
+  properties: {
+    key: { type: 'string', maxLength: 100 }, registerId: { type: 'string', maxLength: 36 },
+    seq: { type: 'integer', minimum: 0, maximum: 1e15, multipleOf: 1 },
+    commandId: { type: 'string' }, type: { type: 'string' }, version: { type: 'integer' },
+    payload: { type: 'object', additionalProperties: true },
+    createdAt: { type: 'string' }, updatedAt: { type: 'string' },
+    syncStatus: { type: 'string', enum: ['pending', 'applied', 'rejected'], maxLength: 10 },
+    error: { type: 'object', properties: {
+      code: { type: 'string' }, message: { type: 'string' }, data: { type: 'object', additionalProperties: true },
+    }, required: ['code', 'message'], additionalProperties: false },
+    result: { type: 'object', additionalProperties: true },
+  },
+  required: ['key', 'registerId', 'seq', 'commandId', 'type', 'version', 'payload', 'createdAt', 'syncStatus', 'updatedAt'],
+  indexes: [['registerId', 'seq'], ['syncStatus', 'registerId', 'seq']],
+};
+export const registerCommandCollection = () => ({ schema: registerCommandSchema });
+
+type BuiltCommand = Pick<RegisterCommand, 'key' | 'type' | 'payload'> & { version: 1 };
+
+export function sessionOpenCommand(s: RegisterSession): BuiltCommand {
+  return { key: `session.open:${s.id}`, type: 'register.session.open', version: 1, payload: {
+    sessionId: s.id, registerId: s.register_id, openedAt: s.opened_at_gmt, countedFloatMinor: s.counted_float_minor,
+    ...(s.store_key == null ? {} : { storeKey: s.store_key }),
+    ...(s.business_day == null ? {} : { businessDay: s.business_day }),
+    ...(s.opened_by == null ? {} : { openedBy: s.opened_by }),
+    ...(s.expected_float_minor == null ? {} : { expectedFloatMinor: s.expected_float_minor }),
+    ...(s.opening_variance_minor == null ? {} : { openingVarianceMinor: s.opening_variance_minor }),
+  } satisfies RegisterSessionOpenPayload };
+}
+
+export function sessionTransitionCommand(s: RegisterSession & { status_at: string }): BuiltCommand {
+  return { key: `session.transition:${s.id}:${s.status}:${s.status_at}`, type: 'register.session.transition', version: 1, payload: {
+    sessionId: s.id, status: s.status, at: s.status_at,
+    ...(s.status !== 'closed' || s.counted == null ? {} : { counted: s.counted }),
+    ...(s.status !== 'closed' || s.closed_by == null ? {} : { closedBy: s.closed_by }),
+    ...(s.status !== 'closed' || s.approved_by == null ? {} : { approvedBy: s.approved_by }),
+  } satisfies RegisterSessionTransitionPayload };
+}
+
+export function movementCommand(m: CashMovement): BuiltCommand {
+  const common = { movementId: m.id, sessionId: m.session_id, createdAt: m.created_at_gmt,
+    ...(m.created_by == null ? {} : { createdBy: m.created_by }) };
+  return m.type === 'void'
+    ? { key: `movement.void:${m.id}`, type: 'register.movement.void', version: 1,
+        payload: { ...common, voids: m.voids! } satisfies RegisterMovementVoidPayload }
+    : { key: `movement.record:${m.id}`, type: 'register.movement.record', version: 1,
+        payload: { ...common, type: m.type, amountMinor: m.amountMinor, reason: m.reason } satisfies RegisterMovementRecordPayload };
+}
+
+export function closureCommand(c: Closure): BuiltCommand {
+  return { key: `closure.submit:${c.id}`, type: 'register.closure.submit', version: 1, payload: {
+    closureId: c.id, sessionId: c.session_id, registerId: c.register_id, number: c.number,
+    openedAt: c.opened_at, closedAt: c.closed_at,
+    ...(c.business_day == null ? {} : { businessDay: c.business_day }),
+    ...(c.closed_by == null ? {} : { closedBy: c.closed_by }),
+    ...(typeof c.breakdowns.approved_by === 'string' && c.breakdowns.approved_by ? { approvedBy: c.breakdowns.approved_by } : {}),
+    tillExpected: c.till_expected, counted: c.counted,
+    periodSalesTotalMinor: c.period_sales_total_minor, periodRefundsTotalMinor: c.period_refunds_total_minor,
+    perpetualSalesTotalMinor: c.perpetual_sales_total_minor, perpetualRefundsTotalMinor: c.perpetual_refunds_total_minor,
+    unsyncedCount: c.unsynced_count, unsyncedTotalMinor: c.unsynced_total_minor, softwareVersion: c.software_version,
+    orderIds: c.order_ids, movementIds: c.movement_ids,
+  } satisfies RegisterClosureSubmitPayload };
+}
+
+const chains = new WeakMap<RegisterCommandCollection, Map<string, Promise<void>>>();
+
+/** Appends missing facts in dependency order; the bytes of an existing key never change. */
+export 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[]> {
+  let registers = chains.get(commands);
+  if (!registers) chains.set(commands, registers = new Map());
+  const run = (registers.get(registerId) ?? Promise.resolve()).then(async () => {
+    const since = await markCommandsSince(host, storeKey, registerId, now ?? new Date().toISOString());
+    const [highest] = await readFresh(commands, { selector: { registerId }, sort: [{ seq: 'desc' }], limit: 1 });
+    let seq = highest?.seq ?? 0;
+    const transitioned = new Set((await readFresh(commands, { selector: { registerId, type: 'register.session.transition' } }))
+      .map(({ payload }) => payload.sessionId));
+    const rows = await readFresh(sessions, { selector: { register_id: registerId } });
+    const complete = new Set((await commands.storageInstance.findDocumentsById(rows.flatMap((session) =>
+      [`session.open:${session.id}`, ...(session.status === 'closed' && session.closure_id ? [`closure.submit:${session.closure_id}`] : [])]), false)).map(({ key }) => key));
+    const facts = await Promise.all(rows.filter((session) =>
+      session.status !== 'closed' || ((session.status_at == null || session.status_at >= since || complete.has(`session.open:${session.id}`))
+        && !complete.has(`closure.submit:${session.closure_id}`)))
+      .map(async (session) => {
+      const [entries, closureRows] = await Promise.all([
+        readFresh(movements, { selector: { session_id: session.id } }),
+        session.closure_id ? closures.storageInstance.findDocumentsById([session.closure_id], false) : Promise.resolve([]),
+      ]);
+      const events = (observed ?? []).filter((row) => row.id === session.id && !transitioned.has(session.id)
+        && row.status !== session.status && row.status !== 'closed')
+        .flatMap((row) => row.status_at == null ? [] : [sessionTransitionCommand({ ...row, status_at: row.status_at })]);
+      events.push(...entries.filter((entry) => entry.type !== 'void').map(movementCommand),
+        ...entries.filter((entry) => entry.type === 'void').map(movementCommand));
+      if (session.status_at != null) events.push(sessionTransitionCommand({ ...session, status_at: session.status_at }));
+      return { session, number: closureRows[0]?.number, built: [sessionOpenCommand(session), ...events,
+        ...closureRows.map((closure) => closureCommand(closure))] };
+    }));
+    facts.sort((a, b) => Number(a.session.status !== 'closed') - Number(b.session.status !== 'closed')
+      || (a.number ?? Infinity) - (b.number ?? Infinity)
+      || a.session.id.localeCompare(b.session.id));
+    const existing = new Set((await commands.storageInstance.findDocumentsById(facts.flatMap(({ built }) => built.map(({ key }) => key)), false))
+      .map(({ key }) => key));
+    const appended: string[] = [];
+    for (const { built } of facts) {
+      for (const command of built) {
+        if (existing.has(command.key)) continue;
+        seq++;
+        const at = now ?? new Date().toISOString();
+        try {
+          await commands.insert({ ...command, registerId, seq, commandId: uuidv7(), createdAt: at, updatedAt: at, syncStatus: 'pending' });
+          appended.push(command.key);
+        } catch (error) {
+          if ((error as RxError)?.code !== 'CONFLICT') throw error;
+        }
+        existing.add(command.key);
+      }
+    }
+    return appended;
+  });
+  registers.set(registerId, run.then(() => undefined, () => undefined));
+  return run;
+}

package/src/register/register-document.ts

@@ -27,6 +27,7 @@ export type RegisterCounters = {
  * same atomic write as its number, and `applied` once its period is in the perpetual totals.
  */
 export 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. */
@@ -52,6 +53,8 @@ export interface RegisterDocument {
 }
 
 const REGISTER = 'register';
+// Matches register_sessions/closures in schemas.ts and register_commands in register-commands.ts.
+const MAX_REGISTER_ID_LENGTH = 36;
 
 export function mintUuid(): string {
   const id = globalThis.crypto?.randomUUID?.();
@@ -121,7 +124,17 @@ export async function readBoundRegister(host: RegisterHost, storeKey: string) {
   return id ? { id, name: register?.stores[storeKey]?.register_name ?? '' } : null;
 }
 
-export function bindRegister(host: RegisterHost, storeKey: string, register: { id: string | null; name: string | null }) {
+export class RegisterIdInvalidError extends Error {
+  constructor() {
+    super('register_id_invalid');
+    this.name = 'RegisterIdInvalidError';
+  }
+}
+
+export async function bindRegister(host: RegisterHost, storeKey: string, register: { id: string | null; name: string | null }) {
+  if (typeof register.id === 'string' && (register.id.length === 0 || register.id.length > MAX_REGISTER_ID_LENGTH)) {
+    throw new RegisterIdInvalidError();
+  }
   return modifyStore(host, storeKey, (store) => ({
     ...(store ?? { sale_counter: 0 }),
     register_id: register.id,
@@ -147,6 +160,18 @@ function withRegister(store: RegisterStore | undefined, registerId: string, buck
   return { ...base, registers: { ...base.registers, [registerId]: bucket } };
 }
 
+/** Records when this register first enabled commands, once, in an atomic write. */
+export async function markCommandsSince(host: RegisterHost, storeKey: string, registerId: string, now: string): Promise<string> {
+  let since = now;
+  await modifyStore(host, storeKey, (store) => {
+    const register = store?.registers?.[registerId] ?? {};
+    since = register.commands_since ?? now;
+    if (register.commands_since !== undefined) return undefined;
+    return withRegister(store, registerId, { ...register, commands_since: since });
+  });
+  return since;
+}
+
 /**
  * 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

package/src/register/session-store.ts

@@ -11,11 +11,12 @@
  * to the decimal strings its envelope carries.
  */
 import type { RxCollection } from 'rxdb';
-import { taxLinesByRate } from '../tax/exact';
+import { DEFAULT_TAX_ROUNDING, taxLinesByRate } from '../tax/exact';
 import type { PosOrder } from '../pos-order/types';
 import { readFresh } from '../rxdb';
 import { deriveExpected, type LedgerRow } from './expected';
 import { recordRegisterFact } from './facts';
+import { MAX_REASON_LENGTH } from './movement-input';
 import { countVariance } from './register-count.helpers';
 import { advancePerpetual, markClosuresSwept, mintClosureNumber, mintUuid as uuid, readRegister, type RegisterHost } from './register-document';
 import type { CashMovement, Closure, RegisterSession } from './schemas';
@@ -39,10 +40,25 @@ export class RegisterSessionClosedError extends Error {
   }
 }
 
+/** ADR-068 6a: movement amounts must be safe integers, positive for paid_in/paid_out and zero for no_sale. */
+export class RegisterMovementAmountError extends Error {
+  constructor(type: 'paid_in' | 'paid_out' | 'no_sale', amountMinor: number) {
+    super(`movement_amount_invalid:${type}:${amountMinor}`);
+    this.name = 'RegisterMovementAmountError';
+  }
+}
+
+export class RegisterMovementReasonError extends Error {
+  constructor() {
+    super('movement_reason_invalid');
+    this.name = 'RegisterMovementReasonError';
+  }
+}
+
 /**
  * The movement is recorded, on a session that closed while it was saved, and no closure is known
- * to count it, so it was kept rather than deleted. The caller must not record it again; job c's
- * server resolves stranded movements. The message can be shown to a cashier as it is.
+ * to count it, so it stays local on the till. The caller must not record it again; the server
+ * refuses it once the closure exists (ADR-068 4). The message can be shown to a cashier as it is.
  */
 export class RegisterMovementStrandedError extends Error {
   readonly id: string;
@@ -280,13 +296,20 @@ export async function recordMovement(
   closures: ClosureCollection,
   input: { sessionId: string; type: 'paid_in' | 'paid_out' | 'no_sale'; amountMinor: number; reason: string; actor: string },
 ) {
+  if (
+    !Number.isSafeInteger(input.amountMinor) ||
+    ((input.type === 'paid_in' || input.type === 'paid_out') && input.amountMinor <= 0) ||
+    (input.type === 'no_sale' && input.amountMinor !== 0)
+  ) throw new RegisterMovementAmountError(input.type, input.amountMinor);
+  const reasonLength = input.reason.trim().length;
+  if (reasonLength === 0 || reasonLength > MAX_REASON_LENGTH) throw new RegisterMovementReasonError();
   await requireLiveSession(sessions, input.sessionId);
   const row = await movements.insert({
     id: uuid(),
     session_id: input.sessionId,
     type: input.type,
     amountMinor: input.amountMinor,
-    reason: input.reason,
+    reason: input.reason.trim(),
     created_by: input.actor,
     created_at_gmt: new Date().toISOString(),
   });
@@ -299,9 +322,8 @@ export async function recordMovement(
   // - with no closure row yet nothing is proven: `writeClosure` freezes the movements its caller
   //   collected, not this collection, and reserves that draft on the register document before
   //   inserting the row, so a caller's array or the reservation may already hold it. It's kept and
-  //   flagged stranded, and job c's server resolves it.
-  // If the re-read or the lookup fails, the outcome is unknown, so it's returned as recorded for
-  // the server to reconcile.
+  //   flagged stranded: it stays local on the till; the server refuses it once the closure exists.
+  // If the re-read or the lookup fails, the outcome is unknown, so it's returned as recorded.
   let counted: readonly string[] | undefined;
   try {
     const after = await readSession(sessions, input.sessionId);
@@ -358,9 +380,8 @@ export async function voidMovement(
   // deleted here, because deleting it would leave its target claimed by a missing reversal:
   // - a closure row that lists it counts it, so it's returned;
   // - a closure row that doesn't list it, or no closure row yet, leaves it uncounted or unproven,
-  //   so it's kept and flagged stranded, and job c's server resolves it.
-  // If the re-read or the lookup fails, the outcome is unknown, so it's returned as recorded for
-  // the server to reconcile.
+  //   so it's kept locally and flagged stranded; the server refuses it once the closure exists.
+  // If the re-read or the lookup fails, the outcome is unknown, so it's returned as recorded.
   let counted: readonly string[] | undefined;
   try {
     const after = await readSession(sessions, row.session_id);
@@ -453,11 +474,17 @@ export async function writeClosure({
   }
   // Same per-rate split a receipt shows (`taxLinesByRate`), run per order so each order's rates
   // add up to its own taxMinor, then summed across the session's orders by rate. A line's own
-  // taxInclusive overrides the order's, matching PosOrderLine's own fallback convention.
+  // taxInclusive overrides the order's, matching PosOrderLine's own fallback convention. Each order is split by the
+  // tax rounding it recorded (#287), so its rows are its receipt's; absent is the default, today's split.
   const taxRates = new Map<string, { ratePpm: number; net_minor: number; tax_minor: number }>();
+  const roundings = new Set<string>();
   for (const order of bound) {
+    // Grouped by the rule applied: a `custom` sale used the default figures, so it joins the default's group.
+    const recorded = order.taxRounding ?? DEFAULT_TAX_ROUNDING;
+    const { granularity, mode } = recorded.granularity === 'custom' ? DEFAULT_TAX_ROUNDING : recorded;
+    roundings.add(`${granularity} ${mode}`);
     const lines = order.lines.map((line) => ({ ...line, taxInclusive: line.taxInclusive ?? order.pricesIncludeTax }));
-    for (const { ratePpm, netMinor, amountMinor } of taxLinesByRate(lines, order.taxMinor)) {
+    for (const { ratePpm, netMinor, amountMinor } of taxLinesByRate(lines, order.taxMinor, undefined, order.taxRounding)) {
       const existing = taxRates.get(String(ratePpm));
       taxRates.set(String(ratePpm), {
         ratePpm,
@@ -502,6 +529,8 @@ export async function writeClosure({
           ratePpm, { name: `Tax ${ratePpm / 10000}%`, net_minor, tax_minor, gross_minor: net_minor + tax_minor },
         ]),
       ),
+      // The session's sales used more than one tax rounding (#287): the Z report says so.
+      ...(roundings.size > 1 ? { tax_rounding_mixed: true } : {}),
       opening_float: {
         expected_minor: session.expected_float_minor ?? null,
         counted_minor: session.counted_float_minor,

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

@@ -17,11 +17,13 @@
 import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import { combineLatest, map, of, switchMap } from 'rxjs';
 import type { RxCollection } from 'rxdb';
+import type { ServerCapabilities } from '@tallyui/core';
 import type { PosOrder } from '../pos-order/types';
 import { readFresh, watchFresh } from '../rxdb';
 import { deriveExpected, type LedgerRow } from './expected';
 import { recordRegisterFact, registerFactsLogger, type Actor } from './facts';
 import { closeNeedsApproval } from './register-count.helpers';
+import { reconcileRegisterCommands, registerCommandsLogger, type RegisterCommandCollection } from './register-commands';
 import { observeRegister$, readRegister, type RegisterBucket, type RegisterDocument, type RegisterHost } from './register-document';
 import type { CashMovement, Closure, RegisterSession } from './schemas';
 import * as store from './session-store';
@@ -79,6 +81,9 @@ export interface UseRegisterSessionOptions {
   movements: CashMovementCollection | null;
   /** `closures`; `null` while it opens. */
   closures: ClosureCollection | null;
+  /** `register_commands`, created with `registerCommandCollection()`; `null` while it opens. */
+  commands?: RegisterCommandCollection | null;
+  capabilities?: ServerCapabilities;
   /** `pos_orders`: a session's sales are those whose `sessionId` is its id. */
   orders: RxCollection<PosOrder> | null;
   /** The register document's host, for the closure number and perpetual totals (`writeClosure`); `null` while it opens. */
@@ -142,6 +147,25 @@ function ledgerRows(orders: readonly PosOrder[]): LedgerRow[] {
 
 export function useRegisterSession(options: UseRegisterSessionOptions) {
   const { sessions, movements, closures, orders, register, storeKey, registerId, enabled, actor, timezone, tenderInProgress, expectedCloseTime, labels } = options;
+  const { commands } = options;
+  const commandEnabled = (options.capabilities?.register ?? 0) >= 1;
+  const commandTarget = useMemo(() => enabled && commandEnabled && commands && sessions && movements && closures && register && registerId
+    ? { commands, sessions, movements, closures, host: register, storeKey, registerId } : null,
+  [enabled, commandEnabled, commands, sessions, movements, closures, register, storeKey, registerId]);
+  const commandTargetRef = useRef(commandTarget);
+  commandTargetRef.current = commandTarget;
+  const reconcile = (row?: RegisterSession) => {
+    const target = commandTargetRef.current;
+    if (!target) return;
+    void reconcileRegisterCommands({ ...target, observed: row ? [row] : undefined }).catch((error: unknown) => {
+      try {
+        registerCommandsLogger.error('Register command reconcile failed', { context: { registerId: target.registerId, error: String(error) } });
+      } catch {
+        // A failing log sink must not affect a register action either.
+      }
+    });
+  };
+  useEffect(reconcile, [commandTarget]);
   const source = useMemo(() => {
     if (!enabled || !sessions || !movements || !closures || !orders || !registerId || !register) return null;
     return combineLatest([
@@ -312,18 +336,29 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
           return await run;
         } finally {
           openingByRegister.delete(key);
+          reconcile();
         }
       },
       startCounting: async () => {
+        let row: Awaited<ReturnType<typeof store.startCounting>> | undefined;
+        try {
         refuseDuringTender();
-        const row = await store.startCounting(live().sessions, current().id);
+        row = await store.startCounting(live().sessions, current().id);
         recordRegisterFact({ kind: 'counting-started', actor, sessionId: row.id, registerId: row.register_id });
         return row;
+        } finally {
+          reconcile(row?.toJSON());
+        }
       },
       backToSelling: async () => {
-        const row = await store.backToSelling(live().sessions, current().id);
+        let row: Awaited<ReturnType<typeof store.backToSelling>> | undefined;
+        try {
+        row = await store.backToSelling(live().sessions, current().id);
         recordRegisterFact({ kind: 'counting-abandoned', actor, sessionId: row.id, registerId: row.register_id });
         return row;
+        } finally {
+          reconcile(row?.toJSON());
+        }
       },
       /**
        * `counted` maps each tender to its counted minor units. An interrupted close resumes with
@@ -397,9 +432,11 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
         } finally {
           closingByRegister.delete(key);
           notifyClosing();
+          reconcile();
         }
       },
       recordMovement: async (input: { type: 'paid_in' | 'paid_out' | 'no_sale'; amountMinor: number; reason: string }) => {
+        try {
         // `live()` first: missing collections or host refuse before `requireOpen` writes anything.
         const { sessions, movements, closures, registerId } = live();
         const sessionId = await requireOpen();
@@ -409,8 +446,12 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
           movementId: row.id, movementType: row.type, amount: row.amountMinor,
         });
         return row;
+        } finally {
+          reconcile();
+        }
       },
       voidMovement: async (id: string) => {
+        try {
         const { sessions, movements, closures, registerId } = live();
         await requireOpen();
         const row = await store.voidMovement(sessions, movements, id, actor.id, closures);
@@ -419,6 +460,9 @@ export function useRegisterSession(options: UseRegisterSessionOptions) {
           movementId: row.id, movementType: row.type, amount: row.amountMinor, voids: id,
         });
         return row;
+        } finally {
+          reconcile();
+        }
       },
     },
   };

package/src/sale/cart.ts

@@ -18,5 +18,6 @@ export function addEntryToCart<Doc>(builder: OrderBuilder, entry: CatalogueEntry
   return builder.addLine({
     productId: traits.getId(product), variantId: variant.id, name,
     sku: variant.sku ?? '', imageUrl: traits.getImageUrl?.(product), unitPrice,
+    taxClass: traits.getTaxClass?.(product, variant.id),
   });
 }