@arcforgelabs/flow 2026.10.32 → 2026.10.33

package/README.md

@@ -27,7 +27,8 @@ run a lab.
 | --- | --- |
 | `VISION.md` | What Flow is for, the core and its integrations, and what it will not do |
 | `AGENTS.md` | Agent entry point (`CLAUDE.md` links to it) |
-| `CONTRIBUTING.md` | How to file issues and pull requests, porting rules, merging |
+| `CONTRIBUTING.md` | How to file issues and pull requests, porting rules, the changelog, merging |
+| `CHANGELOG.md` | What changed in each release: an index of one file per release in `CHANGELOG/` |
 | `SECURITY.md` | How to report a security problem, the trust model, and the rules held hard |
 | `LICENSE` | MIT licence |
 | `docs/DESIGN.md` | The design systems (theme families), how pages and Clerk's components take them, and the screens |
@@ -37,6 +38,7 @@ run a lab.
 | `docs/INVOICING_RULES.md` | The invoicing rules that draft a job's invoice, and the two ways an invoice goes to Xero |
 | `docs/INVOICE_RULES.md` | Invoice rules a lab builds (When, If, Then) that make a ready job wait or never draft |
 | `docs/INVOICE_SENDING.md` | Drafts, Problem and Ready invoices, Mark ready, and Send all ready to the accounting system |
+| `docs/RECONCILE.md` | The daily reconcile: counts and totals per day across the work system's copy, the ledger and the accounting copy |
 | `docs/ALERTS.md` | Quiet alerts: the slim line on a page when something there needs a person, and how a person dismisses it |
 | `docs/AUTOMATIONS.md` | Automations: Flow routines that mark jobs ready to invoice and draft them, each on or off |
 | `docs/LINE_MAPPING.md` | Line mapping: how each work system line finds its price item, and Price codes in Settings |

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.32",
+  "version": "2026.10.33",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,7 @@
   "scripts": {
     "start": "node server/index.js",
     "test": "node --test --test-concurrency=1 test/*.test.js",
+    "changelog:check": "node scripts/release/changelog.mjs check",
     "theme:contrast": "node scripts/theme-contrast.mjs",
     "db:generate": "drizzle-kit generate && node scripts/db-guard-migrations.js"
   },

package/server/api/invoicing.js

@@ -16,11 +16,12 @@ import {
   saveCustomerBilling, saveInvoicingSettings, sendModeFor, sendModeSummary,
 } from '../core/invoicing-rules.js';
 import { boardJobs, describeObligations } from '../core/job-board.js';
+import { readBeforeAct } from '../core/read-before-act.js';
 import { jobReference } from '../core/references.js';
 import {
   acceptFindings, archivePriceItem, checkPrices, createPriceItem, linkPriceItem, readCatalogues, readPriceList, unlinkPriceItem, updatePriceItem,
 } from '../core/price-list.js';
-import { draftInvoiceForObligation, explainObligation, listObligations, setReady } from '../core/ledger.js';
+import { draftInvoiceForObligation, explainObligation, listObligations, setReady, useSourceLines } from '../core/ledger.js';
 import { isHistoryHeld } from '../core/history.js';
 import { invoicePdfDocument, pdfFields, pdfFilename, renderInvoicePdf } from '../core/invoice-pdf.js';
 import { invoiceView, invoiceViews, markNotReady, markReady, sendAgain, sendAllReady } from '../core/sending.js';
@@ -287,25 +288,36 @@ export function createInvoicingRouter({
     }
     const q = text(req.query.q);
     const limit = limitOf(req.query.limit, 200, 500);
-    const views = await invoiceViews(db, organisationId, { accounting: accounting() });
-    const where = [eq(invoices.organisationId, organisationId)];
-    const only = (ids) => (ids.length ? inArray(invoices.id, ids) : sql`false`);
-    if (status === 'to_check') where.push(only(views.toCheck));
-    else if (status === 'ready') where.push(only(views.ready));
-    else if (status === 'problem') where.push(only([...views.problems.keys()]));
-    else if (status) where.push(eq(invoices.status, status));
-    if (q) {
-      const pattern = containing(q);
-      where.push(or(ilike(invoices.number, pattern), ilike(invoices.reference, pattern), ilike(contacts.name, pattern)));
-    }
-    const rows = await db.select({ invoice: invoices, contactName: contacts.name }).from(invoices)
-      .leftJoin(contacts, eq(contacts.id, invoices.contactId))
-      .where(and(...where))
-      .orderBy(desc(invoices.createdAt), desc(invoices.id))
-      .limit(limit);
-    const jobs = await jobsByInvoice(db, organisationId, rows.map((r) => r.invoice.id));
-    const counted = await db.select({ status: invoices.status, n: sql`count(*)::int` }).from(invoices)
+    // Each tab switch runs this, so the independent reads run side by side;
+    // only the to-check, ready and problem lists wait on the draft checks.
+    const system = accounting();
+    const checking = invoiceViews(db, organisationId, { accounting: system });
+    const counting = db.select({ status: invoices.status, n: sql`count(*)::int` }).from(invoices)
       .where(eq(invoices.organisationId, organisationId)).groupBy(invoices.status);
+    const sendMode = system
+      ? Promise.all([sendModeSummary(db, organisationId), system.capabilities.sendStatus({ organisationId })])
+        .then(([summary, sendStatus]) => ({ ...summary, ...sendStatus }))
+      : null;
+    const listing = (async () => {
+      const views = VIEWS_OF_INVOICES.includes(status) ? await checking : null;
+      const where = [eq(invoices.organisationId, organisationId)];
+      const only = (ids) => (ids.length ? inArray(invoices.id, ids) : sql`false`);
+      if (status === 'to_check') where.push(only(views.toCheck));
+      else if (status === 'ready') where.push(only(views.ready));
+      else if (status === 'problem') where.push(only([...views.problems.keys()]));
+      else if (status) where.push(eq(invoices.status, status));
+      if (q) {
+        const pattern = containing(q);
+        where.push(or(ilike(invoices.number, pattern), ilike(invoices.reference, pattern), ilike(contacts.name, pattern)));
+      }
+      const rows = await db.select({ invoice: invoices, contactName: contacts.name }).from(invoices)
+        .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+        .where(and(...where))
+        .orderBy(desc(invoices.createdAt), desc(invoices.id))
+        .limit(limit);
+      return { rows, jobs: await jobsByInvoice(db, organisationId, rows.map((r) => r.invoice.id)) };
+    })();
+    const [views, counted, { rows, jobs }, mode] = await Promise.all([checking, counting, listing, sendMode]);
     const counts = Object.fromEntries(INVOICE_STATUSES.map((s) => [s, 0]));
     for (const { status: s, n } of counted) counts[s] = n;
     counts.to_check = views.toCheck.length;
@@ -324,8 +336,8 @@ export function createInvoicingRouter({
         problems: views.problems.get(invoice.id) ?? [],
       })),
       counts,
-      sendsTo: accounting()?.name ?? null,
-      sendMode: accounting() ? { ...(await sendModeSummary(db, organisationId)), ...(await accounting().capabilities.sendStatus({ organisationId })) } : null,
+      sendsTo: system?.name ?? null,
+      sendMode: mode,
     });
   }));
 
@@ -355,7 +367,9 @@ export function createInvoicingRouter({
     const organisationId = await organisationOf(req);
     const issueDate = optionalDate(req.body?.issueDate, 'issueDate') ?? today();
     const ids = req.body?.invoiceIds === undefined ? null : invoiceIdsOf(req.body);
-    const result = await sendAllReady(db, organisationId, { accounting: accounting(), personId: req.person.id, issueDate, invoiceIds: ids });
+    // Read before act (issue #141) reads each old job from the work system that can.
+    const reader = work().find((a) => typeof a.capabilities.readWorkItem === 'function') ?? null;
+    const result = await sendAllReady(db, organisationId, { accounting: accounting(), work: reader, personId: req.person.id, issueDate, invoiceIds: ids });
     log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} sent all ready: ${JSON.stringify(result)}`);
     res.json({ ok: true, ...result });
   }));
@@ -495,15 +509,33 @@ export function createInvoicingRouter({
     const organisationId = await organisationOf(req);
     // With no accounting system connected, Flow's own records are the check.
     const liveCheck = liveCheckFor(organisationId) ?? null;
-    const [obligation] = await db.select().from(billingObligations)
+    let [obligation] = await db.select().from(billingObligations)
       .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId)));
+    const source = obligation ? work().find((a) => a.id === obligation.sourceSystem) ?? null : null;
+    if (obligation) {
+      // Read before act (issue #141): an old job report is read again first.
+      const read = (await readBeforeAct(db, organisationId, [obligation], { work: source, actor: `person:${req.person.id}` })).get(obligation.id);
+      if (read.outcome === 'waiting' || read.outcome === 'review') {
+        throw new FlowError('not_ready', 'the draft invoice was refused', { reasons: [read.reason ?? read.obligation.holdReason ?? 'the job needs a look'] });
+      }
+      obligation = read.obligation;
+    }
     const { referenceTemplate: template } = await readInvoicingSettings(db, organisationId);
-    const reference = obligation ? await jobReference(db, organisationId, obligation, { template, work: work().find((a) => a.id === obligation.sourceSystem) ?? null }) : null;
+    const reference = obligation ? await jobReference(db, organisationId, obligation, { template, work: source }) : null;
     const { invoice } = await draftInvoiceForObligation(db, organisationId, obligationId, { liveCheck, actor: `person:${req.person.id}`, reference });
     log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} drafted invoice ${invoice.id} from job ${obligationId}`);
     res.status(201).json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoice.id) });
   }));
 
+  // "Use new lines": the job changed in the work system after its draft was
+  // made, and only there. Flow changes its own draft; no other system.
+  router.post('/jobs/:id/use-new-lines', ...manager, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const { invoice } = await useSourceLines(db, organisationId, obligationId, { actor: `person:${req.person.id}` });
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoice.id) });
+  }));
+
   router.post('/jobs/:id/ready', ...signedIn, handle(log, async (req, res) => {
     const obligationId = pathId(req.params.id, 'job');
     const organisationId = await organisationOf(req);

package/server/app.js

@@ -4,6 +4,7 @@ import { createConnectorApi } from './api/connector.js';
 import { createInvoicingRouter } from './api/invoicing.js';
 import { createSignInRouter } from './auth/routes.js';
 import { integrationAlertsSource, invoiceProblemsSource, priceDifferencesSource } from './core/alerts.js';
+import { reconcileHealth } from './core/reconcile.js';
 import { appliedMigrationCounts } from './db/doctor.js';
 import { deployedBuildStatus } from './deployed-build.js';
 import { integrationsHealth } from './integrations/health.js';
@@ -72,6 +73,9 @@ export function createApp({
         .then((migrations) => ({ migrations }), () => null);
     }
     if (integrations) body.integrations = await integrationsHealth(integrations);
+    // The daily reconcile's last run (server/core/reconcile.js): counts only.
+    // A difference does not fail the health check.
+    if (databaseOk && database.db) body.reconcile = await reconcileHealth(database.db).catch(() => null);
     res.status(ok ? 200 : 503).json(body);
   });
 

package/server/core/invoicing-rules.js

@@ -5,6 +5,7 @@ import {
 import { FlowError, notFound } from './errors.js';
 import { listRules, ruleReasons } from './invoice-rules.js';
 import { draftInvoiceForObligation } from './ledger.js';
+import { needsRead, readAccountingFirst, readBeforeAct, READS_PER_PASS } from './read-before-act.js';
 import { checkReferenceTemplate, DEFAULT_REFERENCE, jobReference } from './references.js';
 
 // Invoicing rules (docs/INVOICING_RULES.md). They are the checks a job that
@@ -221,6 +222,12 @@ export function copyCheck(accounting, organisationId) {
   };
 }
 
+async function reloadObligation(db, organisationId, id) {
+  const [row] = await db.select().from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, id)));
+  return row;
+}
+
 // Drafts the invoice of each job that is ready to invoice and passes the
 // ledger's checks and every rule, except for customers whose drafting is off.
 // It writes only Flow's own records: the drafts wait in Flow for a person.
@@ -228,7 +235,7 @@ export function copyCheck(accounting, organisationId) {
 // With `accounting` null no accounting system is connected: Flow's own records
 // are the only check, as for a person's draft (ledger.js, ledgerView).
 export async function autoDraftJobs(db, organisationId, { accounting = null, work = null, now = new Date(), limit = DRAFT_BATCH, actor = ACTOR }) {
-  const result = { drafted: 0, waiting: 0, off: 0, refused: 0 };
+  const result = { drafted: 0, waiting: 0, off: 0, refused: 0, readFirst: 0 };
   const settings = await readInvoicingSettings(db, organisationId);
   const rules = await listRules(db, organisationId);
   if (accounting) {
@@ -251,17 +258,56 @@ export async function autoDraftJobs(db, organisationId, { accounting = null, wor
   const customers = await customerBillingByContact(db, organisationId, candidates.map((o) => o.contactId));
   const liveCheck = accounting ? copyCheck(accounting, organisationId) : null;
   const invoiceDate = isoDay(now);
+  let accountingRead = null;
 
-  for (const obligation of candidates) {
-    const effective = effectiveSettings(settings, customers.get(obligation.contactId));
+  for (const candidate of candidates) {
+    let effective = effectiveSettings(settings, customers.get(candidate.contactId));
     if (!effective.autoDraft) {
       result.off += 1;
       continue;
     }
-    if (ruleBlockers(obligation, effective, { now, rules }).length) {
+    if (ruleBlockers(candidate, effective, { now, rules }).length) {
+      result.waiting += 1;
+      continue;
+    }
+    // Issue #141: an old report is read again first. The rules then check
+    // what the work system says now; the ledger checks the rest.
+    if (result.readFirst >= READS_PER_PASS && needsRead(candidate, { work, now })) {
       result.waiting += 1;
       continue;
     }
+    let { outcome, obligation } = (await readBeforeAct(db, organisationId, [candidate], { work, now, actor })).get(candidate.id);
+    if (outcome !== 'fresh') result.readFirst += 1;
+    if (outcome === 'waiting' || outcome === 'review') {
+      result.waiting += 1;
+      continue;
+    }
+    // Issue #45: the accounting copy reads its latest changes once, before
+    // the first draft. When it changed, the matcher ran: this job may now
+    // have its invoice.
+    if (accounting) {
+      if (!accountingRead) {
+        accountingRead = await readAccountingFirst(db, organisationId, { accounting, now });
+        // The summary says when the copy read or could not read.
+        if (accountingRead.outcome !== 'fresh') result.accountingRead = accountingRead.outcome;
+      }
+      if (accountingRead.outcome === 'waiting') {
+        result.waiting += 1;
+        continue;
+      }
+      if (accountingRead.outcome === 'read') obligation = await reloadObligation(db, organisationId, obligation.id);
+      if (obligation.accountingState !== 'not_found') {
+        result.waiting += 1;
+        continue;
+      }
+    }
+    if (obligation !== candidate) {
+      effective = effectiveSettings(settings, customers.get(obligation.contactId));
+      if (!effective.autoDraft || ruleBlockers(obligation, effective, { now, rules }).length) {
+        result.waiting += 1;
+        continue;
+      }
+    }
     try {
       await draftInvoiceForObligation(db, organisationId, obligation.id, {
         liveCheck,

package/server/core/job-board.js

@@ -1,8 +1,8 @@
 import { and, eq, inArray, isNull } from 'drizzle-orm';
-import { contacts, invoices, priceItems } from '../db/schema.js';
+import { contacts, invoices, priceItems, reviewItems } from '../db/schema.js';
 import { listRules } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings, ruleBlockers } from './invoicing-rules.js';
-import { listObligations } from './ledger.js';
+import { REVIEW_CHANGED, listObligations } from './ledger.js';
 import { isHistoryHeld } from './history.js';
 import { invoiceViews } from './sending.js';
 
@@ -21,7 +21,8 @@ import { invoiceViews } from './sending.js';
 export async function describeObligations(db, organisationId, listed, { accounting = null } = {}) {
   const contactIds = [...new Set(listed.map((e) => e.obligation.contactId).filter(Boolean))];
   const invoiceIds = [...new Set(listed.map((e) => e.obligation.invoiceId).filter(Boolean))];
-  const [names, numbers, views] = await Promise.all([
+  const changedIds = listed.filter((e) => e.obligation.holdState === 'review' && e.obligation.invoiceId).map((e) => e.obligation.id);
+  const [names, numbers, views, changed] = await Promise.all([
     contactIds.length
       ? db.select({ id: contacts.id, name: contacts.name }).from(contacts)
         .where(and(eq(contacts.organisationId, organisationId), inArray(contacts.id, contactIds)))
@@ -31,7 +32,16 @@ export async function describeObligations(db, organisationId, listed, { accounti
         .where(and(eq(invoices.organisationId, organisationId), inArray(invoices.id, invoiceIds)))
       : [],
     invoiceIds.length ? invoiceViews(db, organisationId, { accounting }) : null,
+    // The open "job changed" alerts (ledger.js): only the work system changed
+    // and the draft is not sent, so a person can use the new lines.
+    changedIds.length
+      ? db.select({ flowId: reviewItems.flowId, evidence: reviewItems.evidence }).from(reviewItems).where(and(
+        eq(reviewItems.organisationId, organisationId), eq(reviewItems.kind, REVIEW_CHANGED),
+        eq(reviewItems.state, 'open'), inArray(reviewItems.flowId, changedIds),
+      ))
+      : [],
   ]);
+  const offers = new Set(changed.filter((r) => r.evidence?.canUseNewLines).map((r) => r.flowId));
   const nameOf = new Map(names.map((c) => [c.id, c.name]));
   const invoiceOf = new Map(numbers.map((i) => [i.id, i]));
   const settings = await readInvoicingSettings(db, organisationId);
@@ -46,8 +56,9 @@ export async function describeObligations(db, organisationId, listed, { accounti
   // draft can still come from.
   const waitingFor = (o, v) => (o.invoiceId || !['in_work', 'ready', 'pending', 'held'].includes(v)
     ? [] : ruleBlockers(o, effectiveSettings(settings, customers.get(o.contactId)), { rules }));
-  return listed.map(({ obligation: { lineFingerprint: _fingerprint, organisationId: _org, ...o }, view, reasons }) => ({
+  return listed.map(({ obligation: { lineFingerprint: _fingerprint, organisationId: _org, draftBasis: _basis, ...o }, view, reasons }) => ({
     ...o,
+    canUseNewLines: offers.has(o.id),
     contactName: nameOf.get(o.contactId) ?? null,
     invoiceNumber: invoiceOf.get(o.invoiceId)?.number ?? null,
     invoiceStatus: invoiceOf.get(o.invoiceId)?.status ?? null,

package/server/core/ledger.js

@@ -4,8 +4,9 @@ import {
   billingObligations, obligationEvents, obligationPayments, obligationWritebacks, priceItems,
 } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
-import { createDraftInvoice } from './invoices.js';
+import { createDraftInvoice, getInvoice, updateDraftInvoice } from './invoices.js';
 import { invoiceTotals, lineTotals } from './money.js';
+import { openReview, resolveReviewFor } from './review.js';
 
 // The billing obligation ledger. One billable job in a work system is one
 // obligation. Its view (In work, Ready, Pending, Held, Drafted, Invoiced,
@@ -23,6 +24,29 @@ export const EXACT_MATCHES = ['flow_invoice', 'source_invoice_ref', 'accounting_
 
 const LINKED_STATES = ['drafted', 'authorised', 'part_paid', 'paid', 'voided', 'deleted'];
 
+// Which system owns each fact about a billed job (docs/DATA_SPINE.md, "Who
+// owns each field"). The work system owns the work; Flow owns its invoice
+// and the send; the accounting system owns approval and payment. Only the
+// work fields are compared when a job changes after its invoice was made.
+export const FIELD_OWNERS = {
+  lines: 'work',
+  contactId: 'work',
+  sourceStatus: 'work',
+  reference: 'flow',
+  dueDate: 'flow',
+  send: 'flow',
+  approval: 'accounting',
+  payment: 'accounting',
+};
+const COMPARED = Object.keys(FIELD_OWNERS).filter((field) => FIELD_OWNERS[field] === 'work' && field !== 'sourceStatus');
+
+export const CHANGED_REASON = 'the job changed after its invoice was made';
+export const STATUS_BACK_REASON = 'the job status moved back after its invoice was made';
+// Review queue kinds (server/core/review.js). An item only alerts.
+export const REVIEW_CHANGED = 'job.changed';
+export const REVIEW_STATUS_BACK = 'job.status_back';
+export const REVIEW_DELETED = 'job.deleted';
+
 async function loadObligation(tx, organisationId, obligationId, { lock = false } = {}) {
   let query = tx.select().from(billingObligations)
     .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId)));
@@ -149,26 +173,235 @@ export async function observeJob(db, organisationId, job) {
     const changed = ['sourceInvoiceRef', 'caseRef', 'contactId', 'practitioner', 'shippedOn', 'lineFingerprint', 'totalCents']
       .filter((key) => String(existing[key] ?? '') !== String(facts[key] ?? ''));
     if (!changed.length) {
-      return update(tx, existing, {
+      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;
     }
     const fields = { ...facts, sourceSeenAt: seenAt };
+    let compare = null;
     if (existing.invoiceId && changed.some((key) => ['lineFingerprint', 'totalCents', 'contactId'].includes(key))) {
-      fields.holdState = 'review';
-      fields.holdReason = 'the job changed after its invoice was made';
+      compare = await compareWithDraft(tx, organisationId, existing, facts);
+      if (compare.outcome !== 'none') {
+        fields.holdState = 'review';
+        fields.holdReason = CHANGED_REASON;
+      } else if (existing.holdState === 'review' && existing.holdReason === CHANGED_REASON) {
+        // The job is back to what the invoice was built from.
+        Object.assign(fields, { holdState: 'none', holdReason: null });
+      }
     }
     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 },
-      ...(fields.holdState ? { holdReason: fields.holdReason } : {}),
+      ...(compare ? { compare: { outcome: compare.outcome, fields: compare.fields.map(({ field, changedIn }) => ({ field, changedIn })) } } : {}),
+      ...(fields.holdState === 'review' ? { holdReason: fields.holdReason } : {}),
     });
+    if (compare?.outcome === 'none') {
+      await resolveReviewFor(tx, organisationId, { kind: REVIEW_CHANGED, entity: 'obligation', flowId: row.id, resolution: 'job_matches_invoice', actor });
+    } else if (compare) {
+      await openReview(tx, organisationId, changedReview(row, compare));
+    }
+    await statusBillableAgain(tx, organisationId, existing, row, actor);
     return row;
   });
 }
 
+// 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;
+  await resolveReviewFor(tx, organisationId, { kind: REVIEW_STATUS_BACK, entity: 'obligation', flowId: row.id, resolution: 'status_billable_again', actor });
+}
+
+// The job facts an invoice is built from, kept on the obligation when Flow
+// drafts the invoice: the merge base of the three-way compare.
+function basisOf(o) {
+  return {
+    lines: o.lines.map(({ itemCode = null, priceItemId = null, accountCode = null, description, quantity, unitAmountCents, taxCode }) => (
+      { itemCode, priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }
+    )),
+    contactId: o.contactId ?? null,
+    subtotalCents: o.subtotalCents,
+    taxCents: o.taxCents,
+    totalCents: o.totalCents,
+    sourceStatus: o.sourceStatus ?? null,
+    sourceSeenAt: o.sourceSeenAt ? new Date(o.sourceSeenAt).toISOString() : null,
+  };
+}
+
+// One key for a set of lines, the same for the job's lines and the invoice's.
+function linesKey(lines) {
+  const keys = (lines ?? [])
+    .map((l) => [l.priceItemId ?? l.accountCode ?? String(l.description ?? '').trim().toLowerCase(), l.quantity, l.unitAmountCents, l.taxCode])
+    .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  return createHash('sha256').update(JSON.stringify(keys)).digest('hex');
+}
+
+const sideValue = (side, field) => (field === 'lines' ? linesKey(side.lines) : (side[field] ?? null));
+
+// The three-way compare, field by field, of the facts the invoice was built
+// from (base), the work system now (source) and Flow's invoice now (flow).
+// Only work fields are compared (FIELD_OWNERS). The outcome:
+//   none     the work system is as it was, or as the invoice is: nothing to do
+//   offer    only the work system changed and the draft is not sent: a person
+//            can take the new lines into Flow's own draft (useSourceLines)
+//   conflict both changed, or the invoice left Flow: an alert only
+export function compareThreeWays(base, source, flow, { sent = false } = {}) {
+  const fields = COMPARED.map((field) => {
+    const [b, s, f] = [base, source, flow].map((side) => sideValue(side, field));
+    const changedIn = s === b ? (f === b ? 'none' : 'flow') : (f === b ? 'work' : (f === s ? 'same' : 'both'));
+    return { field, owner: FIELD_OWNERS[field], changedIn };
+  });
+  const work = fields.filter((f) => ['work', 'both'].includes(f.changedIn));
+  let outcome = 'none';
+  if (work.length) outcome = sent || work.some((f) => f.changedIn === 'both') ? 'conflict' : 'offer';
+  return { outcome, sent, fields };
+}
+
+// The invoice has left Flow's hands: issued, queued or sent, or the
+// accounting system holds it.
+function invoiceSent(invoice, obligation) {
+  return invoice.status !== 'draft' || ['queued', 'sent'].includes(invoice.sendState)
+    || LINKED_STATES.includes(obligation.accountingState);
+}
+
+async function compareWithDraft(tx, organisationId, obligation, facts) {
+  // An invoice drafted before the basis was kept: the last report stands in.
+  const base = obligation.draftBasis ?? basisOf(obligation);
+  let invoice;
+  try {
+    invoice = await getInvoice(tx, organisationId, obligation.invoiceId);
+  } catch (error) {
+    if (error?.code !== 'not_found') throw error;
+    return { outcome: 'conflict', sent: false, fields: [], base, missing: true };
+  }
+  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 };
+}
+
+function changedReview(obligation, compare) {
+  return {
+    kind: REVIEW_CHANGED,
+    entity: 'obligation',
+    flowId: obligation.id,
+    systems: [obligation.sourceSystem, 'flow'],
+    moneyAtRiskCents: Math.max(0, obligation.totalCents ?? 0),
+    evidence: {
+      outcome: compare.outcome,
+      sent: compare.sent,
+      invoiceId: obligation.invoiceId,
+      fields: compare.fields,
+      basis: compare.base,
+      job: basisOf(obligation),
+      invoice: compare.flow ? { contactId: compare.flow.contactId, lines: compare.flow.lines.map(({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }) => ({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode })) } : null,
+      canUseNewLines: compare.outcome === 'offer',
+    },
+  };
+}
+
+// "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 }) {
+  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 });
+    }
+    const changes = {};
+    for (const { field, changedIn } of compare.fields) {
+      if (changedIn !== 'work') continue;
+      if (field === 'lines') {
+        changes.lines = obligation.lines.map(({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }) => (
+          { priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }
+        ));
+      } else changes[field] = obligation[field];
+    }
+    const invoice = Object.keys(changes).length
+      ? await updateDraftInvoice(tx, organisationId, obligation.invoiceId, changes)
+      : await getInvoice(tx, organisationId, obligation.invoiceId);
+    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 resolveReviewFor(tx, organisationId, { kind: REVIEW_CHANGED, entity: 'obligation', flowId: row.id, resolution: 'used_new_lines', actor });
+    return { obligation: row, invoice };
+  });
+}
+
+// Records that a job the ledger knows is no longer billable in the work
+// system: deleted there, or its status moved back (for example from Shipped
+// to In production). Flow writes nothing to another system:
+//   deleted                      review hold and an alert
+//   status back, invoice made    review hold and an alert
+//   status back, only ready      the ready mark is cleared and an alert opens;
+//                                the alert closes when the job is billable again
+// The status is stored, so a repeat report of the same status does nothing.
+export async function observeWithdrawn(db, organisationId, entry) {
+  const { sourceSystem, sourceJobRef, sourceStatus = null, deleted = false, reason = null, actor = `system:${sourceSystem}` } = entry;
+  if (!sourceSystem || !sourceJobRef) throw new FlowError('invalid', 'sourceSystem and sourceJobRef are required');
+  const seenAt = entry.observedAt ? new Date(entry.observedAt) : new Date();
+  return db.transaction(async (tx) => {
+    const [obligation] = await tx.select().from(billingObligations)
+      .where(and(
+        eq(billingObligations.organisationId, organisationId),
+        eq(billingObligations.sourceSystem, sourceSystem),
+        eq(billingObligations.sourceJobRef, sourceJobRef),
+      ))
+      .for('update');
+    if (!obligation) return { obligation: null, action: 'none' };
+    if (deleted) {
+      if (obligation.holdState === 'review') return { obligation, action: 'none' };
+      const holdReason = reason ?? 'the job was deleted in the work system';
+      const row = await update(tx, obligation, { holdState: 'review', holdReason });
+      await addEvent(tx, row, 'review', actor, { from: obligation.holdState, reason: holdReason });
+      await openReview(tx, organisationId, statusReview(REVIEW_DELETED, row, { reason: holdReason }));
+      return { obligation: row, action: 'review' };
+    }
+    if (seenAt < obligation.sourceSeenAt || String(obligation.sourceStatus ?? '') === String(sourceStatus ?? '')) {
+      return { obligation, action: 'none' };
+    }
+    const fields = { sourceStatus, sourceSeenAt: seenAt };
+    let action = 'status';
+    if (obligation.invoiceId) {
+      if (obligation.holdState !== 'review') Object.assign(fields, { holdState: 'review', holdReason: STATUS_BACK_REASON });
+      action = 'review';
+    } else if (obligation.readyAt) {
+      // Not setReady's "in work": that marks a person's choice, and the ready
+      // routine must mark the job again when its status is billable again.
+      Object.assign(fields, { readyAt: null, readyBy: null });
+      action = 'ready_cleared';
+    }
+    const row = await update(tx, obligation, fields);
+    await addEvent(tx, row, 'status_moved_back', actor, {
+      from: obligation.sourceStatus, to: sourceStatus, action, ...(fields.holdState ? { holdReason: fields.holdReason } : {}),
+    });
+    if (action !== 'status') {
+      await openReview(tx, organisationId, statusReview(REVIEW_STATUS_BACK, row, { from: obligation.sourceStatus, to: sourceStatus, action }));
+    }
+    return { obligation: row, action };
+  });
+}
+
+function statusReview(kind, obligation, evidence) {
+  return {
+    kind,
+    entity: 'obligation',
+    flowId: obligation.id,
+    systems: [obligation.sourceSystem, 'flow'],
+    moneyAtRiskCents: Math.max(0, obligation.totalCents ?? 0),
+    evidence: { ...evidence, sourceJobRef: obligation.sourceJobRef, invoiceId: obligation.invoiceId ?? null },
+  };
+}
+
 // Records what the accounting system says about the job's invoice. Evidence
 // that is not tied to the job by an exact match never counts as found: it
 // makes the obligation ambiguous, for a person to resolve.
@@ -432,7 +665,10 @@ export async function draftInvoiceForObligation(db, organisationId, obligationId
     });
     // Drafting the invoice says the job is ready, whoever asked.
     const row = await update(tx, obligation, {
-      invoiceId: invoice.id, accountingCheckedAt: now, ...(obligation.readyAt ? {} : { readyAt: now, readyBy: actor }),
+      invoiceId: invoice.id,
+      draftBasis: basisOf(obligation),
+      accountingCheckedAt: now,
+      ...(obligation.readyAt ? {} : { readyAt: now, readyBy: actor }),
     });
     await addEvent(tx, row, 'drafted', actor, { invoiceId: invoice.id, totalCents: invoice.totalCents, live });
     return { obligation: row, invoice };