@arcforgelabs/flow 2026.10.46 → 2026.10.48

package/server/core/invoices.js

@@ -1,5 +1,5 @@
 import { and, asc, desc, eq, sql } from 'drizzle-orm';
-import { contacts, invoiceLines, invoices, invoiceVersions, organisations, priceItems } from '../db/schema.js';
+import { billingObligations, contacts, invoiceLines, invoices, invoiceVersions, obligationEvents, organisations, priceItems } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 import { invoiceTotals, lineTotals } from './money.js';
 
@@ -7,6 +7,11 @@ import { invoiceTotals, lineTotals } from './money.js';
 // invoice its number and stores the document exactly as sent, as a new
 // version. To change an issued invoice, revise it back to a draft and issue
 // it again: the number stays and the earlier versions stay as they were.
+// A draft that was never issued can be deleted. An issued invoice is voided.
+// When its accounting copy is still a draft, deleteDraft asks the accounting
+// adapter to delete it there first, and voids in Flow only after the adapter
+// confirms (docs/XERO.md, "Deleting a draft"). With no accounting system, an
+// issued invoice answers accounting_unavailable.
 
 async function loadInvoice(tx, organisationId, invoiceId, { lock = false } = {}) {
   let query = tx.select().from(invoices)
@@ -182,6 +187,93 @@ export async function voidInvoice(db, organisationId, invoiceId) {
   });
 }
 
+// The job an invoice billed is free again: its obligation no longer points at
+// the invoice, so the lab's rules decide whether Flow drafts it once more.
+async function freeJobs(tx, organisationId, invoice, actor) {
+  const linked = await tx.select().from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoice.id)))
+    .for('update');
+  if (linked.length && !actor) throw new FlowError('invalid', 'actor is required');
+  for (const obligation of linked) {
+    await tx.update(billingObligations)
+      .set({ invoiceId: null, draftBasis: null, updatedAt: sql`now()` })
+      .where(eq(billingObligations.id, obligation.id));
+    await tx.insert(obligationEvents).values({
+      createdAt: sql`clock_timestamp()`,
+      organisationId,
+      obligationId: obligation.id,
+      kind: 'draft_deleted',
+      actor,
+      evidence: { invoiceId: invoice.id },
+    });
+  }
+}
+
+// Same words as the Send gate (server/core/sending.js): writes that are off,
+// or a system that is not connected, stop before anything changes. An issued
+// invoice with no accounting delete answers accounting_unavailable.
+async function deleteInAccounting(accounting, organisationId, invoiceId, actor) {
+  if (!accounting || typeof accounting.capabilities?.deleteInvoice !== 'function') {
+    throw new FlowError('accounting_unavailable', 'No accounting system is connected. An issued invoice stays as it is.');
+  }
+  const status = typeof accounting.capabilities.sendStatus === 'function'
+    ? await accounting.capabilities.sendStatus({ organisationId })
+    : { connected: false, writesAllowed: false };
+  if (!status?.connected) {
+    throw new FlowError('accounting_not_connected', `${accounting.name} is not connected. Connect it in Integrations, then send.`);
+  }
+  if (!status.writesAllowed) {
+    throw new FlowError('accounting_writes_off', `${accounting.name} does not take invoices from this installation yet (writes are off). Nothing was issued.`);
+  }
+  const answer = await accounting.capabilities.deleteInvoice({ organisationId, invoiceId, actor });
+  if (answer?.state === 'approved') {
+    throw new FlowError('accounting_approved', answer.message || 'Approved in the accounting system. Void it there first.');
+  }
+  if (answer?.state === 'deleted' || answer?.state === 'gone') return answer;
+  throw new FlowError('accounting_unavailable', answer?.message || 'The accounting system cannot delete this invoice. Nothing was changed.');
+}
+
+// Removes a draft that was never issued, and frees its job. An invoice that
+// was issued is voided only after its accounting adapter deletes the draft
+// there, or reports it already gone. The issued versions stay. With no
+// accounting delete, or when the accounting invoice is approved or paid,
+// nothing in Flow changes.
+export async function deleteDraft(db, organisationId, invoiceId, { actor = null, accounting = null } = {}) {
+  const current = await loadInvoice(db, organisationId, invoiceId);
+  if (current.status === 'void') throw new FlowError('conflict', 'a void invoice is final');
+  if (current.status === 'draft' && current.issuedVersion === 0) {
+    return db.transaction(async (tx) => {
+      const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
+      if (invoice.status !== 'draft' || invoice.issuedVersion !== 0) {
+        throw new FlowError('was_issued', 'an invoice that was issued cannot be deleted; void it');
+      }
+      await freeJobs(tx, organisationId, invoice, actor);
+      try {
+        await tx.delete(invoices).where(eq(invoices.id, invoice.id));
+      } catch (error) {
+        const code = error?.code ?? error?.cause?.code;
+        if (code === '23503') throw new FlowError('conflict', 'this draft is still linked; remove the link, then delete it');
+        throw error;
+      }
+      return invoice;
+    });
+  }
+  // Read and delete outside the Flow transaction. A timeout or a refusal
+  // throws here, and the invoice stays as it was. The next try reads again.
+  await deleteInAccounting(accounting, organisationId, invoiceId, actor);
+  return db.transaction(async (tx) => {
+    const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
+    if (invoice.status === 'void') return invoice;
+    if (invoice.issuedVersion === 0) {
+      throw new FlowError('was_issued', 'an invoice that was issued cannot be deleted; void it');
+    }
+    const [row] = await tx.update(invoices).set({ status: 'void', updatedAt: sql`now()` })
+      .where(eq(invoices.id, invoice.id)).returning();
+    await freeJobs(tx, organisationId, row, actor);
+    return row;
+  });
+}
+
 export async function getInvoice(db, organisationId, invoiceId) {
   const invoice = await loadInvoice(db, organisationId, invoiceId);
   const lines = await db.select().from(invoiceLines)

package/server/core/invoicing-rules.js

@@ -150,6 +150,16 @@ export async function customerBillingByContact(db, organisationId, contactIds) {
   return new Map(rows.map((r) => [r.contactId, pick(r, CUSTOMER_KEYS)]));
 }
 
+// The customers' names, by contact id. Customer "contains" reads the name
+// (invoice-rules.js), not the contact id the menu tests use.
+async function customerNames(db, organisationId, contactIds) {
+  const ids = [...new Set(contactIds.filter(Boolean))];
+  if (!ids.length) return new Map();
+  const rows = await db.select({ id: contacts.id, name: contacts.name }).from(contacts)
+    .where(and(eq(contacts.organisationId, organisationId), inArray(contacts.id, ids)));
+  return new Map(rows.map((r) => [r.id, r.name]));
+}
+
 // The settings that apply to one customer: its own, else the organisation's.
 // `autoDraft` is the customer's own switch for the draft automation.
 export function effectiveSettings(settings, customer = CUSTOMER_DEFAULTS) {
@@ -255,13 +265,16 @@ export async function autoDraftJobs(db, organisationId, { accounting = null, wor
     sql`${billingObligations.contactId} is not null`,
     // Newest first: a backlog of jobs that wait on a rule never hides new work.
   )).orderBy(sql`${billingObligations.jobDate} desc nulls last`, billingObligations.id).limit(limit);
-  const customers = await customerBillingByContact(db, organisationId, candidates.map((o) => o.contactId));
+  const contactIds = candidates.map((o) => o.contactId);
+  const customers = await customerBillingByContact(db, organisationId, contactIds);
+  const names = await customerNames(db, organisationId, contactIds);
+  const named = (contactId) => ({ ...effectiveSettings(settings, customers.get(contactId)), name: names.get(contactId) ?? null });
   const liveCheck = accounting ? copyCheck(accounting, organisationId) : null;
   const invoiceDate = isoDay(now);
   let accountingRead = null;
 
   for (const candidate of candidates) {
-    let effective = effectiveSettings(settings, customers.get(candidate.contactId));
+    let effective = named(candidate.contactId);
     if (!effective.autoDraft) {
       result.off += 1;
       continue;
@@ -302,7 +315,11 @@ export async function autoDraftJobs(db, organisationId, { accounting = null, wor
       }
     }
     if (obligation !== candidate) {
-      effective = effectiveSettings(settings, customers.get(obligation.contactId));
+      if (obligation.contactId && !names.has(obligation.contactId)) {
+        const extra = await customerNames(db, organisationId, [obligation.contactId]);
+        for (const [id, name] of extra) names.set(id, name);
+      }
+      effective = named(obligation.contactId);
       if (!effective.autoDraft || ruleBlockers(obligation, effective, { now, rules }).length) {
         result.waiting += 1;
         continue;

package/server/core/job-board.js

@@ -55,7 +55,7 @@ export async function describeObligations(db, organisationId, listed, { accounti
   // The invoicing rules a job with no invoice waits on, for every view a
   // draft can still come from.
   const waitingFor = (o, v) => (o.invoiceId || !['in_work', 'ready', 'pending', 'held'].includes(v)
-    ? [] : ruleBlockers(o, effectiveSettings(settings, customers.get(o.contactId)), { rules }));
+    ? [] : ruleBlockers(o, { ...effectiveSettings(settings, customers.get(o.contactId)), name: nameOf.get(o.contactId) ?? null }, { rules }));
   return listed.map(({ obligation: { lineFingerprint: _fingerprint, organisationId: _org, draftBasis: _basis, ...o }, view, reasons }) => ({
     ...o,
     canUseNewLines: offers.has(o.id),

package/server/core/sending.js

@@ -1,8 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
-import { billingObligations, invoiceLines, invoices } from '../db/schema.js';
+import { billingObligations, contacts, invoiceLines, invoices } from '../db/schema.js';
 import { FlowError } from './errors.js';
-import { listRules, rulePending } from './invoice-rules.js';
+import { listRules, rulePending, ruleSkip } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings } from './invoicing-rules.js';
 import { issueInvoice } from './invoices.js';
 import { CHANGED_REASON, diffJobLines, STATUS_BACK_REASON } from './ledger.js';
@@ -17,7 +17,9 @@ import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 // charge, an account) on every line. When an accounting
 // system is connected, its own checks are added (for Xero: the customer
 // matches one Xero contact, every item is in Xero), and the lab's pending
-// rules (invoice-rules.js) add their notes. A draft with a problem is
+// rules (invoice-rules.js) add their notes. An enabled skip rule does too:
+// a draft whose job it matches stays Pending, even when the draft was made
+// by hand or before the rule existed. A draft with a problem is
 // Pending (the "problem" view). A draft without one is Ready.
 //
 // Send all ready issues every ready draft (each gets its number) and, when an
@@ -35,6 +37,13 @@ export const CHECK_LIMIT = 500;
 const WORKER_BATCH = 25;
 const WORKER_EVERY_MS = 30 * 1000;
 const LEASE_MS = 15 * 60 * 1000;
+// One error report names this many refused invoices. The count still says
+// how many the accounting system refused.
+const REFUSAL_REPORT_CAP = 5;
+const REFUSAL_MESSAGE_LIMIT = 160;
+const INVOICE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const INVOICE_NUMBER = /^[A-Za-z0-9-]{1,32}$/;
+const REFUSAL_CODE = /^[a-z0-9_]{1,64}$/i;
 // Outcomes that mean the accounting system holds the invoice.
 const SENT = new Set(['created', 'reconciled', 'existing', 'already_in_xero']);
 
@@ -81,19 +90,21 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
     const found = draftProblems(draft, linesOf.get(draft.id) ?? []);
     if (found.length) problems.set(draft.id, found);
   }
-  const jobs = await db.select({ obligation: billingObligations, reference: invoices.reference }).from(billingObligations)
+  const jobs = await db.select({ obligation: billingObligations, reference: invoices.reference, customerName: contacts.name }).from(billingObligations)
     .innerJoin(invoices, eq(invoices.id, billingObligations.invoiceId))
+    .leftJoin(contacts, and(eq(contacts.id, billingObligations.contactId), eq(contacts.organisationId, billingObligations.organisationId)))
     .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, ids)));
-  // The lab's pending rules (invoice-rules.js): a draft from a job that
-  // matches one waits on Pending with the rule's note, such as a Reference
-  // with no real practitioner.
-  const rules = (await listRules(db, organisationId)).filter((r) => r.enabled && r.action.kind === 'pending');
+  // The lab's rules (invoice-rules.js). A pending rule puts its note on the
+  // draft. A skip rule holds a draft that already exists: void it, or change
+  // the rule. Matching stays in invoice-rules.js.
+  const rules = (await listRules(db, organisationId)).filter((r) => r.enabled && (r.action.kind === 'pending' || r.action.kind === 'skip'));
   if (rules.length && jobs.length) {
     const settings = await readInvoicingSettings(db, organisationId);
     const customers = await customerBillingByContact(db, organisationId, jobs.map((j) => j.obligation.contactId));
-    for (const { obligation, reference } of jobs) {
-      const customer = effectiveSettings(settings, customers.get(obligation.contactId));
-      const found = rulePending(rules, { ...obligation, reference }, { customer });
+    for (const { obligation, reference, customerName } of jobs) {
+      const customer = { ...effectiveSettings(settings, customers.get(obligation.contactId)), name: customerName ?? null };
+      const job = { ...obligation, reference };
+      const found = [...rulePending(rules, job, { customer }), ...ruleSkip(rules, job, { customer })];
       if (found.length) problems.set(obligation.invoiceId, [...(problems.get(obligation.invoiceId) ?? []), ...found]);
     }
   }
@@ -196,23 +207,61 @@ async function assertCanSend(accounting, organisationId) {
 // Read before act (issue #141): the jobs behind these drafts whose work
 // system report is old are read again first. Answers the drafts that may go
 // now; a draft whose job went to review, or could not be read, waits.
+// `stops` names each held draft: `unread` (read failed or past the cap) or
+// `review` (the job changed).
 async function readJobsFirst(db, organisationId, invoiceIds, { work, now, personId }) {
-  if (!invoiceIds.length || typeof work?.capabilities?.readWorkItem !== 'function') return { go: invoiceIds, waiting: [] };
+  if (!invoiceIds.length || typeof work?.capabilities?.readWorkItem !== 'function') {
+    return { go: invoiceIds, waiting: [], stops: [] };
+  }
   const jobs = await db.select().from(billingObligations)
     .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, invoiceIds)));
   const old = jobs.filter((job) => needsRead(job, { work, now }));
   const outcomes = await readBeforeAct(db, organisationId, old.slice(0, READS_PER_PASS), { work, now, actor: `person:${personId}` });
-  const held = new Set(old.slice(READS_PER_PASS).map((job) => job.invoiceId));
+  const held = new Set();
+  const stops = [];
+  for (const job of old.slice(READS_PER_PASS)) {
+    held.add(job.invoiceId);
+    stops.push({ invoiceId: job.invoiceId, kind: 'deferred' });
+  }
   for (const { outcome, obligation } of outcomes.values()) {
-    if (outcome === 'waiting' || outcome === 'review') held.add(obligation.invoiceId);
+    if (outcome === 'waiting') {
+      held.add(obligation.invoiceId);
+      stops.push({ invoiceId: obligation.invoiceId, kind: 'unread' });
+    } else if (outcome === 'review') {
+      held.add(obligation.invoiceId);
+      stops.push({ invoiceId: obligation.invoiceId, kind: 'review' });
+    }
+  }
+  return { go: invoiceIds.filter((id) => !held.has(id)), waiting: invoiceIds.filter((id) => held.has(id)), stops };
+}
+
+// The error when a ticked press sends nothing: name the cause (and the count
+// for jobs), never one shared sentence.
+function stoppedSendMessage({ accountingWaiting, accountingReason, stops, waiting }) {
+  if (accountingWaiting) {
+    if (accountingReason && /more changes than one read takes/i.test(accountingReason)) {
+      return 'The accounting copy has more changes than one read takes. Nothing was sent.';
+    }
+    if (accountingReason) return `${accountingReason.replace(/\.?$/, '')}. Nothing was sent.`;
+    return 'The accounting copy could not be read. Nothing was sent.';
+  }
+  const unread = stops.filter((stop) => stop.kind === 'unread').length;
+  const reviews = stops.filter((stop) => stop.kind === 'review').length;
+  if (unread) {
+    return `${unread} ${unread === 1 ? 'job' : 'jobs'} could not be read from the work system. Nothing was sent.`;
+  }
+  if (reviews) {
+    return `${reviews} ${reviews === 1 ? 'job' : 'jobs'} changed and ${reviews === 1 ? 'needs' : 'need'} a look. Nothing was sent.`;
   }
-  return { go: invoiceIds.filter((id) => !held.has(id)), waiting: invoiceIds.filter((id) => held.has(id)) };
+  const n = waiting.length || 1;
+  return `${n} ${n === 1 ? 'job' : 'jobs'} could not be confirmed with the work system. Nothing was sent.`;
 }
 
 // Send all ready: issues each ready draft, then queues it for the accounting
-// system. With `invoiceIds`, only those drafts, and each must be ready (the
-// Send button on one invoice). `work` is the work integration, for the read
-// before act. Answers { issued, queued, remaining, waiting }.
+// system. With `invoiceIds`, only those drafts. One id (the invoice page) is
+// all or nothing. More than one id (the bulk bar) sends the ones Flow could
+// confirm and leaves the rest. `work` is the work integration, for the read
+// before act. Answers { issued, queued, remaining, waiting, held }.
 export async function sendAllReady(db, organisationId, { accounting = null, work = null, personId, issueDate, invoiceIds = null, now = new Date() }) {
   await assertCanSend(accounting, organisationId);
   // Issue #45: the accounting copy reads its latest changes first, so the
@@ -236,11 +285,23 @@ export async function sendAllReady(db, organisationId, { accounting = null, work
         : 'Only a ready invoice can be sent. Mark it ready first.');
     }
   }
-  const { go, waiting } = accountingRead.outcome === 'waiting'
-    ? { go: [], waiting: ready.slice(0, SEND_BATCH) }
+  const accountingWaiting = accountingRead.outcome === 'waiting';
+  const { go, waiting, stops } = accountingWaiting
+    ? { go: [], waiting: ready.slice(0, SEND_BATCH), stops: [] }
     : await readJobsFirst(db, organisationId, ready.slice(0, SEND_BATCH), { work, now, personId });
-  if (invoiceIds && waiting.length) {
-    throw new FlowError('not_ready', 'Flow could not confirm the job with the work system or the accounting system just now, or the job changed. Nothing was sent. Look at the invoice, then try again.');
+  // One invoice (the invoice page) is all or nothing: a job Flow could not
+  // confirm stops the send. A bulk press sends the ones it confirmed. The
+  // rest stay for the next press (`waiting`), or on Pending when the read
+  // sent the job to review. An accounting read that cannot run still stops
+  // every ticked invoice: that one read covers the whole press. When nothing
+  // can go, the error names the cause and the count.
+  if (invoiceIds && waiting.length && go.length === 0) {
+    throw new FlowError('not_ready', stoppedSendMessage({
+      accountingWaiting,
+      accountingReason: accountingRead.reason,
+      stops,
+      waiting,
+    }));
   }
   const batch = go;
   let issued = 0;
@@ -285,14 +346,65 @@ function unqueue(db, organisationId, invoiceId) {
     .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId), eq(invoices.status, 'draft')));
 }
 
+// The short refusal message for an error report. An email address is dropped,
+// and so is a double-quoted name: Flow's own messages put a customer name in
+// quotes. Single quotes stay, because the accounting system quotes an account
+// code that way. The invoice's own problem, shown to a person, keeps the
+// full message.
+function refusalMessage(message) {
+  let text = String(message ?? '')
+    .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '')
+    .replace(/"[^"\n]{0,240}"/g, '')
+    .replace(/\s+/g, ' ')
+    .replace(/\s+([.,;:])/g, '$1')
+    .trim();
+  // Dropping the address and the quoted name can leave an empty "See for."
+  text = text.replace(/(?:^|\.\s*)See for\.$/i, (match) => (match.startsWith('.') ? '.' : '')).trim();
+  return text.slice(0, REFUSAL_MESSAGE_LIMIT);
+}
+
+// One refused invoice, as the error report may name it. Anything that is not
+// an id, a number or a code is left out.
+function refusalFact(row, error) {
+  const invoiceId = INVOICE_ID.test(row?.id ?? '') ? row.id : null;
+  if (!invoiceId) return null;
+  const number = INVOICE_NUMBER.test(row?.number ?? '') ? row.number : null;
+  const code = REFUSAL_CODE.test(error?.code ?? '') ? error.code : 'send_failed';
+  const message = refusalMessage(error?.message);
+  return { invoiceId, ...(number ? { number } : {}), code, ...(message ? { message } : {}) };
+}
+
+function formatRefusal(item) {
+  const fact = refusalFact(
+    { id: item?.invoiceId, number: item?.number },
+    { code: item?.code, message: item?.message },
+  );
+  if (!fact) return null;
+  const who = fact.number ? `${fact.number} (${fact.invoiceId})` : fact.invoiceId;
+  return fact.message ? `${who} ${fact.code}: ${fact.message}` : `${who} ${fact.code}`;
+}
+
+// The line the error service gets when the accounting system refuses invoices.
+// `result` is the send pass summary (`failed`, `refusals`).
+export function refusalReport(result) {
+  const refusals = Array.isArray(result?.refusals) ? result.refusals : [];
+  const count = Number.isInteger(result?.failed) && result.failed > 0 ? result.failed : refusals.length;
+  const shown = refusals.slice(0, REFUSAL_REPORT_CAP).map(formatRefusal).filter(Boolean);
+  const hidden = Math.max(0, refusals.length - REFUSAL_REPORT_CAP);
+  const detail = [...shown, ...(hidden ? [`and ${hidden} more`] : [])].join('; ');
+  const word = count === 1 ? 'invoice' : 'invoices';
+  return `[sending] the accounting system refused ${count} ${word}${detail ? `: ${detail}` : ''}`;
+}
+
 // One pass of the send worker: up to `limit` queued invoices, oldest first.
 export async function sendQueued(db, organisationId, { accounting, limit = WORKER_BATCH }) {
-  const rows = await db.select({ id: invoices.id, by: invoices.sendRequestedBy }).from(invoices)
+  const rows = await db.select({ id: invoices.id, number: invoices.number, by: invoices.sendRequestedBy }).from(invoices)
     .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'issued'), eq(invoices.sendState, 'queued')))
     .orderBy(asc(invoices.sendUpdatedAt), asc(invoices.id))
     .limit(limit);
   const summary = { sent: 0, failed: 0, waiting: 0 };
   for (const [by, group] of Map.groupBy(rows, (r) => r.by ?? null)) {
+    const known = new Map(group.map((row) => [row.id, row]));
     const { invoices: results } = await accounting.capabilities.pushInvoices({
       organisationId, invoiceIds: group.map((r) => r.id), pushedBy: by,
     });
@@ -308,6 +420,8 @@ export async function sendQueued(db, organisationId, { accounting, limit = WORKE
         await settle(db, organisationId, result.invoiceId, { sendState: 'failed', sendError: { code: error.code, message: error.message } });
         summary.failed += 1;
         summary.refused = [...new Set([...(summary.refused ?? []), error.code])];
+        const fact = refusalFact(known.get(result.invoiceId), error);
+        if (fact) summary.refusals = [...(summary.refusals ?? []), fact];
       }
     }
   }
@@ -358,9 +472,10 @@ export function createSendWorker({ db, integrations, log = console, timers = { s
         if (!ran) return;
         const line = `[sending] ${ran.outcome}: ${JSON.stringify(ran.job.result ?? ran.job.lastError ?? {})}`;
         // An invoice the accounting system refused waits in Problem for a
-        // person; it is reported once, when it is refused.
+        // person. The error report names which invoices and why, once, when
+        // they are refused. The host log keeps the same pass on warn.
         if (ran.outcome === 'dead') log.error?.('[sending] the send run gave up after its last attempt');
-        if (ran.job.result?.failed) log.error?.('[sending] the accounting system refused an invoice');
+        if (ran.job.result?.failed) log.error?.(refusalReport(ran.job.result));
         (ran.outcome === 'succeeded' && !ran.job.result?.failed ? log.info : log.warn)?.(line);
       } catch (error) {
         log.error?.(`[sending] ${error?.code ?? 'error'}: ${error?.message ?? error}`);
@@ -382,5 +497,6 @@ export function createSendWorker({ db, integrations, log = console, timers = { s
       timer = null;
       await running;
     },
+    tick,
   };
 }

package/server/db/doctor.js

@@ -82,7 +82,7 @@ export async function diagnoseDatabase(pool, { adapters = [] } = {}) {
     .map((journal) => ({ journal: journal.id, applied: applied[journal.id], shipped: journal.tags.length, next: journal.tags.slice(applied[journal.id]) }));
 
   const { rows } = await pool.query(
-    "select table_name, column_name from information_schema.columns where table_schema = 'public'",
+    "select table_name, column_name from information_schema.columns where table_schema = current_schema()",
   );
   const actual = new Map();
   for (const row of rows) {

package/server/db/index.js

@@ -13,10 +13,28 @@ const migrationsFolder = fileURLToPath(new URL('./migrations', import.meta.url))
 export const MIGRATION_LOCK_KEY = 7_139_000_101n;
 const DEFAULT_MIGRATION_LOCK_TIMEOUT_MS = 300_000;
 
+// Flow's tables live in their own schema, not "public": Replit's publish
+// compares the workspace's "public" with production's and offers to make
+// production match, deletes included (migration 0021, docs/REPLIT.md). Every
+// connection searches "flow" first, so queries keep plain table names; the
+// database's own default says the same for a pooler's sessions.
+export const FLOW_SCHEMA = 'flow';
+export const FLOW_SEARCH_PATH = `${FLOW_SCHEMA}, public`;
+const setSearchPath = (client) => client.query(`set search_path to ${FLOW_SEARCH_PATH}`);
+
 // Opens Flow's PostgreSQL database. The caller owns the pool: call close().
 export function openDatabase({ url = process.env.DATABASE_URL, max = 10 } = {}) {
   if (!url) throw new Error('flow: DATABASE_URL is not set');
   const pool = new pg.Pool({ connectionString: url, max });
+  // A client runs its queries in order, so this comes before any other.
+  pool.on('connect', (client) => {
+    setSearchPath(client).catch(() => {});
+  });
+  // The server can close an idle connection (a restart, a pooler, migration
+  // 0021); the pool drops it and opens another. Unheard, it would stop Flow.
+  pool.on('error', (error) => {
+    console.warn(`[db] an idle database connection closed: ${error.message}`);
+  });
   const db = drizzle(pool, { schema });
   return { db, pool, close: () => pool.end() };
 }
@@ -56,6 +74,7 @@ export async function withMigrationLock(db, fn, { timeoutMs = migrationLockTimeo
   if (direct) {
     client = new pg.Client({ connectionString: direct });
     await client.connect();
+    await setSearchPath(client);
   } else {
     client = source instanceof pg.Pool ? await source.connect() : source;
   }

package/server/db/migrations/0021_flow_schema.sql

@@ -0,0 +1,68 @@
+-- Flow's tables move from "public" to their own schema, "flow" (issue: Replit's
+-- publish compares the workspace's "public" schema with production's and
+-- offers to make production match, deletes included; docs/REPLIT.md, "The
+-- workspace database"). Every connection searches "flow" first
+-- (server/db/index.js, FLOW_SEARCH_PATH), so queries keep their table names.
+-- The adapters' tables move too, when they exist; an adapter turned on later
+-- creates its tables in "flow". It runs again without harm.
+DO $flow_guard$
+DECLARE
+	t text;
+BEGIN
+	CREATE SCHEMA IF NOT EXISTS flow;
+	FOREACH t IN ARRAY ARRAY[
+		'alert_dismissals', 'automations', 'background_jobs', 'billing_obligations', 'contacts',
+		'customer_billing_settings', 'external_links', 'integration_setting_events', 'integration_settings',
+		'invoice_lines', 'invoice_rules', 'invoice_versions', 'invoices', 'invoicing_settings',
+		'job_field_events', 'job_field_settings', 'job_field_values', 'job_fields', 'line_mappings',
+		'link_rejections', 'link_suggestions', 'obligation_events', 'obligation_payments',
+		'obligation_writebacks', 'organisations', 'outbox', 'people', 'pipeline_cursors',
+		'price_item_links', 'price_items', 'prior_links', 'review_items',
+		'seazona_api_governor', 'seazona_api_requests', 'seazona_clients', 'seazona_history_batch_jobs',
+		'seazona_history_batches', 'seazona_history_jobs', 'seazona_history_rows', 'seazona_invoices',
+		'seazona_lane_state', 'seazona_order_read_failures', 'seazona_orders', 'seazona_person_settings',
+		'seazona_record_read_failures', 'seazona_reference', 'seazona_stage_moves', 'seazona_sweep_findings',
+		'xero_call_guard', 'xero_calls', 'xero_connections', 'xero_contacts', 'xero_credit_notes',
+		'xero_daily_checks', 'xero_import_settings', 'xero_invoice_links', 'xero_invoice_pushes',
+		'xero_invoices', 'xero_items', 'xero_mirror_cursors', 'xero_payment_cursors', 'xero_payments',
+		'xero_sync_runs', 'xero_webhook_events'
+	] LOOP
+		IF to_regclass(format('public.%I', t)) IS NOT NULL AND to_regclass(format('flow.%I', t)) IS NULL THEN
+			EXECUTE format('ALTER TABLE public.%I SET SCHEMA flow', t);
+		END IF;
+	END LOOP;
+	FOREACH t IN ARRAY ARRAY['flow_refuse_change', 'flow_invoice_lines_draft_only', 'flow_invoice_rules'] LOOP
+		IF to_regprocedure(format('public.%I()', t)) IS NOT NULL AND to_regprocedure(format('flow.%I()', t)) IS NULL THEN
+			EXECUTE format('ALTER FUNCTION public.%I() SET SCHEMA flow', t);
+		END IF;
+		-- The trigger functions name tables without a schema.
+		IF to_regprocedure(format('flow.%I()', t)) IS NOT NULL THEN
+			EXECUTE format('ALTER FUNCTION flow.%I() SET search_path = flow, public', t);
+		END IF;
+	END LOOP;
+	-- New sessions, a pooler's included, search "flow" first: a transaction
+	-- pooler does not keep a session's SET. Flow's role sets it for itself, and
+	-- the database too when Flow owns it; Flow's own connections set it anyway.
+	BEGIN
+		EXECUTE format('ALTER ROLE %I IN DATABASE %I SET search_path TO flow, public', current_user, current_database());
+	EXCEPTION WHEN insufficient_privilege THEN
+		RAISE NOTICE 'flow: this role cannot set its own search_path; Flow sets its own';
+	END;
+	BEGIN
+		EXECUTE format('ALTER DATABASE %I SET search_path TO flow, public', current_database());
+	EXCEPTION WHEN insufficient_privilege THEN
+		RAISE NOTICE 'flow: not the database owner, so its default search_path stays; Flow sets its own';
+	END;
+	-- A pooler keeps the server sessions it opened before this move, with the
+	-- old search_path, and hands them to new clients. Close the idle ones
+	-- of this role: the pooler opens new ones, which take the setting above.
+	BEGIN
+		PERFORM pg_terminate_backend(a.pid) FROM pg_stat_activity a
+		 WHERE a.datname = current_database() AND a.usename = current_user
+		   AND a.pid <> pg_backend_pid() AND a.state = 'idle' AND a.backend_type = 'client backend';
+	EXCEPTION WHEN others THEN
+		RAISE NOTICE 'flow: could not close the idle sessions; a pooler''s open sessions keep the old search_path until they close';
+	END;
+	-- This session too: the migrations after this one create their tables in "flow".
+	PERFORM set_config('search_path', 'flow, public', false);
+END $flow_guard$;

package/server/db/migrations/0022_contacts.sql

@@ -0,0 +1,11 @@
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "first_name" text;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "last_name" text;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "phone" text;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "mobile" text;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "account_number" text;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "tax_number" text;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "tax_rate" text;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "address" jsonb;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "practitioners" jsonb DEFAULT '[]'::jsonb NOT NULL;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "active" boolean DEFAULT true NOT NULL;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "updated_at" timestamp with time zone DEFAULT now() NOT NULL;