@tallyui/pos 0.1.0 → 3.0.0-next.0

package/src/register/index.ts

@@ -0,0 +1,32 @@
+export { normalizeAmount, isServerDecimal, movementFieldError } from './movement-input';
+export type { MovementType } from './movement-input';
+export { deriveExpected } from './expected';
+export type { LedgerRow, Movement } from './expected';
+export { parseMinor, validAmount, countVariance, overThreshold, closeNeedsApproval, denominationTotal, varianceText } from './register-count.helpers';
+export { denominations } from './register-count.denominations';
+export { registerSessionSchema, registerSessionCollection, cashMovementSchema, closureSchema } from './schemas';
+export type { RegisterSession, CashMovement, Closure } from './schemas';
+export {
+  mintUuid, readRegister, ensureRegister, observeRegister$, getBoundRegisterId, readBoundRegister, bindRegister,
+  unbindRegister, nextSaleCounter, mintClosureNumber, advancePerpetual, RegisterIdInvalidError,
+} from './register-document';
+export type { RegisterHost, RegisterCounters, RegisterBucket, RegisterStore, RegisterDocument } from './register-document';
+export {
+  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';
+export { deriveSettled } from './settled-figures';
+export type { Correction, RecordedFigures } from './settled-figures';
+export { exportCsv } from './export-csv';
+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, 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/money.ts

@@ -0,0 +1,18 @@
+/**
+ * Minor-unit money formatting shared across the register package (moved out of `export-csv.ts` so
+ * `closure-document.ts` reuses the same implementation instead of duplicating it).
+ */
+
+/**
+ * `minor` as a fixed-point decimal string with exactly `exponent` places: `-50` at exponent 2 is
+ * `'-0.50'`, `1250` is `'12.50'`, and at exponent 0, `1500` is `'1500'`. Integer maths only —
+ * sign, `Math.trunc`, and the remainder padded to `exponent` digits — no `toFixed` on floats.
+ */
+export function minorToDecimal(minor: number, exponent: number): string {
+  const sign = minor < 0 ? '-' : '';
+  const abs = Math.abs(minor);
+  const scale = 10 ** exponent;
+  const whole = Math.trunc(abs / scale);
+  const fraction = abs % scale;
+  return exponent === 0 ? `${sign}${whole}` : `${sign}${whole}.${String(fraction).padStart(exponent, '0')}`;
+}

package/src/register/movement-input.ts

@@ -0,0 +1,59 @@
+/**
+ * A cash-movement grammar a server can enforce, mirrored on the device.
+ *
+ * The limits come from WCPOS's server, which refuses a movement whose amount is not a plain
+ * unsigned decimal string, whose integer part carries more than fifteen significant digits,
+ * whose paid in/out amount is not positive, or whose reason is blank or over 500 characters.
+ * Gating the confirm button on `Number(amount) > 0` alone let several of those through, and a
+ * refused movement is cash that has already physically moved: the row is marked permanently
+ * failed and never reaches the ledger.
+ *
+ * No amount here is ever minor units — this mirror of the server's grammar only ever sees the
+ * string the cashier typed. Port provenance and re-sync notes: ADR-032 amendment 1.
+ */
+const SERVER_DECIMAL = /^\d+(?:\.\d+)?$/;
+const MAX_INTEGER_DIGITS = 15;
+export const MAX_REASON_LENGTH = 500;
+
+export type MovementType = 'paid_in' | 'paid_out' | 'no_sale';
+
+/**
+ * Rewrite what a keypad produced into the server's grammar, but only where the cashier's
+ * intent is unambiguous: a bare leading or trailing point is a half-typed number, and a comma
+ * followed by one or two digits is a decimal separator on a Spanish or German keypad.
+ *
+ * The digit count is the whole safeguard. `"1,000"` is a thousands separator to an English
+ * cashier on a hardware keyboard and a decimal to nobody, so converting it would silently
+ * record a movement of ONE — money quietly lost, which is the exact failure this module
+ * exists to prevent. Anything ambiguous is left as typed so it fails visibly instead.
+ */
+const KEYPAD_DECIMAL_COMMA = /^(\d+),(\d{1,2})$/;
+export function normalizeAmount(raw: string): string {
+  const trimmed = raw.trim();
+  const dotted = trimmed.replace(KEYPAD_DECIMAL_COMMA, '$1.$2');
+  return dotted.replace(/^\./, '0.').replace(/\.$/, '');
+}
+
+/** Whether the server's `decimal()` would accept this string. */
+export function isServerDecimal(value: string): boolean {
+  if (!SERVER_DECIMAL.test(value)) return false;
+  return value.split('.')[0].replace(/^0+/, '').length <= MAX_INTEGER_DIGITS;
+}
+
+/**
+ * The field the server would name in its 400, or null when it would accept the movement.
+ * A no sale carries no amount — the sheet sends '0' — but still needs a reason.
+ */
+export function movementFieldError(input: {
+  type: MovementType;
+  amount: string;
+  reason: string;
+}): 'amount' | 'reason' | null {
+  if (input.type !== 'no_sale') {
+    const amount = normalizeAmount(input.amount);
+    if (!isServerDecimal(amount) || Number(amount) <= 0) return 'amount';
+  }
+  const reason = input.reason.trim();
+  if (!reason || reason.length > MAX_REASON_LENGTH) return 'reason';
+  return null;
+}

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-count.denominations.ts

@@ -0,0 +1,11 @@
+/**
+ * Cash denominations by face value, in integer minor units, largest first (ADR-032 amendment 1:
+ * WCPOS `next` `3b5331b5c`). Every list, `default` included, assumes a two-decimal currency.
+ */
+const coinsMinor = [200, 100, 50, 20, 10, 5, 2, 1];
+export const denominations: Record<string, number[]> = {
+  GBP: [5000, 2000, 1000, 500, ...coinsMinor],
+  EUR: [50000, 20000, 10000, 5000, 2000, 1000, 500, ...coinsMinor],
+  USD: [10000, 5000, 2000, 1000, 500, 100, 25, 10, 5, 1],
+  default: [10000, 5000, 2000, 1000, 500, 200, 100, 50, 25, 10, 5, 1],
+};

package/src/register/register-count.helpers.ts

@@ -0,0 +1,64 @@
+/**
+ * The pure maths behind a register count: variance against the expected float, a display
+ * string for it, and the denomination arithmetic the counting keypad uses. Port provenance
+ * (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`.
+ *
+ * Money here is TallyUI's convention: integer minor units. Everywhere WCPOS assumed two
+ * decimals, these take the currency's `exponent` instead — 0 for JPY, 3 for KWD — except
+ * `validAmount`, which like WCPOS still takes the cashier's typed text.
+ */
+
+/**
+ * Parses a decimal string the cashier typed into integer minor units at `exponent` decimal
+ * places, without rounding. Returns `NaN` when the string carries more precision than the
+ * currency allows, so a safe-integer check on the result also rejects it.
+ */
+export function parseMinor(text: string, exponent: number): number {
+  const [whole, fraction = ''] = text.trim().split('.');
+  if (fraction.length > exponent) return NaN;
+  return Number(whole || '0') * 10 ** exponent + Number(fraction.padEnd(exponent, '0') || '0');
+}
+
+export const validAmount = (value: string, exponent: number) =>
+  /^(?:\d+\.?\d*|\.\d+)$/.test(value) &&
+  Number.isFinite(Number(value)) &&
+  Number.isSafeInteger(parseMinor(value, exponent));
+
+/** Counted minus expected, both already in minor units. */
+export const countVariance = (countedMinor: number, expectedMinor: number) =>
+  countedMinor - expectedMinor;
+
+/** Whether the variance exceeds the store's configured threshold (minor units; none means never). */
+export const overThreshold = (variance: number, thresholdMinor?: number | null) =>
+  thresholdMinor != null && Math.abs(variance) > thresholdMinor;
+
+/**
+ * Whether a close's cash count needs a manager's approval: its cash variance against the expected
+ * cash is over the threshold. The one definition `RegisterCount` and `useRegisterSession`'s
+ * `closeSession` gate share (ADR-032).
+ */
+export const closeNeedsApproval = (countedCashMinor: number, expectedCashMinor: number, thresholdMinor?: number | null) =>
+  overThreshold(countVariance(countedCashMinor, expectedCashMinor), thresholdMinor);
+
+/** Sums denomination face values (already minor units) by piece count. */
+export const denominationTotal = (pieces: Record<number, number>) =>
+  Object.entries(pieces).reduce((sum, [value, count]) => sum + Number(value) * count, 0);
+
+/**
+ * The variance line under the count: exact, short or over. `format` takes a major-unit
+ * amount, as an app's currency formatter expects, so `exponent` converts `variance` back for
+ * it; `t` supplies the translated words for the `register.exact`/`register.short`/
+ * `register.over` keys. Both are the app's own — neutral here.
+ *
+ * The direction lives in the word, not a sign (the Front desk, 2026-09-28): a signed amount
+ * next to "short" read as a double negative, so the amount here is always its absolute value.
+ */
+export function varianceText(
+  variance: number,
+  exponent: number,
+  format: (value: number) => string,
+  t: (key: string) => string,
+) {
+  if (!variance) return t('register.exact');
+  return `${format(Math.abs(variance) / 10 ** exponent)} ${t(variance < 0 ? 'register.short' : 'register.over')}`;
+}

package/src/register/register-document.ts

@@ -0,0 +1,268 @@
+/**
+ * The till's identity and counters: one RxDB local document, `register`. Port provenance
+ * (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`.
+ *
+ * The host is whatever carries local documents: `register_sessions`, created with
+ * `registerSessionCollection` (a Tally database has no database-level local documents). WCPOS
+ * keys its buckets by site UUID plus a numeric WooCommerce store id; TallyUI keys them by one
+ * neutral `storeKey` the app derives (for example the connector id plus the base URL). WCPOS's
+ * module-level snapshots (`getRegisterSnapshot`, `getRegisterId`, `getCurrentBoundRegisterId`)
+ * are not ported: callers pass the host and read the document explicitly.
+ */
+import type { RxLocalDocumentMutation } from 'rxdb';
+import { map } from 'rxjs';
+import type { Closure } from './schemas';
+
+export type RegisterHost = RxLocalDocumentMutation<any>;
+
+export type RegisterCounters = {
+  last_closure_number: number;
+  perpetual_sales_total_minor: number;
+  perpetual_refunds_total_minor: number;
+  counters_started_at?: string | null;
+};
+
+/**
+ * One register's counters, plus the closure being written: the draft is reserved here, in the
+ * same atomic write as its number, and `applied` once its period is in the perpetual totals.
+ */
+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. */
+  swept_closure_ids?: string[];
+};
+
+export interface RegisterStore {
+  sale_counter: number;
+  registers?: Record<string, RegisterBucket>;
+  /** The register (drawer) this till is bound to in this store. */
+  register_id?: string | null;
+  register_name?: string | null;
+}
+
+export interface RegisterDocument {
+  id: string;
+  name: string;
+  /** The caller's platform, for example `'ios'` or `'web'`. */
+  platform: string;
+  created_at: string;
+  /** Keyed by `storeKey`. */
+  stores: Record<string, RegisterStore>;
+}
+
+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?.();
+  if (id) return id;
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export async function readRegister(host: RegisterHost): Promise<RegisterDocument | null> {
+  return ((await host.getLocal<RegisterDocument>(REGISTER))?.toJSON(true).data as RegisterDocument | undefined) ?? null;
+}
+
+/** Reads the register document, minting it on first use; concurrent callers get the same one. */
+export async function ensureRegister(host: RegisterHost, platform: string): Promise<RegisterDocument> {
+  const existing = await readRegister(host);
+  if (existing) return existing;
+  const id = mintUuid().toLowerCase();
+  const data: RegisterDocument = {
+    id,
+    name: `Register ${id.slice(-4).toUpperCase()}`,
+    platform,
+    created_at: new Date().toISOString(),
+    stores: {},
+  };
+  try {
+    await host.insertLocal(REGISTER, data);
+    return data;
+  } catch (error) {
+    const winner = await readRegister(host);
+    if (winner) return winner;
+    throw error;
+  }
+}
+
+export function observeRegister$(host: RegisterHost) {
+  return host
+    .getLocal$<RegisterDocument>(REGISTER)
+    .pipe(map((doc) => (doc?.toJSON(true).data as RegisterDocument | undefined) ?? null));
+}
+
+/** Applies `modify` to one store's bucket in a single atomic write; `undefined` leaves the document unchanged. */
+async function modifyStore(
+  host: RegisterHost,
+  storeKey: string,
+  modify: (store: RegisterStore | undefined) => RegisterStore | undefined,
+) {
+  const doc = await host.getLocal<RegisterDocument>(REGISTER);
+  if (!doc) throw new Error('Register is not initialized');
+  // RxDB can batch modifiers and return the same final document to each caller, so callers
+  // capture their own result inside `modify`.
+  await doc.incrementalModify((data) => {
+    const store = modify(data.stores[storeKey]);
+    return store ? { ...data, stores: { ...data.stores, [storeKey]: store } } : data;
+  });
+}
+
+export function getBoundRegisterId(register: RegisterDocument | null, storeKey: string): string | null {
+  return register?.stores?.[storeKey]?.register_id ?? null;
+}
+
+export async function readBoundRegister(host: RegisterHost, storeKey: string) {
+  const register = await readRegister(host);
+  const id = getBoundRegisterId(register, storeKey);
+  return id ? { id, name: register?.stores[storeKey]?.register_name ?? '' } : 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,
+    register_name: register.name,
+  }));
+}
+
+export function unbindRegister(host: RegisterHost, storeKey: string) {
+  return modifyStore(host, storeKey, (store) => store && { ...store, register_id: null, register_name: null });
+}
+
+export async function nextSaleCounter(host: RegisterHost, storeKey: string): Promise<number> {
+  let counter = 0;
+  await modifyStore(host, storeKey, (store) => {
+    counter = (store?.sale_counter ?? 0) + 1;
+    return { ...(store ?? {}), sale_counter: counter };
+  });
+  return counter;
+}
+
+function withRegister(store: RegisterStore | undefined, registerId: string, bucket: RegisterBucket): RegisterStore {
+  const base = store ?? { sale_counter: 0 };
+  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
+ * same number back. A different draft is refused while an earlier one is reserved but not yet
+ * applied (`closure_write_incomplete`).
+ */
+export async function mintClosureNumber(
+  host: RegisterHost,
+  storeKey: string,
+  registerId: string,
+  closure?: Closure,
+): Promise<number> {
+  let number = 0;
+  await modifyStore(host, storeKey, (store) => {
+    const register = store?.registers?.[registerId] ?? {};
+    const reservation = register.closure_reservation;
+    if (closure && reservation?.row.id === closure.id && !!reservation.row.number_retried === !!closure.number_retried) {
+      number = reservation.row.number;
+      return undefined;
+    }
+    if (closure && reservation && reservation.row.id !== closure.id && !reservation.applied) {
+      throw new Error('closure_write_incomplete');
+    }
+    number = (register.last_closure_number ?? 0) + 1;
+    // A re-mint of a closure whose period was already applied to the register must not
+    // add it again: the register totals already carry it.
+    const applied = closure && reservation?.row.id === closure.id && reservation.applied ? reservation.row : null;
+    const sales = closure
+      ? (register.perpetual_sales_total_minor ?? 0) - (applied?.period_sales_total_minor ?? 0) + closure.period_sales_total_minor
+      : 0;
+    const refunds = closure
+      ? (register.perpetual_refunds_total_minor ?? 0) - (applied?.period_refunds_total_minor ?? 0) + closure.period_refunds_total_minor
+      : 0;
+    const next = closure
+      ? {
+          row: { ...closure, number, perpetual_sales_total_minor: sales, perpetual_refunds_total_minor: refunds },
+          applied: !!applied || !!closure.number_retried,
+        }
+      : reservation;
+    return withRegister(store, registerId, {
+      ...register,
+      last_closure_number: number,
+      ...(next ? { closure_reservation: next } : {}),
+      // An applied period follows the closure row it came from.
+      ...(applied ? { perpetual_sales_total_minor: sales, perpetual_refunds_total_minor: refunds } : {}),
+    });
+  });
+  return number;
+}
+
+/**
+ * Adds a closed period to the register's perpetual totals. With `closureId`, it applies that
+ * reserved closure once: the totals become the reservation's, and a repeat does nothing.
+ */
+export function advancePerpetual(
+  host: RegisterHost,
+  storeKey: string,
+  registerId: string,
+  period: { salesMinor: number; refundsMinor: number; closureId?: string },
+) {
+  return modifyStore(host, storeKey, (store) => {
+    const register = store?.registers?.[registerId] ?? {};
+    const reservation = register.closure_reservation;
+    if (period.closureId && (!reservation || reservation.row.id !== period.closureId || reservation.applied)) {
+      return undefined;
+    }
+    const sales = register.perpetual_sales_total_minor ?? 0;
+    const refunds = register.perpetual_refunds_total_minor ?? 0;
+    return withRegister(store, registerId, {
+      ...register,
+      ...(period.closureId && reservation ? { closure_reservation: { ...reservation, applied: true } } : {}),
+      perpetual_sales_total_minor: period.closureId && reservation
+        ? Math.max(sales, reservation.row.perpetual_sales_total_minor)
+        : sales + period.salesMinor,
+      perpetual_refunds_total_minor: period.closureId && reservation
+        ? Math.max(refunds, reservation.row.perpetual_refunds_total_minor)
+        : refunds + period.refundsMinor,
+      counters_started_at: register.counters_started_at ?? new Date().toISOString(),
+    });
+  });
+}
+
+/**
+ * Adds closure ids to the register's swept set (ADR-032, the #158 follow-ups), once each: the
+ * orphan-stamp sweep's bound, so a closure already checked costs the sweep no `pos_orders` query.
+ */
+export function markClosuresSwept(host: RegisterHost, storeKey: string, registerId: string, closureIds: readonly string[]) {
+  return modifyStore(host, storeKey, (store) => {
+    const register = store?.registers?.[registerId] ?? {};
+    const swept = new Set(register.swept_closure_ids);
+    closureIds.forEach((closureId) => swept.add(closureId));
+    return withRegister(store, registerId, { ...register, swept_closure_ids: [...swept] });
+  });
+}