@tallyui/pos 3.7.1 → 3.9.0

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/index.ts

@@ -13,7 +13,7 @@ export {
 } from './register-document';
 export type { RegisterHost, RegisterCounters, RegisterBucket, RegisterStore, RegisterDocument } from './register-document';
 export {
-  RegisterSessionRequiredError, RegisterSessionClosedError, RegisterNeedsUpgradeError, isKnownSessionStatus, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, openSessionSelector,
+  RegisterSessionRequiredError, RegisterSessionClosedError, RegisterNeedsUpgradeError, RegisterSessionConflictError, RegisterTakeOverError, isKnownSessionStatus, RegisterMovementAmountError, RegisterMovementReasonError, RegisterMovementStrandedError, openSessionSelector,
   requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure,
 } from './session-store';
 export type { RegisterSessionCollection, CashMovementCollection, ClosureCollection } from './session-store';
@@ -30,4 +30,5 @@ export { registerFactsLogger, recordRegisterFact, type Actor, type RegisterFact
 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 { adoptRegisterResults, takeOverSession, abandonSession } from './register-adoption';
 export type { RegisterCommand, RegisterCommandCollection } from './register-commands';

package/src/register/register-adoption.ts

@@ -0,0 +1,105 @@
+import { readFresh } from '../rxdb';
+import { uuidv7 } from '../pos-order/uuidv7';
+import { registerCommandsLogger, type RegisterCommandCollection } from './register-commands';
+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.
+ * Superseded rejections make open/counting sessions terminal; a conflict session leaves only by an applied open or abandon (ADR-078 decision 9); terminal/unknown states stay untouched.
+ * Applied conflict opens restore the latest transition's counting state, otherwise open; pending rows do nothing.
+ * Answers are walked in seq/key order; adoption is idempotent and safe to run at any time.
+ */
+export async function adoptRegisterResults({ commands, sessions, registerId }: {
+  commands: RegisterCommandCollection; sessions: RegisterSessionCollection; registerId: string;
+}): Promise<void> {
+  const run = (chains.get(commands) ?? Promise.resolve()).then(async () => {
+    const [answers, transitions, rows] = await Promise.all([
+      readFresh(commands, { selector: { registerId, syncStatus: { $in: ['applied', 'rejected'] } }, sort: [{ seq: 'asc' }, { key: 'asc' }] }),
+      readFresh(commands, { selector: { registerId, type: 'register.session.transition' }, sort: [{ seq: 'desc' }, { key: 'desc' }] }),
+      readFresh(sessions, { selector: { register_id: registerId } }),
+    ]);
+    for (const session of rows) {
+      if (session.status === 'conflict' && answers.some((answer) => answer.payload.sessionId === session.id
+        && answer.syncStatus === 'rejected' && answer.error?.code === 'register_session_abandoned')) {
+        await finishAbandon({ commands, sessions, sessionId: session.id });
+        continue;
+      }
+      const latest = transitions.find(({ payload }) => payload.sessionId === session.id);
+      const modify = (doc: RegisterSession): RegisterSession => {
+        let next = doc;
+        for (const answer of answers) {
+          if (!isKnownSessionStatus(next.status) || next.status === 'closed' || next.status === 'superseded' || next.status === 'abandoned') break;
+          if (answer.payload.sessionId !== doc.id) continue;
+          if (answer.syncStatus === 'rejected') {
+            if (answer.error?.code === 'register_session_superseded'
+              && (next.status === 'open' || next.status === 'counting')) next = { ...next, status: 'superseded' };
+            else if (answer.type === 'register.session.open' && answer.error?.code === 'register_session_already_open'
+              && (next.status === 'open' || next.status === 'counting')) next = { ...next, status: 'conflict' };
+          } else if (answer.type === 'register.session.open') {
+            const resumed = answer.result?.resumed?.fromSessionId;
+            if (typeof resumed === 'string' && next.server_session_id == null) next = { ...next, server_session_id: resumed };
+            if (next.status === 'conflict') next = { ...next, status: latest?.payload.status === 'counting' ? 'counting' : 'open' };
+          }
+        }
+        return next;
+      };
+      if (modify(session) === session) continue;
+      const row = await sessions.findOne(session.id).exec();
+      if (row) await row.incrementalModify(modify);
+    }
+  }).catch((error: unknown) => {
+    registerCommandsLogger.error('Register result adoption failed', { context: { registerId, error: String(error) } });
+  });
+  chains.set(commands, run.then(() => undefined, () => undefined));
+  return run;
+}
+
+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();
+    if (session?.status !== 'conflict' || !row) throw new RegisterSessionRequiredError();
+    await row.incrementalModify((doc) => {
+      if (doc.syncStatus !== 'rejected' || doc.error?.code !== 'register_session_already_open'
+        || typeof doc.error.data?.sessionId !== 'string') throw new RegisterSessionRequiredError();
+      const { error, ...rest } = doc;
+      return { ...rest, commandId: uuidv7(), version: 2, syncStatus: 'pending',
+        payload: { ...doc.payload, supersedes: error.data!.sessionId }, updatedAt: now ?? new Date().toISOString() };
+    });
+  });
+  chains.set(commands, run.then(() => undefined, () => undefined));
+  return run;
+}
+
+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 : ({
+      ...doc, syncStatus: 'rejected', error: { code: 'register_session_abandoned', message: 'The cashier chose another register.' },
+      updatedAt: now ?? new Date().toISOString(),
+    }));
+  }
+  await (await sessions.findOne(sessionId).exec(true)).incrementalModify((doc) => doc.status === 'conflict' ? { ...doc, status: 'abandoned' } : doc);
+}
+
+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 } });
+    if (session?.status === 'abandoned') return;
+    if (session?.status !== 'conflict') throw new RegisterSessionRequiredError();
+    const [open] = await readFresh(commands, { selector: { key: `session.open:${sessionId}` } });
+    if (open?.syncStatus === 'pending') throw new RegisterTakeOverError('REGISTER_TAKEOVER_PENDING');
+    await finishAbandon(input);
+  });
+  chains.set(commands, run.then(() => undefined, () => undefined));
+  return run;
+}

package/src/register/register-commands.ts

@@ -38,16 +38,28 @@ export const registerCommandSchema: RxJsonSchema<RegisterCommand> = {
 };
 export const registerCommandCollection = () => ({ schema: registerCommandSchema });
 
-type BuiltCommand = Pick<RegisterCommand, 'key' | 'type' | 'payload'> & { version: 1 };
+type BuiltCommand = Pick<RegisterCommand, 'key' | 'type' | 'payload'> & { version: 1 | 2 };
 
-export function sessionOpenCommand(s: RegisterSession): BuiltCommand {
-  return { key: `session.open:${s.id}`, type: 'register.session.open', version: 1, payload: {
+/** ADR-078: 1 to 64 characters after trim. */
+export function deviceNameOf(name: string | null | undefined): string | undefined {
+  let trimmed = name?.trim();
+  if (trimmed && trimmed.length > 64) {
+    const last = trimmed.charCodeAt(63);
+    trimmed = trimmed.slice(0, last >= 0xd800 && last <= 0xdbff ? 63 : 64).trimEnd();
+  }
+  return trimmed || undefined;
+}
+
+export function sessionOpenCommand(s: RegisterSession, v2?: { deviceName?: string | null }): BuiltCommand {
+  const deviceName = deviceNameOf(v2?.deviceName);
+  return { key: `session.open:${s.id}`, type: 'register.session.open', version: v2 ? 2 : 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 }),
+    ...(deviceName === undefined ? {} : { deviceName }),
   } satisfies RegisterSessionOpenPayload };
 }
 
@@ -88,9 +100,10 @@ export function closureCommand(c: Closure): BuiltCommand {
 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 }: {
+export function reconcileRegisterCommands({ commands, sessions, movements, closures, host, storeKey, registerId, now, observed, registerContract, deviceName }: {
   commands: RegisterCommandCollection; sessions: RegisterSessionCollection; movements: CashMovementCollection;
   closures: ClosureCollection; host: RegisterHost; storeKey: string; registerId: string; now?: string; observed?: RegisterSession[];
+  registerContract?: number; deviceName?: string | null;
 }): Promise<string[]> {
   // `conflict` and `superseded` are local states derived from the store's answers (ADR-078 decision 9), never sent as a transition.
   const sentStatus = (s: RegisterSession): s is RegisterSession & { status: RegisterSessionTransitionPayload['status'] } => s.status === 'open' || s.status === 'counting' || s.status === 'closed';
@@ -106,8 +119,8 @@ export function reconcileRegisterCommands({ commands, sessions, movements, closu
     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}`)))
+      session.status !== 'abandoned' && (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 } }),
@@ -119,7 +132,7 @@ export function reconcileRegisterCommands({ commands, sessions, movements, closu
       events.push(...entries.filter((entry) => entry.type !== 'void').map(movementCommand),
         ...entries.filter((entry) => entry.type === 'void').map(movementCommand));
       if (session.status_at != null && sentStatus(session)) events.push(sessionTransitionCommand({ ...session, status_at: session.status_at }));
-      return { session, number: closureRows[0]?.number, built: [sessionOpenCommand(session), ...events,
+      return { session, number: closureRows[0]?.number, built: [(registerContract ?? 0) >= 2 ? sessionOpenCommand(session, { deviceName }) : sessionOpenCommand(session), ...events,
         ...closureRows.map((closure) => closureCommand(closure))] };
     }));
     facts.sort((a, b) => Number(a.session.status !== 'closed') - Number(b.session.status !== 'closed')

package/src/register/schemas.ts

@@ -24,8 +24,8 @@ export interface RegisterSession {
   register_id: string;
   /** The app's neutral store key (see `bindRegister`). */
   store_key?: string | null;
-  /** Stored status is an open string so a later local state costs no migration (ADR-078 decision 9); the union names today's states. */
-  status: 'open' | 'counting' | 'closed' | 'conflict' | 'superseded';
+  /** Stored status is an open string so a later local state costs no migration (ADR-078 decision 9); the union names today's states. `abandoned` is local only and terminal (the cashier chose another register while in conflict). */
+  status: 'open' | 'counting' | 'closed' | 'conflict' | 'superseded' | 'abandoned';
   /** The store session this local id was resumed as (ADR-078 decision 2), never the session that superseded it; null until a resume. */
   server_session_id?: string | null;
   /** The store's day the session opened, `yyyy-MM-dd`. */
@@ -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;

package/src/register/session-store.ts

@@ -4,8 +4,8 @@
  *
  * Everything here writes local-only collections (`schemas.ts`). WCPOS's outbox (`pending`,
  * `retryMovement`) moves to registers job c. A session's sales are the `pos_orders` documents
- * whose `sessionId` is the session's id, and their payments are its ledger rows. Refunds are
- * not attributed yet (no refund model, as in `deriveExpected`). The frozen closure's money
+ * whose `sessionId` is the session's id, and their payments are its ledger rows.
+ * A session's refunds are its applied `pos_refunds` records, when the app passes them (ADR-080 amendment 1). The frozen closure's money
  * breakdowns (`payment_methods`, `opening_float`, `movements`, `tax_rates`) are minor-unit
  * integers, the same convention as the closure row itself; `closure-document.ts` converts them
  * to the decimal strings its envelope carries.
@@ -13,8 +13,9 @@
 import type { RxCollection } from 'rxdb';
 import { DEFAULT_TAX_ROUNDING, taxLinesByRate } from '../tax/exact';
 import type { PosOrder } from '../pos-order/types';
+import type { PosRefund } from '../refund/pos-refund';
 import { readFresh } from '../rxdb';
-import { deriveExpected, type LedgerRow } from './expected';
+import { deriveExpected, refundAmounts, type LedgerRow } from './expected';
 import { recordRegisterFact } from './facts';
 import { MAX_REASON_LENGTH } from './movement-input';
 import { countVariance } from './register-count.helpers';
@@ -49,6 +50,24 @@ export class RegisterNeedsUpgradeError extends Error {
   }
 }
 
+/** Opening is refused while the register has a `conflict` session (ADR-078); its message can be shown to a cashier as it is. */
+export class RegisterSessionConflictError extends Error {
+  readonly code = 'REGISTER_SESSION_CONFLICT';
+  constructor() {
+    super('This register is open on another till. Take it over or choose another register.');
+    this.name = 'RegisterSessionConflictError';
+  }
+}
+
+export class RegisterTakeOverError extends Error {
+  constructor(readonly code: 'REGISTER_TAKEOVER_UNSUPPORTED' | 'REGISTER_TAKEOVER_PENDING') {
+    super(code === 'REGISTER_TAKEOVER_UNSUPPORTED'
+      ? 'This store cannot take over a register. Choose another register.'
+      : 'Taking over this register is still waiting for the store.');
+    this.name = 'RegisterTakeOverError';
+  }
+}
+
 /** 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) {
@@ -80,7 +99,7 @@ export class RegisterMovementStrandedError extends Error {
   }
 }
 
-/** Every move a session may make. Nothing leaves `closed`; everything else is refused.
+/** Every move a session may make. `closed` and `abandoned` are terminal: nothing leaves them; everything else is refused.
  * No cashier move leaves `conflict` or `superseded`; the store's answers set them (ADR-078). */
 const TRANSITIONS: Record<RegisterSession['status'], readonly RegisterSession['status'][]> = {
   open: ['counting', 'closed'],
@@ -88,6 +107,7 @@ const TRANSITIONS: Record<RegisterSession['status'], readonly RegisterSession['s
   closed: [],
   conflict: [],
   superseded: [],
+  abandoned: [],
 };
 
 /** Whether this build knows the stored session status. */
@@ -116,6 +136,7 @@ async function requireLiveSession(sessions: RegisterSessionCollection, id: strin
   if (!session) throw new RegisterSessionRequiredError();
   if (!isKnownSessionStatus(session.status)) throw new RegisterNeedsUpgradeError();
   if (session.status === 'closed') throw new RegisterSessionClosedError();
+  if (session.status === 'abandoned') throw new RegisterSessionClosedError();
   return session;
 }
 
@@ -420,6 +441,7 @@ export async function voidMovement(
  * Only a closed session (`closed` with `closed_at_gmt`) has a closure, and a closed session is
  * final, so its existing closure is returned as it was frozen. Orders the server rejected still
  * count in the drawer, because the cash was taken.
+ * A refund still pending at close is not counted, and the Z lists it.
  */
 export async function writeClosure({
   closures,
@@ -430,6 +452,7 @@ export async function writeClosure({
   otherTenders,
   movements,
   orders,
+  refunds,
   tillExpected,
   labels,
   resolveCashierName,
@@ -447,6 +470,8 @@ export async function writeClosure({
   movements: readonly CashMovement[];
   /** Any `pos_orders`; only those whose `sessionId` is this session's are counted. */
   orders: readonly PosOrder[];
+  /** `pos_refunds` rows; only this session's applied ones are counted (ADR-080 amendment 1). */
+  refunds?: readonly PosRefund[];
   tillExpected?: Record<string, number>;
   labels?: { register_name: string; closed_by_name: string; opened_by_name?: string; approved_by_name?: string };
   resolveCashierName?: (id: string) => string;
@@ -466,6 +491,7 @@ export async function writeClosure({
     return existing;
   }
   const bound = orders.filter((order) => order.sessionId === session.id);
+  const countedRefunds = (refunds ?? []).filter((refund) => refund.status === 'applied' && refund.sessionId === session.id);
   // Each payment is captured, and a cash payment's amount is already net of change.
   const rows: LedgerRow[] = bound.flatMap((order) =>
     order.payments.map((payment) => ({
@@ -483,6 +509,7 @@ export async function writeClosure({
       session: { id: session.id, countedFloatMinor: session.counted_float_minor },
       movements: entries,
       ledgerRowsBySession: rows,
+      refunds,
     });
   const counts = { cash: counted, ...otherTenders };
   const sum = (values: number[]) => values.reduce((total, value) => total + value, 0);
@@ -491,6 +518,11 @@ export async function writeClosure({
     const method = row.kind === 'cash' ? 'cash' : row.method_id;
     payment_methods[method] = { sales_minor: (payment_methods[method]?.sales_minor ?? 0) + row.amountMinor, refunds_minor: 0 };
   }
+  for (const refund of countedRefunds) {
+    for (const [method, amount] of refundAmounts(refund)) {
+      payment_methods[method] = { sales_minor: payment_methods[method]?.sales_minor ?? 0, refunds_minor: (payment_methods[method]?.refunds_minor ?? 0) + amount };
+    }
+  }
   // 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. Each order is split by the
@@ -532,7 +564,7 @@ export async function writeClosure({
       Object.entries(counts).map(([method, value]) => [method, countVariance(value, till_expected[method] ?? 0)]),
     ),
     period_sales_total_minor: sum(rows.map((row) => row.amountMinor)),
-    period_refunds_total_minor: 0,
+    period_refunds_total_minor: sum(countedRefunds.flatMap((refund) => refundAmounts(refund).map(([, amount]) => amount))),
     perpetual_sales_total_minor: 0,
     perpetual_refunds_total_minor: 0,
     unsynced_count: unsynced.length,
@@ -561,7 +593,11 @@ export async function writeClosure({
         id, type, amountMinor, reason, voids: voids ?? null, created_at_gmt, created_by: created_by ?? null, voided_by: voided_by ?? null,
       })),
       transaction_count: bound.length,
-      refund_count: 0,
+      refund_count: countedRefunds.length,
+      ...(refunds !== undefined ? {
+        refund_ids: countedRefunds.map((refund) => refund.id),
+        pending_refund_ids: refunds.filter((refund) => refund.status === 'pending' && refund.sessionId === session.id).map((refund) => refund.id),
+      } : {}),
       cashiers: [...new Set(bound.map((order) => order.cashierRef ?? '').filter(Boolean))].map((id) => ({
         id,
         name: resolveCashierName?.(id) || id,