@arcforgelabs/flow 2026.11.9 → 2026.11.10

package/server/db/migrations/meta/_journal.json

@@ -211,6 +211,27 @@
       "when": 1794463202822,
       "tag": "0029_job_remake",
       "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "7",
+      "when": 1794487419926,
+      "tag": "0030_contact_hidden",
+      "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "7",
+      "when": 1794488676084,
+      "tag": "0031_bill_to",
+      "breakpoints": true
+    },
+    {
+      "idx": 32,
+      "version": "7",
+      "when": 1794491329391,
+      "tag": "0032_contact_merge",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -61,10 +61,27 @@ export const contacts = pgTable('contacts', {
   address: jsonb('address'),
   practitioners: jsonb('practitioners').notNull().default([]),
   active: boolean('active').notNull().default(true),
+  // Not a client: Flow made the contact from an accounting contact that the
+  // accounting system does not mark a customer, and nothing in Flow makes it
+  // one. It stays, out of the lists (docs/CONTACTS.md, "Hidden contacts").
+  hidden: boolean('hidden').notNull().default(false),
+  // Merge (docs/CONTACTS.md, "Merge two contacts"): a person merged this
+  // contact into another. Its jobs, invoices and links moved there; the row
+  // stays, out of every list. The kept contact holds its name in `aliases`.
+  mergedIntoId: uuid('merged_into_id'),
+  mergedAt: timestamp('merged_at', { withTimezone: true }),
+  mergedBy: text('merged_by'),
+  aliases: jsonb('aliases').notNull().default([]),
   createdAt: createdAt(),
   updatedAt: updatedAt(),
 }, (t) => [
   unique('contacts_org_id').on(t.organisationId, t.id),
+  foreignKey({
+    name: 'contacts_merged_into_same_org',
+    columns: [t.organisationId, t.mergedIntoId],
+    foreignColumns: [t.organisationId, t.id],
+  }),
+  check('contacts_merged_into_other', sql`${t.mergedIntoId} is null or ${t.mergedIntoId} <> ${t.id}`),
   unique('contacts_org_kind_name').on(t.organisationId, t.kind, t.name),
   check('contacts_kind_valid', sql`${t.kind} in ('customer', 'supplier')`),
 ]);
@@ -678,6 +695,10 @@ export const customerBillingSettings = pgTable('customer_billing_settings', {
   autoDraft: boolean('auto_draft'),
   sendMode: text('send_mode'),
   paymentTermsDays: integer('payment_terms_days'),
+  // The payer: another Flow customer whose accounting contact this
+  // customer's work is billed to (a parent organisation). Many customers may
+  // name one payer. Null bills the customer itself (docs/CONTACTS.md, "Bill to").
+  billToContactId: uuid('bill_to_contact_id'),
   updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
   updatedAt: updatedAt(),
 }, (t) => [
@@ -687,6 +708,13 @@ export const customerBillingSettings = pgTable('customer_billing_settings', {
     columns: [t.organisationId, t.contactId],
     foreignColumns: [contacts.organisationId, contacts.id],
   }),
+  foreignKey({
+    name: 'customer_billing_settings_bill_to_same_org',
+    columns: [t.organisationId, t.billToContactId],
+    foreignColumns: [contacts.organisationId, contacts.id],
+  }),
+  index('customer_billing_settings_bill_to').on(t.organisationId, t.billToContactId),
+  check('customer_billing_settings_bill_to_other', sql`${t.billToContactId} is null or ${t.billToContactId} <> ${t.contactId}`),
   check('customer_billing_settings_send_mode_valid', sql`${t.sendMode} is null or ${t.sendMode} in ('accounting_draft', 'approve_and_email')`),
   check('customer_billing_settings_terms_valid', sql`${t.paymentTermsDays} is null or ${t.paymentTermsDays} between 0 and 365`),
 ]);

package/server/integrations/xero/create-contact.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { sql } from 'drizzle-orm';
-import { getContact } from '../../core/contacts.js';
+import { billedContact, getContact } from '../../core/contacts.js';
 import { flowIdFor, linkRecord, supersedeLink } from '../../core/links.js';
 import { mapContact, matchContactFor, normaliseName, upsertContact } from './catalogue.js';
 import { xeroError } from './client.js';
@@ -79,8 +79,20 @@ export async function matchCustomer(db, runtime, { organisationId, contactId })
   const connected = Boolean(connection && connection.mode === runtime.settings.mode);
   if (!connected) return { state: 'off', offerCreate: false, offerLink: false, xeroContactId: null, name: null, differs: [] };
   const contact = await getContact(db, organisationId, contactId);
+  // Bill to: a customer with a payer is billed as the payer. Link and Create
+  // are for the payer's own page.
+  const payer = await billedContact(db, organisationId, contactId);
+  if (payer.id !== contactId) {
+    const billed = await matchContactFor(db, organisationId, { contactId: payer.id, name: payer.name });
+    return {
+      state: billed.state, offerCreate: false, offerLink: false, differs: [],
+      xeroContactId: billed.contact?.xeroContactId ?? null, name: billed.contact?.name ?? null,
+      billTo: { id: payer.id, name: payer.name },
+    };
+  }
   const match = await matchContactFor(db, organisationId, { contactId, name: contact.name });
   return {
+    billTo: null,
     // Fields both sides changed (Two-way edits, contact-sync.js): alert only.
     differs: match.state === 'matched' ? (await contactClashes(db, organisationId, contactId)).map(({ field, flow, xero }) => ({ field, flow, xero })) : [],
     state: match.state,
@@ -97,6 +109,7 @@ export async function createCustomer(db, runtime, { organisationId, contactId, a
   }
   runtime.assertWritesAllowed();
   const flowContact = await getContact(db, organisationId, contactId);
+  if (flowContact.mergedIntoId) throw xeroError('contact_merged', 'This contact was merged into another. Use that one.', { status: 409 });
   const known = await matchContactFor(db, organisationId, { contactId, name: flowContact.name });
   if (known.state === 'ambiguous') {
     throw xeroError('xero_contact_ambiguous', `More than one Xero contact is named "${flowContact.name}". Merge or rename them in Xero, then sync.`, { status: 409 });
@@ -140,6 +153,7 @@ export async function linkCustomer(db, runtime, { organisationId, contactId, xer
     throw xeroError('xero_not_connected', 'Connect Xero first.', { status: 409 });
   }
   const flowContact = await getContact(db, organisationId, contactId);
+  if (flowContact.mergedIntoId) throw xeroError('contact_merged', 'This contact was merged into another. Use that one.', { status: 409 });
   const { rows: [row] } = await db.execute(sql`select xero_contact_id, name, status from xero_contacts
     where organisation_id = ${organisationId} and xero_contact_id = ${xeroContactId}`);
   if (!row) throw xeroError('xero_contact_unknown', 'Flow has no copy of that Xero contact. Sync, then try again.', { status: 404 });

package/server/integrations/xero/delete-invoice.js

@@ -30,7 +30,7 @@ async function linkedXeroId(db, organisationId, invoiceId) {
   if (pushes[0]?.xero_invoice_id) return pushes[0].xero_invoice_id;
   const { rows: links } = await db.execute(sql`
     select xero_invoice_id from xero_invoice_links
-    where organisation_id = ${organisationId} and invoice_id = ${invoiceId}`);
+    where organisation_id = ${organisationId} and invoice_id = ${invoiceId} and released_at is null`);
   return links[0]?.xero_invoice_id ?? null;
 }
 

package/server/integrations/xero/drafts.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { and, eq, inArray, sql } from 'drizzle-orm';
 import { isCallsStopped } from '../call-guard.js';
+import { billedContact } from '../../core/contacts.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';
@@ -325,15 +326,29 @@ export async function previewDrafts(db, runtime, organisationId, invoiceIds) {
   return { syncedAt, warnings, invoices: results };
 }
 
+// The Xero contact an invoice goes to: its customer's, or its payer's when the
+// customer bills to another customer (docs/CONTACTS.md, "Bill to"). A missing
+// payer is linked or made on the payer's own contact page, not here.
+async function accountingContactFor(db, organisationId, invoice, document) {
+  const payer = await billedContact(db, organisationId, invoice.contactId);
+  const own = payer.id === invoice.contactId;
+  const name = own ? document.contact.name : payer.name;
+  return { match: await matchContactFor(db, organisationId, { contactId: payer.id, name }), name, own };
+}
+
+const payerMissing = (name) => problem('xero_contact_missing',
+  `This client is billed to ${name}, and no Xero contact is named "${name}". Link ${name} to its Xero client on its contact page, then check again.`,
+  { short: 'Payer not in Xero' });
+
 async function previewOne(db, runtime, organisationId, invoiceId) {
   const { invoice, version, document } = await documentFor(db, organisationId, invoiceId);
   const problems = [];
   if (invoice.status === 'void') problems.push(problem('invoice_void', 'This invoice is void. Flow does not send it to Xero.'));
   if (invoice.status === 'draft') problems.push(problem('invoice_not_issued', 'This invoice is a draft. Issue it, then send it to Xero.'));
-  const match = await matchContactFor(db, organisationId, { contactId: invoice.contactId, name: document.contact.name });
+  const { match, name, own } = await accountingContactFor(db, organisationId, invoice, document);
   const offerCreate = match.state === 'missing' && runtime.settings.createContacts && writesAllowed(runtime.settings);
-  if (match.state === 'missing') problems.push(missingContact(document.contact.name, { offerCreate }));
-  if (match.state === 'ambiguous') problems.push(twiceContact(document.contact.name));
+  if (match.state === 'missing') problems.push(own ? missingContact(name, { offerCreate }) : payerMissing(name));
+  if (match.state === 'ambiguous') problems.push(own ? twiceContact(name) : { ...twiceContact(name), offerLink: false });
   const items = await xeroItemsForCodes(db, organisationId, document.lines.map((l) => l.itemCode));
   const sendMode = await sendModeFor(db, organisationId, invoice.contactId);
   const { draft, problems: lineProblems } = buildDraft(document, { settings: runtime.settings, contact: match.contact, items, sendMode });
@@ -513,10 +528,10 @@ async function pushOne(db, runtime, client, organisationId, invoiceId, { pushedB
     }
   }
 
-  const match = await matchContactFor(db, organisationId, { contactId: invoice.contactId, name: document.contact.name });
+  const { match, name, own } = await accountingContactFor(db, organisationId, invoice, document);
   if (match.state !== 'matched') {
     const offerCreate = match.state === 'missing' && runtime.settings.createContacts && writesAllowed(runtime.settings);
-    const found = match.state === 'missing' ? missingContact(document.contact.name, { offerCreate }) : twiceContact(document.contact.name);
+    const found = match.state === 'missing' ? (own ? missingContact(name, { offerCreate }) : payerMissing(name)) : { ...twiceContact(name), offerLink: own };
     throw xeroError(found.code, found.message, { status: 409, short: found.short });
   }
   const items = await xeroItemsForCodes(db, organisationId, document.lines.map((l) => l.itemCode));

package/server/integrations/xero/ledger.js

@@ -1,7 +1,8 @@
 import { and, eq, inArray, sql } from 'drizzle-orm';
+import { payersOf } from '../../core/contacts.js';
 import { recordAccountingEvidence, recordPayment } from '../../core/ledger.js';
 import { billingObligations, contacts as flowContacts } from '../../db/schema.js';
-import { matchContact, parseXeroDate } from './catalogue.js';
+import { matchContactFor, parseXeroDate } from './catalogue.js';
 import { withXeroLane } from './governor.js';
 
 // What the billing obligation ledger (server/core/ledger.js) needs from Xero:
@@ -136,9 +137,11 @@ export async function checkInvoice(db, runtime, client, organisationId, obligati
   if (references.length) {
     let customer = null;
     if (obligation.contactId) {
+      // A customer with a payer is billed under the payer's name (Bill to).
+      const payer = (await payersOf(db, organisationId, [obligation.contactId])).get(obligation.contactId);
       const [contact] = await db.select({ name: flowContacts.name }).from(flowContacts)
-        .where(and(eq(flowContacts.organisationId, organisationId), eq(flowContacts.id, obligation.contactId)));
-      const match = contact ? await matchContact(db, organisationId, contact.name) : { state: 'missing' };
+        .where(and(eq(flowContacts.organisationId, organisationId), eq(flowContacts.id, payer)));
+      const match = contact ? await matchContactFor(db, organisationId, { contactId: payer, name: contact.name }) : { state: 'missing' };
       customer = match.state === 'matched' ? match.contact.xeroContactId : null;
       if (match.state === 'ambiguous') {
         const error = new Error(`More than one Xero contact is named "${contact.name}"; Flow cannot tell which invoices are this customer's.`);
@@ -231,7 +234,7 @@ export async function recordXeroPayments(db, runtime, organisationId, { actor, s
       const { rows } = await db.execute(sql`select xero_invoice_id, invoice_id from xero_invoice_pushes
         where organisation_id = ${organisationId} and xero_invoice_id = any(${sql.param(xeroIds)}::text[])
         union all select xero_invoice_id, invoice_id from xero_invoice_links
-        where organisation_id = ${organisationId} and xero_invoice_id = any(${sql.param(xeroIds)}::text[])`);
+        where organisation_id = ${organisationId} and xero_invoice_id = any(${sql.param(xeroIds)}::text[]) and released_at is null`);
       for (const row of rows) byFlowInvoice.set(row.xero_invoice_id, row.invoice_id);
     }
     const flowInvoiceIds = [...new Set(byFlowInvoice.values())];

package/server/integrations/xero/links.js

@@ -1,10 +1,12 @@
-import { and, eq, sql } from 'drizzle-orm';
+import { and, eq, isNull, sql } from 'drizzle-orm';
 import { billingObligations, contacts, invoices, obligationEvents, priceItems } from '../../db/schema.js';
+import { payersOf } from '../../core/contacts.js';
 import { createContact } from '../../core/directory.js';
 import { FlowError } from '../../core/errors.js';
 import { createDraftInvoice, issueInvoice } from '../../core/invoices.js';
-import { linkJobToInvoice } from '../../core/ledger.js';
+import { linkJobToInvoice, recordAccountingEvidence, releaseAccountingRef } from '../../core/ledger.js';
 import { normaliseName } from './catalogue.js';
+import { findInvoices } from './lookup.js';
 import { canFit, markRivals, scoreFit, sureFits } from './fit.js';
 
 // The Import page (docs/XERO_IMPORT.md): each sales invoice in Flow's copy of
@@ -54,7 +56,7 @@ async function classify(db, organisationId) {
     select xero_invoice_id, invoice_id, 'sent' as matched_by from xero_invoice_pushes
       where organisation_id = ${organisationId} and xero_invoice_id is not null
     union all
-    select xero_invoice_id, invoice_id, matched_by from xero_invoice_links where organisation_id = ${organisationId}`);
+    select xero_invoice_id, invoice_id, matched_by from xero_invoice_links where organisation_id = ${organisationId} and released_at is null`);
   const linkOf = new Map();
   const linkedInvoices = new Set();
   for (const r of linkRows) {
@@ -63,13 +65,23 @@ async function classify(db, organisationId) {
   }
   // Flow's customers by name, as the drafts match them (only a name with one
   // contact counts).
-  const people = await db.select({ id: contacts.id, name: contacts.name }).from(contacts)
-    .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')));
+  // A merged contact is gone; the kept one answers to its aliases too.
+  const people = await db.select({ id: contacts.id, name: contacts.name, aliases: contacts.aliases }).from(contacts)
+    .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer'), isNull(contacts.mergedIntoId)));
   const byName = new Map();
   for (const p of people) {
-    const key = normaliseName(p.name);
-    byName.set(key, byName.has(key) ? null : p.id);
+    for (const name of [p.name, ...(p.aliases ?? [])]) {
+      const key = normaliseName(name);
+      if (byName.has(key) && byName.get(key) === p.id) continue;
+      byName.set(key, byName.has(key) ? null : p.id);
+    }
   }
+  // The identity-map link first, so a Xero contact of another name finds its
+  // Flow customer, then the name.
+  const { rows: contactLinks } = await db.execute(sql`select l.external_id, l.flow_id from external_links l
+    join contacts c on c.organisation_id = l.organisation_id and c.id = l.flow_id and c.kind = 'customer'
+    where l.organisation_id = ${organisationId} and l.system = 'xero' and l.entity = 'contact' and l.state = 'active'`);
+  const byLink = new Map(contactLinks.map((l) => [l.external_id, l.flow_id]));
   const { rows: flowInvoices } = await db.execute(sql`
     select i.id, i.number, i.contact_id, i.total_cents, i.subtotal_cents, i.reference, i.status, coalesce(i.issue_date, i.created_at::date) as date,
       coalesce((select array_agg(distinct p.code) from invoice_lines l join price_items p on p.id = l.price_item_id
@@ -83,6 +95,11 @@ async function classify(db, organisationId) {
     select o.id, o.contact_id, o.total_cents, o.job_date, o.practitioner, o.case_ref, o.accounting_ref, o.source_invoice_ref, o.lines
     from billing_obligations o
     where o.organisation_id = ${organisationId} and o.invoice_id is null`);
+  // Bill to (docs/CONTACTS.md): a customer with a payer is billed under the
+  // payer's Xero contact, so its jobs and invoices fit that contact's invoices.
+  // A Xero row of a client's own Xero contact fits as that client's payer too.
+  const payerOf = await payersOf(db, organisationId, people.map((p) => p.id));
+  const billedAs = (contactId) => (contactId ? payerOf.get(contactId) ?? contactId : null);
   const jobByRef = new Map(jobs.filter((j) => j.accounting_ref).map((j) => [j.accounting_ref, j]));
   // The work system's own invoice number, as Xero numbers it (a trailing R is
   // a reissue). Only a number one job holds counts.
@@ -95,7 +112,7 @@ async function classify(db, organisationId) {
   }
 
   const rows = xero.map((x) => {
-    const contactId = x.contact_name ? byName.get(normaliseName(x.contact_name)) ?? null : null;
+    const contactId = byLink.get(x.xero_contact_id) ?? (x.contact_name ? byName.get(normaliseName(x.contact_name)) ?? null : null);
     const row = {
       xeroInvoiceId: x.xero_invoice_id,
       number: x.invoice_number,
@@ -117,10 +134,11 @@ async function classify(db, organisationId) {
       return { ...row, state: 'linked' };
     }
     row.itemCodes = [...new Set((x.lines ?? []).map((l) => l.itemCode).filter(Boolean))];
-    const xeroFit = { id: x.xero_invoice_id, number: x.invoice_number, contactId, totalCents: row.totalCents, issuedOn: row.issuedOn,
+    const billedTo = billedAs(contactId);
+    const xeroFit = { id: x.xero_invoice_id, number: x.invoice_number, contactId: billedTo, totalCents: row.totalCents, issuedOn: row.issuedOn,
       itemCodes: (x.lines ?? []).map((l) => l.itemCode).filter(Boolean), reference: x.reference };
     row.invoices = open.map((i) => {
-      const flowFit = { id: i.id, contactId: i.contact_id, totalCents: num(i.total_cents), subtotalCents: num(i.subtotal_cents), date: day(i.date),
+      const flowFit = { id: i.id, contactId: billedAs(i.contact_id), totalCents: num(i.total_cents), subtotalCents: num(i.subtotal_cents), date: day(i.date),
         itemCodes: i.item_codes ?? [], reference: i.reference, jobs: i.jobs ?? [] };
       const scored = scoreFit(xeroFit, flowFit);
       return canFit(xeroFit, flowFit, scored)
@@ -129,8 +147,8 @@ async function classify(db, organisationId) {
         : null;
     }).filter(Boolean);
     const tied = jobByRef.get(x.xero_invoice_id) ?? (x.invoice_number ? jobByNumber.get(workNumber(x.invoice_number)) : null) ?? null;
-    const fits = tied ? [tied] : contactId
-      ? jobs.filter((j) => !j.accounting_ref && j.contact_id === contactId && num(j.total_cents) === row.totalCents && near(day(j.job_date), row.issuedOn))
+    const fits = tied ? [tied] : billedTo
+      ? jobs.filter((j) => !j.accounting_ref && billedAs(j.contact_id) === billedTo && num(j.total_cents) === row.totalCents && near(day(j.job_date), row.issuedOn))
       : [];
     row.jobs = fits.map((j) => ({ id: j.id, jobDate: day(j.job_date), practitioner: j.practitioner, caseRef: j.case_ref, totalCents: num(j.total_cents), tied: j === tied,
       itemCodes: [...new Set((j.lines ?? []).map((l) => l.itemCode).filter(Boolean))] }));
@@ -208,9 +226,16 @@ export async function saveImportSettings(db, organisationId, { autoLink, makeUnm
 }
 
 async function insertLink(db, organisationId, { xeroInvoiceId, invoiceId, matchedBy, actor }) {
+  // A released link (releaseXeroLink) gives its row to the new one.
+  const { rows: held } = await db.execute(sql`select 1 from xero_invoice_links where organisation_id = ${organisationId}
+    and invoice_id = ${invoiceId} and xero_invoice_id <> ${xeroInvoiceId} limit 1`);
+  if (held.length) throw new FlowError('invalid', 'the Xero invoice or the Flow invoice is linked already');
   const { rows } = await db.execute(sql`insert into xero_invoice_links (organisation_id, xero_invoice_id, invoice_id, matched_by, linked_by)
     values (${organisationId}, ${xeroInvoiceId}, ${invoiceId}, ${matchedBy}, ${actor})
-    on conflict do nothing returning xero_invoice_id`);
+    on conflict (organisation_id, xero_invoice_id) do update set invoice_id = excluded.invoice_id, matched_by = excluded.matched_by,
+      linked_by = excluded.linked_by, created_at = now(), released_by = null, released_at = null, deleted_by = null, deleted_at = null
+      where xero_invoice_links.released_at is not null
+    returning xero_invoice_id`);
   if (!rows.length) throw new FlowError('invalid', 'the Xero invoice or the Flow invoice is linked already');
 }
 
@@ -251,7 +276,8 @@ export async function useXeroInvoice(db, organisationId, invoiceId, { xeroInvoic
     if (!invoice) throw new FlowError('not_found', 'Flow invoice not found');
     // A copy voided earlier, still holding its job, gives way the same way.
     if (!['issued', 'void'].includes(invoice.status)) throw new FlowError('invalid', 'only an approved or void Flow invoice can give way to a Xero invoice');
-    if (row.contactId !== invoice.contact_id) throw new FlowError('invalid', 'the Xero invoice is for another client');
+    const payers = await payersOf(tx, organisationId, [invoice.contact_id, row.contactId]);
+    if (!row.contactId || payers.get(row.contactId) !== payers.get(invoice.contact_id)) throw new FlowError('invalid', 'the Xero invoice is for another client');
     const { rows: pushed } = await tx.execute(sql`select 1 from xero_invoice_pushes where organisation_id = ${organisationId} and invoice_id = ${invoiceId} and xero_invoice_id is not null limit 1`);
     if (pushed.length) throw new FlowError('invalid', 'Flow sent that invoice to Xero already');
     const jobs = await tx.select({ id: billingObligations.id }).from(billingObligations)
@@ -267,7 +293,8 @@ export async function useXeroInvoice(db, organisationId, invoiceId, { xeroInvoic
         evidence: { invoiceId, reason: 'used_xero_invoice', xeroInvoiceId, xeroNumber: row.number ?? null },
       });
     }
-    const made = await makeFrom(tx, organisationId, row, { jobId: jobs[0]?.id ?? null, actor });
+    // The new Flow invoice stays with the client of the one it replaces.
+    const made = await makeFrom(tx, organisationId, row, { jobId: jobs[0]?.id ?? null, contactId: invoice.contact_id, actor });
     return { voided: { id: invoiceId, number: invoice.number }, invoice: { id: made.invoice.id, number: made.invoice.number }, xeroInvoiceId, jobId: jobs[0]?.id ?? null };
   });
 }
@@ -281,14 +308,21 @@ export async function makeFlowInvoice(db, organisationId, xeroInvoiceId, { jobId
   return makeFrom(db, organisationId, await rowFor(db, organisationId, xeroInvoiceId), { jobId, actor });
 }
 
-async function makeFrom(db, organisationId, row, { jobId = null, actor }) {
+async function makeFrom(db, organisationId, row, { jobId = null, contactId: chosen = null, actor }) {
   const { xeroInvoiceId } = row;
   const { rows: [x] } = await db.execute(sql`select x.lines, x.due_on, c.email from xero_invoices x
     left join xero_contacts c on c.organisation_id = x.organisation_id and c.xero_contact_id = x.xero_contact_id
     where x.organisation_id = ${organisationId} and x.xero_invoice_id = ${xeroInvoiceId}`);
   if (!row.clientName) throw new FlowError('invalid', 'the Xero invoice has no contact in the copy; sync contacts first');
   return db.transaction(async (tx) => {
-    const contactId = row.contactId ?? (await createContact(tx, organisationId, { kind: 'customer', name: row.clientName, email: x.email ?? null })).id;
+    // The job's own customer when it bills to this payer (Bill to), so the
+    // Flow invoice stays with the client the work was for.
+    const { rows: [job] } = jobId ? await tx.execute(sql`select contact_id from billing_obligations
+      where organisation_id = ${organisationId} and id = ${jobId}`) : { rows: [] };
+    const payers = await payersOf(tx, organisationId, [job?.contact_id, row.contactId]);
+    const samePayer = job?.contact_id && row.contactId && payers.get(job.contact_id) === payers.get(row.contactId);
+    const contactId = chosen ?? (samePayer ? job.contact_id : null)
+      ?? row.contactId ?? (await createContact(tx, organisationId, { kind: 'customer', name: row.clientName, email: x.email ?? null })).id;
     const items = await tx.select({ id: priceItems.id, code: priceItems.code, name: priceItems.name }).from(priceItems)
       .where(eq(priceItems.organisationId, organisationId));
     const byCode = new Map(items.map((i) => [i.code.toUpperCase(), i]));
@@ -308,7 +342,16 @@ async function makeFrom(db, organisationId, row, { jobId = null, actor }) {
     const draft = await createDraftInvoice(tx, organisationId, { contactId, reference: row.reference ?? null, dueDate: day(x.due_on), lines });
     const invoice = await issueInvoice(tx, organisationId, draft.id, { issuedBy: actor, issueDate: row.issuedOn ?? new Date().toISOString().slice(0, 10) });
     await insertLink(tx, organisationId, { xeroInvoiceId, invoiceId: invoice.id, matchedBy: 'made', actor });
-    if (jobId) await linkJobToInvoice(tx, organisationId, jobId, { invoiceId: invoice.id, accountingRef: xeroInvoiceId, actor });
+    if (jobId) {
+      await linkJobToInvoice(tx, organisationId, jobId, { invoiceId: invoice.id, accountingRef: xeroInvoiceId, actor });
+      // The job's accounting state in the same step, from the copy the
+      // invoice was made from: the ledger says billed or paid at once, not
+      // after the matcher's next pass.
+      const { invoices: [copy] } = await findInvoices(tx, organisationId, { invoiceIds: [xeroInvoiceId] });
+      if (copy?.state) {
+        await recordAccountingEvidence(tx, organisationId, jobId, { state: copy.state, accountingRef: xeroInvoiceId, matchedBy: 'accounting_ref', actor });
+      }
+    }
     return { xeroInvoiceId, invoice };
   });
 }
@@ -329,3 +372,27 @@ export async function matchXero(db, organisationId, { actor = 'automation:xero-i
   }
   return result;
 }
+
+// A person releases a wrong pair: the Xero invoice is linked to a Flow invoice
+// that was voided, and is another job's bill. The link stays as a record
+// (released_by, released_at) and the Xero invoice can link again. Each job
+// that points at the Xero invoice and no longer holds a Flow invoice lets go
+// of it, and the matcher never pairs them again. A live Flow invoice keeps
+// its link: void it first.
+export async function releaseXeroLink(db, organisationId, xeroInvoiceId, { actor, reason }) {
+  if (!actor) throw new FlowError('invalid', 'actor is required');
+  if (!reason?.trim()) throw new FlowError('invalid', 'say why the link is released');
+  return db.transaction(async (tx) => {
+    const { rows: [link] } = await tx.execute(sql`select l.invoice_id, i.number, i.status from xero_invoice_links l
+      join invoices i on i.organisation_id = l.organisation_id and i.id = l.invoice_id
+      where l.organisation_id = ${organisationId} and l.xero_invoice_id = ${xeroInvoiceId} and l.released_at is null for update of l`);
+    if (!link) throw new FlowError('not_found', 'the Xero invoice has no link to release');
+    if (link.status !== 'void') throw new FlowError('invalid', `Flow invoice ${link.number ?? link.invoice_id} is ${link.status}: void it first`);
+    await tx.execute(sql`update xero_invoice_links set released_by = ${actor}, released_at = now()
+      where organisation_id = ${organisationId} and xero_invoice_id = ${xeroInvoiceId}`);
+    const { rows: jobs } = await tx.execute(sql`select id from billing_obligations
+      where organisation_id = ${organisationId} and accounting_ref = ${xeroInvoiceId} and invoice_id is null`);
+    for (const job of jobs) await releaseAccountingRef(tx, organisationId, job.id, { accountingRef: xeroInvoiceId, system: 'xero', actor, reason });
+    return { xeroInvoiceId, invoice: { id: link.invoice_id, number: link.number }, jobs: jobs.map((j) => j.id) };
+  });
+}

package/server/integrations/xero/lookup.js

@@ -15,8 +15,10 @@ export const MIRROR_FRESH_MS = 24 * 60 * 60 * 1000;
 export const PROOF_RESOURCES = Object.freeze(['invoices', 'credit_notes']);
 
 // `contact` is the Flow contact a new client becomes (docs/CONTACTS.md,
-// "Add Xero clients"). A contact Xero marks a supplier only still links by
-// name, but never becomes a Flow customer (`adoptable` false).
+// "Add Xero clients"). Only a contact Xero marks a customer (it has a sales
+// invoice there) becomes one (`adoptable`). The others (suppliers, staff,
+// names from bank lines) still link by name. `customer` is Xero's mark: the
+// core hides a Flow contact made from one that has none ("Hidden contacts").
 export async function listCustomers(db, organisationId) {
   const { rows } = await db.execute(sql`
     select xero_contact_id, name, first_name, last_name, email, phone, mobile, account_number, tax_number, address,
@@ -27,7 +29,8 @@ export async function listCustomers(db, organisationId) {
   return rows.map((r) => ({
     id: r.xero_contact_id,
     name: r.name,
-    adoptable: Boolean(r.is_customer || !r.is_supplier),
+    adoptable: Boolean(r.is_customer),
+    customer: Boolean(r.is_customer),
     contact: {
       kind: 'customer', name: r.name, firstName: r.first_name, lastName: r.last_name, email: r.email, phone: r.phone,
       mobile: r.mobile, accountNumber: r.account_number, taxNumber: r.tax_number, address: r.address,
@@ -135,7 +138,7 @@ export async function findInvoices(db, organisationId, query = {}) {
         where organisation_id = i.organisation_id and xero_invoice_id = i.xero_invoice_id
         union all
         select invoice_id, 1, 0 from xero_invoice_links
-        where organisation_id = i.organisation_id and xero_invoice_id = i.xero_invoice_id
+        where organisation_id = i.organisation_id and xero_invoice_id = i.xero_invoice_id and released_at is null
       ) f order by pick, version desc limit 1
     ) p on true
     where i.organisation_id = ${organisationId} and i.type = 'ACCREC'

package/server/integrations/xero/migrations/0015_xero_link_release.sql

@@ -0,0 +1,7 @@
+-- A person releases a Xero invoice's link to a Flow invoice that was voided
+-- (links.js, releaseXeroLink): the pair was wrong, and the Xero invoice is
+-- free to link again. The row stays, with who and when; a new link takes its
+-- place. Nothing is deleted.
+ALTER TABLE "xero_invoice_links" ADD COLUMN IF NOT EXISTS "released_by" text;
+--> statement-breakpoint
+ALTER TABLE "xero_invoice_links" ADD COLUMN IF NOT EXISTS "released_at" timestamp with time zone;

package/server/integrations/xero/migrations/0016_xero_copy_version.sql

@@ -0,0 +1,11 @@
+-- The version of the copy each resource was read with: the mapper's version
+-- (mirror.js COPY_VERSION) and whether free text is kept. When it changes,
+-- the next read starts again from the beginning, so old rows get a new field.
+-- Null: read before Flow noted it; the first read notes it without starting
+-- again (kept_reference still starts one when the setting differs).
+ALTER TABLE "xero_mirror_cursors" ADD COLUMN IF NOT EXISTS "copy_version" text;
+--> statement-breakpoint
+-- Who asked for a full read again, and when (POST /api/xero/mirror/reread).
+ALTER TABLE "xero_mirror_cursors" ADD COLUMN IF NOT EXISTS "reread_by" text;
+--> statement-breakpoint
+ALTER TABLE "xero_mirror_cursors" ADD COLUMN IF NOT EXISTS "reread_at" timestamp with time zone;

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

@@ -106,6 +106,20 @@
       "when": 1792570000000,
       "tag": "0014_xero_mirror_reference",
       "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1792580000000,
+      "tag": "0015_xero_link_release",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1792590000000,
+      "tag": "0016_xero_copy_version",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/mirror.js

@@ -23,6 +23,12 @@ import { withXeroLane } from './governor.js';
 
 export const MIRROR_RESOURCES = Object.freeze(['invoices', 'credit_notes', 'payments']);
 
+// The mapper's version. Raise it when a mapper copies a new field: each
+// resource is then read again from the beginning, so old rows get the field
+// (docs/XERO.md, "Copy version").
+export const COPY_VERSION = 1;
+const copyVersion = (keepReference) => `${COPY_VERSION}:${keepReference ? 'text' : 'no_text'}`;
+
 // A Xero amount (a JSON number with up to 4 decimals) to whole cents, half away
 // from zero, without float drift.
 export function toCents(amount) {
@@ -202,13 +208,18 @@ export async function storeRows(tx, organisationId, resource, rows, counts) {
 // would keep the free text they were read with. The rows stay; each is
 // written again only if it differs.
 async function readCursor(db, organisationId, resource, { keepReference }) {
-  await db.execute(sql`insert into xero_mirror_cursors (organisation_id, resource, kept_reference)
-    values (${organisationId}, ${resource}, ${keepReference}) on conflict do nothing`);
-  await db.execute(sql`update xero_mirror_cursors set modified_since = null, page = 1, kept_reference = ${keepReference}
-    where organisation_id = ${organisationId} and resource = ${resource} and kept_reference is distinct from ${keepReference}`);
+  const version = copyVersion(keepReference);
+  await db.execute(sql`insert into xero_mirror_cursors (organisation_id, resource, kept_reference, copy_version)
+    values (${organisationId}, ${resource}, ${keepReference}, ${version}) on conflict do nothing`);
+  await db.execute(sql`update xero_mirror_cursors set modified_since = null, page = 1, kept_reference = ${keepReference}, copy_version = ${version}
+    where organisation_id = ${organisationId} and resource = ${resource}
+      and (kept_reference is distinct from ${keepReference} or (copy_version is not null and copy_version <> ${version}))`);
+  // A copy read before Flow noted its version takes the version as it is.
+  await db.execute(sql`update xero_mirror_cursors set copy_version = ${version}
+    where organisation_id = ${organisationId} and resource = ${resource} and copy_version is null`);
   const { rows: [row] } = await db.execute(sql`select * from xero_mirror_cursors
     where organisation_id = ${organisationId} and resource = ${resource}`);
-  return { modifiedSince: row.modified_since ? new Date(row.modified_since) : null, page: row.page };
+  return { modifiedSince: row.modified_since ? new Date(row.modified_since) : null, page: row.page, rereadAt: row.reread_at ?? null };
 }
 
 // Where the next page starts, from the page just read. A full page moves the
@@ -255,18 +266,29 @@ export async function mirrorResource(db, runtime, organisationId, resource, { ma
       }
       const rows = mapRecords(resource, raw, settings);
       const next = nextPosition(position, rows, pageSize);
-      await db.transaction(async (tx) => {
+      const asked = await db.transaction(async (tx) => {
         await storeRows(tx, organisationId, resource, rows, counts);
+        // An owner asked for a read again while this pass ran: keep the
+        // cursor at the start they set, and stop.
+        const { rows: [cursor] } = await tx.execute(sql`select reread_at from xero_mirror_cursors
+          where organisation_id = ${organisationId} and resource = ${resource} for update`);
+        if (String(cursor?.reread_at ?? '') !== String(position.rereadAt ?? '')) {
+          await tx.execute(sql`update xero_mirror_cursors set rows_read = rows_read + ${raw.length}, last_read_at = now(), last_error = null
+            where organisation_id = ${organisationId} and resource = ${resource}`);
+          return true;
+        }
         await tx.execute(sql`update xero_mirror_cursors set
           modified_since = ${next.modifiedSince}, page = ${next.page}, rows_read = rows_read + ${raw.length},
           last_read_at = now(), last_error = null,
           passes = passes + ${next.done ? 1 : 0},
           last_pass_finished_at = case when ${next.done} then now() else last_pass_finished_at end
           where organisation_id = ${organisationId} and resource = ${resource}`);
+        return false;
       });
       counts.pages += 1;
       counts.read += raw.length;
-      position = next;
+      if (asked) return { resource, ...counts, stopped: 'reread' };
+      position = { ...next, rereadAt: position.rereadAt };
       if (next.done) return { resource, ...counts, stopped: 'done' };
     }
   });
@@ -311,10 +333,39 @@ export async function mirrorXero(db, runtime, organisationId, { resources = MIRR
   });
 }
 
+// A person asks for the whole copy to be read again (an owner only): the next
+// read of each resource starts from the beginning. The rows stay; each is
+// written again only if it differs. No call is made here.
+export async function rereadCopy(db, organisationId, { resources = MIRROR_RESOURCES, actor }) {
+  if (!actor) throw new TypeError('actor is required');
+  for (const resource of resources) {
+    await db.execute(sql`insert into xero_mirror_cursors (organisation_id, resource) values (${organisationId}, ${resource}) on conflict do nothing`);
+    await db.execute(sql`update xero_mirror_cursors set modified_since = null, page = 1, reread_by = ${actor}, reread_at = now()
+      where organisation_id = ${organisationId} and resource = ${resource}`);
+  }
+  return mirrorStatus(db, organisationId);
+}
+
+// For each of the last 12 months, the sales invoices in the copy and how many
+// have a Reference and line item codes: the fields the matcher reads. A low
+// month is a copy that missed them (docs/XERO.md, "Copy version").
+async function completeness(db, organisationId) {
+  const { rows } = await db.execute(sql`select to_char(date_trunc('month', issued_on), 'YYYY-MM') as month,
+      count(*)::int as invoices,
+      count(*) filter (where coalesce(trim(reference), '') <> '')::int as with_reference,
+      count(*) filter (where jsonb_typeof(lines) = 'array'
+        and exists (select 1 from jsonb_array_elements(lines) l where coalesce(l->>'itemCode', '') <> ''))::int as with_item_codes
+    from xero_invoices
+    where organisation_id = ${organisationId} and type = 'ACCREC' and status not in ('DELETED', 'VOIDED')
+      and issued_on >= date_trunc('month', now()) - interval '11 months'
+    group by 1 order by 1`);
+  return rows.map((r) => ({ month: r.month, invoices: r.invoices, withReference: r.with_reference, withItemCodes: r.with_item_codes }));
+}
+
 // What the copy holds, and where each cursor stands. No Xero calls.
 export async function mirrorStatus(db, organisationId) {
   const { rows: cursors } = await db.execute(sql`select resource, modified_since, page, passes, rows_read,
-    last_read_at, last_pass_finished_at, last_error from xero_mirror_cursors where organisation_id = ${organisationId}
+    last_read_at, last_pass_finished_at, last_error, copy_version, kept_reference, reread_by, reread_at from xero_mirror_cursors where organisation_id = ${organisationId}
     order by resource`);
   const { rows: [counts] } = await db.execute(sql`select
     (select count(*)::int from xero_invoices where organisation_id = ${organisationId}) as invoices,
@@ -331,6 +382,10 @@ export async function mirrorStatus(db, organisationId) {
       lastReadAt: c.last_read_at,
       lastPassFinishedAt: c.last_pass_finished_at,
       lastError: c.last_error,
+      copyVersion: c.copy_version ?? null,
+      keptReference: c.kept_reference ?? null,
+      rereadAt: c.reread_at ?? null,
     })),
+    completeness: await completeness(db, organisationId),
   };
 }