@arcforgelabs/flow 2026.11.2 → 2026.11.4

package/server/core/invoice-rules.js

@@ -1,9 +1,10 @@
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
-import { and, asc, eq, sql } from 'drizzle-orm';
-import { invoiceRules, invoicingSettings } from '../db/schema.js';
+import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
+import { billingObligations, invoiceRuleExceptions, invoiceRules, invoicingSettings, obligationEvents, priceItems } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
+import { getInvoice, updateDraftInvoice } from './invoices.js';
 
 // Invoice rules (docs/INVOICE_RULES.md): a lab's own checks on a job before
 // Flow drafts its invoice. Each rule is When, If and Then, and a lab owner
@@ -62,7 +63,7 @@ export const FIELDS = Object.freeze({
   // one marker, so a new branch needs no new rule.
   customer: {
     label: 'Customer', kind: 'choice', options: 'customers',
-    tests: ['is', 'is_not', 'is_one_of', 'contains', 'does_not_contain', 'is_empty'],
+    tests: ['is', 'is_not', 'is_one_of', 'is_not_one_of', 'contains', 'does_not_contain', 'is_empty'],
     read: (j) => j.contactId,
   },
   customer_billable: { label: 'Customer is billable', kind: 'boolean', read: (j, { customer }) => customer.billable !== false },
@@ -73,7 +74,7 @@ export const FIELDS = Object.freeze({
 export const TESTS = Object.freeze({
   number: ['more_than', 'at_most', 'is', 'is_not', 'is_empty'],
   money: ['more_than', 'at_most', 'is', 'is_not'],
-  choice: ['is', 'is_not', 'is_one_of', 'is_empty'],
+  choice: ['is', 'is_not', 'is_one_of', 'is_not_one_of', 'is_empty'],
   text: ['is', 'is_not', 'is_one_of', 'is_not_one_of', 'contains', 'does_not_contain', 'starts_with', 'does_not_start_with', 'has_number', 'number_in_words', 'one_word', 'is_empty', 'is_not_empty'],
   boolean: ['is'],
   items: ['has', 'has_not'],
@@ -134,6 +135,13 @@ export function readRule(raw) {
     const note = typeof raw.action.note === 'string' ? raw.action.note.trim() : '';
     if (!note || note.length > MAX_NOTE) throw invalid(`a pending rule needs a note of ${MAX_NOTE} characters at most: what a person must fix`);
     action.note = note;
+    // The fix a person can take with one press: add this price list item to
+    // the draft (for example a shipping line the work system left off).
+    if (raw.action.addItem !== undefined && raw.action.addItem !== null) {
+      const item = typeof raw.action.addItem === 'string' ? raw.action.addItem.trim() : '';
+      if (!item || item.length > 40) throw invalid('addItem must be a price list code of 40 characters at most');
+      action.addItem = item;
+    }
   } else {
     const early = conditions.find((c) => FIELDS[c.field].draftOnly);
     if (early) throw invalid(`${FIELDS[early.field].label} is on the draft only: use Then "Pending, with a note"`);
@@ -189,6 +197,7 @@ function matches(condition, job, context) {
     default: {
       const left = norm(have);
       if (test === 'is_one_of') return value.some((v) => norm(v) === left);
+      if (test === 'is_not_one_of') return !value.some((v) => norm(v) === left);
       return test === 'is' ? left === norm(value) : left !== norm(value);
     }
   }
@@ -227,12 +236,21 @@ const ruleResolution = (rule) => {
   return { kind: 'rule_review' };
 };
 
+// A rule leaves a job alone when a person made an exception for it
+// (`job.ruleExceptions`, rule ids), or, for a rule with `addItem`, when the
+// draft already has that item (`job.draftItems`, codes): the fix was taken.
 export function rulePending(rules, job, { customer = {}, now = new Date() } = {}) {
   const context = { customer, now };
+  const excepted = new Set(job.ruleExceptions ?? []);
+  const onDraft = new Set((job.draftItems ?? []).map(norm));
   return rules
     .filter((r) => r.enabled && r.trigger === 'job_ready' && r.action.kind === 'pending')
+    .filter((r) => !excepted.has(r.id) && !(r.action.addItem && onDraft.has(norm(r.action.addItem))))
     .filter((r) => r.conditions.every((c) => matches(c, job, context)))
-    .map((r) => ({ code: 'rule', message: r.action.note, short: r.name.slice(0, 40), rule: r.id ?? null, fields: [...new Set(r.conditions.map((c) => c.field))], resolution: ruleResolution(r) }));
+    .map((r) => ({
+      code: 'rule', message: r.action.note, short: r.name.slice(0, 40), rule: r.id ?? null, fields: [...new Set(r.conditions.map((c) => c.field))],
+      resolution: ruleResolution(r), ...(r.action.addItem ? { addItem: r.action.addItem } : {}),
+    }));
 }
 
 // Drafts an enabled skip rule matches stay on Pending at Send (sending.js).
@@ -295,9 +313,9 @@ async function seed(db, organisationId) {
   });
 }
 
-const shape = (r) => ({
+const shape = (r, exceptions = 0) => ({
   id: r.id, name: r.name, icon: r.icon, position: r.position, enabled: r.enabled, trigger: r.trigger,
-  conditions: r.conditions, action: r.action, starter: Boolean(r.starterKey), updatedAt: r.updatedAt,
+  conditions: r.conditions, action: r.action, starter: Boolean(r.starterKey), updatedAt: r.updatedAt, exceptions,
 });
 
 // The organisation's rules, in order. The first read makes the starter rules.
@@ -307,11 +325,101 @@ export async function listRules(db, organisationId) {
   if (!settings?.seeded) await seed(db, organisationId);
   const rows = await db.select().from(invoiceRules).where(eq(invoiceRules.organisationId, organisationId))
     .orderBy(asc(invoiceRules.position), asc(invoiceRules.createdAt));
-  return rows.map(shape);
+  const counts = await db.select({ ruleId: invoiceRuleExceptions.ruleId, count: sql`count(*)::int` }).from(invoiceRuleExceptions)
+    .where(eq(invoiceRuleExceptions.organisationId, organisationId)).groupBy(invoiceRuleExceptions.ruleId);
+  const byRule = new Map(counts.map((c) => [c.ruleId, Number(c.count)]));
+  return rows.map((r) => shape(r, byRule.get(r.id) ?? 0));
+}
+
+// ── Exceptions ─────────────────────────────────────────────────────────────
+
+// A person says one job is fine although a rule matches it. The rule then
+// leaves the job alone. Only a rule with an item to add takes one: its Skip.
+// Each exception keeps who, when and why, stays listed on the rule, and is
+// in the job's history. It holds while the rule's item and the job's lines
+// stay as they were; a change to either ends it, so a person looks again.
+export async function addRuleException(db, organisationId, ruleId, obligationId, { reason, actor }) {
+  const why = typeof reason === 'string' ? reason.trim() : '';
+  if (!why || why.length > 200) throw invalid('an exception needs a reason of 1 to 200 characters');
+  if (!actor) throw invalid('actor is required');
+  const rule = await loadRule(db, organisationId, ruleId);
+  if (rule.action?.kind !== 'pending' || !rule.action.addItem) throw invalid('only a pending rule with an item to add takes an exception; change or turn off the rule');
+  return db.transaction(async (tx) => {
+    const [job] = await tx.select({ id: billingObligations.id, lineFingerprint: billingObligations.lineFingerprint }).from(billingObligations)
+      .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId))).for('update');
+    if (!job) throw notFound('job');
+    const values = { reason: why, actor, itemCode: rule.action.addItem, lineFingerprint: job.lineFingerprint, createdAt: sql`now()` };
+    const [row] = await tx.insert(invoiceRuleExceptions).values({ organisationId, ruleId, obligationId, ...values })
+      .onConflictDoUpdate({ target: [invoiceRuleExceptions.ruleId, invoiceRuleExceptions.obligationId], set: values })
+      .returning();
+    await tx.insert(obligationEvents).values({ organisationId, obligationId, kind: 'rule_exception_added', actor,
+      evidence: { ruleId, rule: rule.name, item: rule.action.addItem, reason: why } });
+    return row;
+  });
+}
+
+// The rule ids each job has a current exception for, by job.
+export async function ruleExceptionsFor(db, organisationId, obligationIds) {
+  if (!obligationIds.length) return new Map();
+  const rows = await db.select({ ruleId: invoiceRuleExceptions.ruleId, obligationId: invoiceRuleExceptions.obligationId }).from(invoiceRuleExceptions)
+    .innerJoin(invoiceRules, eq(invoiceRules.id, invoiceRuleExceptions.ruleId))
+    .innerJoin(billingObligations, eq(billingObligations.id, invoiceRuleExceptions.obligationId))
+    .where(and(eq(invoiceRuleExceptions.organisationId, organisationId), inArray(invoiceRuleExceptions.obligationId, obligationIds), CURRENT));
+  const out = new Map();
+  for (const r of rows) out.set(r.obligationId, [...(out.get(r.obligationId) ?? []), r.ruleId]);
+  return out;
+}
+const CURRENT = sql`(${invoiceRuleExceptions.itemCode} is not distinct from (${invoiceRules.action} ->> 'addItem')
+  and ${invoiceRuleExceptions.lineFingerprint} is not distinct from ${billingObligations.lineFingerprint})`;
+
+// One rule's exceptions, newest first. `current` is false when the rule's
+// item or the job's lines changed since: the rule applies to that job again.
+export async function listRuleExceptions(db, organisationId, ruleId) {
+  await loadRule(db, organisationId, ruleId);
+  return db.select({ id: invoiceRuleExceptions.id, obligationId: invoiceRuleExceptions.obligationId, reason: invoiceRuleExceptions.reason,
+    actor: invoiceRuleExceptions.actor, itemCode: invoiceRuleExceptions.itemCode, createdAt: invoiceRuleExceptions.createdAt, current: sql`${CURRENT}`.mapWith(Boolean) })
+    .from(invoiceRuleExceptions)
+    .innerJoin(invoiceRules, eq(invoiceRules.id, invoiceRuleExceptions.ruleId))
+    .innerJoin(billingObligations, eq(billingObligations.id, invoiceRuleExceptions.obligationId))
+    .where(and(eq(invoiceRuleExceptions.organisationId, organisationId), eq(invoiceRuleExceptions.ruleId, ruleId)))
+    .orderBy(desc(invoiceRuleExceptions.createdAt));
+}
+
+// One job's exceptions, for its invoice page.
+export async function jobRuleExceptions(db, organisationId, obligationId) {
+  return db.select({ id: invoiceRuleExceptions.id, ruleId: invoiceRuleExceptions.ruleId, rule: invoiceRules.name, reason: invoiceRuleExceptions.reason,
+    actor: invoiceRuleExceptions.actor, itemCode: invoiceRuleExceptions.itemCode, createdAt: invoiceRuleExceptions.createdAt, current: sql`${CURRENT}`.mapWith(Boolean) })
+    .from(invoiceRuleExceptions)
+    .innerJoin(invoiceRules, eq(invoiceRules.id, invoiceRuleExceptions.ruleId))
+    .innerJoin(billingObligations, eq(billingObligations.id, invoiceRuleExceptions.obligationId))
+    .where(and(eq(invoiceRuleExceptions.organisationId, organisationId), eq(invoiceRuleExceptions.obligationId, obligationId)))
+    .orderBy(desc(invoiceRuleExceptions.createdAt));
+}
+
+// Takes an exception back: the rule applies to the job again.
+export async function removeRuleException(db, organisationId, ruleId, exceptionId, { actor = 'system' } = {}) {
+  return db.transaction(async (tx) => {
+    const [row] = await tx.delete(invoiceRuleExceptions).where(and(eq(invoiceRuleExceptions.organisationId, organisationId),
+      eq(invoiceRuleExceptions.ruleId, ruleId), eq(invoiceRuleExceptions.id, exceptionId))).returning();
+    if (!row) throw notFound('exception');
+    await tx.insert(obligationEvents).values({ organisationId, obligationId: row.obligationId, kind: 'rule_exception_removed', actor,
+      evidence: { ruleId, item: row.itemCode, reason: row.reason } });
+  });
+}
+
+// A rule's item must be on the price list, and not archived.
+async function checkRuleItem(db, organisationId, rule) {
+  const code = rule.action.addItem;
+  if (!code) return;
+  const [item] = await db.select({ archivedAt: priceItems.archivedAt }).from(priceItems)
+    .where(and(eq(priceItems.organisationId, organisationId), sql`upper(${priceItems.code}) = upper(${code})`));
+  if (!item) throw invalid(`the price list has no item ${code}`);
+  if (item.archivedAt) throw invalid(`price item ${code} is archived`);
 }
 
 export async function createRule(db, organisationId, raw, { personId = null } = {}) {
   const rule = readRule(raw);
+  await checkRuleItem(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;
@@ -331,6 +439,7 @@ export async function updateRule(db, organisationId, ruleId, changes, { personId
   const row = await loadRule(db, organisationId, ruleId);
   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);
   const [saved] = await db.update(invoiceRules).set({ ...rule, updatedBy: personId, updatedAt: sql`now()` })
     .where(eq(invoiceRules.id, row.id)).returning();
   return shape(saved);
@@ -340,3 +449,44 @@ export async function deleteRule(db, organisationId, ruleId) {
   const row = await loadRule(db, organisationId, ruleId);
   await db.delete(invoiceRules).where(eq(invoiceRules.id, row.id));
 }
+
+// ── A rule's one-press fix ─────────────────────────────────────────────────
+
+// "Add <item>" on a Pending draft: adds one of the rule's price list item to
+// the draft, at the price list's price. The rule then leaves the draft alone.
+// Flow never writes the line to the work system: the invoice page says the
+// job and the work system differ until the work system has it too.
+export async function addRuleItem(db, organisationId, invoiceId, ruleId) {
+  const rule = await loadRule(db, organisationId, ruleId);
+  const code = rule.action?.addItem;
+  if (!code || rule.action.kind !== 'pending') throw invalid('this rule has no item to add');
+  if (!rule.enabled) throw invalid('this rule is off');
+  const [item] = await db.select().from(priceItems)
+    .where(and(eq(priceItems.organisationId, organisationId), sql`upper(${priceItems.code}) = upper(${code})`));
+  if (!item) throw invalid(`the price list has no item ${code}`);
+  if (item.archivedAt) throw invalid(`price item ${code} is archived`);
+  // The lines are read under the draft's lock: a second press, or an edit at
+  // the same time, adds nothing twice and loses nothing.
+  await updateDraftInvoice(db, organisationId, invoiceId, {
+    lines: (current) => (current.some((l) => l.priceItemId === item.id) ? null : [
+      ...current.map(({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }) => (
+        { priceItemId, accountCode, description, quantity, unitAmountCents, taxCode })),
+      { priceItemId: item.id, quantity: 1 },
+    ]),
+  });
+  return getInvoice(db, organisationId, invoiceId);
+}
+
+// "Skip" on a Pending draft: an exception for the draft's job, with a reason.
+// The same, before the job has a draft: the job board shows the job needs an
+// item, and the person knows it does not (picked up, for example).
+export async function exceptJob(db, organisationId, obligationId, ruleId, { reason, actor }) {
+  return addRuleException(db, organisationId, ruleId, obligationId, { reason, actor });
+}
+
+export async function exceptDraft(db, organisationId, invoiceId, ruleId, { reason, actor }) {
+  const [job] = await db.select({ id: billingObligations.id }).from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoiceId)));
+  if (!job) throw invalid('this invoice has no job; edit the invoice instead');
+  return addRuleException(db, organisationId, ruleId, job.id, { reason, actor });
+}

package/server/core/invoices.js

@@ -111,7 +111,15 @@ export async function updateDraftInvoice(db, organisationId, invoiceId, changes)
         .where(eq(invoices.id, invoice.id)).returning();
     }
     if ('lines' in changes) {
-      row = await writeLines(tx, row, await resolveLines(tx, organisationId, changes.lines));
+      // `lines` may be a function of the draft's current lines, read under
+      // the lock, so a change made at the same time is not lost.
+      let lines = changes.lines;
+      if (typeof lines === 'function') {
+        const current = await tx.select().from(invoiceLines).where(eq(invoiceLines.invoiceId, invoice.id)).orderBy(asc(invoiceLines.position));
+        lines = lines(current);
+        if (lines === null) return row;
+      }
+      row = await writeLines(tx, row, await resolveLines(tx, organisationId, lines));
     }
     return row;
   });

package/server/core/invoicing-rules.js

@@ -1,6 +1,6 @@
 import { and, eq, inArray, isNull, sql } from 'drizzle-orm';
 import {
-  billingObligations, contacts, customerBillingSettings, invoicingSettings, SEND_MODES,
+  billingObligations, contacts, customerBillingSettings, externalLinks, invoicingSettings, SEND_MODES,
 } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 import { listRules, ruleReasons } from './invoice-rules.js';
@@ -214,20 +214,45 @@ const isoDay = (at) => `${at.getFullYear()}-${String(at.getMonth() + 1).padStart
 // The ledger's live check, answered from the accounting system's copy in Flow
 // instead of a call for each job: the copy is complete and was read lately,
 // the matcher checked the job after the copy last changed, and the copy holds
-// no invoice with the job's own invoice number.
-export function copyCheck(accounting, organisationId) {
-  return async (obligation) => {
+// no invoice with the job's own invoice number. Another customer's invoice
+// with the same number is not this job's: when the job's customer is linked to
+// an accounting contact (`db` given), only that contact's invoices count.
+// Send's window for the same client and Reference (xero/drafts.js).
+const SAME_REFERENCE_DAYS = 90;
+
+export function copyCheck(accounting, organisationId, { db = null } = {}) {
+  const contactOf = async (contactId) => {
+    if (!db || !contactId) return null;
+    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),
+    ));
+    return link?.externalId ?? null;
+  };
+  return async (obligation, { reference = null } = {}) => {
     const { complete, fresh, changedAt, invoices } = await accounting.capabilities.findInvoices({
       organisationId,
       numbers: obligation.sourceInvoiceRef ? [obligation.sourceInvoiceRef] : [],
+      references: reference ? [reference] : [],
     });
     if (!complete || !fresh) throw new Error('the accounting copy is not complete or not fresh');
     if (obligation.accountingState !== 'not_found') return { state: obligation.accountingState, matchedBy: 'copy' };
     if (changedAt && (!obligation.accountingCheckedAt || new Date(obligation.accountingCheckedAt) < changedAt)) {
       throw new Error('the accounting copy changed after the job was last matched');
     }
-    const sales = invoices.filter((i) => !['voided', 'deleted'].includes(i.state));
+    const xeroContactId = await contactOf(obligation.contactId);
+    const live = invoices.filter((i) => !['voided', 'deleted'].includes(i.state));
+    const sameNumber = (i) => obligation.sourceInvoiceRef && String(i.number ?? '').toUpperCase() === obligation.sourceInvoiceRef.toUpperCase();
+    const sales = live.filter((i) => sameNumber(i) && (!xeroContactId || i.contactId === xeroContactId));
     if (sales.length) return { state: sales[0].state, accountingRef: sales[0].id, matchedBy: 'copy' };
+    // The same client and Reference as this draft, within Send's window: Send
+    // would stop it (xero/drafts.js), so the draft is not made. A person
+    // links the job to that invoice, or says it is another job.
+    const day = obligation.jobDate ? Date.parse(`${String(obligation.jobDate).slice(0, 10)}T00:00:00Z`) : Date.now();
+    const sameReference = reference && xeroContactId ? live.filter((i) => i.contactId === xeroContactId
+      && String(i.reference ?? '').toUpperCase() === reference.toUpperCase()
+      && (!i.issuedOn || Math.abs(Date.parse(`${String(i.issuedOn).slice(0, 10)}T00:00:00Z`) - day) <= SAME_REFERENCE_DAYS * 86_400_000)) : [];
+    if (sameReference.length) return { state: 'ambiguous', accountingRef: sameReference[0].id, matchedBy: 'reference' };
     return { state: 'not_found', matchedBy: 'copy' };
   };
 }
@@ -269,7 +294,7 @@ export async function autoDraftJobs(db, organisationId, { accounting = null, wor
   const customers = await customerBillingByContact(db, organisationId, contactIds);
   const names = await customerNames(db, organisationId, contactIds);
   const named = (contactId) => ({ ...effectiveSettings(settings, customers.get(contactId)), name: names.get(contactId) ?? null });
-  const liveCheck = accounting ? copyCheck(accounting, organisationId) : null;
+  const liveCheck = accounting ? copyCheck(accounting, organisationId, { db }) : null;
   const invoiceDate = isoDay(now);
   let accountingRead = null;
 

package/server/core/job-board.js

@@ -1,6 +1,6 @@
 import { and, eq, inArray, isNull } from 'drizzle-orm';
 import { contacts, invoices, priceItems, reviewItems } from '../db/schema.js';
-import { listRules, ruleWait } from './invoice-rules.js';
+import { listRules, ruleExceptionsFor, rulePending, ruleWait } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings, ruleBlockers } from './invoicing-rules.js';
 import { REVIEW_CHANGED, listObligations } from './ledger.js';
 import { isHistoryHeld } from './history.js';
@@ -47,6 +47,20 @@ export async function describeObligations(db, organisationId, listed, { accounti
   const settings = await readInvoicingSettings(db, organisationId);
   const customers = await customerBillingByContact(db, organisationId, contactIds);
   const rules = await listRules(db, organisationId);
+  // A rule with an item to add also checks the job as the work system has it,
+  // from the first read: the lab prints from the work system, so it must be
+  // right there, not only on Flow's invoice. The card says what to add.
+  const addRules = rules.filter((r) => r.action.kind === 'pending' && r.action.addItem);
+  const excepted = addRules.length ? await ruleExceptionsFor(db, organisationId, listed.map((e) => e.obligation.id)) : new Map();
+  const sourceNeeds = (o) => {
+    if (!addRules.length) return [];
+    const customer = { ...effectiveSettings(settings, customers.get(o.contactId)), name: nameOf.get(o.contactId) ?? null };
+    // The work system's own lines count as having the item, whatever the
+    // rule's conditions say, so the badge shows only while the item is missing there.
+    const inSource = (o.lines ?? []).flatMap((l) => [l.itemCode, l.label].filter(Boolean));
+    return rulePending(addRules, { ...o, ruleExceptions: excepted.get(o.id) ?? [], draftItems: inSource }, { customer })
+      .map((p) => ({ rule: p.rule, item: p.addItem, note: p.message, short: p.short }));
+  };
   const ready = new Set(views?.ready ?? []);
   const toCheck = new Set(views?.toCheck ?? []);
   const invoiceView = (id) => (!id || !views ? null
@@ -74,6 +88,7 @@ export async function describeObligations(db, organisationId, listed, { accounti
     invoiceProblems: (o.invoiceId && views?.problems.get(o.invoiceId)) || [],
     view,
     reasons,
+    sourceNeeds: sourceNeeds(o),
     ...waiting(o, view),
   }));
 }

package/server/core/job-match.js

@@ -101,8 +101,9 @@ export async function listReconcile(db, organisationId) {
     status: billingObligations.sourceStatus,
     sourceSystem: billingObligations.sourceSystem,
     sourceJobRef: billingObligations.sourceJobRef,
-    // An unclear accounting match: "Make invoice" settles it first.
-    unclear: sql`${billingObligations.accountingState} = 'ambiguous'`.mapWith(Boolean),
+    // An unclear accounting match, or a matched accounting invoice that was
+    // voided or deleted there: "Make invoice" settles it first.
+    unclear: sql`${billingObligations.accountingState} in ('ambiguous', 'voided', 'deleted') and ${billingObligations.invoiceId} is null`.mapWith(Boolean),
     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}
@@ -152,8 +153,9 @@ export async function jobMatchDetail(db, organisationId, obligationId, { referen
     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',
+    // An unclear accounting match, or a matched accounting invoice that was
+    // voided or deleted there: "Make invoice" settles it first.
+    unclear: !o.invoiceId && ['ambiguous', 'voided', 'deleted'].includes(o.accountingState),
   };
 
   const search = String(q ?? '').trim();

package/server/core/ledger.js

@@ -769,7 +769,51 @@ export async function setHold(db, organisationId, obligationId, { holdState, rea
     const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
     const row = await update(tx, obligation, { holdState, holdReason: holdState === 'none' ? null : reason.trim() });
     await addEvent(tx, row, holdState === 'none' ? 'released' : holdState, actor, {
-      from: obligation.holdState, reason: row.holdReason,
+      from: obligation.holdState, reason: holdState === 'none' ? (reason?.trim() || null) : row.holdReason,
+    });
+    return row;
+  });
+}
+
+const GONE_STATES = ['voided', 'deleted'];
+
+// A person (or the assistant, after the lab says yes) frees a job that is
+// stuck on an invoice that bills nothing now: a Flow invoice that was voided,
+// or an accounting invoice that was voided or deleted there. The job lets go
+// of that invoice and goes on hold, so nothing drafts until a person releases
+// it (setHold to 'none'). A Flow invoice that is still live must be voided
+// first: this never voids or changes an invoice.
+export async function freeVoidedJob(db, organisationId, obligationId, { actor, reason, system = null }) {
+  requireActor(actor);
+  if (!reason?.trim()) throw new FlowError('invalid', 'say why the job is freed');
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    let flowInvoice = null;
+    if (obligation.invoiceId) {
+      [flowInvoice] = await tx.select({ id: invoices.id, number: invoices.number, status: invoices.status }).from(invoices)
+        .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, obligation.invoiceId)));
+      if (flowInvoice && flowInvoice.status !== 'void') {
+        throw new FlowError('invalid', `Flow invoice ${flowInvoice.number ?? flowInvoice.id} is ${flowInvoice.status}: void it first, then free the job`);
+      }
+    }
+    const gone = GONE_STATES.includes(obligation.accountingState) ? obligation.accountingRef : null;
+    if (!flowInvoice && !gone) throw new FlowError('invalid', 'the job is not linked to a void or deleted invoice');
+    const row = await update(tx, obligation, {
+      ...(flowInvoice ? { invoiceId: null, draftBasis: null } : {}),
+      ...(gone || GONE_STATES.includes(obligation.accountingState)
+        ? { accountingState: 'not_found', accountingRef: null, accountingUrl: null, accountingMatchedBy: null, accountingCheckedAt: sql`now()` }
+        : {}),
+      holdState: 'held',
+      holdReason: reason.trim(),
+    });
+    if (gone && system) {
+      await tx.insert(linkRejections).values({ organisationId, obligationId: obligation.id, system, externalId: gone, actor }).onConflictDoNothing();
+    }
+    await addEvent(tx, row, 'freed', actor, {
+      reason: reason.trim(),
+      ...(flowInvoice ? { invoiceId: flowInvoice.id } : {}),
+      ...(gone ? { released: gone } : {}),
+      from: obligation.holdState,
     });
     return row;
   });
@@ -777,9 +821,10 @@ 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;
+// exactly. Or the accounting invoice the matcher linked was voided or deleted
+// there: it bills nothing now. A person settles it on the Reconcile page or
+// the job: "Make invoice", or a link to a Flow invoice (linkJobToInvoice).
+const unlinked = (o) => !o.invoiceId && (GONE_STATES.includes(o.accountingState) || (o.accountingState === 'ambiguous' && !o.accountingRef));
 
 // The matcher's open suggestions for one job, best first.
 export async function linkSuggestionsFor(db, organisationId, obligationId) {
@@ -814,14 +859,26 @@ async function rejectSuggestions(tx, obligation, { actor }) {
 // "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 }) {
+// `system` is the accounting system's id: a released voided or deleted link
+// becomes that person's "not this one" too, so the matcher never offers it.
+export async function confirmNoInvoice(db, organisationId, obligationId, { actor, system = null }) {
   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 });
+    // A voided or deleted link is let go, so the matcher stops following it.
+    const gone = GONE_STATES.includes(obligation.accountingState) ? obligation.accountingRef : null;
+    const row = await update(tx, obligation, {
+      accountingState: 'not_found', accountingCheckedAt: sql`now()`,
+      ...(gone ? { accountingRef: null, accountingUrl: null, accountingMatchedBy: null } : {}),
+    });
+    if (gone && system) {
+      await tx.insert(linkRejections).values({ organisationId, obligationId: obligation.id, system, externalId: gone, actor }).onConflictDoNothing();
+    }
+    await addEvent(tx, row, 'accounting_checked', actor, {
+      reported: 'not_found', state: 'not_found', matchedBy: 'person', rejected, ...(gone ? { released: gone } : {}),
+    });
     return row;
   });
 }
@@ -913,7 +970,9 @@ export async function draftInvoiceForObligation(db, organisationId, obligationId
     let live = null;
     if (!reasons.length && accounting) {
       try {
-        live = await liveCheck(obligation);
+        // The draft's own Reference too: Send stops the same client and
+        // Reference in Xero, so the draft must not be made either.
+        live = await liveCheck(obligation, { reference });
       } catch (error) {
         reasons.push(`the live accounting check failed: ${error.message}`);
       }

package/server/core/pipeline.js

@@ -342,6 +342,10 @@ export function rankCandidates(obligation, invoices, { prior = null, rivals = []
 
 const amountsAgree = (obligation, invoice) => totalsFor(obligation).has(invoice.totalCents);
 const withoutReissue = (ref) => String(ref).replace(/R$/i, '');
+// A voided or deleted accounting invoice bills nothing: it never links a job
+// by itself. A lab that reissued work voids the first invoice, and that one
+// keeps the work system's number.
+const live = (invoice) => !['voided', 'deleted'].includes(invoice.state);
 
 async function saveSuggestions(db, organisationId, obligationId, system, ranked) {
   const keep = ranked.slice(0, 5);
@@ -392,14 +396,14 @@ export async function matchJob(db, organisationId, obligation, {
   });
   if (prior) {
     const [invoice] = await find({ invoiceIds: [prior.externalId] });
-    if (invoice && !rejected.has(invoice.id) && (prior.matchedBy === 'person' || amountsAgree(obligation, invoice))) {
+    if (invoice && live(invoice) && !rejected.has(invoice.id) && (prior.matchedBy === 'person' || amountsAgree(obligation, invoice))) {
       return exact(invoice, 'prior_link');
     }
   }
   if (obligation.sourceInvoiceRef) {
     const numbers = [obligation.sourceInvoiceRef, withoutReissue(obligation.sourceInvoiceRef)];
     const same = (await find({ numbers }))
-      .filter((i) => !rejected.has(i.id) && (!xeroContactId || i.contactId === xeroContactId));
+      .filter((i) => live(i) && !rejected.has(i.id) && (!xeroContactId || i.contactId === xeroContactId));
     if (same.length === 1) return exact(same[0], 'source_invoice_ref');
   }
   // Without the customer's accounting contact there is nothing to compare.

package/server/core/reconcile.js

@@ -30,6 +30,9 @@ export const RECONCILE_REVIEW_KIND = 'reconcile.day';
 export const ACTOR = 'system:reconcile';
 export const RECONCILE_DAYS = 60;
 export const EVIDENCE_IDS = 20;
+// A job ready this long with no invoice in Flow or the accounting system,
+// and no hold, is a difference: something stops it that nobody sees.
+export const READY_GRACE_DAYS = 3;
 const RUN_EVERY_MS = 24 * 60 * 60 * 1000;
 const RECHECK_MS = 60 * 60 * 1000;
 const TICK_MS = 10 * 60 * 1000;
@@ -55,7 +58,7 @@ function emptyDay(day) {
     flowInvoices: { count: 0, totalCents: 0 },
     accounting: { linked: 0, found: 0, totalCents: 0 },
     differences: {
-      missingInLedger: [], missingInWork: [], missingInAccounting: [], accountingTotalDiffers: [],
+      missingInLedger: [], missingInWork: [], missingInAccounting: [], accountingTotalDiffers: [], readyNotInvoiced: [],
     },
   };
 }
@@ -76,7 +79,7 @@ const moneyAtRisk = (entry) => Object.values(entry.differences).flat()
   .reduce((cents, d) => cents + Math.abs(d.cents ?? 0), 0);
 
 // One pass over Flow's own tables. Answers one entry per day, oldest first.
-export async function reconcileDays(db, organisationId, { integrations, from, to }) {
+export async function reconcileDays(db, organisationId, { integrations, from, to, now = Date.now() }) {
   const byDay = new Map();
   const dayOf = (day) => {
     if (!byDay.has(day)) byDay.set(day, emptyDay(day));
@@ -110,6 +113,8 @@ export async function reconcileDays(db, organisationId, { integrations, from, to
     accountingState: billingObligations.accountingState,
     accountingRef: billingObligations.accountingRef,
     invoiceId: billingObligations.invoiceId,
+    readyAt: billingObligations.readyAt,
+    holdState: billingObligations.holdState,
     invoiceStatus: invoices.status,
     invoiceTotalCents: invoices.totalCents,
   })
@@ -148,6 +153,9 @@ export async function reconcileDays(db, organisationId, { integrations, from, to
     if (o.invoiceId) {
       entry.flowInvoices.count += 1;
       entry.flowInvoices.totalCents += o.invoiceTotalCents ?? 0;
+    } else if (!o.accountingRef && o.holdState === 'none' && o.readyAt
+      && new Date(o.readyAt).getTime() < now - READY_GRACE_DAYS * 86_400_000) {
+      entry.differences.readyNotInvoiced.push({ id: o.id, cents: o.totalCents });
     }
     // Only a work system that is on can say a job is gone from its copy.
     if (reported.has(o.sourceSystem)) {
@@ -217,7 +225,7 @@ export async function runReconcile(db, organisationId, {
   const open = await openDayItems(db, organisationId);
   // An open item older than the window is checked too, so it can close.
   const oldest = [...open.keys()].reduce((min, day) => (day < min ? day : min), isoDay(now - (days - 1) * 86_400_000));
-  const { systems, days: entries } = await reconcileDays(db, organisationId, { integrations, from: oldest, to });
+  const { systems, days: entries } = await reconcileDays(db, organisationId, { integrations, from: oldest, to, now });
   const differing = entries.filter((e) => differenceCount(e) > 0);
   const recheck = new Set(unconfirmed);
   const firstSeen = [];