@tallyui/pos 0.1.0 → 3.0.0-next.0

package/src/register/closure-document.ts

@@ -0,0 +1,277 @@
+/**
+ * The register's closure and X-report documents (ADR-032): WCPOS's receipt-template envelope, so
+ * its shipped templates and renderer can be copied in later (ADR-032, backlog 48). Port
+ * provenance (ADR-032 amendment 1): WCPOS `next` `3b5331b5c` `closure-document.ts`.
+ *
+ * Neutral changes: money is a2's integer minor units on input, from `Closure`'s/`RegisterSession`'s
+ * own fields AND from `breakdowns` (`writeClosure` freezes `payment_methods`, `opening_float`,
+ * `movements` and `tax_rates` in the same minor-unit convention as the closure row itself — it is
+ * not an opaque, already-decimal blob). `buildClosureDocument` converts every `*_minor`/`amountMinor`
+ * breakdown field to the decimal strings the envelope carries with `minorToDecimal` at
+ * `ClosureContext.exponent` (b1's `exportCsv` does the same); `number` is a2's `Closure.number`
+ * (`printed_number`/`server_number` don't exist); `store_id` is sourced from a2's `store_key`;
+ * date-fns/`@date-fns/tz` become `Intl`, following a2's `businessDayOf`; a cashier id stays a2's
+ * string id (not WCPOS's numeric one).
+ */
+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 };
+
+export type ClosureContext = {
+  store: Values;
+  currency: string;
+  timezone: string;
+  locale: string;
+  printedAt: string;
+  /** Minor-unit decimal places for every money field the envelope carries. */
+  exponent: number;
+  formatMoney: (value: string) => string;
+  i18n: Record<string, string>;
+  /** Overrides an X-report's `server_expected` tender map, in minor units. */
+  expected?: Record<string, number>;
+  /**
+   * `buildXReportDocument`'s own breakdowns merge only (unlike `buildClosureDocument`'s frozen
+   * `Closure.breakdowns`): its money fields are still expected as decimal strings, not minor
+   * units. Job c's X-report caller, once it exists, converts them before passing this in.
+   */
+  breakdowns?: Values;
+};
+
+const decimalMap = (minor: Record<string, number>, exponent: number): Record<string, string> =>
+  Object.fromEntries(Object.entries(minor).map(([key, value]) => [key, minorToDecimal(value, exponent)]));
+
+/** `writeClosure`'s frozen minor-unit breakdown money (`payment_methods`, `tax_rates`,
+ * `opening_float`, `movements[].amountMinor`) → the decimal strings the envelope carries. */
+function decimalizeBreakdowns(breakdowns: Values, exponent: number): Values {
+  const dec = (m: unknown) => (typeof m === 'number' ? minorToDecimal(m, exponent) : m);
+  const group = (key: string, pairs: [string, string][]) => {
+    const source = breakdowns[key] as Record<string, Values> | undefined;
+    return (
+      source &&
+      Object.fromEntries(
+        Object.entries(source).map(([id, entry]) => [
+          id,
+          { ...entry, ...Object.fromEntries(pairs.map(([from, to]) => [to, dec(entry[from])])) },
+        ]),
+      )
+    );
+  };
+  const openingFloat = breakdowns.opening_float as Values | undefined;
+  return {
+    ...breakdowns,
+    ...(breakdowns.payment_methods
+      ? { payment_methods: group('payment_methods', [['sales_minor', 'sales'], ['refunds_minor', 'refunds']]) }
+      : {}),
+    ...(breakdowns.tax_rates
+      ? { tax_rates: group('tax_rates', [['net_minor', 'net'], ['tax_minor', 'tax'], ['gross_minor', 'gross']]) }
+      : {}),
+    ...(openingFloat
+      ? {
+          opening_float: {
+            ...openingFloat, expected: dec(openingFloat.expected_minor), counted: dec(openingFloat.counted_minor),
+            variance: dec(openingFloat.variance_minor),
+          },
+        }
+      : {}),
+    ...(breakdowns.movements
+      ? { movements: (breakdowns.movements as BreakdownMovement[]).map((m) => ({ ...m, amount: dec(m.amountMinor) })) }
+      : {}),
+  };
+}
+
+// Server Receipt_Date_Formatter keys; absent dates remain empty, not today's date.
+export function formatClosureDate(
+  value: string | null | undefined,
+  context: Pick<ClosureContext, 'timezone' | 'locale'>,
+) {
+  const date = value
+    ? new Date(/[Zz]|[+-]\d\d:\d\d$/.test(value) ? value : `${value.replace(' ', 'T')}Z`)
+    : null;
+  const timeZone = context.timezone === 'device' ? undefined : context.timezone;
+  const display = (settings: Intl.DateTimeFormatOptions) =>
+    date ? new Intl.DateTimeFormat(context.locale, { timeZone, ...settings, hour12: false }).format(date) : '';
+  const result: Record<string, string> = {
+    datetime: display({ dateStyle: 'medium', timeStyle: 'short' }),
+    date: display({ dateStyle: 'medium' }),
+    time: display({ timeStyle: 'short' }),
+  };
+  for (const style of ['short', 'long', 'full'] as const) {
+    result[`datetime_${style}`] = display({ dateStyle: style, timeStyle: style === 'short' ? 'short' : style });
+    result[`date_${style}`] = display({ dateStyle: style });
+  }
+  const parts = date
+    ? Object.fromEntries(
+        new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' })
+          .formatToParts(date)
+          .map(({ type, value: v }) => [type, v]),
+      )
+    : ({} as Record<string, string>);
+  result.date_ymd = date ? `${parts.year}-${parts.month}-${parts.day}` : '';
+  result.date_dmy = date ? `${parts.day}/${parts.month}/${parts.year}` : '';
+  result.date_mdy = date ? `${parts.month}/${parts.day}/${parts.year}` : '';
+  result.day = date ? parts.day : '';
+  result.month = date ? parts.month : '';
+  result.year = date ? parts.year : '';
+  for (const style of ['short', 'long'] as const) {
+    result[`weekday_${style}`] = display({ weekday: style });
+    result[`month_${style}`] = display({ month: style });
+  }
+  return result;
+}
+
+// Generic over the row so its own literal fields (e.g. `Closure`'s `unsynced_count: number`)
+// survive the `money(row, [...])` spread below into the return type, instead of widening to
+// `Values`'s `unknown` — the same reason `BreakdownMovement` types the movements mapping.
+function envelope<R extends Values>(row: R, context: ClosureContext, xreport = false) {
+  const money = <T extends Values, K extends string>(values: T, fields: K[]) =>
+    Object.assign(
+      {},
+      values,
+      Object.fromEntries(fields.map((key) => [`${key}_display`, context.formatMoney(String(values[key] ?? ''))])),
+    ) as T & Record<`${K}_display`, string>;
+  const breakdowns = (row.breakdowns ?? {}) as Values;
+  const labels: Values = {
+    opened_by_name: '', closed_by_name: '', approved_by_name: '',
+    ...Object.fromEntries(Object.entries(breakdowns).filter(([key]) => key.endsWith('_name'))),
+    ...(breakdowns.labels as Values),
+  };
+  const rows = (key: string, fields: string[]) =>
+    Object.entries((breakdowns[key] ?? {}) as Record<string, Values>).map(([entryKey, value]) =>
+      money({ ...value, name: value.name ?? value.method ?? value.rate ?? entryKey }, fields),
+    );
+  const methods = (breakdowns.payment_methods ?? {}) as Record<string, Values>;
+  const counted = (row.counted ?? {}) as Record<string, string>;
+  const expected = (row.expected ?? {}) as Record<string, string>;
+  const variances = (row.variance ?? {}) as Record<string, string>;
+  const tenders = [...new Set([...Object.keys(counted), ...Object.keys(expected)])].map((name) => {
+    const variance = variances[name] ?? '';
+    const method = Object.values(methods).find((m) => m.method === name) ?? methods[name];
+    return money(
+      {
+        name,
+        label: method?.name || name.charAt(0).toUpperCase() + name.slice(1),
+        expected: expected[name] ?? '', counted: counted[name] ?? '', variance,
+        has_variance: Number(variance || 0) !== 0,
+        variance_label:
+          variance === '' ? '' : context.i18n[Number(variance) > 0 ? 'over' : Number(variance) < 0 ? 'short' : 'exact'],
+        variance_absolute_display: context.formatMoney(variance.replace('-', '')),
+      },
+      ['expected', 'counted', 'variance'],
+    );
+  });
+  return {
+    closure: {
+      has_sales:
+        row.period_sales_total != null || row.period_refunds_total != null || Number(breakdowns.transaction_count) > 0,
+      has_perpetual: row.perpetual_sales_total != null || row.perpetual_refunds_total != null,
+      ...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,
+      closed_by: row.closed_by ?? null,
+      approved_by: breakdowns.approved_by ?? null,
+      closed_at_gmt: row.closed_at,
+      opened_at: formatClosureDate(row.opened_at as string, context),
+      closed_at: formatClosureDate(row.closed_at as string, context),
+      tenders,
+      breakdowns: {
+        ...breakdowns,
+        labels,
+        payment_methods: rows('payment_methods', ['sales', 'refunds']),
+        tax_rates: rows('tax_rates', ['net', 'tax', 'gross']),
+        opening_float: money((breakdowns.opening_float ?? {}) as Values, ['expected', 'counted', 'variance']),
+        movements: ((breakdowns.movements ?? []) as BreakdownMovement[]).map((m) => ({
+          ...money(m, ['amount']),
+          created_at: formatClosureDate((m.created_at_gmt ?? m.created_at) as string, context),
+          type_label: context.i18n[String(m.type)] ?? m.type,
+          voided: !!m.voided_by,
+        })),
+        cashiers: ((breakdowns.cashiers ?? []) as (Values | string)[]).map((c) => (typeof c === 'string' ? { id: c, name: c } : c)),
+      },
+    },
+    store: context.store,
+    register: { id: row.register_id, name: labels.register_name ?? '' },
+    software: { name: 'WCPOS', plugin_version: row.software_version ?? '' },
+    order: { currency: context.currency, printed: formatClosureDate(context.printedAt, context) },
+    fiscal: {
+      immutable_id: '', hash: '', qr_payload: '', tax_agency_code: '', signature_excerpt: '',
+      document_label: '', sequence: null, signed_at: null, extra_fields: [],
+      document_type: xreport ? 'xreport' : 'closure',
+      receipt_number: xreport ? '' : String(row.number),
+      is_sale_document: false, is_refund_document: false, is_closure_document: true,
+      is_x_report: xreport,
+      is_reprint: !xreport && !!row.print_count,
+      reprint_count: xreport ? 0 : ((row.print_count as number) ?? 0),
+    },
+    i18n: context.i18n,
+  };
+}
+
+export function buildClosureDocument(row: Closure, context: ClosureContext) {
+  const { exponent } = context;
+  const dec = (m: number) => minorToDecimal(m, exponent);
+  const {
+    store_key, till_expected, expected, counted, variance, period_sales_total_minor, period_refunds_total_minor,
+    perpetual_sales_total_minor, perpetual_refunds_total_minor, unsynced_total_minor, ...rest
+  } = row;
+  return envelope(
+    {
+      ...rest,
+      breakdowns: decimalizeBreakdowns(rest.breakdowns, exponent),
+      store_id: store_key,
+      till_expected: decimalMap(till_expected, exponent),
+      expected: decimalMap(expected, exponent),
+      counted: decimalMap(counted, exponent),
+      variance: decimalMap(variance, exponent),
+      period_sales_total: dec(period_sales_total_minor),
+      period_refunds_total: dec(period_refunds_total_minor),
+      perpetual_sales_total: dec(perpetual_sales_total_minor),
+      perpetual_refunds_total: dec(perpetual_refunds_total_minor),
+      unsynced_total: dec(unsynced_total_minor),
+    },
+    context,
+  );
+}
+
+export function buildXReportDocument(session: RegisterSession, context: ClosureContext) {
+  const { exponent } = context;
+  const dec = (m: number | null | undefined) => (m == null ? undefined : minorToDecimal(m, exponent));
+  const expectedMinor = context.expected ?? session.server_expected ?? {};
+  const countedMinor = session.counted ?? {};
+  const varianceMinor = Object.fromEntries(
+    Object.entries(countedMinor).map(([key, value]) => [key, value - (expectedMinor[key] ?? 0)]),
+  );
+  return envelope(
+    {
+      id: session.id,
+      register_id: session.register_id,
+      store_id: session.store_key,
+      opened_at: session.opened_at_gmt,
+      expected: decimalMap(expectedMinor, exponent),
+      counted: decimalMap(countedMinor, exponent),
+      variance: decimalMap(varianceMinor, exponent),
+      breakdowns: {
+        ...context.breakdowns,
+        opening_float: {
+          expected: dec(session.expected_float_minor), counted: dec(session.counted_float_minor),
+          variance: dec(session.opening_variance_minor),
+        },
+      },
+    },
+    context,
+    true,
+  );
+}

package/src/register/closure-rows.ts

@@ -0,0 +1,65 @@
+/**
+ * The closures list's pure selectors (ADR-032): a requested scope clamped to the local history
+ * window, and its rows within that scope, newest first. Port provenance (ADR-032 amendment 1):
+ * WCPOS `next` `3b5331b5c` `use-closure-rows.ts` — `ClosureScope`, `clampClosureScope` and
+ * `selectClosureRows` only. The React hook that pages the server and merges local/remote rows is
+ * registers job c, not ported here.
+ */
+import { businessDayOf } from './session-store';
+import type { Closure } from './schemas';
+
+export type ClosureScope = {
+  from: string;
+  to: string;
+  registerId: string;
+  storeKey?: string;
+  cashier?: string;
+};
+
+/**
+ * WCPOS's `HISTORY_DAYS` (`@wcpos/sync-core`) bounds how far back local report history reaches
+ * without a server aggregation call. Its value is 92 (wcpos/roadmap#332, "the 92-day reach").
+ */
+const DEFAULT_HISTORY_DAYS = 92;
+
+/** `day` minus `days` calendar days, both `yyyy-MM-dd`: calendar arithmetic, not a zone conversion. */
+function daysBefore(day: string, days: number): string {
+  const at = new Date(`${day}T00:00:00Z`);
+  at.setUTCDate(at.getUTCDate() - days);
+  return at.toISOString().slice(0, 10);
+}
+
+/** Clamps a requested scope's `from`/`to` to `today` and to `historyDays` before it. */
+export function clampClosureScope(
+  scope: ClosureScope,
+  today: string,
+  historyDays = DEFAULT_HISTORY_DAYS,
+): ClosureScope {
+  const min = daysBefore(today, historyDays);
+  const clamp = (day: string) => (day < min ? min : day > today ? today : day);
+  return { ...scope, from: clamp(scope.from), to: clamp(scope.to) };
+}
+
+/**
+ * Rows within `scope`, newest business day first, then newest `closed_at`. A row with no
+ * `business_day` (a legacy or remote row) gets one from `opened_at` in `timezone`, reusing a2's
+ * `businessDayOf` rather than duplicating it. Register and cashier are optional filters; the
+ * store is not — a row's `store_key` must equal `scope.storeKey` (both `null` when neither is
+ * set), as WCPOS always compared `store_id`.
+ */
+export function selectClosureRows(rows: readonly Closure[], scope: ClosureScope, timezone: string) {
+  return rows
+    .map((row) => ({
+      ...row,
+      business_day: row.business_day || businessDayOf(row.opened_at, timezone),
+    }))
+    .filter(
+      (row) =>
+        row.business_day >= scope.from &&
+        row.business_day <= scope.to &&
+        (!scope.registerId || row.register_id === scope.registerId) &&
+        (row.store_key ?? null) === (scope.storeKey ?? null) &&
+        (scope.cashier === undefined || row.closed_by === scope.cashier),
+    )
+    .sort((a, b) => b.business_day.localeCompare(a.business_day) || b.closed_at.localeCompare(a.closed_at));
+}

package/src/register/document-labels.ts

@@ -0,0 +1,46 @@
+// Offline defaults use the same label keys as the shipped server closure template. Port
+// provenance (ADR-032 amendment 1): WCPOS `next` `3b5331b5c` `document-labels.ts`, unchanged —
+// no money, no imports.
+export const labelKeys = {
+  x_report: 'register.x_report',
+  closure: 'reports.document.closure',
+  opened: 'reports.document.opened',
+  closed: 'register.closed',
+  approver: 'reports.document.approver',
+  opening_float: 'reports.document.opening_float',
+  expected: 'reports.document.expected',
+  counted: 'register.counted',
+  variance: 'register.variance',
+  tenders: 'reports.document.tenders',
+  tender: 'reports.document.tender',
+  cash_movements: 'reports.document.cash_movements',
+  time: 'common.time',
+  type: 'common.type',
+  amount: 'register.amount',
+  reason: 'register.reason',
+  sales: 'reports.sales',
+  period_sales: 'register.period_sales',
+  period_refunds: 'register.period_refunds',
+  transactions: 'reports.document.transactions',
+  refunds: 'common.refunds',
+  payment_method: 'reports.document.payment_method',
+  cashiers: 'reports.document.cashiers',
+  tax_rates: 'common.tax_rates',
+  tax_rate: 'reports.document.tax_rate',
+  net: 'reports.document.net',
+  tax: 'common.tax',
+  gross: 'reports.document.gross',
+  perpetual_totals: 'reports.document.perpetual_totals',
+  perpetual_sales: 'register.perpetual_sales',
+  perpetual_refunds: 'register.perpetual_refunds',
+  unsynced_sales: 'reports.document.unsynced_sales',
+  short: 'reports.document.short',
+  over: 'reports.document.over',
+  exact: 'reports.exact',
+  voided: 'pos_checkout.status_voided',
+  paid_in: 'register.paid_in',
+  paid_out: 'register.paid_out',
+  no_sale: 'register.no_sale',
+  void: 'register.void',
+  copy: 'reports.document.copy',
+};

package/src/register/expected.ts

@@ -0,0 +1,66 @@
+/**
+ * What the register should hold at close, per tender method: the session's cash float plus
+ * 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.
+ */
+
+/** `session_id`, `kind`, `method_id`, `status` kept as WCPOS names them; money is TallyUI's integer-minor-units convention. */
+export type LedgerRow = {
+  session_id?: string | null;
+  kind: string;
+  method_id: string;
+  status: string;
+  amountMinor: number;
+};
+
+/** `type`, `voids` and `voided_by` are kept as WCPOS names them: neutral across backends. */
+export type Movement = {
+  id: string;
+  session_id: string;
+  type: string;
+  amountMinor: number;
+  voided_by?: string | null;
+  voids?: string | null;
+};
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function deriveExpected({
+  session,
+  movements,
+  ledgerRowsBySession,
+}: {
+  session: { id: string; countedFloatMinor: number };
+  movements: readonly Movement[];
+  ledgerRowsBySession: readonly LedgerRow[];
+}): Record<string, number> {
+  const totals: Record<string, number> = { cash: session.countedFloatMinor };
+  for (const row of ledgerRowsBySession) {
+    if (row.session_id !== session.id || row.status !== 'captured') continue;
+    const method = row.kind === 'cash' ? 'cash' : row.method_id;
+    totals[method] = (totals[method] ?? 0) + row.amountMinor;
+  }
+  const voids = new Set(
+    movements
+      .filter((row) => row.session_id === session.id && row.type === 'void')
+      .map((row) => row.voids),
+  );
+  for (const row of movements) {
+    if (row.session_id !== session.id || row.voided_by || voids.has(row.id)) continue;
+    if (row.type === 'paid_in') totals.cash += row.amountMinor;
+    if (row.type === 'paid_out') totals.cash -= row.amountMinor;
+  }
+  return totals;
+}

package/src/register/export-csv.ts

@@ -0,0 +1,74 @@
+/**
+ * A CSV export of the closures currently shown: one column per tender the visible rows use, an
+ * expected-only tender kept as a zero-counted shortage, quoted/escaped cells with a CRLF line
+ * ending, and a leading `'` on formula- or control-prefixed text so a spreadsheet reads it as
+ * text (LEDGER.md #26, #27). Port provenance (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`
+ * `export-csv.ts`. Money is a2's integer minor units: an `exponent` parameter (as in a1's
+ * `parseMinor`/`varianceText`) formats each cell back to the decimal string WCPOS's server sent,
+ * e.g. `1250` at exponent 2 becomes `'12.50'`.
+ */
+import { minorToDecimal } from './money';
+import type { Closure } from './schemas';
+
+/** Widens a tender-map lookup back to `number | undefined`: a method absent from the map. */
+const at = (map: Record<string, number>, key: string): number | undefined => map[key];
+
+export function exportCsv(
+  rows: readonly Closure[],
+  exponent: number,
+  t: (key: string) => string,
+  names: Record<string, string> = {},
+  storeName = '',
+) {
+  const tenders = [
+    ...new Set(
+      rows.flatMap((row) => [
+        ...Object.keys(row.expected),
+        ...Object.keys(row.counted),
+        ...Object.keys(row.variance),
+      ]),
+    ),
+  ];
+  const cell = (value: unknown) => {
+    const text = String(value ?? '');
+    return `"${(/^(?:[\t\r\n]|[\s\x00-\x1f\x7f-\x9f]*[=+\-@])/.test(text) ? "'" + text : text).replace(/"/g, '""')}"`;
+  };
+  const header = ['business_day', 'closure', 'register', 'store', 'opened', 'closed', 'closer'].map((key) =>
+    t(`reports.csv_${key}`),
+  );
+  header.push(
+    ...tenders.flatMap((method) => [
+      `${t('reports.document.expected')} (${method})`,
+      `${t('register.counted')} (${method})`,
+      `${t('register.variance')} (${method})`,
+    ]),
+    t('reports.csv_status'),
+  );
+  return [
+    header,
+    ...rows.map((row) => [
+      row.business_day,
+      row.number,
+      row.breakdowns.register_name || names[row.register_id] || row.register_id.slice(0, 8),
+      row.breakdowns.store_name || storeName || row.store_key,
+      row.opened_at,
+      row.closed_at,
+      row.breakdowns.closed_by_name || t('register.unknown_cashier'),
+      ...tenders.flatMap((method) => {
+        const expected = at(row.expected, method);
+        const counted = at(row.counted, method) ?? (expected === undefined ? undefined : 0);
+        const value = at(row.variance, method) ?? (expected === undefined ? undefined : (counted ?? 0) - expected);
+        return [
+          expected === undefined ? '' : minorToDecimal(expected, exponent),
+          counted === undefined ? '' : minorToDecimal(counted, exponent),
+          value === undefined
+            ? ''
+            : `${minorToDecimal(Math.abs(value), exponent)} ${t(value < 0 ? 'register.short' : value > 0 ? 'register.over' : 'reports.exact')}`,
+        ];
+      }),
+      row.unsynced_count > 0 ? t('register.unsynced') : row.corrections_count ? t('reports.corrected') : '',
+    ]),
+  ]
+    .map((row) => row.map(cell).join(','))
+    .join('\r\n');
+}

package/src/register/facts.ts

@@ -0,0 +1,109 @@
+/**
+ * Register facts (ADR-032): a closed vocabulary of human register actions, logged through
+ * TallyUI's own logger. Port provenance (ADR-032 amendment 1): WCPOS `next` `3b5331b5c`
+ * `audit.ts`, `RegisterFact` and `recordRegisterFact` only — `useRegisterActor` is React and
+ * belongs to job c, and so do the outbox/bridge-diagnostic facts (`outbox-approval-refused`,
+ * `outbox-request-failed`, `movement-retry-requested`, `movement-accepted`, `session-adopted`,
+ * `session-pruned`, `binding-changed`, `binding-removed`, `directory-unavailable`,
+ * `bridge-cycle-failed`): a2 has no outbox or hardware-bridge concept yet to attach them to.
+ *
+ * Neutral changes from the WCPOS source: WCPOS's `mintUuid` (`register-document.ts`) becomes
+ * a2's own; a person id (`approvedBy`) is a2's string id, not WCPOS's numeric one; money fields
+ * are a2's integer minor units, matching `CashMovement.amountMinor` and `Closure.counted`/
+ * `variance`.
+ *
+ * TallyUI's own addition (registers c1a): `late-sale`, a sale whose money was taken but whose
+ * session refused the stamp (ADR-032 amendment "Late sale"). Its `sessionId` is the session it
+ * tried, and its durable subject is the order.
+ */
+import { createLogger } from '../logging';
+import { mintUuid } from './register-document';
+import type { CashMovement, Closure, RegisterSession } from './schemas';
+
+/** The register-session logging scope; the app attaches its own sinks (console, remote, toast). */
+export const registerFactsLogger = createLogger('register-session');
+
+const attempt = () => ({ operationId: mintUuid().replace(/-/g, '') });
+
+export type Actor = { id: string; name: string };
+type Pair = { sessionId: string | undefined; registerId: string | null | undefined };
+type Human = Pair & { actor: Actor };
+type Movement = Pair & { movementId: string; movementType: CashMovement['type']; amount: number };
+
+type SimpleKind = 'counting-started' | 'counting-abandoned' | 'approval-refused' | 'x-report-dispatched' | 'drawer-dispatched';
+export type RegisterFact =
+  | (Human & { kind: 'session-opened'; amount: number; variance: RegisterSession['opening_variance_minor'] })
+  | (Human & { kind: SimpleKind })
+  | (Human & { kind: 'session-closed'; closureId: string } & Pick<Closure, 'number' | 'counted' | 'variance'>)
+  | (Human & Movement & { kind: 'movement-recorded' })
+  | (Human & Movement & { kind: 'movement-voided'; voids: string })
+  | (Human & { kind: 'approval-granted'; approvedBy: string | null })
+  | (Human & { kind: 'variance-over-threshold'; variance: number; threshold: number | undefined })
+  | (Pair & { kind: 'late-sale'; orderId: string; actor?: Actor });
+
+/** A human action without its own durable record gets a fresh attempt id; a durable action (a
+ * session, a movement or a late sale's order) uses the stable id of its subject. */
+function identity(fact: RegisterFact): { operationId: string } {
+  switch (fact.kind) {
+    case 'session-opened':
+      return { operationId: fact.sessionId?.replace(/-/g, '') ?? '' };
+    case 'session-closed':
+      return { operationId: fact.closureId.replace(/-/g, '') };
+    case 'movement-recorded':
+    case 'movement-voided':
+      return { operationId: fact.movementId.replace(/-/g, '') };
+    case 'late-sale':
+      return { operationId: fact.orderId.replace(/-/g, '') };
+    default:
+      return attempt();
+  }
+}
+
+export function recordRegisterFact(fact: RegisterFact): void {
+  const terminal = identity(fact);
+  const pair = { sessionId: fact.sessionId, registerId: fact.registerId };
+  const emit = (
+    message: string,
+    type: string,
+    context: Record<string, unknown> = {},
+    level: 'info' | 'warn' = 'info',
+  ) => registerFactsLogger[level](message, { actor: fact.actor, terminal, context: { type, ...pair, ...context } });
+  switch (fact.kind) {
+    case 'session-opened':
+      return emit('Register session opened', 'register.session-opened', { amount: fact.amount, variance: fact.variance });
+    case 'counting-started':
+      return emit('Register session counting started', 'register.counting-started');
+    case 'counting-abandoned':
+      return emit('Register session counting abandoned', 'register.counting-abandoned');
+    case 'session-closed':
+      return emit('Register session closed', 'register.session-closed', {
+        closureId: fact.closureId, number: fact.number, counted: fact.counted, variance: fact.variance,
+      });
+    case 'movement-recorded':
+      // No-sale is the cashier action, independent of drawer dispatch, and makes no cash claim.
+      if (fact.movementType === 'no_sale')
+        return emit('Register no-sale recorded', 'register.no-sale-recorded', { movementId: fact.movementId });
+      return emit('Register cash movement recorded', 'register.movement-recorded', {
+        movementId: fact.movementId, movementType: fact.movementType, amount: fact.amount,
+      });
+    case 'movement-voided':
+      return emit('Register cash movement voided', 'register.movement-voided', {
+        movementId: fact.movementId, movementType: fact.movementType, amount: fact.amount, voids: fact.voids,
+      });
+    case 'approval-granted':
+      return emit('Register session approval granted', 'register.approval-granted', { approvedBy: fact.approvedBy });
+    case 'approval-refused':
+      return emit('Register session approval refused', 'register.approval-refused', {}, 'warn');
+    case 'variance-over-threshold':
+      return emit('Register count exceeds variance threshold', 'register.variance-over-threshold',
+        { variance: fact.variance, threshold: fact.threshold }, 'warn');
+    // These prove dispatch success, not that paper printed or a physical drawer opened.
+    case 'x-report-dispatched':
+      return emit('Register X-report print dispatched', 'register.x-report-printed');
+    case 'drawer-dispatched':
+      return emit('Register drawer kick dispatched', 'register.drawer-opened');
+    // The money was taken, so the sale is kept and queued, outside every closure.
+    case 'late-sale':
+      return emit('Register late sale kept outside its session', 'register.late-sale', { orderId: fact.orderId }, 'warn');
+  }
+}