@arcforgelabs/flow 2026.10.37 → 2026.10.38

package/README.md

@@ -55,6 +55,7 @@ run a lab.
 | `docs/REPLIT.md` | A Replit workspace of this repository that follows a release channel (`FLOW_DEPLOY_REF`) |
 | `docs/INTEGRATIONS.md` | How an integration adapter is built, turned on and off, and owns its tables |
 | `docs/XERO.md` | The Xero adapter: modes, settings, rate limits, connecting Xero and draft invoices |
+| `docs/XERO_IMPORT.md` | Xero › Import: each Xero invoice in Flow's copy linked to its Flow invoice, or made into one |
 | `docs/SEAZONA.md` | The Seazona adapter: modes, settings, the rate governor, replay files and its tables |
 | `docs/SENTRY.md` | The Sentry adapter: errors and problem reports to the installation's own Sentry project |
 | `server/integrations/port.js` | The integration port every adapter implements |

package/npm-shrinkwrap.json

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

package/package.json

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

package/server/api/custom-fields.js

@@ -1,6 +1,6 @@
 import express from 'express';
 import {
-  CUSTOM_FIELD_TYPES, GROUPABLE_TYPES, OPTION_COLORS, archiveField, choosablePeople, createField, jobFieldHistory, listFields,
+  CUSTOM_FIELD_TYPES, GROUPABLE_TYPES, OPTION_COLORS, archiveField, choosablePeople, createField, ensureAssignee, jobFieldHistory, listFields,
   listJobFieldValues, orderFields, setJobFieldValue, updateField,
 } from '../core/custom-fields.js';
 import { FlowError } from '../core/errors.js';
@@ -71,6 +71,7 @@ export function createCustomFieldsRouter({ db, personAuth, work = () => [], log
   router.get('/', ...signedIn, handle(async (req, res) => {
     const organisationId = await organisationOf(req);
     const archived = req.query.archived === '1' || req.query.archived === 'true';
+    await ensureAssignee(db, organisationId);
     const [fields, system, chosen] = await Promise.all([listFields(db, organisationId, { archived }), systemFields(), choosablePeople(db)]);
     res.json({ ok: true, fields, systemFields: system, people: chosen, types: CUSTOM_FIELD_TYPES, groupable: GROUPABLE_TYPES, colors: OPTION_COLORS });
   }));

package/server/api/invoicing.js

@@ -17,12 +17,14 @@ import {
 } from '../core/invoicing-rules.js';
 import { boardJobs, describeObligations } from '../core/job-board.js';
 import { readBeforeAct } from '../core/read-before-act.js';
+import { invoiceMatchDetail, jobMatchDetail, listReconcile } from '../core/job-match.js';
 import { jobReference } from '../core/references.js';
 import {
   acceptFindings, archivePriceItem, checkPrices, createPriceItem, linkPriceItem, readCatalogues, readPriceList, unlinkPriceItem, updatePriceItem,
 } from '../core/price-list.js';
 import {
-  draftInvoiceForObligation, explainObligation, jobChangeFor, listObligations, setReady, useSourceLines,
+  confirmNoInvoice, draftInvoiceForObligation, explainObligation, jobChangeFor, linkJobToInvoice, listObligations,
+  setReady, useSourceLines,
 } from '../core/ledger.js';
 import { isHistoryHeld } from '../core/history.js';
 import { invoicePdfDocument, pdfFields, pdfFilename, renderInvoicePdf } from '../core/invoice-pdf.js';
@@ -588,6 +590,53 @@ export function createInvoicingRouter({
     res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoice.id, accounting(), work()) });
   }));
 
+  // A job with no invoice whose match is unclear (ledger.js). The linking
+  // tool lists the matcher's suggestions, read from the accounting copy;
+  // "Make invoice" says there is none yet; "Link" picks one of them.
+  // The Reconcile page: Flow's jobs with no Flow invoice, Flow invoices with
+  // no job, and one of them beside its possible other side
+  // (core/job-match.js). Flow's own records only; no integration is called.
+  router.get('/reconcile', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, ...await listReconcile(db, organisationId) });
+  }));
+
+  router.get('/jobs/:id/reconcile', ...signedIn, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const [obligation] = await db.select().from(billingObligations)
+      .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId)));
+    if (!obligation) throw new FlowError('not_found', 'job not found');
+    // The Reference Flow would give its invoice, from Flow's own copy only.
+    const { referenceTemplate: template } = await readInvoicingSettings(db, organisationId);
+    const source = work().find((a) => a.id === obligation.sourceSystem) ?? null;
+    const reference = await jobReference(db, organisationId, obligation, { template, work: source });
+    const detail = await jobMatchDetail(db, organisationId, obligationId, { reference, q: text(req.query.q) ?? '' });
+    res.json({ ok: true, ...detail, job: { ...detail.job, sourceName: source?.name ?? null } });
+  }));
+
+  router.get('/invoices/:id/reconcile', ...signedIn, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, ...await invoiceMatchDetail(db, organisationId, invoiceId, { q: text(req.query.q) ?? '' }) });
+  }));
+
+  router.post('/jobs/:id/no-invoice', ...manager, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const job = await confirmNoInvoice(db, organisationId, obligationId, { actor: `person:${req.person.id}` });
+    res.json({ ok: true, job: { id: job.id, accountingState: job.accountingState } });
+  }));
+
+  // Links a job to a Flow invoice that already exists.
+  router.post('/jobs/:id/link', ...manager, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const invoiceId = pathId(text(req.body?.invoiceId) ?? '', 'invoice');
+    const job = await linkJobToInvoice(db, organisationId, obligationId, { invoiceId, actor: `person:${req.person.id}` });
+    res.json({ ok: true, job: { id: job.id, invoiceId: job.invoiceId } });
+  }));
+
   router.post('/jobs/:id/ready', ...signedIn, handle(log, async (req, res) => {
     const obligationId = pathId(req.params.id, 'job');
     const organisationId = await organisationOf(req);

package/server/core/custom-fields.js

@@ -133,6 +133,24 @@ export async function createField(db, organisationId, raw, { personId = null } =
   });
 }
 
+// Every lab gets an Assignee: a person field, made once, the first time
+// the lab's fields are read and it has no person field at all (live or
+// archived). The lab can then rename it or archive it like any field, and
+// Flow does not make it again. A field already named Assignee of another
+// type is left alone.
+export const ASSIGNEE = { name: 'Assignee', type: 'person' };
+export async function ensureAssignee(db, organisationId) {
+  const [{ count }] = await db.select({ count: sql`count(*)`.mapWith(Number) }).from(jobFields)
+    .where(and(eq(jobFields.organisationId, organisationId), eq(jobFields.type, 'person')));
+  if (count > 0) return null;
+  try {
+    return await createField(db, organisationId, ASSIGNEE);
+  } catch (error) {
+    if (error.code === 'conflict' || error.code === 'invalid' || error.code === '23505') return null;
+    throw error;
+  }
+}
+
 export async function updateField(db, organisationId, id, raw, { personId = null } = {}) {
   const previous = await readRow(db, organisationId, id);
   if (previous.archivedAt) throw new FlowError('conflict', 'the field is archived; bring it back first');

package/server/core/job-board.js

@@ -102,7 +102,7 @@ export async function boardJobs(db, organisationId, { work = [], accounting = nu
       if (status && !statuses.has(status)) statuses.set(status, { label: status, final: false, firstSeenAt: null });
       return {
         sourceSystem: o.sourceSystem, sourceJobRef: o.sourceJobRef, caseRef: o.caseRef, status,
-        clientName: o.contactName, workClientName: null, practitioner: o.practitioner, department: null,
+        clientName: o.contactName, workClientName: null, practitioner: o.practitioner, patient: null, department: null,
         orderedOn: null, dueOn: null, jobDate: o.jobDate, shippedOn: o.shippedOn,
         totalCents: o.totalCents, lines: ledgerLines(o.lines), obligation: o,
       };
@@ -129,6 +129,7 @@ export async function boardJobs(db, organisationId, { work = [], accounting = nu
         workClientName: item.clientName ?? null,
         practitioner: item.practitioner ?? o?.practitioner ?? null,
         department: item.department ?? null,
+        patient: item.patient ?? null,
         orderedOn: item.orderedOn ?? null,
         dueOn: item.dueOn ?? null,
         jobDate: o?.jobDate ?? null,

package/server/core/job-match.js

@@ -0,0 +1,241 @@
+import { and, asc, desc, eq, ilike, inArray, isNotNull, isNull, ne, or, sql } from 'drizzle-orm';
+import { billingObligations, contacts, invoiceLines, invoices, priceItems } from '../db/schema.js';
+import { notFound } from './errors.js';
+
+// The Reconcile page (docs/JOB_INVOICE_LINKS.md, "Reconcile"): Flow's own
+// jobs against Flow's own invoices. A job that is ready to invoice and has
+// no Flow invoice, and a Flow invoice that no job is linked to, are gaps.
+// For one of them it lists the possible other side, each fact compared. It
+// only reads; linkJobToInvoice and confirmNoInvoice (ledger.js) write.
+// Matching a Flow invoice to one in an accounting system is that
+// integration's own work, not this page's.
+
+// A job with no Flow invoice that should have one: ready, not held, and not
+// tied to an accounting invoice by the earlier matcher.
+const JOB_GAP = and(
+  isNotNull(billingObligations.readyAt),
+  isNull(billingObligations.invoiceId),
+  isNull(billingObligations.accountingRef),
+  ne(billingObligations.holdState, 'held'),
+);
+
+const hasJob = sql`exists (select 1 from billing_obligations o
+  where o.organisation_id = ${invoices.organisationId} and o.invoice_id = ${invoices.id})`;
+
+const SAME = 'same';
+const DIFFERS = 'differs';
+const daysApart = (a, b) => Math.round((Date.parse(b) - Date.parse(a)) / 86_400_000);
+const norm = (text) => String(text ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+const WINDOW_DAYS = 60;
+// An invoice's date: its issue date, or the day a draft was made.
+const dateOf = (i) => i.issueDate ?? (i.createdAt ? new Date(i.createdAt).toISOString().slice(0, 10) : null);
+const SHOWN = 3;
+const SEARCHED = 8;
+
+// One fact against the other side's: `same`, `differs`, or null when either
+// side does not know.
+function compare(ours, theirs) {
+  if (ours == null || ours === '' || theirs == null || theirs === '') return null;
+  return norm(ours) === norm(theirs) ? SAME : DIFFERS;
+}
+
+// Two sets of lines, the same price items and amounts in any order.
+function compareLines(a, b) {
+  if (!a.length || !b.length) return null;
+  const key = (l) => `${l.priceItemId ?? norm(l.code)}|${l.amountCents ?? ''}`;
+  return a.map(key).sort().join(',') === b.map(key).sort().join(',') ? SAME : DIFFERS;
+}
+
+// A job line's amount before tax.
+function lineCents(line) {
+  if (line.lineAmountCents != null) return line.lineAmountCents;
+  if (line.unitAmountCents == null) return null;
+  return line.unitAmountCents * (line.quantity ?? 1);
+}
+
+// Every fact of one candidate against the record it may belong to. `a` and
+// `b` are { contactId, reference, date, lines, totalCents }.
+function checksOf(a, b, otherCount) {
+  return {
+    client: a.contactId && b.contactId ? (a.contactId === b.contactId ? SAME : DIFFERS) : null,
+    reference: compare(a.reference, b.reference),
+    date: a.date && b.date ? { days: daysApart(a.date, b.date) } : null,
+    lines: compareLines(a.lines, b.lines),
+    total: a.totalCents == null || b.totalCents == null ? null : a.totalCents === b.totalCents ? SAME : DIFFERS,
+    others: otherCount,
+  };
+}
+
+// Higher is a better match: the total, the lines, the Reference, the date,
+// and not taken by another record.
+function scoreOf(c) {
+  return (c.total === SAME ? 4 : 0) + (c.lines === SAME ? 3 : 0) + (c.reference === SAME ? 3 : 0) + (c.client === SAME ? 2 : 0)
+    + (c.date && Math.abs(c.date.days) <= 3 ? 1 : 0) - (c.others ? 2 : 0);
+}
+
+async function codesFor(db, organisationId, ids) {
+  if (!ids.length) return new Map();
+  const rows = await db.select({ id: priceItems.id, code: priceItems.code }).from(priceItems)
+    .where(and(eq(priceItems.organisationId, organisationId), inArray(priceItems.id, ids)));
+  return new Map(rows.map((r) => [r.id, r.code]));
+}
+
+function jobLines(o, codes) {
+  return (o.lines ?? []).map((l) => ({
+    priceItemId: l.priceItemId ?? null, code: l.itemCode ?? codes.get(l.priceItemId) ?? null, description: l.description ?? null, amountCents: lineCents(l),
+  }));
+}
+
+// The two queues, oldest first. jobs: { id, clientName, practitioner,
+// jobDate, totalCents, possible }; invoices: { id, number, clientName,
+// issueDate, status, totalCents, possible }. `possible` counts the other
+// side with the same client and total.
+export async function listReconcile(db, organisationId) {
+  const jobs = await db.select({
+    id: billingObligations.id,
+    clientName: contacts.name,
+    practitioner: billingObligations.practitioner,
+    jobDate: billingObligations.jobDate,
+    totalCents: billingObligations.totalCents,
+    possible: sql`(select count(*) from invoices i
+      where i.organisation_id = ${billingObligations.organisationId} and i.contact_id = ${billingObligations.contactId}
+        and i.status <> 'void' and i.total_cents = ${billingObligations.totalCents}
+        and not exists (select 1 from billing_obligations x where x.organisation_id = i.organisation_id and x.invoice_id = i.id))`.mapWith(Number),
+  }).from(billingObligations)
+    .leftJoin(contacts, eq(contacts.id, billingObligations.contactId))
+    .where(and(eq(billingObligations.organisationId, organisationId), JOB_GAP))
+    .orderBy(sql`${billingObligations.jobDate} asc nulls last`, asc(billingObligations.createdAt));
+  const lonely = await db.select({
+    id: invoices.id,
+    number: invoices.number,
+    clientName: contacts.name,
+    issueDate: sql`coalesce(${invoices.issueDate}, ${invoices.createdAt}::date)::text`,
+    status: invoices.status,
+    totalCents: invoices.totalCents,
+    possible: sql`(select count(*) from billing_obligations o
+      where o.organisation_id = ${invoices.organisationId} and o.contact_id = ${invoices.contactId}
+        and o.invoice_id is null and o.accounting_ref is null and o.total_cents = ${invoices.totalCents})`.mapWith(Number),
+  }).from(invoices)
+    .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+    .where(and(eq(invoices.organisationId, organisationId), ne(invoices.status, 'void'), sql`not ${hasJob}`))
+    .orderBy(sql`${invoices.issueDate} asc nulls last`, asc(invoices.createdAt));
+  return { jobs, invoices: lonely };
+}
+
+// One job and the Flow invoices that may be its own, best first. With `q`,
+// any Flow invoice whose number, client, Reference or total matches.
+// `reference` is the Reference Flow would give the job's invoice.
+export async function jobMatchDetail(db, organisationId, obligationId, { reference = null, q = '' } = {}) {
+  const [row] = await db.select({ obligation: billingObligations, clientName: contacts.name })
+    .from(billingObligations)
+    .leftJoin(contacts, eq(contacts.id, billingObligations.contactId))
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId)));
+  if (!row) throw notFound('job');
+  const o = row.obligation;
+  const codes = await codesFor(db, organisationId, (o.lines ?? []).map((l) => l.priceItemId).filter(Boolean));
+  const job = {
+    id: o.id,
+    clientName: row.clientName,
+    practitioner: o.practitioner,
+    reference,
+    jobDate: o.jobDate,
+    sourceSystem: o.sourceSystem,
+    sourceJobRef: o.sourceJobRef,
+    caseRef: o.caseRef,
+    sourceStatus: o.sourceStatus,
+    lines: jobLines(o, codes),
+    totalCents: o.totalCents,
+    open: !o.invoiceId && !o.accountingRef,
+    // An unclear accounting match: "Make invoice" settles it first.
+    unclear: o.accountingState === 'ambiguous',
+  };
+
+  const search = String(q ?? '').trim();
+  const where = [eq(invoices.organisationId, organisationId), ne(invoices.status, 'void')];
+  if (search) where.push(searchInvoices(search));
+  else {
+    if (!o.contactId) return { job, invoices: [] };
+    where.push(eq(invoices.contactId, o.contactId));
+    if (o.jobDate) where.push(sql`abs(coalesce(${invoices.issueDate}, ${invoices.createdAt}::date) - ${o.jobDate}::date) <= ${WINDOW_DAYS}`);
+  }
+  const found = await db.select({ invoice: invoices, clientName: contacts.name }).from(invoices)
+    .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+    .where(and(...where)).orderBy(desc(invoices.createdAt)).limit(50);
+  const detail = await invoiceFacts(db, organisationId, found.map((f) => f.invoice));
+  const ours = { contactId: o.contactId, reference, date: o.jobDate, lines: job.lines, totalCents: o.totalCents };
+  const ranked = found.map(({ invoice, clientName }) => {
+    const d = detail.get(invoice.id);
+    const checks = checksOf(ours, { contactId: invoice.contactId, reference: invoice.reference, date: dateOf(invoice), lines: d.lines, totalCents: invoice.totalCents }, d.jobs.length);
+    return {
+      id: invoice.id, number: invoice.number, clientName, issueDate: invoice.issueDate, date: dateOf(invoice), status: invoice.status,
+      reference: invoice.reference, lines: d.lines, totalCents: invoice.totalCents, jobs: d.jobs, checks, score: scoreOf(checks),
+    };
+  }).sort((a, b) => b.score - a.score).slice(0, search ? SEARCHED : SHOWN);
+  return { job, invoices: ranked.map((c, index) => ({ ...c, best: index === 0 && c.score > 0 })) };
+}
+
+// One Flow invoice with no job, and the jobs with no invoice that may be its
+// own, best first.
+export async function invoiceMatchDetail(db, organisationId, invoiceId, { q = '' } = {}) {
+  const [row] = await db.select({ invoice: invoices, clientName: contacts.name }).from(invoices)
+    .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+    .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId)));
+  if (!row) throw notFound('invoice');
+  const i = row.invoice;
+  const d = (await invoiceFacts(db, organisationId, [i])).get(i.id);
+  const invoice = {
+    id: i.id, number: i.number, clientName: row.clientName, issueDate: i.issueDate, date: dateOf(i), status: i.status, reference: i.reference,
+    lines: d.lines, totalCents: i.totalCents, jobs: d.jobs, open: d.jobs.length === 0 && i.status !== 'void',
+  };
+  const search = String(q ?? '').trim();
+  const where = [eq(billingObligations.organisationId, organisationId), isNull(billingObligations.invoiceId), isNull(billingObligations.accountingRef)];
+  if (search) {
+    const like = `%${search.replace(/[%_\\]/g, '\\$&')}%`;
+    where.push(or(ilike(contacts.name, like), ilike(billingObligations.practitioner, like), ilike(billingObligations.caseRef, like), ilike(billingObligations.sourceJobRef, like)));
+  } else {
+    where.push(eq(billingObligations.contactId, i.contactId));
+    if (invoice.date) where.push(sql`abs(coalesce(${billingObligations.jobDate}, ${billingObligations.createdAt}::date) - ${invoice.date}::date) <= ${WINDOW_DAYS}`);
+  }
+  const found = await db.select({ obligation: billingObligations, clientName: contacts.name }).from(billingObligations)
+    .leftJoin(contacts, eq(contacts.id, billingObligations.contactId))
+    .where(and(...where)).orderBy(desc(billingObligations.createdAt)).limit(50);
+  const codes = await codesFor(db, organisationId, found.flatMap((f) => (f.obligation.lines ?? []).map((l) => l.priceItemId)).filter(Boolean));
+  const theirs = { contactId: i.contactId, reference: i.reference, date: invoice.date, lines: d.lines, totalCents: i.totalCents };
+  const ranked = found.map(({ obligation: o, clientName }) => {
+    const lines = jobLines(o, codes);
+    const checks = checksOf(theirs, { contactId: o.contactId, reference: null, date: o.jobDate, lines, totalCents: o.totalCents }, 0);
+    return {
+      id: o.id, clientName, practitioner: o.practitioner, jobDate: o.jobDate, caseRef: o.caseRef, sourceStatus: o.sourceStatus,
+      sourceSystem: o.sourceSystem, lines, totalCents: o.totalCents, ready: Boolean(o.readyAt), checks, score: scoreOf(checks),
+    };
+  }).sort((a, b) => b.score - a.score).slice(0, search ? SEARCHED : SHOWN);
+  return { invoice, jobs: ranked.map((c, index) => ({ ...c, best: index === 0 && c.score > 0 })) };
+}
+
+// A search box's words against Flow invoices: number, client, Reference, or
+// a total in dollars ("150" or "$150.00").
+function searchInvoices(search) {
+  const like = `%${search.replace(/[%_\\]/g, '\\$&')}%`;
+  const terms = [ilike(invoices.number, like), ilike(contacts.name, like), ilike(invoices.reference, like)];
+  const amount = /^\$?\s*(\d+(?:,\d{3})*(?:\.\d{1,2})?)$/.exec(search);
+  if (amount) terms.push(eq(invoices.totalCents, Math.round(Number(amount[1].replace(/,/g, '')) * 100)));
+  return or(...terms);
+}
+
+// Each invoice's lines (code and amount before tax) and the jobs linked to it.
+async function invoiceFacts(db, organisationId, rows) {
+  const ids = rows.map((r) => r.id);
+  const facts = new Map(ids.map((id) => [id, { lines: [], jobs: [] }]));
+  if (!ids.length) return facts;
+  const lines = await db.select({ invoiceId: invoiceLines.invoiceId, priceItemId: invoiceLines.priceItemId, code: priceItems.code, description: invoiceLines.description, amountCents: invoiceLines.lineAmountCents })
+    .from(invoiceLines)
+    .leftJoin(priceItems, eq(priceItems.id, invoiceLines.priceItemId))
+    .where(and(eq(invoiceLines.organisationId, organisationId), inArray(invoiceLines.invoiceId, ids)))
+    .orderBy(asc(invoiceLines.position));
+  for (const { invoiceId, ...line } of lines) facts.get(invoiceId).lines.push(line);
+  const jobs = await db.select({ id: billingObligations.id, invoiceId: billingObligations.invoiceId, jobDate: billingObligations.jobDate, practitioner: billingObligations.practitioner })
+    .from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, ids)));
+  for (const { invoiceId, ...job } of jobs) facts.get(invoiceId).jobs.push(job);
+  return facts;
+}

package/server/core/ledger.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
 import {
-  billingObligations, invoices, obligationEvents, obligationPayments, obligationWritebacks, priceItems,
+  billingObligations, invoices, linkRejections, linkSuggestions, obligationEvents, obligationPayments, obligationWritebacks, priceItems,
 } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 import { createDraftInvoice, getInvoice, updateDraftInvoice } from './invoices.js';
@@ -668,6 +668,85 @@ export async function setHold(db, organisationId, obligationId, { holdState, rea
   });
 }
 
+// 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. A person settles it on the Reconcile page: "Make invoice", or a
+// link to a Flow invoice (linkJobToInvoice).
+const unlinked = (o) => o.accountingState === 'ambiguous' && !o.invoiceId && !o.accountingRef;
+
+// The matcher's open suggestions for one job, best first.
+export async function linkSuggestionsFor(db, organisationId, obligationId) {
+  return db.select({
+    system: linkSuggestions.system, externalId: linkSuggestions.externalId, externalNumber: linkSuggestions.externalNumber,
+    score: linkSuggestions.score, signals: linkSuggestions.signals,
+  }).from(linkSuggestions).where(and(
+    eq(linkSuggestions.organisationId, organisationId),
+    eq(linkSuggestions.obligationId, obligationId),
+    eq(linkSuggestions.state, 'open'),
+  )).orderBy(asc(linkSuggestions.rank));
+}
+
+// Rejects every open suggestion for the job ("not this one"): the matcher
+// never suggests those pairs again.
+async function rejectSuggestions(tx, obligation, { actor }) {
+  const open = await tx.select().from(linkSuggestions).where(and(
+    eq(linkSuggestions.organisationId, obligation.organisationId),
+    eq(linkSuggestions.obligationId, obligation.id),
+    eq(linkSuggestions.state, 'open'),
+  ));
+  for (const suggestion of open) {
+    await tx.update(linkSuggestions).set({ state: 'rejected', decidedBy: actor, decidedAt: sql`now()`, updatedAt: sql`now()` })
+      .where(eq(linkSuggestions.id, suggestion.id));
+    await tx.insert(linkRejections)
+      .values({ organisationId: obligation.organisationId, obligationId: obligation.id, system: suggestion.system, externalId: suggestion.externalId, actor })
+      .onConflictDoNothing();
+  }
+  return open.map((s) => s.externalId);
+}
+
+// "Make invoice": a person says the job has no invoice yet. Every suggestion
+// is rejected and the job is recorded as not found, so it can draft. The
+// live check before the draft still runs (draftInvoiceForObligation).
+export async function confirmNoInvoice(db, organisationId, obligationId, { actor }) {
+  requireActor(actor);
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    if (!unlinked(obligation)) throw new FlowError('invalid', 'the job is not waiting for a person to settle its invoice');
+    const rejected = await rejectSuggestions(tx, obligation, { actor });
+    const row = await update(tx, obligation, { accountingState: 'not_found', accountingCheckedAt: sql`now()` });
+    await addEvent(tx, row, 'accounting_checked', actor, { reported: 'not_found', state: 'not_found', matchedBy: 'person', rejected });
+    return row;
+  });
+}
+
+// A person links a job to a Flow invoice that already exists (Reconcile).
+// The job then has its invoice: Flow drafts no other. A job held on unclear
+// accounting evidence is settled by it; whether the Flow invoice matches one
+// in the accounting system is that integration's own work, not the job's.
+// `accountingRef` is given by an accounting integration that made the Flow
+// invoice from the accounting invoice the job is tied to already.
+export async function linkJobToInvoice(db, organisationId, obligationId, { invoiceId, accountingRef = null, actor }) {
+  requireActor(actor);
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    if (obligation.invoiceId) throw new FlowError('invalid', 'the job has an invoice already');
+    if (obligation.accountingRef && obligation.accountingRef !== accountingRef) throw new FlowError('invalid', 'the job is linked to an accounting invoice already');
+    const [invoice] = await tx.select({ id: invoices.id, status: invoices.status, contactId: invoices.contactId }).from(invoices)
+      .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId)));
+    if (!invoice) throw notFound('invoice');
+    if (invoice.status === 'void') throw new FlowError('invalid', 'the invoice is void');
+    const rejected = await rejectSuggestions(tx, obligation, { actor });
+    const row = await update(tx, obligation, {
+      invoiceId: invoice.id,
+      draftBasis: basisOf(obligation),
+      ...(obligation.accountingState === 'ambiguous' ? { accountingState: 'unknown' } : {}),
+      ...(obligation.readyAt ? {} : { readyAt: sql`now()`, readyBy: actor }),
+    });
+    await addEvent(tx, row, 'invoice_linked', actor, { invoiceId: invoice.id, matchedBy: 'person', rejected });
+    return row;
+  });
+}
+
 // The obligation's view and the reasons for it, from its stored evidence only.
 // `accounting` is false while no accounting system is connected: Flow's own
 // records are then the only check, so a job nobody checked in one can draft.

package/server/integrations/seazona/feed.js

@@ -202,7 +202,7 @@ export async function listWork(db, { now = Date.now(), finishedDays = WORK_FINIS
     return {
       sourceSystem: 'seazona',
       sourceJobRef: order.id,
-      // The Seazona order id is the case number. Never patient data.
+      // The Seazona order id is the case number.
       caseRef: order.id,
       status,
       clientId: order.clientId,
@@ -211,6 +211,9 @@ export async function listWork(db, { now = Date.now(), finishedDays = WORK_FINIS
       department: order.department,
       orderedOn: parseSeazonaDate(order.orderedText),
       dueOn: parseSeazonaDate(order.dueText),
+      // The patient, only when this installation keeps patient names
+      // (SEAZONA_KEEP_PATIENT_REFERENCE); otherwise the copy has none.
+      patient: order.patientReference ?? null,
       lines: (order.lines ?? []).map((l) => ({ code: l.code ?? null, description: l.description, amountCents: l.amountCents ?? null })),
       totalCents: order.subtotalCents,
     };

package/server/integrations/xero/fit.js

@@ -0,0 +1,108 @@
+// How sure Flow is that a Xero invoice in the copy is one Flow invoice
+// (docs/XERO_IMPORT.md, "Sure match"). The checks are the ones the job
+// matcher learned on work-system jobs against Xero (server/core/pipeline.js
+// scoreCandidate), plus what the Flow invoice's own jobs know: the matcher's
+// tie to this Xero invoice, and the work system's invoice number.
+//
+// A pair is sure only when one piece of hard evidence ties it, or when the
+// score is high and clearly ahead; and in both cases only when it is the one
+// fit both ways (`sureFits`).
+
+export const SURE_SCORE = 11; // total, same items, and within 3 days
+export const SURE_LEAD = 3;
+export const POOL_DAYS = 14;
+const day = (iso) => Date.parse(`${iso}T00:00:00Z`);
+const daysApart = (a, b) => (a && b ? Math.abs(day(a) - day(b)) / 86_400_000 : null);
+const withGst = (cents) => Math.round(cents * 1.1);
+const withoutReissue = (ref) => String(ref ?? '').trim().replace(/R$/i, '').toLowerCase();
+const words = (text) => String(text ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+
+// xero: { id, number, contactId, totalCents, issuedOn, itemCodes[], reference }
+// flow: { id, contactId, totalCents, subtotalCents, date, itemCodes[], reference,
+//         jobs: [{ accountingRef, sourceInvoiceRef, practitioner }] }
+// Answers { score, signals, hard }; `hard` names the evidence that ties them.
+export function scoreFit(xero, flow) {
+  const signals = [];
+  const add = (signal, weight) => signals.push({ signal, weight });
+  const jobs = flow.jobs ?? [];
+  let hard = null;
+  if (jobs.some((j) => j.accountingRef && j.accountingRef === xero.id)) hard = 'job_tied';
+  else if (xero.number && jobs.some((j) => j.sourceInvoiceRef && withoutReissue(j.sourceInvoiceRef) === withoutReissue(xero.number))) hard = 'work_invoice_number';
+  if (hard) add(hard, 10);
+  if (xero.contactId && xero.contactId === flow.contactId) add('client', 2);
+  if (xero.totalCents === flow.totalCents) add('total', 6);
+  else if ([flow.subtotalCents, withGst(flow.subtotalCents)].includes(xero.totalCents)) add('total_gst', 5);
+  const ours = new Set(flow.itemCodes ?? []);
+  const theirs = new Set(xero.itemCodes ?? []);
+  if (ours.size && theirs.size) {
+    const shared = [...ours].filter((c) => theirs.has(c)).length;
+    if (shared === ours.size && shared === theirs.size) add('items_same', 3);
+    else if (shared) add('items_overlap', 1);
+    else add('items_differ', -3);
+  }
+  const apart = daysApart(xero.issuedOn, flow.date);
+  if (apart !== null && apart <= 3) add('date_close', 2);
+  else if (apart !== null && apart <= POOL_DAYS) add('date_near', 1);
+  // A Reference is in the copy unless XERO_KEEP_REFERENCE is off.
+  if (xero.reference && flow.reference) {
+    if (words(xero.reference) === words(flow.reference)) add('reference_same', 3);
+    else add('reference_differs', -2);
+  } else if (xero.reference && jobs.some((j) => j.practitioner && words(xero.reference).includes(words(j.practitioner)))) {
+    add('practitioner', 1);
+  }
+  return { score: signals.reduce((sum, s) => sum + s.weight, 0), signals, hard };
+}
+
+// Whether the pair may be offered at all: hard evidence, or the same client
+// with an amount that fits and dates within two weeks.
+export function canFit(xero, flow, scored) {
+  if (scored.hard) return true;
+  const amount = scored.signals.some((s) => s.signal === 'total' || s.signal === 'total_gst');
+  const near = scored.signals.some((s) => s.signal === 'date_close' || s.signal === 'date_near');
+  return Boolean(xero.contactId && xero.contactId === flow.contactId && amount && near);
+}
+
+// pairs: [{ xeroId, flowId, apart, fit }], `fit` being the candidate with its
+// score. A fit loses RIVAL_WEIGHT, and is marked `rival`, when the same Flow
+// invoice has another Xero invoice dated at least RIVAL_DAYS closer to it, or
+// the same Xero invoice has another Flow invoice that much closer. Fits a day
+// or two apart stay level, so a person picks.
+export const RIVAL_WEIGHT = 4;
+export const RIVAL_DAYS = 3;
+export function markRivals(pairs) {
+  for (const p of pairs) {
+    if (p.fit.hard) continue;
+    const closer = pairs.some((o) => o !== p && o.apart + RIVAL_DAYS <= p.apart && (o.flowId === p.flowId || o.xeroId === p.xeroId));
+    if (closer) {
+      p.fit.score -= RIVAL_WEIGHT;
+      p.fit.rival = true;
+    }
+  }
+}
+
+// pairs: [{ xeroId, flowId, score, hard }]. Answers the set of `xeroId` whose
+// best fit is sure: hard evidence or SURE_SCORE, at least SURE_LEAD ahead of
+// that Xero invoice's next fit, and that Flow invoice's best fit back.
+export function sureFits(pairs) {
+  const byXero = new Map();
+  const byFlow = new Map();
+  for (const p of pairs) {
+    if (!byXero.has(p.xeroId)) byXero.set(p.xeroId, []);
+    if (!byFlow.has(p.flowId)) byFlow.set(p.flowId, []);
+    byXero.get(p.xeroId).push(p);
+    byFlow.get(p.flowId).push(p);
+  }
+  const ranked = (list) => [...list].sort((a, b) => b.score - a.score);
+  const clear = (list) => {
+    const [top, next] = ranked(list);
+    if (!top || !(top.hard || top.score >= SURE_SCORE)) return null;
+    if (next && (next.hard || top.score - next.score < SURE_LEAD)) return null;
+    return top;
+  };
+  const sure = new Map();
+  for (const [xeroId, list] of byXero) {
+    const top = clear(list);
+    if (top && clear(byFlow.get(top.flowId))?.xeroId === xeroId) sure.set(xeroId, top.flowId);
+  }
+  return sure;
+}

package/server/integrations/xero/import.js

@@ -5,6 +5,7 @@ import { isCallsStopped } from '../call-guard.js';
 import { lastSync, syncCatalogue } from './catalogue.js';
 import { mirrorState } from './lookup.js';
 import { MIRROR_RESOURCES, mirrorXero } from './mirror.js';
+import { matchXero } from './links.js';
 import { checkSentInvoices } from './reconcile.js';
 import { runWebhookWork, WEBHOOK_REFRESH_MS, webhooksActive } from './webhooks.js';
 
@@ -82,7 +83,11 @@ export async function runImportSlice(db, runtime, job, { maxPages = SLICE_PAGES
   const sent = invoices && (invoices.inserted || invoices.changed || job.payload?.reason !== 'changes')
     ? await checkSentInvoices(db, runtime, job.organisationId)
     : null;
-  return { results, more: stopped, ...(sent ? { sent } : {}) };
+  // Each Xero invoice against Flow's own (links.js): sure fits are linked, and
+  // with the Import setting on, a Flow invoice is made for each with no fit.
+  // Flow's database only.
+  const matched = sent ? await matchXero(db, job.organisationId) : null;
+  return { results, more: stopped, ...(sent ? { sent } : {}), ...(matched ? { matched } : {}) };
 }
 
 // Claims and runs one due import job, then queues the next slice when one is