@arcforgelabs/flow 2026.10.37 → 2026.10.39

package/server/core/custom-fields.js

@@ -1,6 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { and, asc, eq, inArray, isNull, sql } from 'drizzle-orm';
-import { CUSTOM_FIELD_TYPES, jobFieldEvents, jobFields, jobFieldValues, people } from '../db/schema.js';
+import {
+  CUSTOM_FIELD_TYPES, integrationSettingEvents, integrationSettings, jobFieldEvents, jobFields, jobFieldSettings, jobFieldValues, people,
+} from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 
 // Custom fields (docs/CUSTOM_FIELDS.md): fields a lab makes for its jobs in
@@ -14,6 +16,14 @@ export { CUSTOM_FIELD_TYPES };
 // person, or yes and no.
 export const GROUPABLE_TYPES = ['dropdown', 'person', 'checkbox'];
 export const OPTION_COLORS = ['gray', 'blue', 'teal', 'green', 'amber', 'red', 'purple', 'pink'];
+// Each type group's own colour, until the lab picks another.
+export const TYPE_COLORS = { dropdown: 'green', person: 'blue', checkbox: 'purple', date: 'teal', number: 'amber', text: 'gray' };
+
+function readColor(raw, what) {
+  if (raw === null) return null;
+  if (!OPTION_COLORS.includes(raw)) throw invalid(`${what} must be one of ${OPTION_COLORS.join(', ')}`);
+  return raw;
+}
 
 const MAX_FIELDS = 50;
 const MAX_OPTIONS = 50;
@@ -74,6 +84,7 @@ export function readField(raw, { partial = false, previous = null } = {}) {
   } else if (input.type !== undefined && input.type !== previous?.type) {
     throw invalid('the type of a field cannot change; make a new field instead');
   }
+  if (input.color !== undefined) out.color = readColor(input.color, 'color');
   const type = out.type ?? previous?.type;
   if (type === 'dropdown' && (!partial || input.options !== undefined)) out.options = readOptions(input.options, previous?.options ?? []);
   else if (type !== 'dropdown' && input.options !== undefined && input.options !== null && !(Array.isArray(input.options) && !input.options.length)) {
@@ -87,6 +98,7 @@ export const publicField = (row) => ({
   name: row.name,
   type: row.type,
   options: row.options ?? [],
+  color: row.color ?? null,
   position: row.position,
   groupable: GROUPABLE_TYPES.includes(row.type),
   archived: Boolean(row.archivedAt),
@@ -95,11 +107,15 @@ export const publicField = (row) => ({
   updatedAt: row.updatedAt?.toISOString?.() ?? row.updatedAt,
 });
 
+// `valueCount` is how many jobs have a value, so Delete can say what goes.
 export async function listFields(db, organisationId, { archived = false } = {}) {
   const where = [eq(jobFields.organisationId, organisationId)];
   if (!archived) where.push(isNull(jobFields.archivedAt));
-  const rows = await db.select().from(jobFields).where(and(...where)).orderBy(asc(jobFields.position), asc(jobFields.createdAt));
-  return rows.map(publicField);
+  const rows = await db.select({
+    field: jobFields,
+    valueCount: sql`(select count(*) from ${jobFieldValues} v where v.organisation_id = ${jobFields.organisationId} and v.field_id = ${jobFields.id})`.mapWith(Number),
+  }).from(jobFields).where(and(...where)).orderBy(asc(jobFields.position), asc(jobFields.createdAt));
+  return rows.map(({ field, valueCount }) => ({ ...publicField(field), valueCount }));
 }
 
 async function readRow(db, organisationId, id) {
@@ -133,6 +149,66 @@ 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, archive or delete it like any field,
+// and Flow does not make it again: job_field_settings.assignee_made_at
+// records that it was made (or that the lab already had a person field).
+// 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 [settings] = await db.select({ at: jobFieldSettings.assigneeMadeAt }).from(jobFieldSettings)
+    .where(eq(jobFieldSettings.organisationId, organisationId));
+  if (settings?.at) return null;
+  // Only the request that marks it makes it.
+  const [marked] = await db.insert(jobFieldSettings).values({ organisationId, assigneeMadeAt: new Date() })
+    .onConflictDoUpdate({ target: jobFieldSettings.organisationId, set: { assigneeMadeAt: new Date() }, setWhere: isNull(jobFieldSettings.assigneeMadeAt) })
+    .returning({ organisationId: jobFieldSettings.organisationId });
+  if (!marked) return null;
+  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;
+  }
+}
+
+// Each type group's colour: TYPE_COLORS, with the lab's own choices on top.
+export async function readGroupColors(db, organisationId) {
+  const [row] = await db.select({ colors: jobFieldSettings.groupColors }).from(jobFieldSettings)
+    .where(eq(jobFieldSettings.organisationId, organisationId));
+  const own = row?.colors ?? {};
+  return Object.fromEntries(CUSTOM_FIELD_TYPES.map((t) => [t, OPTION_COLORS.includes(own[t]) ? own[t] : TYPE_COLORS[t]]));
+}
+
+// Give one type group a colour. null puts back its own colour.
+export async function setGroupColor(db, organisationId, type, raw, { personId = null } = {}) {
+  if (!CUSTOM_FIELD_TYPES.includes(type)) throw notFound('group');
+  const color = raw === undefined ? undefined : readColor(raw, 'color');
+  if (color === undefined) throw invalid('color is required (null puts back the group\'s own colour)');
+  const own = { ...(await db.select({ colors: jobFieldSettings.groupColors }).from(jobFieldSettings)
+    .where(eq(jobFieldSettings.organisationId, organisationId)))[0]?.colors };
+  if (color === null || color === TYPE_COLORS[type]) delete own[type]; else own[type] = color;
+  await db.insert(jobFieldSettings).values({ organisationId, groupColors: own, updatedBy: personId })
+    .onConflictDoUpdate({ target: jobFieldSettings.organisationId, set: { groupColors: own, updatedBy: personId, updatedAt: new Date() } });
+  return readGroupColors(db, organisationId);
+}
+
+// When an integration was connected: the first time its settings were saved
+// or it was turned on in Flow, or, for one set up in the host's own
+// settings, the first time Flow saw one of its records (`seenSince`).
+export async function integrationConnectedAt(db, adapterId, seenSince = null) {
+  const [[saved], [event]] = await Promise.all([
+    db.select({ at: sql`min(${integrationSettings.createdAt})` }).from(integrationSettings).where(eq(integrationSettings.adapterId, adapterId)),
+    db.select({ at: sql`min(${integrationSettingEvents.createdAt})` }).from(integrationSettingEvents).where(eq(integrationSettingEvents.adapterId, adapterId)),
+  ]);
+  const times = [saved?.at, event?.at, seenSince].filter(Boolean).map((t) => new Date(t)).filter((t) => !Number.isNaN(t.getTime()));
+  return times.length ? new Date(Math.min(...times)).toISOString() : null;
+}
+
 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');
@@ -153,6 +229,16 @@ export async function archiveField(db, organisationId, id, { archived = true, pe
   return publicField(row);
 }
 
+// Delete a field for good, with every job's value and its history (the
+// tables cascade). Archive is the step that keeps them.
+export async function deleteField(db, organisationId, id) {
+  const field = await readRow(db, organisationId, id);
+  const [{ count }] = await db.select({ count: sql`count(*)`.mapWith(Number) }).from(jobFieldValues)
+    .where(and(eq(jobFieldValues.organisationId, organisationId), eq(jobFieldValues.fieldId, field.id)));
+  await db.delete(jobFields).where(and(eq(jobFields.organisationId, organisationId), eq(jobFields.id, field.id)));
+  return { id: field.id, name: field.name, valuesDeleted: count };
+}
+
 // Put the fields in this order. `ids` lists every field that is not archived.
 export async function orderFields(db, organisationId, ids, { personId = null } = {}) {
   if (!Array.isArray(ids) || ids.some((i) => typeof i !== 'string')) throw invalid('ids must be a list of field ids');

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';
@@ -305,20 +305,21 @@ function changedReview(obligation, compare) {
 
 // "Use new lines": a person takes the work system's new lines (and its
 // customer, when that changed) into Flow's own unsent draft. Flow writes only
-// its own draft, never another system. Refused when the draft changed too,
-// or has left Flow: those stay alerts for a person.
-export async function useSourceLines(db, organisationId, obligationId, { actor }) {
+// its own draft, never another system. Refused when the invoice has left
+// Flow. When the draft changed too, `accept` (a person's "Accept change")
+// takes the work system's value over the draft's; without it, refused.
+export async function useSourceLines(db, organisationId, obligationId, { actor, accept = false }) {
   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 no invoice');
     const compare = await compareWithDraft(tx, organisationId, obligation, obligation);
-    if (compare.outcome === 'conflict') {
-      throw new FlowError('conflict', compare.sent ? 'the invoice has left Flow; change it where it is now' : 'the draft changed in Flow too; a person must compare them', { fields: compare.fields });
+    if (compare.outcome === 'conflict' && (compare.sent || compare.missing || !accept)) {
+      throw new FlowError('conflict', compare.missing ? 'the invoice was not found' : compare.sent ? 'the invoice has left Flow; change it where it is now' : 'the draft changed in Flow too; a person must compare them', { fields: compare.fields });
     }
     const changes = {};
     for (const { field, changedIn } of compare.fields) {
-      if (changedIn !== 'work') continue;
+      if (changedIn !== 'work' && !(accept && changedIn === 'both')) continue;
       if (field === 'lines') {
         changes.lines = obligation.lines.map(({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }) => (
           { priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }
@@ -338,12 +339,30 @@ export async function useSourceLines(db, organisationId, obligationId, { actor }
     const fields = { draftBasis: basisOf(obligation) };
     if (obligation.holdState === 'review' && obligation.holdReason === CHANGED_REASON) Object.assign(fields, { holdState: 'none', holdReason: null });
     const row = await update(tx, obligation, fields);
-    await addEvent(tx, row, 'source_lines_used', actor, { invoiceId: invoice.id, changed: Object.keys(changes), totalCents: invoice.totalCents });
+    await addEvent(tx, row, 'source_lines_used', actor, { invoiceId: invoice.id, changed: Object.keys(changes), totalCents: invoice.totalCents, ...(accept ? { accepted: compare.outcome } : {}) });
     await resolveReviewFor(tx, organisationId, { kind: REVIEW_CHANGED, entity: 'obligation', flowId: row.id, resolution: 'used_new_lines', actor });
     return { obligation: row, invoice };
   });
 }
 
+// After a person rechecks a job (POST /jobs/:id/recheck): a "job changed"
+// hold whose job now matches the draft again (the work system was fixed, or
+// the draft was) is over. Answers the obligation.
+export async function settleJobChange(db, organisationId, obligationId, { actor }) {
+  requireActor(actor);
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    if (!obligation.invoiceId || obligation.holdState !== 'review' || obligation.holdReason !== CHANGED_REASON) return obligation;
+    const compare = await compareWithDraft(tx, organisationId, obligation, obligation);
+    const settled = compare.fields.every(({ changedIn }) => ['none', 'same', 'flow'].includes(changedIn)) && !compare.missing;
+    if (!settled) return obligation;
+    const row = await update(tx, obligation, { holdState: 'none', holdReason: null, draftBasis: basisOf(obligation) });
+    await addEvent(tx, row, 'review_settled', actor, { invoiceId: obligation.invoiceId });
+    await resolveReviewFor(tx, organisationId, { kind: REVIEW_CHANGED, entity: 'obligation', flowId: row.id, resolution: 'job_matches_invoice', actor });
+    return row;
+  });
+}
+
 // What changed in a job after its invoice was made, for the invoice page:
 // each line as it was (the draft basis) and as the work system has it now.
 // Lines pair by price item, else item code, account or description; an
@@ -411,6 +430,9 @@ export async function jobChangeFor(db, organisationId, invoiceId) {
     outcome: compare.outcome,
     sent: compare.sent,
     canAdopt: compare.outcome === 'offer',
+    // "Accept change": the draft takes the work system's values, even when
+    // the draft changed too. Not once the invoice has left Flow.
+    canAccept: !compare.sent && !compare.missing,
     lines: diffJobLines(was.lines ?? [], obligation.lines ?? []),
     contact: (was.contactId ?? null) === (obligation.contactId ?? null) ? null : { was: was.contactId ?? null, now: obligation.contactId ?? null },
     total: { was: was.totalCents ?? null, now: obligation.totalCents },
@@ -668,6 +690,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/core/price-list.js

@@ -174,13 +174,13 @@ export async function linkByCode(db, organisationId, catalogue, { items = null,
 // A person's link: `externalId` in `system`'s list goes to this price item.
 // For an accounting system it replaces the item's earlier link; a record
 // linked elsewhere moves here.
-export async function linkPriceItem(db, organisationId, priceItemId, { system, externalId }, { catalogues, personId = null }) {
+async function writeLink(db, organisationId, priceItemId, { system, externalId }, { catalogues, personId }) {
   const item = await loadItem(db, organisationId, priceItemId);
   const catalogue = catalogues.get(system);
   if (!catalogue) throw new FlowError('conflict', `${system} is not connected, or its price list has not been read yet`);
   const record = catalogue.byId.get(String(externalId ?? ''));
   if (!record) throw notFound(`${catalogue.name} record`);
-  const link = await db.transaction(async (tx) => {
+  return db.transaction(async (tx) => {
     await tx.delete(priceItemLinks).where(and(
       eq(priceItemLinks.organisationId, organisationId), eq(priceItemLinks.system, system), eq(priceItemLinks.externalId, String(record.id)),
     ));
@@ -194,10 +194,35 @@ export async function linkPriceItem(db, organisationId, priceItemId, { system, e
     }).returning();
     return row;
   });
+}
+
+export async function linkPriceItem(db, organisationId, priceItemId, { system, externalId }, { catalogues, personId = null }) {
+  const link = await writeLink(db, organisationId, priceItemId, { system, externalId }, { catalogues, personId });
   await remapJobs(db, organisationId);
   return link;
 }
 
+// Many links at once (Reconcile prices, "Link sure matches"): each one as
+// linkPriceItem makes it, then one remap. A link that fails stops the rest;
+// the ones before it stay.
+export const MAX_LINKS_AT_ONCE = 500;
+export async function linkPriceItems(db, organisationId, links, { catalogues, personId = null }) {
+  if (!Array.isArray(links) || !links.length) throw invalid('links must be a list of { priceItemId, system, externalId }');
+  if (links.length > MAX_LINKS_AT_ONCE) throw invalid(`${MAX_LINKS_AT_ONCE} links at once at most`);
+  const made = [];
+  try {
+    for (const link of links) {
+      if (!link || typeof link !== 'object' || !link.priceItemId || !link.system || !link.externalId) {
+        throw invalid('each link needs priceItemId, system and externalId');
+      }
+      made.push(await writeLink(db, organisationId, link.priceItemId, link, { catalogues, personId }));
+    }
+  } finally {
+    if (made.length) await remapJobs(db, organisationId);
+  }
+  return made;
+}
+
 export async function unlinkPriceItem(db, organisationId, linkId) {
   const rows = await db.delete(priceItemLinks)
     .where(and(eq(priceItemLinks.organisationId, organisationId), eq(priceItemLinks.id, linkId))).returning();

package/server/core/read-before-act.js

@@ -30,11 +30,12 @@ const NO_LONGER_BILLABLE = 'the work system no longer reports the job as billabl
 // Answers Map(obligationId -> { outcome, obligation, reason? }), where
 // outcome is fresh (no read needed), read, review (sent to review) or
 // waiting (the read could not run).
-export async function readBeforeAct(db, organisationId, obligations, { work, now = new Date(), actor }) {
+// `force` reads even a fresh report (a person's "Recheck").
+export async function readBeforeAct(db, organisationId, obligations, { work, now = new Date(), actor, force = false }) {
   const outcomes = new Map();
   let toJob = null;
   for (const obligation of obligations) {
-    if (!needsRead(obligation, { work, now })) {
+    if (!needsRead(obligation, { work, now: force ? new Date(8.64e15) : now })) {
       outcomes.set(obligation.id, { outcome: 'fresh', obligation });
       continue;
     }