@arcforgelabs/flow 2026.10.53 → 2026.11.2

package/server/core/ledger.js

@@ -100,12 +100,13 @@ async function normaliseLines(tx, organisationId, lines) {
     priceItemId = item?.archivedAt ? null : (item?.id ?? null);
     description = (description ?? item?.name ?? '').trim();
     unitAmountCents ??= item?.unitAmountCents;
-    taxCode ??= item?.taxCode ?? 'GST';
+    taxCode ??= item?.taxCode ?? (line.taxCode === null ? null : 'GST');
     const quantity = line.quantity ?? 1;
     if (!description) throw new FlowError('invalid', `line ${index + 1}: description is required`);
     let totals;
     try {
-      totals = lineTotals({ quantity, unitAmountCents, taxCode });
+      totals = lineTotals({ quantity, unitAmountCents, taxCode: taxCode ?? 'GST_FREE' });
+      if (taxCode === null) totals.taxCents = null;
     } catch (error) {
       throw new FlowError('invalid', `line ${index + 1}: ${error.message}`);
     }
@@ -128,6 +129,48 @@ function fingerprint(lines) {
   return createHash('sha256').update(JSON.stringify(keys)).digest('hex');
 }
 
+const SOURCE_TOTAL_FIELDS = ['subtotalCents', 'taxCents', 'totalCents'];
+const REVIEW_SOURCE_TOTALS = 'job.source_totals';
+
+function readSourceTotals(raw) {
+  if (raw == null) return null;
+  const totals = {};
+  for (const field of SOURCE_TOTAL_FIELDS) {
+    if (raw[field] == null) continue;
+    if (!Number.isSafeInteger(raw[field])) throw new FlowError('invalid', 'source ' + field + ' must be whole cents');
+    totals[field] = raw[field];
+  }
+  return Object.keys(totals).length ? totals : null;
+}
+
+// A source invoice total is evidence, not permission to allocate its tax.
+export function sourceBillingProblems(obligation) {
+  const reasons = [];
+  const lines = obligation.lines ?? [];
+  if (lines.some((line) => line.taxCode === null)) reasons.push('a source line has unknown tax treatment');
+  const calculated = invoiceTotals(lines);
+  if (SOURCE_TOTAL_FIELDS.some((field) => obligation.sourceTotals?.[field] != null && obligation.sourceTotals[field] !== calculated[field])) {
+    reasons.push('the source invoice totals differ from the reconstructed lines');
+  }
+  return reasons;
+}
+
+async function recordSourceReview(tx, row, actor) {
+  const reasons = sourceBillingProblems(row);
+  if (reasons.length) {
+    await openReview(tx, row.organisationId, {
+      kind: REVIEW_SOURCE_TOTALS, entity: 'obligation', flowId: row.id,
+      systems: [row.sourceSystem, 'flow'], moneyAtRiskCents: Math.abs(row.totalCents),
+      evidence: { reasons, sourceTotals: row.sourceTotals, reconstructed: invoiceTotals(row.lines),
+        unknownTaxLines: row.lines.flatMap((line, index) => line.taxCode === null ? [index + 1] : []),
+        sourceJobRef: row.sourceJobRef, invoiceId: row.invoiceId },
+    });
+  } else {
+    await resolveReviewFor(tx, row.organisationId, { kind: REVIEW_SOURCE_TOTALS, entity: 'obligation', flowId: row.id, resolution: 'source_totals_match', actor });
+  }
+  return row;
+}
+
 // Records what the work system reports about a billable job. The first report
 // makes the obligation; a later report with other lines or totals changes it.
 // If the job changes after Flow made its invoice, the obligation goes to review.
@@ -137,17 +180,20 @@ export async function observeJob(db, organisationId, job) {
   const seenAt = job.observedAt ? new Date(job.observedAt) : new Date();
   return db.transaction(async (tx) => {
     const lines = await normaliseLines(tx, organisationId, job.lines);
+    const sourceTotals = readSourceTotals(job.sourceTotals);
+    const totals = { ...invoiceTotals(lines), ...sourceTotals };
+    if (sourceTotals?.totalCents == null) totals.totalCents = totals.subtotalCents + totals.taxCents;
     const facts = {
       sourceInvoiceRef: job.sourceInvoiceRef ?? null,
       caseRef: job.caseRef ?? null,
       contactId: job.contactId ?? null,
       practitioner: job.practitioner ?? null,
-      shippedOn: job.shippedOn ?? null,
       jobDate: job.jobDate ?? null,
       sourceStatus: job.sourceStatus ?? null,
       lines,
       lineFingerprint: fingerprint(lines),
-      ...invoiceTotals(lines),
+      sourceTotals,
+      ...totals,
       mappingComplete: lines.every((l) => l.priceItemId || l.accountCode),
     };
     const [existing] = await tx.select().from(billingObligations)
@@ -158,26 +204,36 @@ export async function observeJob(db, organisationId, job) {
       ))
       .for('update');
 
+    // A work system without a shipped date (Seazona) says only that the job
+    // is shipped: the day Flow sees its status move to a shipped one is its
+    // shipped day. A job Flow first sees already shipped (a first sync, or a
+    // job shipped before Flow kept this day) stays without one.
+    const statusMoved = existing && String(existing.sourceStatus ?? '') !== String(facts.sourceStatus ?? '');
+    facts.shippedOn = job.shippedOn ?? existing?.shippedOn
+      ?? (job.shipped && statusMoved ? localDay(seenAt) : null);
+
     if (!existing) {
       const [row] = await tx.insert(billingObligations)
         .values({ organisationId, sourceSystem, sourceJobRef, sourceSeenAt: seenAt, ...facts })
         .returning();
       await addEvent(tx, row, 'observed', actor, {
-        lineFingerprint: row.lineFingerprint, totalCents: row.totalCents, mappingComplete: row.mappingComplete,
+        lineFingerprint: row.lineFingerprint, totalCents: row.totalCents, mappingComplete: row.mappingComplete, sourceStatus: row.sourceStatus, sourceTotals: row.sourceTotals,
       });
-      return row;
+      return recordSourceReview(tx, row, actor);
     }
 
     // An older report never replaces a newer one.
     if (seenAt < existing.sourceSeenAt) return existing;
-    const changed = ['sourceInvoiceRef', 'caseRef', 'contactId', 'practitioner', 'shippedOn', 'lineFingerprint', 'totalCents']
-      .filter((key) => String(existing[key] ?? '') !== String(facts[key] ?? ''));
+    const changed = ['sourceInvoiceRef', 'caseRef', 'contactId', 'practitioner', 'shippedOn', 'lineFingerprint', 'subtotalCents', 'taxCents', 'totalCents', 'sourceTotals']
+      .filter((key) => key === 'sourceTotals'
+        ? SOURCE_TOTAL_FIELDS.some((field) => (existing.sourceTotals?.[field] ?? null) !== (facts.sourceTotals?.[field] ?? null))
+        : String(existing[key] ?? '') !== String(facts[key] ?? ''));
     if (!changed.length) {
       const row = await update(tx, existing, {
         sourceSeenAt: seenAt, mappingComplete: facts.mappingComplete, lines, jobDate: facts.jobDate, sourceStatus: facts.sourceStatus,
       });
-      await statusBillableAgain(tx, organisationId, existing, row, actor);
-      return row;
+      await statusChanged(tx, organisationId, existing, row, actor);
+      return recordSourceReview(tx, row, actor);
     }
     const fields = { ...facts, sourceSeenAt: seenAt };
     let compare = null;
@@ -194,8 +250,8 @@ export async function observeJob(db, organisationId, job) {
     const row = await update(tx, existing, fields);
     await addEvent(tx, row, 'source_changed', actor, {
       changed,
-      before: { lineFingerprint: existing.lineFingerprint, totalCents: existing.totalCents },
-      after: { lineFingerprint: row.lineFingerprint, totalCents: row.totalCents },
+      before: { lineFingerprint: existing.lineFingerprint, totalCents: existing.totalCents, sourceTotals: existing.sourceTotals },
+      after: { lineFingerprint: row.lineFingerprint, totalCents: row.totalCents, sourceTotals: row.sourceTotals },
       ...(compare ? { compare: { outcome: compare.outcome, fields: compare.fields.map(({ field, changedIn }) => ({ field, changedIn })) } } : {}),
       ...(fields.holdState === 'review' ? { holdReason: fields.holdReason } : {}),
     });
@@ -204,15 +260,28 @@ export async function observeJob(db, organisationId, job) {
     } else if (compare) {
       await openReview(tx, organisationId, changedReview(row, compare));
     }
-    await statusBillableAgain(tx, organisationId, existing, row, actor);
-    return row;
+    await statusChanged(tx, organisationId, existing, row, actor);
+    return recordSourceReview(tx, row, actor);
   });
 }
 
+// Each move of the work system status is an event, so "was the job shipped
+// in this range" has an answer after the status moves on.
+async function statusChanged(tx, organisationId, before, row, actor) {
+  if (String(before.sourceStatus ?? '') === String(row.sourceStatus ?? '')) return;
+  await addEvent(tx, row, 'status_changed', actor, { from: before.sourceStatus ?? null, to: row.sourceStatus ?? null });
+  await statusBillableAgain(tx, organisationId, before, row, actor);
+}
+
+// The calendar day of a time where the lab works (FLOW_TIME_ZONE).
+function localDay(at) {
+  return new Intl.DateTimeFormat('en-CA', { timeZone: process.env.FLOW_TIME_ZONE || 'Australia/Sydney' }).format(at);
+}
+
 // A job billable again after its status moved back (observeWithdrawn): the
 // alert is over when no invoice was made in the meantime.
 async function statusBillableAgain(tx, organisationId, before, row, actor) {
-  if (row.invoiceId || String(before.sourceStatus ?? '') === String(row.sourceStatus ?? '')) return;
+  if (row.invoiceId) return;
   await resolveReviewFor(tx, organisationId, { kind: REVIEW_STATUS_BACK, entity: 'obligation', flowId: row.id, resolution: 'status_billable_again', actor });
 }
 
@@ -280,7 +349,7 @@ async function compareWithDraft(tx, organisationId, obligation, facts) {
   }
   const flow = { lines: invoice.lines, contactId: invoice.contactId };
   const compare = compareThreeWays(base, facts, flow, { sent: invoiceSent(invoice, obligation) });
-  return { ...compare, base, flow, invoiceStatus: invoice.status };
+  return { ...compare, base, flow, invoiceStatus: invoice.status, invoiceTotals: { subtotalCents: invoice.subtotalCents, taxCents: invoice.taxCents, totalCents: invoice.totalCents } };
 }
 
 function changedReview(obligation, compare) {
@@ -313,6 +382,8 @@ export async function useSourceLines(db, organisationId, obligationId, { 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 sourceProblems = sourceBillingProblems(obligation);
+    if (sourceProblems.length) throw new FlowError('not_ready', sourceProblems.join('; '));
     const compare = await compareWithDraft(tx, organisationId, obligation, obligation);
     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 });
@@ -408,17 +479,29 @@ export function diffJobLines(wasLines = [], nowLines = []) {
   return changes.sort((a, b) => a.position - b.position || (a.change === 'removed' ? -1 : 1));
 }
 
-// The open "job changed" problem of an invoice, for the invoice page, or
+// The open job-change or source-billing problem, for the invoice page, or
 // null: the job as it was when the invoice was made, as the work system has
 // it now, and whether a person can adopt the change into Flow's own draft
 // ("Adopt changes", useSourceLines). An invoice drafted before the basis was
 // kept compares with the invoice's own lines.
 export async function jobChangeFor(db, organisationId, invoiceId) {
   const [obligation] = await db.select().from(billingObligations)
-    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoiceId),
-      eq(billingObligations.holdState, 'review'), eq(billingObligations.holdReason, CHANGED_REASON)));
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoiceId)));
   if (!obligation) return null;
+  const changed = obligation.holdState === 'review' && obligation.holdReason === CHANGED_REASON;
+  const sourceProblems = sourceBillingProblems(obligation);
+  if (!changed && !sourceProblems.length) return null;
   const compare = await compareWithDraft(db, organisationId, obligation, obligation);
+  // Source review is only for Flow's draft. Issued documents keep the existing
+  // job-change/accounting comparison, never a new source-resolution action.
+  const sourceReview = sourceProblems.length && compare.invoiceStatus === 'draft' ? {
+    sourceTotals: obligation.sourceTotals ?? null,
+    reconstructed: { ...invoiceTotals(obligation.lines), ...(obligation.lines.some((line) => line.taxCode === null) ? { taxCents: null, totalCents: null } : {}) },
+    unknownTaxLines: obligation.lines.flatMap((line, index) => line.taxCode === null
+      ? [{ position: index + 1, description: line.description, itemCode: line.itemCode ?? null }] : []),
+    savedInvoice: compare.invoiceTotals,
+  } : null;
+  if (!changed && !sourceReview) return null;
   const was = obligation.draftBasis
     ?? (compare.flow ? { lines: compare.flow.lines, contactId: compare.flow.contactId, totalCents: null } : basisOf(obligation));
   return {
@@ -426,13 +509,15 @@ export async function jobChangeFor(db, organisationId, invoiceId) {
     sourceSystem: obligation.sourceSystem,
     sourceJobRef: obligation.sourceJobRef,
     sourceInvoiceRef: obligation.sourceInvoiceRef,
+    caseRef: obligation.caseRef,
+    sourceReview,
     seenAt: obligation.sourceSeenAt,
     outcome: compare.outcome,
     sent: compare.sent,
-    canAdopt: compare.outcome === 'offer',
+    canAdopt: !sourceReview && 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,
+    canAccept: !sourceReview && !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 },
@@ -786,7 +871,10 @@ export function ledgerView(obligation, { now = new Date(), sourceMaxAgeMs = SOUR
   if (['authorised', 'part_paid'].includes(o.accountingState)) {
     return { view: 'invoiced', reasons: [`invoice ${o.accountingRef} is ${o.accountingState.replace('_', ' ')}`] };
   }
+  // Existing invoices own their stage. sending.js still checks source conflicts
+  // before approval or Send, after the non-chargeable rules.
   if (o.invoiceId || o.accountingState === 'drafted') return { view: 'drafted', reasons: ['a draft invoice exists'] };
+  if (sourceBillingProblems(o).length) return { view: 'review_required', reasons: draftBlockers(o, { now, sourceMaxAgeMs, accounting }) };
   const reasons = draftBlockers(o, { now, sourceMaxAgeMs, accounting });
   // Flow's own stage: a job is in work until a person or an automation marks
   // it ready to invoice (setReady).
@@ -795,7 +883,7 @@ export function ledgerView(obligation, { now = new Date(), sourceMaxAgeMs = SOUR
 }
 
 function draftBlockers(o, { now, sourceMaxAgeMs, accounting = true }) {
-  const reasons = [];
+  const reasons = sourceBillingProblems(o);
   if (o.holdState !== 'none') reasons.push(`the job is ${o.holdState}`);
   if (o.invoiceId) reasons.push('the job already has an invoice');
   if (o.accountingState === 'unknown') {

package/server/core/line-mapping.js

@@ -24,8 +24,10 @@ import { FlowError, notFound } from './errors.js';
 //
 // A mapped line keeps the work system's amount and tax flag; the price item
 // gives its code, its text and, when the work system gave none, its price and
-// tax. With `linePrice: 'list'` the price item's price wins instead. A line
-// no step answers keeps no code, so the ledger holds the job.
+// tax. A closest-name guess cannot supply missing source tax; it needs an
+// explicit tax flag before mapping. With `linePrice: 'list'` the price item's
+// price wins instead. A line no step answers keeps no code, so the ledger
+// holds the job.
 
 export const STEPS = Object.freeze([
   'same_code', 'account', 'saved', 'catalog_name', 'price_alias', 'catalog_name_price', 'catalog_score', 'alias',
@@ -156,7 +158,7 @@ export function mapLine(line, context) {
     description: (item.description || item.name || original).trim(),
     quantity,
     unitAmountCents: config.linePrice === 'list' ? item.unitAmountCents : (price ?? item.unitAmountCents),
-    taxCode: taxCode ?? line.taxCode ?? item.taxCode,
+    taxCode: line.taxCode ?? taxCode ?? item.taxCode,
     mappedBy: step,
   });
   const fromRow = (row, step) => {
@@ -180,7 +182,7 @@ export function mapLine(line, context) {
         if (row) {
           return {
             ...base, itemCode: null, accountCode: row.accountCode, description: row.description || original, quantity,
-            unitAmountCents: price, taxCode: row.taxCode ?? line.taxCode, mappedBy: step,
+            unitAmountCents: price, taxCode: line.taxCode ?? row.taxCode ?? (line.taxCode === null ? null : undefined), mappedBy: step,
           };
         }
         break;
@@ -207,7 +209,9 @@ export function mapLine(line, context) {
         break;
       }
       case 'catalog_score': {
-        if (price === null) break;
+        // A guessed item would also supply its tax here (or in the ledger).
+        // Leave unknown tax for an exact match or a person's saved choice.
+        if (price === null || line.taxCode == null) break;
         const scored = (context.byPrice.get(price) ?? [])
           .map((item) => ({ item, score: nameScore(item, { exact, lookup, original: lineText(original) }) }))
           .sort((a, b) => b.score - a.score || a.item.name.localeCompare(b.item.name) || a.item.code.localeCompare(b.item.code));

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

@@ -1,7 +1,7 @@
 import { and, eq } from 'drizzle-orm';
 import { billingObligations } from '../db/schema.js';
 import { FlowError } from './errors.js';
-import { observeJob, observeWithdrawn } from './ledger.js';
+import { observeJob, observeWithdrawn, sourceBillingProblems } from './ledger.js';
 import { matchJobs, workJobMaker } from './pipeline.js';
 
 // Read before act (issue #141). Flow drafts and sends from its own copy of
@@ -50,7 +50,7 @@ export async function readBeforeAct(db, organisationId, obligations, { work, now
         continue;
       }
       const fresh = await reload(db, organisationId, obligation.id);
-      outcomes.set(obligation.id, { outcome: fresh.holdState === 'review' ? 'review' : 'read', obligation: fresh });
+      outcomes.set(obligation.id, { outcome: fresh.holdState === 'review' || sourceBillingProblems(fresh).length ? 'review' : 'read', obligation: fresh });
     } else if (answer?.state === 'withdrawn') {
       // The ledger decides as for the feed (observeWithdrawn): deleted, or
       // moved back after its invoice, goes to review; moved back while only

package/server/core/reconcile.js

@@ -124,6 +124,20 @@ export async function reconcileDays(db, organisationId, { integrations, from, to
           and e.kind in ('observed', 'source_changed') and e.actor <> ${HISTORY_ACTOR})`,
     ));
 
+  // A billable feed cannot prove absence. Check the remaining ledger refs
+  // against the source copy without billing filters. Older adapters retain
+  // the feed comparison until they declare workJobPresence.
+  const present = new Set(work.keys());
+  for (const adapter of workAdapters) {
+    if (!adapter.capabilities.workJobPresence) continue;
+    const jobRefs = [...new Set(obligations
+      .filter((o) => o.sourceSystem === adapter.id && !present.has(`${adapter.id}:${o.sourceJobRef}`))
+      .map((o) => o.sourceJobRef))];
+    for (let i = 0; i < jobRefs.length; i += FIND_BATCH) {
+      const { presentRefs } = await adapter.capabilities.workJobPresence({ organisationId, jobRefs: jobRefs.slice(i, i + FIND_BATCH) });
+      for (const ref of presentRefs) present.add(`${adapter.id}:${ref}`);
+    }
+  }
   const reported = new Set(workAdapters.map((a) => a.id));
   const inLedger = new Set();
   for (const o of obligations) {
@@ -139,7 +153,7 @@ export async function reconcileDays(db, organisationId, { integrations, from, to
     if (reported.has(o.sourceSystem)) {
       const key = `${o.sourceSystem}:${o.sourceJobRef}`;
       inLedger.add(key);
-      if (!work.has(key)) entry.differences.missingInWork.push({ id: o.id, cents: o.totalCents });
+      if (!present.has(key)) entry.differences.missingInWork.push({ id: o.id, cents: o.totalCents });
     }
   }
   for (const [key, job] of work) {

package/server/core/sending.js

@@ -5,7 +5,7 @@ import { FlowError } from './errors.js';
 import { listRules, ruleNonChargeable, rulePending, ruleSkip } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings } from './invoicing-rules.js';
 import { issueInvoice } from './invoices.js';
-import { CHANGED_REASON, diffJobLines, STATUS_BACK_REASON } from './ledger.js';
+import { CHANGED_REASON, diffJobLines, sourceBillingProblems, STATUS_BACK_REASON } from './ledger.js';
 import { soleOrganisation } from './pipeline.js';
 import { needsRead, readAccountingFirst, readBeforeAct, READS_PER_PASS } from './read-before-act.js';
 import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
@@ -50,20 +50,24 @@ const REFUSAL_CODE = /^[a-z0-9_]{1,64}$/i;
 const SENT = new Set(['created', 'reconciled', 'existing', 'already_in_xero']);
 
 // `short` is the few words the Invoices list shows; `message` says how to fix
-// it. `extra` adds `fields` (the invoice fields to fix) and `line`.
-const problem = (code, message, short = null, extra = {}) => ({ code, message, ...(short ? { short } : {}), ...extra });
+// it. Draft warnings must name their resolution UI at the owner, not in a
+// separate warning-code inventory. The invoice page dispatches this intent.
+const problem = (code, message, short, resolution, extra = {}) => {
+  if (typeof resolution?.kind !== 'string' || !resolution.kind) throw new FlowError('warning_resolution_required', `Draft warning ${code} needs a resolution UI.`);
+  return { code, message, ...(short ? { short } : {}), ...extra, resolution };
+};
 
 // An issued invoice the accounting system refused. A refusal stored without
 // its few words (before 2026-10-28) shows "Not sent"; its message stays.
-const refusal = (sendError) => (sendError ? { short: 'Not sent', ...sendError } : problem('send_failed', 'Sending failed.', 'Not sent'));
+const refusal = (sendError) => (sendError ? { short: 'Not sent', ...sendError } : { code: 'send_failed', message: 'Sending failed.', short: 'Not sent' });
 
 // Flow's own checks of one draft. `lines` are its invoice lines.
 export function draftProblems(invoice, lines) {
   const problems = [];
-  if (!lines.length) problems.push(problem('no_lines', 'The invoice has no lines.', 'No lines'));
-  else if (invoice.totalCents <= 0) problems.push(problem('no_amount', 'The total is $0.00 or less.', 'Total $0'));
+  if (!lines.length) problems.push(problem('no_lines', 'The invoice has no lines.', 'No lines', { kind: 'invoice_edit' }));
+  else if (invoice.totalCents <= 0) problems.push(problem('no_amount', 'The total is $0.00 or less.', 'Total $0', { kind: 'invoice_edit' }));
   for (const line of lines) {
-    if (!line.priceItemId && !line.accountCode) problems.push(problem('line_no_item', `Line ${line.position} has no price item.`, `Line ${line.position}: no item`, { fields: ['line_item'], line: line.position }));
+    if (!line.priceItemId && !line.accountCode) problems.push(problem('line_no_item', `Line ${line.position} has no price item.`, `Line ${line.position}: no item`, { kind: 'invoice_edit' }, { fields: ['line_item'], line: line.position }));
   }
   return problems;
 }
@@ -116,10 +120,18 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
   }
   // A draft whose job the ledger sent to review (the job changed after the
   // draft was made, or the work system deleted it) waits for a person.
+  for (const { obligation } of jobs) {
+    for (const reason of sourceBillingProblems(obligation)) {
+      const found = { ...problem('job_review', 'Check the source invoice: ' + reason + '.', 'Source tax', { kind: 'job_review' }), sourceBilling: true };
+      problems.set(obligation.invoiceId, [...(problems.get(obligation.invoiceId) ?? []), found]);
+    }
+  }
   const reviewed = jobs.map((j) => j.obligation).filter((o) => o.holdState === 'review');
   for (const obligation of reviewed) {
     const { invoiceId, holdReason: reason } = obligation;
-    const found = problem('job_review', `The job needs a look before this invoice goes: ${reason ?? 'it was sent to review'}.`, reviewShort(obligation));
+    const resolution = reason === CHANGED_REASON ? { kind: 'job_review' }
+      : { kind: 'job_hold', reason: reason ?? 'the job is review' };
+    const found = problem('job_review', `The job needs a look before this invoice goes: ${reason ?? 'it was sent to review'}.`, reviewShort(obligation), resolution);
     problems.set(invoiceId, [...(problems.get(invoiceId) ?? []), found]);
   }
   if (accounting) {
@@ -439,7 +451,8 @@ export async function sendQueued(db, organisationId, { accounting, limit = WORKE
         summary.waiting += 1;
       } else {
         const error = result.error ?? { code: `send_${result.outcome}`, message: `Sending ended as ${result.outcome}.` };
-        await settle(db, organisationId, result.invoiceId, { sendState: 'failed', sendError: { code: error.code, message: error.message, ...(error.short ? { short: error.short } : {}) } });
+        const xero = xeroMatch(error);
+        await settle(db, organisationId, result.invoiceId, { sendState: 'failed', sendError: { code: error.code, message: error.message, ...(error.short ? { short: error.short } : {}), ...(xero ? { xero } : {}) } });
         summary.failed += 1;
         summary.refused = [...new Set([...(summary.refused ?? []), error.code])];
         const fact = refusalFact(known.get(result.invoiceId), error);
@@ -450,6 +463,17 @@ export async function sendQueued(db, organisationId, { accounting, limit = WORKE
   return summary;
 }
 
+// The Xero invoice a refusal matched, kept so the page can link to it.
+// Only an id, a number and a status. Anything else in the error stays out.
+function xeroMatch(error) {
+  const xero = error?.details?.xero;
+  if (!xero || typeof xero !== 'object') return null;
+  if (!INVOICE_ID.test(xero.invoiceId ?? '')) return null;
+  const number = INVOICE_NUMBER.test(xero.number ?? '') ? xero.number : null;
+  const status = /^[A-Z0-9_]{1,32}$/.test(xero.status ?? '') ? xero.status : null;
+  return { invoiceId: xero.invoiceId, ...(number ? { number } : {}), ...(status ? { status } : {}) };
+}
+
 function settle(db, organisationId, invoiceId, fields) {
   return db.update(invoices).set({ ...fields, sendUpdatedAt: sql`now()` })
     .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId), eq(invoices.sendState, 'queued')));

package/server/db/migrations/0025_powerful_leopardon.sql

@@ -0,0 +1 @@
+ALTER TABLE "billing_obligations" ADD COLUMN IF NOT EXISTS "source_totals" jsonb;

package/server/db/migrations/0026_bitter_sersi.sql

@@ -0,0 +1,38 @@
+CREATE TABLE IF NOT EXISTS "agent_audit" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"grant_id" uuid NOT NULL,
+	"person_id" uuid NOT NULL,
+	"tool" text NOT NULL,
+	"status" integer NOT NULL,
+	"row_count" integer DEFAULT 0 NOT NULL,
+	"duration_ms" integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "agent_grants" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"person_id" uuid NOT NULL,
+	"client_id" text NOT NULL,
+	"app_name" text NOT NULL,
+	"resource" text NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"access_level" text DEFAULT 'read' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"last_used_at" timestamp with time zone,
+	"revoked_at" timestamp with time zone,
+	"failure_day" date,
+	"failure_count" integer DEFAULT 0 NOT NULL,
+	"paused_at" timestamp with time zone,
+	CONSTRAINT "agent_grants_person_client_resource" UNIQUE("person_id","client_id","resource"),
+	CONSTRAINT "agent_grants_read_only" CHECK (access_level = 'read')
+);
+--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "agent_grants" ADD CONSTRAINT "agent_grants_person_id_people_id_fk" FOREIGN KEY ("person_id") REFERENCES "flow"."people"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "agent_grants" ADD CONSTRAINT "agent_grants_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "flow"."organisations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "agent_audit_created" ON "agent_audit" USING btree ("created_at");