@arcforgelabs/flow 2026.10.30 → 2026.10.32-beta.1

package/server/integrations/seazona/migrations/meta/_journal.json

@@ -22,6 +22,20 @@
       "when": 1792448378477,
       "tag": "0002_call_safety",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1792452091297,
+      "tag": "0003_call_guard",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1792453111948,
+      "tag": "0004_history_import",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/seazona/routes.js

@@ -0,0 +1,145 @@
+import express from 'express';
+import { FlowError } from '../../core/errors.js';
+import { listHistoryJobs, releaseHistoryJob } from '../../core/history.js';
+import { soleOrganisation } from '../../core/pipeline.js';
+import {
+  applyBatch,
+  cancelBatch,
+  decideJobs,
+  describeColumns,
+  historySummary,
+  listBatches,
+  readBatch,
+  reconcileBatch,
+  stageBatch,
+} from './history/index.js';
+import { readBackfill, startBackfill, stopBackfill } from './history/backfill.js';
+
+// The Seazona adapter's routes, mounted at /api/seazona (server/integrations/port.js).
+// The history import (docs/SEAZONA.md, "History import"):
+//
+//   GET  /history                         any signed-in person: totals and batches
+//   GET  /history/columns                 any signed-in person: the headers Flow reads
+//   POST /history/batches                 owner or admin: upload a CSV export
+//                                         (text/csv body, ?fileName=; or JSON
+//                                         { csv, fileName, columns })
+//   GET  /history/batches/:id?outcome=&limit=&offset=   any signed-in person
+//   POST /history/batches/:id/reconcile   owner or admin: match again
+//   POST /history/batches/:id/decisions   owner or admin: { decisions: [{ jobKey, decision, clientId? }] }
+//   POST /history/batches/:id/apply       owner or admin: write the batch into Flow's history
+//   POST /history/batches/:id/cancel      owner or admin
+//   POST /history/backfill                owner or admin: { from, through? } reads
+//                                         past orders from the Seazona API, a few a run
+//   POST /history/backfill/stop           owner or admin
+//   GET  /history/ledger?state=&limit=&offset=   any signed-in person: held
+//                                         history jobs by accounting state
+//                                         (state: one state, or needs_person)
+//   POST /history/ledger/:obligationId/release   owner or admin: the job may draft
+//
+// None of these call Seazona.
+
+export const MAX_UPLOAD = '25mb';
+
+function sendError(res, error, log) {
+  const status = error instanceof FlowError ? (error.status ?? 400) : 500;
+  if (status >= 500) log.error?.(`[seazona] history import: ${error.code ?? 'error'}: ${error.message}`);
+  const body = { ok: false, code: error.code ?? 'seazona_failed', error: status === 500 ? 'Something went wrong with the import.' : error.message };
+  if (error.details !== undefined) body.details = error.details;
+  return res.status(status).json(body);
+}
+
+const handle = (log, fn) => async (req, res) => {
+  try {
+    await fn(req, res);
+  } catch (error) {
+    sendError(res, error, log);
+  }
+};
+
+export function createSeazonaRouter({ db, personAuth, settings, log = console }) {
+  const router = express.Router();
+  // Sign-in off: every route answers 503, as the Xero routes do.
+  const signedIn = personAuth
+    ? [personAuth.requireSession]
+    : [(_req, res) => res.status(503).json({ ok: false, code: 'sign_in_not_configured', error: 'Sign-in is not configured on this installation (FLOW_AUTH is unset).' })];
+  const manager = personAuth ? [...signedIn, personAuth.requireRole('owner', 'admin')] : signedIn;
+  const actor = (req) => (req.person?.id ? `person:${req.person.id}` : 'person:unknown');
+  const json = express.json({ limit: MAX_UPLOAD });
+  const csv = express.text({ type: ['text/csv', 'text/plain', 'application/csv'], limit: MAX_UPLOAD });
+
+  if (!db) {
+    router.use((req, res) => res.status(503).json({ ok: false, code: 'no_database', error: 'Flow has no database' }));
+    return router;
+  }
+
+  router.get('/history', ...signedIn, handle(log, async (req, res) => {
+    res.json({ ok: true, history: await historySummary(db), backfill: await readBackfill(db), batches: await listBatches(db) });
+  }));
+
+  router.get('/history/columns', ...signedIn, (req, res) => res.json({ ok: true, profile: 'invoice_lines', columns: describeColumns() }));
+
+  router.post('/history/batches', ...manager, csv, json, handle(log, async (req, res) => {
+    const body = typeof req.body === 'string' ? { csv: req.body, fileName: req.query.fileName } : (req.body ?? {});
+    const batch = await stageBatch(db, {
+      csv: body.csv,
+      fileName: body.fileName ?? null,
+      columns: body.columns ?? {},
+      createdBy: actor(req),
+      keepPatientReference: Boolean(settings?.keepPatientReference),
+    });
+    log.info?.(`[seazona] history import: batch ${batch.id} ${batch.duplicate ? 'already staged' : 'staged'} by ${actor(req)}: ${JSON.stringify(batch.counts)}`);
+    res.status(batch.duplicate ? 200 : 201).json({ ok: true, batch });
+  }));
+
+  router.get('/history/batches/:id', ...signedIn, handle(log, async (req, res) => {
+    const { outcome = null, limit, offset } = req.query;
+    res.json({ ok: true, batch: await readBatch(db, req.params.id, { outcome: outcome || null, limit, offset }) });
+  }));
+
+  router.post('/history/batches/:id/reconcile', ...manager, handle(log, async (req, res) => {
+    res.json({ ok: true, batch: await reconcileBatch(db, req.params.id) });
+  }));
+
+  router.post('/history/batches/:id/decisions', ...manager, json, handle(log, async (req, res) => {
+    res.json({ ok: true, batch: await decideJobs(db, req.params.id, req.body?.decisions, { by: actor(req) }) });
+  }));
+
+  router.post('/history/batches/:id/apply', ...manager, handle(log, async (req, res) => {
+    const batch = await applyBatch(db, req.params.id, { by: actor(req) });
+    log.info?.(`[seazona] history import: batch ${batch.id} applied by ${actor(req)}: ${batch.applied} new, ${batch.updated} updated`);
+    res.json({ ok: true, batch });
+  }));
+
+  router.post('/history/batches/:id/cancel', ...manager, handle(log, async (req, res) => {
+    res.json({ ok: true, batch: await cancelBatch(db, req.params.id) });
+  }));
+
+  const organisation = async () => {
+    const id = await soleOrganisation(db);
+    if (!id) throw Object.assign(new FlowError('invalid', 'the installation needs exactly one organisation'), { status: 409 });
+    return id;
+  };
+
+  router.post('/history/backfill', ...manager, json, handle(log, async (req, res) => {
+    const backfill = await startBackfill(db, { from: req.body?.from, through: req.body?.through ?? null, createdBy: actor(req), settings });
+    log.info?.(`[seazona] history backfill from ${backfill.from} to ${backfill.through} started by ${actor(req)}`);
+    res.status(201).json({ ok: true, backfill });
+  }));
+
+  router.post('/history/backfill/stop', ...manager, handle(log, async (req, res) => {
+    res.json({ ok: true, backfill: await stopBackfill(db) });
+  }));
+
+  router.get('/history/ledger', ...signedIn, handle(log, async (req, res) => {
+    const { state = null, limit, offset } = req.query;
+    res.json({ ok: true, ...(await listHistoryJobs(db, await organisation(), { state: state || null, limit, offset })) });
+  }));
+
+  router.post('/history/ledger/:obligationId/release', ...manager, handle(log, async (req, res) => {
+    const row = await releaseHistoryJob(db, await organisation(), req.params.obligationId, { actor: actor(req) });
+    log.info?.(`[seazona] history import: job ${row.sourceJobRef} released by ${actor(req)}`);
+    res.json({ ok: true, job: { id: row.id, holdState: row.holdState } });
+  }));
+
+  return router;
+}

package/server/integrations/seazona/schema.js

@@ -21,6 +21,9 @@ export const seazonaApiGovernor = pgTable('seazona_api_governor', {
   circuitOpens: integer('circuit_opens').notNull().default(0),
   haltedReason: text('halted_reason'),
   haltedAt: at('halted_at'),
+  // The call guard's stopped resources (../call-guard.js). Seazona's guard
+  // halts on any 401 or 403, so this stays empty; the shared guard needs it.
+  stoppedResources: jsonb('stopped_resources').notNull().default({}),
   updatedAt: at('updated_at').notNull().defaultNow(),
 });
 
@@ -33,6 +36,7 @@ export const seazonaApiRequests = pgTable('seazona_api_requests', {
   clientKey: text('client_key').notNull(),
   workflow: text('workflow').notNull(),
   admittedAt: at('admitted_at').notNull(),
+  resource: text('resource'),
   requestPath: text('request_path'),
   statusCode: integer('status_code'),
   failureKind: text('failure_kind'),
@@ -177,3 +181,93 @@ export const seazonaRecordReadFailures = pgTable('seazona_record_read_failures',
 }, (t) => [
   primaryKey({ columns: [t.resource, t.recordKey] }),
 ]);
+
+// History import (docs/SEAZONA.md, "History import"). Seazona's own CSV
+// export brings in the years before the API sync started, with no API call.
+// A batch is one uploaded file. Its rows are kept as Flow read them (only the
+// columns Flow knows; never an unknown column, and no patient field unless
+// SEAZONA_KEEP_PATIENT_REFERENCE is on). Its jobs are the rows grouped into
+// work, each with what reconciliation found and what a person decided.
+// Applying a batch copies its jobs into `seazona_history_jobs`, Flow's own
+// record of past work. A batch is never deleted; a cancelled one stays.
+export const seazonaHistoryBatches = pgTable('seazona_history_batches', {
+  id: bigserial('id', { mode: 'number' }).primaryKey(),
+  fileName: text('file_name'),
+  // The file's sha256: the same file uploaded twice finds its first batch.
+  fileSha256: text('file_sha256').notNull(),
+  profile: text('profile').notNull(),
+  // Flow field -> the file's column header.
+  columns: jsonb('columns').notNull().default({}),
+  // Headers Flow does not know. Only the names are kept, never the values.
+  ignoredColumns: jsonb('ignored_columns').notNull().default([]),
+  // staged -> reconciled -> applied, or cancelled.
+  status: text('status').notNull(),
+  counts: jsonb('counts').notNull().default({}),
+  createdBy: text('created_by').notNull(),
+  createdAt: at('created_at').notNull().defaultNow(),
+  reconciledAt: at('reconciled_at'),
+  appliedAt: at('applied_at'),
+  appliedBy: text('applied_by'),
+}, (t) => [
+  index('seazona_history_batches_file').on(t.fileSha256),
+]);
+
+export const seazonaHistoryRows = pgTable('seazona_history_rows', {
+  batchId: bigint('batch_id', { mode: 'number' }).notNull(),
+  rowNumber: integer('row_number').notNull(),
+  jobKey: text('job_key'),
+  fields: jsonb('fields').notNull(),
+  // Why the row cannot be read, for example `missing_date`. Empty when fine.
+  problems: jsonb('problems').notNull().default([]),
+}, (t) => [
+  primaryKey({ columns: [t.batchId, t.rowNumber] }),
+]);
+
+export const seazonaHistoryBatchJobs = pgTable('seazona_history_batch_jobs', {
+  batchId: bigint('batch_id', { mode: 'number' }).notNull(),
+  jobKey: text('job_key').notNull(),
+  job: jsonb('job').notNull(),
+  recordHash: text('record_hash').notNull(),
+  // What reconciliation found: new, same, changed, needs_person.
+  outcome: text('outcome'),
+  // Each finding: { code, blocking, detail }.
+  findings: jsonb('findings').notNull().default([]),
+  // What Seazona's API copy holds for the same work, when Flow found it.
+  mirrorOrderId: text('mirror_order_id'),
+  mirrorInvoiceNumber: text('mirror_invoice_number'),
+  clientId: text('client_id'),
+  // A person's choice: import, skip, or null (follow the outcome).
+  decision: text('decision'),
+  decidedBy: text('decided_by'),
+  decidedAt: at('decided_at'),
+}, (t) => [
+  primaryKey({ columns: [t.batchId, t.jobKey] }),
+]);
+
+export const seazonaHistoryJobs = pgTable('seazona_history_jobs', {
+  jobKey: text('job_key').primaryKey(),
+  invoiceNumber: text('invoice_number'),
+  caseRef: text('case_ref'),
+  clientId: text('client_id'),
+  company: text('company'),
+  doctorName: text('doctor_name'),
+  status: text('status'),
+  jobDate: text('job_date'),
+  dueDate: text('due_date'),
+  shippedDate: text('shipped_date'),
+  lines: jsonb('lines').notNull().default([]),
+  subtotalCents: cents('subtotal_cents'),
+  totalCents: cents('total_cents'),
+  patientReference: text('patient_reference'),
+  mirrorOrderId: text('mirror_order_id'),
+  mirrorInvoiceNumber: text('mirror_invoice_number'),
+  recordHash: text('record_hash').notNull(),
+  // The batch that last wrote the row, and the first one.
+  batchId: bigint('batch_id', { mode: 'number' }).notNull(),
+  firstBatchId: bigint('first_batch_id', { mode: 'number' }).notNull(),
+  firstImportedAt: at('first_imported_at').notNull(),
+  lastChangedAt: at('last_changed_at').notNull(),
+}, (t) => [
+  index('seazona_history_jobs_invoice').on(t.invoiceNumber),
+  index('seazona_history_jobs_changed').on(t.lastChangedAt),
+]);

package/server/integrations/seazona/settings.js

@@ -99,19 +99,30 @@ export function resolveSeazonaSettings(env = process.env) {
       clients: { cadenceMs: ms('SEAZONA_CLIENT_CADENCE_MS', 30 * MINUTE, MINUTE, DAY_MS), freshnessMs: 60 * MINUTE },
       products: { cadenceMs: ms('SEAZONA_REFERENCE_CADENCE_MS', DAY_MS, MINUTE, 30 * DAY_MS), freshnessMs: 2 * DAY_MS },
       users: { cadenceMs: ms('SEAZONA_REFERENCE_CADENCE_MS', DAY_MS, MINUTE, 30 * DAY_MS), freshnessMs: 2 * DAY_MS },
+      // The history backfill (docs/SEAZONA.md, "History import"). It calls
+      // Seazona only while a person has started one.
+      history: { cadenceMs: ms('SEAZONA_HISTORY_CADENCE_MS', 2 * MINUTE, MINUTE, DAY_MS), freshnessMs: 30 * DAY_MS },
     },
+    // Calls the history backfill makes per run, at most: a small share of
+    // the rate limit, so the live lanes always have room.
+    historyCallsPerRun: clampInt(env.SEAZONA_HISTORY_CALLS_PER_RUN, 10, 1, 25),
+    historyPageSize: clampInt(env.SEAZONA_HISTORY_PAGE_SIZE, 500, 1, 500),
     // Re-read this much before a lastModified cursor, so a change written
     // while the last run was reading is not missed.
     cursorOverlapMs: 5 * MINUTE,
     // The recent-order lane reads orders placed in the last N days, a few
-    // days per run (GET orders/?ordered= matches one UTC day).
+    // days per run, page by page (GET orders/?ordered=&page=&pageSize=).
     orderLookbackDays: clampInt(env.SEAZONA_ORDER_LOOKBACK_DAYS, 30, 1, 3650),
     orderDaysPerRun: clampInt(env.SEAZONA_ORDER_DAYS_PER_RUN, 6, 1, 31),
     // The first invoice run reads from the start of today (UTC) minus this.
     invoiceLookbackDays: clampInt(env.SEAZONA_INVOICE_LOOKBACK_DAYS, 0, 0, 3650),
-    // Seazona documents no paging. A list exactly this long may be cut off,
-    // so the lane holds its cursor instead of trusting it.
+    // A list this long may be cut off, so the lane reads on (issue #125):
+    // the next part of a changed list from its last row, the next order
+    // page. Also the order page size (at most 500).
     listCap: clampInt(env.SEAZONA_LIST_CAP, 50, 1, 10_000),
+    // A lane makes at most this many list calls a run; the next run goes on
+    // from where it stopped.
+    listPagesPerRun: clampInt(env.SEAZONA_LIST_PAGES_PER_RUN, 10, 1, 100),
     // The active-order lane re-reads this many open orders per run, oldest first.
     activeOrdersPerRun: clampInt(env.SEAZONA_ACTIVE_ORDERS_PER_RUN, 25, 1, 500),
     // Issue #12: after this many failed reads in a row an order waits this long.

package/server/integrations/seazona/sync-once.js

@@ -6,7 +6,7 @@
 //   DATABASE_URL=postgres://… FLOW_INTEGRATIONS=seazona SEAZONA_MODE=sandbox … \
 //     node server/integrations/seazona/sync-once.js [lane …]
 //
-// Lanes: invoices, orders_recent, orders_active, clients, products, users.
+// Lanes: invoices, orders_recent, orders_active, clients, products, users, history.
 // None named: all of them.
 import { openDatabase } from '../../db/index.js';
 import { resolveEnabledIntegrations } from '../index.js';

package/server/integrations/seazona/tables.js

@@ -14,5 +14,9 @@ export const seazonaSchema = Object.freeze({
     'seazona_lane_state',
     'seazona_order_read_failures',
     'seazona_record_read_failures',
+    'seazona_history_batches',
+    'seazona_history_rows',
+    'seazona_history_batch_jobs',
+    'seazona_history_jobs',
   ]),
 });

package/server/integrations/xero/client.js

@@ -2,9 +2,11 @@ import { FlowError } from '../../core/errors.js';
 import { XERO_ENDPOINTS } from './settings.js';
 
 // The Xero Accounting API client. Every call goes through the rate-limit
-// governor (governor.js). A 429 is retried after the wait Xero asks for,
-// except a DayLimit 429, which opens the circuit and fails fast. Tokens are
-// sent only in the Authorization header and never logged or put in errors.
+// governor (governor.js) and, when one is given, the call guard
+// (../call-guard.js): a call the guard has stopped fails at once, and every
+// call's ending is recorded there. A 429 is retried after the wait Xero asks
+// for, except a DayLimit 429, which opens the circuit and fails fast. Tokens
+// are sent only in the Authorization header and never logged or put in errors.
 
 export const DEFAULT_TIMEOUT_MS = 15_000;
 export const DEFAULT_ATTEMPTS = 2;
@@ -86,6 +88,14 @@ function quote(value) {
 
 const first = (list) => (Array.isArray(list) && list.length ? list[0] : null);
 
+// The resource a call reads or writes, for the call guard: the first path
+// segment (Invoices, Payments, Contacts). A 401 or 403 that a fresh token
+// does not clear stops that resource only, so a scope the connection lacks
+// (for example payments) does not stop the rest.
+export function resourceOf(path) {
+  return String(path).replace(/^\/+/, '').split(/[/?#]/)[0] || null;
+}
+
 // `accessToken()` returns a current access token; `invalidateAccessToken()`
 // drops a cached one after Xero answers 401, and the request is tried once
 // more with a fresh token.
@@ -95,6 +105,7 @@ export function createXeroClient({
   invalidateAccessToken = () => {},
   fetch: fetchImpl = globalThis.fetch,
   governor,
+  guard = null,
   apiBase = XERO_ENDPOINTS.api,
   timeoutMs = DEFAULT_TIMEOUT_MS,
   attempts = DEFAULT_ATTEMPTS,
@@ -106,10 +117,12 @@ export function createXeroClient({
   const base = apiBase.endsWith('/') ? apiBase : `${apiBase}/`;
   let lastRateLimit = null;
 
-  async function send(method, url, headers, bodyText) {
+  // `call` is { resource, path } for the guard.
+  async function send(method, url, headers, bodyText, call) {
     await governor.acquire(tenantId);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const startedAt = Date.now();
     try {
       let response;
       try {
@@ -117,6 +130,7 @@ export function createXeroClient({
       } catch (error) {
         if (error?.code === 'xero_replay_no_match') throw error;
         const timedOut = error?.name === 'AbortError';
+        await guard?.record(tenantId, { ...call, failureKind: timedOut ? 'timeout' : 'network', durationMs: Date.now() - startedAt });
         throw xeroError(timedOut ? 'xero_timeout' : 'xero_unreachable',
           timedOut ? `Xero did not answer within ${timeoutMs} ms.` : 'Flow could not reach Xero.',
           { status: timedOut ? 504 : 503 });
@@ -124,7 +138,7 @@ export function createXeroClient({
       const text = await response.text().catch(() => '');
       lastRateLimit = readRateLimitHeaders(response);
       governor.observe(tenantId, lastRateLimit);
-      return { response, text };
+      return { response, text, durationMs: Date.now() - startedAt };
     } finally {
       clearTimeout(timer);
       governor.release(tenantId);
@@ -139,8 +153,10 @@ export function createXeroClient({
     // Serialised once, so a retry sends the same bytes under the same
     // Idempotency-Key.
     const bodyText = body === undefined ? undefined : JSON.stringify(body);
+    const call = { resource: resourceOf(path), path: url.pathname };
     let refreshed = false;
     for (let attempt = 1; ; attempt += 1) {
+      await guard?.check(tenantId, { resource: call.resource });
       const headers = {
         ...extra,
         Authorization: `Bearer ${await accessToken()}`,
@@ -148,12 +164,16 @@ export function createXeroClient({
         'xero-tenant-id': tenantId,
         ...(bodyText === undefined ? {} : { 'Content-Type': 'application/json' }),
       };
-      const { response, text } = await send(method, url, headers, bodyText);
+      const { response, text, durationMs } = await send(method, url, headers, bodyText, call);
       const payload = parseJson(text);
+      // A first 401 usually means the access token expired: it is not counted,
+      // and the call is tried once more with a fresh token.
+      const expiredToken = response.status === 401 && !refreshed;
+      if (!expiredToken) await guard?.record(tenantId, { ...call, statusCode: response.status, durationMs });
       if (response.ok) return payload ?? {};
 
       const error = apiError(response, payload);
-      if (response.status === 401 && !refreshed) {
+      if (expiredToken) {
         refreshed = true;
         invalidateAccessToken();
         attempt -= 1;

package/server/integrations/xero/drafts.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { and, eq, inArray, sql } from 'drizzle-orm';
+import { isCallsStopped } from '../call-guard.js';
 import { getInvoice, listInvoiceVersions } from '../../core/invoices.js';
 import { sendModeFor } from '../../core/invoicing-rules.js';
 import { contacts as flowContacts, invoices as flowInvoices, priceItems } from '../../db/schema.js';
@@ -206,6 +207,38 @@ export async function listPushes(db, organisationId, invoiceId) {
   return rows.map(mapPush);
 }
 
+// What the customer's Xero copy of one Flow invoice version says, from Flow's
+// copy of Xero (no calls): the stored push, and the mirror row when the
+// mirror has it. Before the version is in Xero, only who numbers it and the
+// default due days are known.
+export async function documentFacts(db, runtime, { organisationId, invoiceId, version = null }) {
+  const { settings } = runtime;
+  const facts = { system: 'Xero', sent: false, numberedBy: settings.invoiceNumber, defaultDueDays: settings.defaultDueDays };
+  if (!version) return facts;
+  const { rows: [push] } = await db.execute(sql`select xero_invoice_id, xero_invoice_number, xero_status, request_body
+    from xero_invoice_pushes
+    where organisation_id = ${organisationId} and invoice_id = ${invoiceId} and version = ${version} and xero_invoice_id is not null`);
+  if (!push) return facts;
+  const { rows: [copy] } = await db.execute(sql`select invoice_number, reference, status,
+      to_char(issued_on, 'YYYY-MM-DD') as issued_on, to_char(due_on, 'YYYY-MM-DD') as due_on
+    from xero_invoices where organisation_id = ${organisationId} and xero_invoice_id = ${push.xero_invoice_id}`);
+  let sent = {};
+  try {
+    sent = JSON.parse(push.request_body) ?? {};
+  } catch {
+    // An unreadable body leaves only the mirror and the push's own columns.
+  }
+  return {
+    ...facts,
+    sent: true,
+    number: copy?.invoice_number || push.xero_invoice_number || sent.InvoiceNumber || null,
+    reference: copy?.reference || sent.Reference || null,
+    issueDate: copy?.issued_on || sent.Date || null,
+    dueDate: copy?.due_on || sent.DueDate || null,
+    status: copy?.status || push.xero_status || null,
+  };
+}
+
 async function settle(db, id, fields) {
   const { rows } = await db.execute(sql`update xero_invoice_pushes set
       state = ${fields.state},
@@ -313,7 +346,7 @@ export async function pushDrafts(db, runtime, organisationId, invoiceIds, { push
       try {
         results.push(await pushOne(db, runtime, client, organisationId, invoiceId, { pushedBy, allowExisting: allowed.has(invoiceId) }));
       } catch (error) {
-        if (error.code === 'xero_rate_limited' || error.code === 'xero_reconnect_needed') {
+        if (stopsTheBatch(error)) {
           // Every later invoice would fail the same way: stop and say so.
           results.push(failed(invoiceId, error));
           for (const rest of invoiceIds.slice(invoiceIds.indexOf(invoiceId) + 1)) results.push(failed(rest, error, 'not_tried'));
@@ -392,9 +425,13 @@ async function assertTracking(client, tracking) {
   }
 }
 
-// Xero errors that prove no invoice was made: Xero refused the request.
+// Errors after which every later call would fail the same way: stop the batch.
+const stopsTheBatch = (error) => error.code === 'xero_rate_limited' || error.code === 'xero_reconnect_needed' || isCallsStopped(error);
+
+// Xero errors that prove no invoice was made: Xero refused the request, or
+// the call guard stopped it before it went.
 function provesNothingCreated(error) {
-  return error.code === 'xero_validation_failed' || error.code === 'xero_rate_limited'
+  return isCallsStopped(error) || error.code === 'xero_validation_failed' || error.code === 'xero_rate_limited'
     || error.code === 'xero_unauthorized' || error.code === 'xero_reconnect_needed'
     || (error.code === 'xero_api_error' && error.status >= 400 && error.status < 500);
 }
@@ -509,7 +546,7 @@ async function dispatch(db, client, push, document, { fresh = false } = {}) {
       throw error;
     }
     await settle(db, push.id, { state: 'ambiguous', errorCode: error.code ?? 'xero_uncertain', errorMessage: error.message });
-    if (error.code === 'xero_rate_limited' || error.code === 'xero_reconnect_needed') throw error;
+    if (stopsTheBatch(error)) throw error;
     return {
       invoiceId: push.invoiceId,
       version: push.version,
@@ -555,8 +592,9 @@ async function verify(db, client, push, draft, document, created, outcome) {
 // ---------------------------------------------------------------------------
 // Email
 
-// Xero errors that prove it sent no email: it refused the request.
-const emailRefused = (error) => error.code === 'xero_validation_failed'
+// Xero errors that prove it sent no email: it refused the request, or the
+// call guard stopped it before it went.
+const emailRefused = (error) => isCallsStopped(error) || error.code === 'xero_validation_failed'
   || (error.code === 'xero_api_error' && error.status >= 400 && error.status < 500);
 
 // Asks Xero to email an approved invoice that Flow sent and checked, once.
@@ -576,7 +614,7 @@ async function emailIfDue(db, client, push) {
       ? `Xero did not email the invoice: ${error.message}`
       : 'Flow does not know whether Xero emailed the invoice. Check the invoice in Xero before you send it again.';
     await db.execute(sql`update xero_invoice_pushes set email_state = ${state}, email_error = ${message}, updated_at = now() where id = ${push.id}`);
-    if (error.code === 'xero_rate_limited' || error.code === 'xero_reconnect_needed') throw error;
+    if (stopsTheBatch(error)) throw error;
     return { state, error: message, at: null };
   }
   const { rows: [done] } = await db.execute(sql`update xero_invoice_pushes set email_state = 'sent', email_error = null, emailed_at = now(), updated_at = now()
@@ -613,7 +651,7 @@ async function resume(db, runtime, client, push, document) {
       .filter((inv) => !GONE.has(inv.Status) && !push.preExistingIds.includes(inv.InvoiceID)
         && differences(inv, draft, document).filter((d) => d !== 'date').length === 0);
   } catch (error) {
-    if (error.code === 'xero_rate_limited') throw error;
+    if (error.code === 'xero_rate_limited' || isCallsStopped(error)) throw error;
     return { invoiceId: push.invoiceId, version: push.version, outcome: 'ambiguous', error: { code: 'xero_outcome_unknown', message: 'Flow could not look in Xero to settle an earlier attempt. Send again later.' } };
   }
   if (candidates.length === 1) return verify(db, client, push, draft, document, candidates[0], 'reconciled');