@arcforgelabs/flow 2026.11.9 → 2026.11.10

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.11.9",
+  "version": "2026.11.10",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.11.9",
+      "version": "2026.11.10",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.11.9",
+  "version": "2026.11.10",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/api/invoicing.js

@@ -35,6 +35,7 @@ import { isHistoryHeld } from '../core/history.js';
 import { invoicePdfDocument, pdfFields, pdfFilename, renderInvoicePdf } from '../core/invoice-pdf.js';
 import { invoiceView, invoiceViews, markNotReady, markReady, sendAgain, sendAllReady } from '../core/sending.js';
 import { createContact, getContact, listContacts, presentContact, updateContact } from '../core/contacts.js';
+import { mergeContacts } from '../core/merge-contacts.js';
 import {
   billingObligations, contacts, invoices, INVOICE_STATUSES, organisations, priceItems, TAX_CODES,
 } from '../db/schema.js';
@@ -64,7 +65,7 @@ import {
 //   POST  /invoices/:id/void          owner or admin
 //   DELETE /invoices/:id              owner or admin: a draft that was never issued.
 //                                     Frees its job, and the lab's rules then decide.
-//   GET   /contacts?q=&limit=         customers, by name
+//   GET   /contacts?q=&limit=         customers, by name (hidden=true: the contacts that are not clients)
 //   GET   /price-items?q=             the price list, by code
 //   GET   /jobs?view=&limit=          billable jobs (the obligation ledger), with counts by view;
 //                                     a job with no invoice lists the invoicing rules it waits on;
@@ -695,10 +696,13 @@ export function createInvoicingRouter({
     if (kind && !['customer', 'supplier', 'all'].includes(kind)) throw invalid('kind must be customer, supplier or all');
     const active = text(req.query.active);
     if (active && !['true', 'false', 'all'].includes(active)) throw invalid('active must be true, false or all');
+    const hidden = text(req.query.hidden);
+    if (hidden && !['true', 'false', 'all'].includes(hidden)) throw invalid('hidden must be true, false or all');
     const rows = await listContacts(db, organisationId, {
       q: text(req.query.q),
       kind: kind === 'all' ? null : (kind || 'customer'),
       active: active === 'all' ? null : active === 'false' ? false : true,
+      hidden: hidden === 'all' ? null : hidden === 'true',
       limit: limitOf(req.query.limit, 50, 500),
       offset: offsetOf(req.query.offset),
     });
@@ -724,6 +728,18 @@ export function createInvoicingRouter({
     res.json({ ok: true, contact });
   }));
 
+  // Merge two contacts: this one stays; `fromId` moves into it
+  // (docs/CONTACTS.md, "Merge two contacts").
+  router.post('/contacts/:id/merge', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const keepId = pathId(req.params.id, 'contact');
+    const fromId = text(req.body?.fromId);
+    if (!UUID.test(fromId)) throw invalid('fromId must name the contact to merge');
+    const result = await mergeContacts(db, organisationId, { keepId, fromId, actor: `person:${req.person.id}` });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} merged contact ${fromId} into ${keepId}`);
+    res.json({ ok: true, ...result, contact: presentContact(await getContact(db, organisationId, keepId)) });
+  }));
+
   router.get('/price-items', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await organisationOf(req);
     const q = text(req.query.q);
@@ -988,7 +1004,7 @@ export function createInvoicingRouter({
     const [statuses, customers, items, practitioners] = await Promise.all([
       workStatuses(db, organisationId),
       db.select({ value: contacts.id, label: contacts.name }).from(contacts)
-        .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')))
+        .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer'), isNull(contacts.mergedIntoId)))
         .orderBy(asc(contacts.name)).limit(1000),
       db.select({ value: priceItems.code, label: priceItems.name }).from(priceItems)
         .where(and(eq(priceItems.organisationId, organisationId), isNull(priceItems.archivedAt)))

package/server/core/contacts.js

@@ -1,5 +1,5 @@
-import { and, asc, eq, ilike, or, sql } from 'drizzle-orm';
-import { contacts, CONTACT_KINDS } from '../db/schema.js';
+import { and, asc, eq, ilike, inArray, isNotNull, isNull, or, sql } from 'drizzle-orm';
+import { contacts, CONTACT_KINDS, customerBillingSettings } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 
 // Flow's own contacts (docs/CONTACTS.md). A contact is a customer or a
@@ -79,6 +79,11 @@ export function readContact(input, { partial = false } = {}) {
     if (input.active != null && typeof input.active !== 'boolean') throw invalid('active must be true or false');
     out.active = input.active !== false;
   }
+  // Only when sent: a new contact is never hidden by default.
+  if (has('hidden')) {
+    if (typeof input.hidden !== 'boolean') throw invalid('hidden must be true or false');
+    out.hidden = input.hidden;
+  }
   return out;
 }
 
@@ -88,6 +93,22 @@ function duplicate(error, kind) {
   throw error;
 }
 
+// A hidden contact of that name (not a client, docs/CONTACTS.md) is the usual
+// reason when the lists do not show it: say so. Read before the write, so a
+// caller's transaction is never left aborted.
+async function refuseHiddenName(db, organisationId, { kind, name }) {
+  // Another name of a contact (a merge kept it): that contact is the one.
+  const [alias] = await db.select({ id: contacts.id, name: contacts.name }).from(contacts).where(and(
+    eq(contacts.organisationId, organisationId), eq(contacts.kind, kind), isNull(contacts.mergedIntoId),
+    sql`${contacts.aliases} @> ${JSON.stringify([name])}::jsonb`,
+  )).limit(1);
+  if (alias) throw new FlowError('conflict', `${alias.name} has this name as another name. Use that one.`, { contactId: alias.id });
+  const [same] = await db.select({ id: contacts.id }).from(contacts).where(and(
+    eq(contacts.organisationId, organisationId), eq(contacts.kind, kind), eq(contacts.name, name), eq(contacts.hidden, true),
+  ));
+  if (same) throw new FlowError('conflict', `A hidden ${kind} with this name exists. Show it in Contacts, Hidden.`, { contactId: same.id });
+}
+
 export function presentContact(row) {
   return {
     id: row.id,
@@ -104,6 +125,9 @@ export function presentContact(row) {
     address: row.address ?? null,
     practitioners: row.practitioners ?? [],
     active: row.active !== false,
+    hidden: row.hidden === true,
+    aliases: row.aliases ?? [],
+    mergedIntoId: row.mergedIntoId ?? null,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
   };
@@ -111,6 +135,7 @@ export function presentContact(row) {
 
 export async function createContact(db, organisationId, input) {
   const values = readContact(input);
+  await refuseHiddenName(db, organisationId, values);
   try {
     const [row] = await db.insert(contacts).values({ organisationId, ...values }).returning();
     return row;
@@ -130,6 +155,16 @@ export async function updateContact(db, organisationId, id, input) {
   const current = await getContact(db, organisationId, id);
   const patch = readContact(input, { partial: true });
   if (!Object.keys(patch).length) return current;
+  if (current.mergedIntoId) throw invalid('this contact was merged into another; change that one');
+  // Bill to joins customers only (docs/CONTACTS.md).
+  if (patch.kind && patch.kind !== current.kind) {
+    const [billing] = await db.select({ id: customerBillingSettings.contactId }).from(customerBillingSettings).where(and(
+      eq(customerBillingSettings.organisationId, organisationId),
+      or(and(eq(customerBillingSettings.contactId, id), isNotNull(customerBillingSettings.billToContactId)),
+        eq(customerBillingSettings.billToContactId, id)),
+    )).limit(1);
+    if (billing) throw invalid('this customer is in a Bill to; clear Bill to first');
+  }
   try {
     const [row] = await db.update(contacts)
       .set({ ...patch, updatedAt: sql`now()` })
@@ -142,15 +177,21 @@ export async function updateContact(db, organisationId, id, input) {
 }
 
 // `kind` null lists customers and suppliers. `active` null lists both.
-export async function listContacts(db, organisationId, { q = '', kind = 'customer', active = true, limit = 200, offset = 0 } = {}) {
-  const where = [eq(contacts.organisationId, organisationId)];
+// `hidden` false (the default) leaves out the contacts that are not clients
+// (docs/CONTACTS.md, "Hidden contacts"); true lists only those; null, both.
+export async function listContacts(db, organisationId, { q = '', kind = 'customer', active = true, hidden = false, limit = 200, offset = 0 } = {}) {
+  // A merged contact is in no list (docs/CONTACTS.md, "Merge two contacts").
+  const where = [eq(contacts.organisationId, organisationId), isNull(contacts.mergedIntoId)];
   if (kind) where.push(eq(contacts.kind, kind));
   if (active === true) where.push(eq(contacts.active, true));
   if (active === false) where.push(eq(contacts.active, false));
+  if (hidden === true) where.push(eq(contacts.hidden, true));
+  if (hidden === false) where.push(eq(contacts.hidden, false));
   const needle = String(q ?? '').trim().replace(/[\\%_]/g, (c) => `\\${c}`);
   if (needle) {
     const like = `%${needle}%`;
-    where.push(or(ilike(contacts.name, like), ilike(contacts.email, like), ilike(contacts.accountNumber, like)));
+    where.push(or(ilike(contacts.name, like), ilike(contacts.email, like), ilike(contacts.accountNumber, like),
+      sql`${contacts.aliases}::text ilike ${like}`));
   }
   const rows = await db.select().from(contacts).where(and(...where))
     .orderBy(asc(contacts.name), asc(contacts.id))
@@ -158,3 +199,36 @@ export async function listContacts(db, organisationId, { q = '', kind = 'custome
     .offset(offset);
   return rows.map(presentContact);
 }
+
+// Bill to (docs/CONTACTS.md): the contact each customer's work is billed to
+// in the accounting system. A customer with a payer bills to the payer; any
+// other bills to itself. Answers a map for every id given.
+export async function payersOf(db, organisationId, contactIds) {
+  const ids = [...new Set(contactIds.filter(Boolean))];
+  const out = new Map(ids.map((id) => [id, id]));
+  if (!ids.length) return out;
+  const rows = await db.select({ contactId: customerBillingSettings.contactId, payer: customerBillingSettings.billToContactId })
+    .from(customerBillingSettings)
+    .where(and(eq(customerBillingSettings.organisationId, organisationId), inArray(customerBillingSettings.contactId, ids),
+      isNotNull(customerBillingSettings.billToContactId)));
+  for (const r of rows) out.set(r.contactId, r.payer);
+  return out;
+}
+
+// The customers that bill to each payer given, the payer included.
+export async function billedBy(db, organisationId, payerIds) {
+  const ids = [...new Set(payerIds.filter(Boolean))];
+  const out = new Map(ids.map((id) => [id, new Set([id])]));
+  if (!ids.length) return out;
+  const rows = await db.select({ contactId: customerBillingSettings.contactId, payer: customerBillingSettings.billToContactId })
+    .from(customerBillingSettings)
+    .where(and(eq(customerBillingSettings.organisationId, organisationId), inArray(customerBillingSettings.billToContactId, ids)));
+  for (const r of rows) out.get(r.payer).add(r.contactId);
+  return out;
+}
+
+// The contact one customer is billed as: its payer, else itself.
+export async function billedContact(db, organisationId, contactId) {
+  const payer = (await payersOf(db, organisationId, [contactId])).get(contactId);
+  return getContact(db, organisationId, payer);
+}

package/server/core/invoice-rules.js

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
-import { billingObligations, invoiceRuleExceptions, invoiceRules, invoicingSettings, obligationEvents, priceItems } from '../db/schema.js';
+import { billingObligations, contacts, invoiceRuleExceptions, invoiceRules, invoicingSettings, obligationEvents, priceItems } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 import { getInvoice, updateDraftInvoice } from './invoices.js';
 
@@ -466,9 +466,21 @@ async function checkRuleItem(db, organisationId, rule) {
   if (item.archivedAt) throw invalid(`price item ${code} is archived`);
 }
 
+// A rule never names a merged contact: it could never match
+// (docs/CONTACTS.md, "Merge two contacts").
+async function checkRuleCustomers(db, organisationId, rule) {
+  const ids = rule.conditions.filter((c) => c.field === 'customer' && c.value != null && !['contains', 'does_not_contain'].includes(c.test))
+    .flatMap((c) => (Array.isArray(c.value) ? c.value : [c.value])).filter((id) => /^[0-9a-f-]{36}$/i.test(id));
+  if (!ids.length) return;
+  const [merged] = await db.select({ name: contacts.name }).from(contacts).where(and(eq(contacts.organisationId, organisationId),
+    inArray(contacts.id, ids), sql`${contacts.mergedIntoId} is not null`)).limit(1);
+  if (merged) throw invalid('a customer in this rule was merged into another; pick that one');
+}
+
 export async function createRule(db, organisationId, raw, { personId = null } = {}) {
   const rule = readRule(raw);
   await checkRuleItem(db, organisationId, rule);
+  await checkRuleCustomers(db, organisationId, rule);
   const existing = await listRules(db, organisationId);
   if (existing.length >= MAX_RULES) throw invalid(`an organisation can have ${MAX_RULES} rules at most`);
   const position = existing.length ? Math.max(...existing.map((r) => r.position)) + 1 : 0;
@@ -489,6 +501,7 @@ export async function updateRule(db, organisationId, ruleId, changes, { personId
   if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw invalid('the change must be an object');
   const rule = readRule({ name: row.name, icon: row.icon, enabled: row.enabled, conditions: row.conditions, action: row.action, ...changes });
   if (rule.action.addItem && rule.action.addItem !== row.action?.addItem) await checkRuleItem(db, organisationId, rule);
+  if (Object.prototype.hasOwnProperty.call(changes, 'conditions')) await checkRuleCustomers(db, organisationId, rule);
   const [saved] = await db.update(invoiceRules).set({ ...rule, updatedBy: personId, updatedAt: sql`now()` })
     .where(eq(invoiceRules.id, row.id)).returning();
   return shape(saved);

package/server/core/invoices.js

@@ -81,6 +81,7 @@ export async function createDraftInvoice(db, organisationId, { contactId, refere
       .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, contactId)));
     if (!contact) throw new FlowError('invalid', 'contact not found');
     if (contact.kind !== 'customer') throw new FlowError('invalid', 'an invoice goes to a customer contact');
+    if (contact.mergedIntoId) throw new FlowError('invalid', 'this contact was merged into another; pick that one');
     const resolved = await resolveLines(tx, organisationId, lines);
     const [invoice] = await tx.insert(invoices)
       .values({ organisationId, contactId, reference, dueDate })
@@ -99,6 +100,7 @@ export async function updateDraftInvoice(db, organisationId, invoiceId, changes)
         .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, changes.contactId)));
       if (!contact) throw new FlowError('invalid', 'contact not found');
       if (contact.kind !== 'customer') throw new FlowError('invalid', 'an invoice goes to a customer contact');
+      if (contact.mergedIntoId) throw new FlowError('invalid', 'this contact was merged into another; pick that one');
       fields.contactId = changes.contactId;
     }
     if ('reference' in changes) fields.reference = changes.reference;

package/server/core/invoicing-rules.js

@@ -2,6 +2,7 @@ import { and, eq, inArray, isNull, sql } from 'drizzle-orm';
 import {
   billingObligations, contacts, customerBillingSettings, externalLinks, invoicingSettings, SEND_MODES,
 } from '../db/schema.js';
+import { payersOf } from './contacts.js';
 import { FlowError, notFound } from './errors.js';
 import { HISTORY_HOLD_REASON } from './history.js';
 import { accountingItemsFor, listRules, ruleNonChargeable, ruleReasons } from './invoice-rules.js';
@@ -38,8 +39,9 @@ export const INVOICING_DEFAULTS = Object.freeze({
 });
 
 const CUSTOMER_DEFAULTS = Object.freeze({
-  billable: true, defaultPractitioner: null, autoDraft: null, sendMode: null, paymentTermsDays: null,
+  billable: true, defaultPractitioner: null, autoDraft: null, sendMode: null, paymentTermsDays: null, billToContactId: null,
 });
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 const pick = (row, keys) => Object.fromEntries(keys.map((k) => [k, row[k]]));
 const SETTING_KEYS = Object.keys(INVOICING_DEFAULTS);
@@ -108,10 +110,11 @@ export async function saveInvoicingSettings(db, organisationId, changes, { perso
 }
 
 async function requireCustomer(db, organisationId, contactId) {
-  const [contact] = await db.select({ id: contacts.id, kind: contacts.kind }).from(contacts)
+  const [contact] = await db.select({ id: contacts.id, kind: contacts.kind, mergedIntoId: contacts.mergedIntoId }).from(contacts)
     .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, contactId)));
   if (!contact) throw notFound('customer');
   if (contact.kind !== 'customer') throw invalid('invoicing settings are for a customer contact');
+  return contact;
 }
 
 // One customer's own settings. A null value takes the organisation's setting.
@@ -124,7 +127,23 @@ export async function readCustomerBilling(db, organisationId, contactId) {
 
 export async function saveCustomerBilling(db, organisationId, contactId, changes, { personId = null } = {}) {
   if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw invalid('the settings must be an object');
-  await requireCustomer(db, organisationId, contactId);
+  const customer = await requireCustomer(db, organisationId, contactId);
+  if (customer.mergedIntoId) throw invalid('this customer was merged into another; change that one');
+  // Bill to is checked and saved under one lock per organisation, so two
+  // saves at once never make a chain of payers.
+  if (Object.prototype.hasOwnProperty.call(changes, 'billToContactId')) {
+    return db.transaction(async (tx) => {
+      await tx.execute(sql`select pg_advisory_xact_lock(hashtext(${`bill_to:${organisationId}`}))`);
+      // A merge takes the same lock: read again inside it.
+      if ((await requireCustomer(tx, organisationId, contactId)).mergedIntoId) throw invalid('this customer was merged into another; change that one');
+      return saveBilling(tx, organisationId, contactId, changes, personId);
+    });
+  }
+  return saveBilling(db, organisationId, contactId, changes, personId);
+}
+
+async function saveBilling(db, organisationId, contactId, changes, personId) {
+  const before = (await readCustomerBilling(db, organisationId, contactId)).billToContactId;
   const fields = {};
   for (const [key, value] of Object.entries(changes)) {
     if (key === 'billable') fields[key] = flag(value, key);
@@ -132,6 +151,7 @@ export async function saveCustomerBilling(db, organisationId, contactId, changes
     else if (key === 'autoDraft') fields[key] = value === null ? null : flag(value, key);
     else if (key === 'sendMode') fields[key] = value === null ? null : sendMode(value, key);
     else if (key === 'paymentTermsDays') fields[key] = value === null ? null : wholeNumber(value, key, 0, 365);
+    else if (key === 'billToContactId') fields[key] = await billTo(db, organisationId, contactId, value);
     else throw invalid(`unknown setting: ${key}`);
   }
   await db.insert(customerBillingSettings)
@@ -140,9 +160,38 @@ export async function saveCustomerBilling(db, organisationId, contactId, changes
       target: [customerBillingSettings.organisationId, customerBillingSettings.contactId],
       set: { ...fields, updatedBy: personId, updatedAt: sql`now()` },
     });
+  // A new payer is a new place to look: the matcher checks this customer's
+  // unbilled jobs again on its next pass.
+  if ('billToContactId' in fields && fields.billToContactId !== before) {
+    await db.update(billingObligations).set({ accountingCheckedAt: null, updatedAt: sql`now()` }).where(and(
+      eq(billingObligations.organisationId, organisationId), eq(billingObligations.contactId, contactId),
+      isNull(billingObligations.accountingRef), isNull(billingObligations.invoiceId),
+    ));
+  }
   return readCustomerBilling(db, organisationId, contactId);
 }
 
+// Bill to (docs/CONTACTS.md): another customer, the payer, whose accounting
+// contact this customer's work is billed to. One level only: a payer bills
+// to itself, and a customer that is a payer names no payer.
+async function billTo(db, organisationId, contactId, value) {
+  if (value === null) return null;
+  if (typeof value !== 'string' || !UUID.test(value)) throw invalid('billToContactId must name a customer');
+  if (value === contactId) throw invalid('a customer cannot bill to itself; clear Bill to instead');
+  const [payer] = await db.select({ id: contacts.id, kind: contacts.kind, name: contacts.name, mergedIntoId: contacts.mergedIntoId }).from(contacts)
+    .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, value)));
+  if (!payer) throw notFound('customer');
+  if (payer.kind !== 'customer') throw invalid('the payer must be a customer');
+  if (payer.mergedIntoId) throw invalid(`${payer.name} was merged into another customer; pick that one`);
+  const [payerOwn] = await db.select({ billTo: customerBillingSettings.billToContactId }).from(customerBillingSettings)
+    .where(and(eq(customerBillingSettings.organisationId, organisationId), eq(customerBillingSettings.contactId, value)));
+  if (payerOwn?.billTo) throw invalid(`${payer.name} bills to another customer; pick that one`);
+  const [billed] = await db.select({ id: customerBillingSettings.contactId }).from(customerBillingSettings)
+    .where(and(eq(customerBillingSettings.organisationId, organisationId), eq(customerBillingSettings.billToContactId, contactId))).limit(1);
+  if (billed) throw invalid('other customers bill to this customer, so it cannot bill to another');
+  return value;
+}
+
 // The customers' own settings, by contact id.
 export async function customerBillingByContact(db, organisationId, contactIds) {
   const ids = [...new Set(contactIds.filter(Boolean))];
@@ -263,9 +312,11 @@ const SAME_REFERENCE_DAYS = 90;
 export function copyCheck(accounting, organisationId, { db = null } = {}) {
   const contactOf = async (contactId) => {
     if (!db || !contactId) return null;
+    // A customer with a payer is billed under the payer's contact (Bill to).
+    const payer = (await payersOf(db, organisationId, [contactId])).get(contactId);
     const [link] = await db.select({ externalId: externalLinks.externalId }).from(externalLinks).where(and(
       eq(externalLinks.organisationId, organisationId), eq(externalLinks.system, accounting.id),
-      eq(externalLinks.entity, 'contact'), eq(externalLinks.state, 'active'), eq(externalLinks.flowId, contactId),
+      eq(externalLinks.entity, 'contact'), eq(externalLinks.state, 'active'), eq(externalLinks.flowId, payer),
     ));
     return link?.externalId ?? null;
   };

package/server/core/ledger.js

@@ -828,6 +828,26 @@ export async function freeVoidedJob(db, organisationId, obligationId, { actor, r
   });
 }
 
+// A person found that the accounting invoice a job points at is not its bill
+// (a wrong pair). The job lets go of it: it is unchecked again, and the
+// matcher never pairs the two again. Nothing else on the job changes. A job
+// that still holds a Flow invoice keeps it; free that first.
+export async function releaseAccountingRef(db, organisationId, obligationId, { accountingRef, system, actor, reason }) {
+  requireActor(actor);
+  if (!reason?.trim()) throw new FlowError('invalid', 'say why the accounting invoice is released');
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    if (obligation.accountingRef !== accountingRef) return obligation;
+    if (obligation.invoiceId) throw new FlowError('invalid', 'the job still holds a Flow invoice: free it first');
+    const row = await update(tx, obligation, {
+      accountingState: 'unknown', accountingRef: null, accountingUrl: null, accountingMatchedBy: null, accountingCheckedAt: null,
+    });
+    await tx.insert(linkRejections).values({ organisationId, obligationId: obligation.id, system, externalId: accountingRef, actor }).onConflictDoNothing();
+    await addEvent(tx, row, 'accounting_released', actor, { released: accountingRef, reason: reason.trim(), from: obligation.accountingState });
+    return row;
+  });
+}
+
 // A job with no invoice of its own whose accounting evidence is ambiguous:
 // the matcher found accounting invoices that may be this job's, but none
 // exactly. Or the accounting invoice the matcher linked was voided or deleted
@@ -912,13 +932,16 @@ export async function linkJobToInvoice(db, organisationId, obligationId, { invoi
     // A job that waited for a person (no invoice found, or more than one fit)
     // is settled now: the matcher reads it again on its next pass and records
     // the invoice's stage. A link made from an accounting invoice
-    // (`accountingRef`) is exact, so the matcher follows that invoice.
+    // (`accountingRef`) is exact, so the matcher follows that invoice: the
+    // job is due on its next pass, whatever state it was in (a job with no
+    // accounting contact was `unknown`, checked, and would wait for the copy
+    // to change).
     const settled = ['not_found', 'ambiguous'].includes(obligation.accountingState);
     const row = await update(tx, obligation, {
       invoiceId: invoice.id,
       draftBasis: basisOf(obligation),
       ...(settled ? { accountingState: 'unknown', accountingCheckedAt: null } : {}),
-      ...(accountingRef && !obligation.accountingRef ? { accountingRef } : {}),
+      ...(accountingRef && !obligation.accountingRef ? { accountingRef, accountingCheckedAt: null } : {}),
       ...(obligation.readyAt ? {} : { readyAt: sql`now()`, readyBy: actor }),
     });
     await addEvent(tx, row, 'invoice_linked', actor, { invoiceId: invoice.id, matchedBy: 'person', rejected });

package/server/core/merge-contacts.js

@@ -0,0 +1,182 @@
+import { sql } from 'drizzle-orm';
+import { FlowError, notFound } from './errors.js';
+
+// Merge two contacts (docs/CONTACTS.md, "Merge two contacts"). One client is
+// sometimes two Flow contacts: the work system's name and the accounting
+// system's longer name. A person merges them in one step. The kept contact
+// gets the other's jobs, invoices, links, rule values and Bill to rows, and
+// keeps its name as an alias. The merged row stays, out of every list; Flow
+// never deletes it and never merges without a person.
+
+const invalid = (message, details) => new FlowError('invalid', message, details);
+const conflict = (message, details) => new FlowError('conflict', message, details);
+
+const ID_TESTS = new Set(['is', 'is_not', 'is_one_of', 'is_not_one_of']);
+
+// A rule's conditions with the merged contact's id changed to the kept one,
+// or null when no condition names it.
+export function rewriteConditions(conditions, fromId, keepId) {
+  let changed = false;
+  const out = (conditions ?? []).map((c) => {
+    if (c?.field !== 'customer' || !ID_TESTS.has(c.test)) return c;
+    if (Array.isArray(c.value)) {
+      if (!c.value.includes(fromId)) return c;
+      changed = true;
+      return { ...c, value: [...new Set(c.value.map((v) => (v === fromId ? keepId : v)))] };
+    }
+    if (c.value !== fromId) return c;
+    changed = true;
+    return { ...c, value: keepId };
+  });
+  return changed ? out : null;
+}
+
+async function lockedContact(tx, organisationId, id) {
+  const { rows: [row] } = await tx.execute(sql`select id, kind, name, aliases, merged_into_id from contacts
+    where organisation_id = ${organisationId} and id = ${id} for update`);
+  if (!row) throw notFound('contact');
+  return row;
+}
+
+// Answers what moved: { keep, from, moved: { jobs, invoices, links, rules, billTo } }.
+export async function mergeContacts(db, organisationId, { keepId, fromId, actor }) {
+  if (!actor) throw new TypeError('actor is required');
+  if (!keepId || !fromId) throw invalid('keepId and fromId are required');
+  if (keepId === fromId) throw invalid('pick two different contacts');
+  return db.transaction(async (tx) => {
+    // The same lock as Bill to, so a Bill to save and a merge take turns.
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtext(${`bill_to:${organisationId}`}))`);
+    const [first, second] = [keepId, fromId].sort();
+    const rows = new Map();
+    for (const id of [first, second]) rows.set(id, await lockedContact(tx, organisationId, id));
+    const keep = rows.get(keepId);
+    const from = rows.get(fromId);
+    if (keep.merged_into_id || from.merged_into_id) throw conflict('one of these contacts was already merged');
+    if (keep.kind !== from.kind) throw invalid('a customer merges only with a customer, a supplier only with a supplier');
+
+    // Links: the kept contact may hold one active link for each system.
+    const { rows: links } = await tx.execute(sql`select id, system, external_id, state, flow_id from external_links
+      where organisation_id = ${organisationId} and entity = 'contact' and flow_id in (${keepId}, ${fromId}) and state <> 'superseded'`);
+    const activeKeep = new Map(links.filter((l) => l.flow_id === keepId && l.state === 'active').map((l) => [l.system, l]));
+    for (const l of links) {
+      if (l.flow_id === fromId && l.state === 'active' && activeKeep.has(l.system)) {
+        throw conflict(`both contacts are linked in ${l.system}; keep one link first`, { system: l.system });
+      }
+    }
+
+    // Bill to stays one level (docs/CONTACTS.md, "Bill to").
+    const { rows: billing } = await tx.execute(sql`select contact_id, bill_to_contact_id from customer_billing_settings
+      where organisation_id = ${organisationId} and (contact_id in (${keepId}, ${fromId}) or bill_to_contact_id in (${keepId}, ${fromId}))`);
+    const own = (id) => billing.find((b) => b.contact_id === id) ?? null;
+    const payerOf = (id) => own(id)?.bill_to_contact_id ?? null;
+    const outside = (id) => (id === keepId || id === fromId ? null : id);
+    const keepPayer = outside(payerOf(keepId));
+    const fromPayer = outside(payerOf(fromId));
+    if (keepPayer && fromPayer && keepPayer !== fromPayer) throw conflict('the two contacts bill to different payers; clear one Bill to first');
+    // The kept contact bills to the payer either one had.
+    const payer = keepPayer ?? fromPayer;
+    const clients = billing.filter((b) => [keepId, fromId].includes(b.bill_to_contact_id) && ![keepId, fromId].includes(b.contact_id));
+    if (payer && clients.length) throw conflict('the merged contact would bill to a payer and be a payer; clear Bill to first');
+
+    // Jobs: each moved job notes the merge, and an unbilled one goes back to
+    // the matcher under its new customer.
+    const { rows: jobs } = await tx.execute(sql`update billing_obligations set contact_id = ${keepId},
+        draft_basis = case when draft_basis->>'contactId' = ${fromId} then jsonb_set(draft_basis, '{contactId}', to_jsonb(${keepId}::text)) else draft_basis end,
+        updated_at = now()
+      where organisation_id = ${organisationId} and contact_id = ${fromId} returning id`);
+    if (jobs.length) {
+      const evidence = JSON.stringify({ from: fromId, to: keepId });
+      await tx.execute(sql`insert into obligation_events (organisation_id, obligation_id, kind, actor, evidence)
+        select ${organisationId}, id, 'contact_merged', ${actor}, ${evidence}::jsonb from unnest(${sql.param(jobs.map((j) => j.id))}::uuid[]) as id`);
+    }
+    const { rows: invoices } = await tx.execute(sql`update invoices set contact_id = ${keepId}, updated_at = now()
+      where organisation_id = ${organisationId} and contact_id = ${fromId} returning id`);
+
+    // Links move; a guess that the kept contact already answers is closed,
+    // with its review item.
+    let movedLinks = 0;
+    for (const l of links.filter((x) => x.flow_id === fromId)) {
+      if (l.state === 'proposed' && activeKeep.has(l.system)) {
+        await tx.execute(sql`update external_links set state = 'superseded', updated_at = now() where id = ${l.id}`);
+        await tx.execute(sql`update review_items set state = 'resolved', resolution = 'contact_merged', resolved_by = ${actor},
+            resolved_at = now(), updated_at = now()
+          where organisation_id = ${organisationId} and entity = 'contact' and flow_id = ${fromId} and state = 'open'
+            and kind = 'link.proposed' and evidence->>'linkId' = ${l.id}`);
+        continue;
+      }
+      await tx.execute(sql`update external_links set flow_id = ${keepId}, updated_at = now() where id = ${l.id}`);
+      movedLinks += 1;
+    }
+
+    // Rules that name the merged contact name the kept one.
+    const { rows: rules } = await tx.execute(sql`select id, conditions from invoice_rules
+      where organisation_id = ${organisationId} and conditions::text like ${`%${fromId}%`}`);
+    let movedRules = 0;
+    for (const rule of rules) {
+      const next = rewriteConditions(rule.conditions, fromId, keepId);
+      if (!next) continue;
+      await tx.execute(sql`update invoice_rules set conditions = ${JSON.stringify(next)}::jsonb, updated_at = now() where id = ${rule.id}`);
+      movedRules += 1;
+    }
+
+    // Bill to: clients of the merged contact bill to the kept one. The kept
+    // contact takes the merged one's own row when it has none, and bills to
+    // the payer either had. The merged contact's leftover row names no payer.
+    const { rows: billTo } = await tx.execute(sql`update customer_billing_settings
+      set bill_to_contact_id = case when contact_id = ${keepId} then null else ${keepId}::uuid end, updated_at = now()
+      where organisation_id = ${organisationId} and bill_to_contact_id = ${fromId} returning contact_id`);
+    let movedBillTo = billTo.filter((b) => b.contact_id !== keepId).length;
+    if (own(fromId) && !own(keepId)) {
+      await tx.execute(sql`update customer_billing_settings set contact_id = ${keepId}, bill_to_contact_id = ${payer}, updated_at = now()
+        where organisation_id = ${organisationId} and contact_id = ${fromId}`);
+      movedBillTo += 1;
+    } else {
+      if (own(keepId)) {
+        await tx.execute(sql`update customer_billing_settings set bill_to_contact_id = ${payer}, updated_at = now()
+          where organisation_id = ${organisationId} and contact_id = ${keepId}`);
+      }
+      if (own(fromId)) {
+        await tx.execute(sql`update customer_billing_settings set bill_to_contact_id = null, updated_at = now()
+          where organisation_id = ${organisationId} and contact_id = ${fromId}`);
+      }
+    }
+
+    // Every unbilled job of the kept contact, and of the clients that bill to
+    // it, goes back to the matcher: its links and payer may have changed.
+    await tx.execute(sql`update billing_obligations set accounting_checked_at = null
+      where organisation_id = ${organisationId} and accounting_ref is null and invoice_id is null
+        and (contact_id = ${keepId} or contact_id in (select contact_id from customer_billing_settings
+          where organisation_id = ${organisationId} and bill_to_contact_id = ${keepId}))`);
+
+    // Open review items of the merged contact go to the kept one, unless it
+    // has one of the same kind open; those close.
+    await tx.execute(sql`update review_items r set flow_id = ${keepId}, updated_at = now()
+      where r.organisation_id = ${organisationId} and r.entity = 'contact' and r.flow_id = ${fromId} and r.state = 'open'
+        and not exists (select 1 from review_items o where o.organisation_id = r.organisation_id and o.kind = r.kind
+          and o.entity = 'contact' and o.flow_id = ${keepId} and o.state = 'open')`);
+    await tx.execute(sql`update review_items set state = 'resolved', resolution = 'contact_merged', resolved_by = ${actor},
+        resolved_at = now(), updated_at = now()
+      where organisation_id = ${organisationId} and entity = 'contact' and flow_id = ${fromId} and state = 'open'`);
+
+    // The names: the kept contact answers to the merged one's names too.
+    const names = [from.name, ...(from.aliases ?? []), ...(keep.aliases ?? [])];
+    const aliases = [...new Set(names.filter((n) => n && n !== keep.name))].slice(0, 20);
+    await tx.execute(sql`update contacts set aliases = ${JSON.stringify(aliases)}::jsonb, updated_at = now()
+      where organisation_id = ${organisationId} and id = ${keepId}`);
+    // The merged row frees its name, so the kept contact can take it; the
+    // name lives on as the kept contact's alias. Earlier merges into the
+    // merged contact point at the kept one.
+    const freed = `${from.name.slice(0, 230)} (merged ${fromId.slice(0, 8)})`;
+    await tx.execute(sql`update contacts set merged_into_id = ${keepId}, merged_at = now(), merged_by = ${actor},
+        name = ${freed}, hidden = true, active = false, updated_at = now()
+      where organisation_id = ${organisationId} and id = ${fromId}`);
+    await tx.execute(sql`update contacts set merged_into_id = ${keepId}, updated_at = now()
+      where organisation_id = ${organisationId} and merged_into_id = ${fromId}`);
+
+    return {
+      keep: keepId,
+      from: fromId,
+      moved: { jobs: jobs.length, invoices: invoices.length, links: movedLinks, rules: movedRules, billTo: movedBillTo },
+    };
+  });
+}