@arcforgelabs/flow 2026.10.26 → 2026.10.29

package/server/core/invoicing-rules.js

@@ -0,0 +1,255 @@
+import { and, eq, inArray, isNull, sql } from 'drizzle-orm';
+import {
+  billingObligations, contacts, customerBillingSettings, invoicingSettings, SEND_MODES,
+} from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { listRules, ruleReasons } from './invoice-rules.js';
+import { draftInvoiceForObligation } from './ledger.js';
+
+// Invoicing rules (docs/INVOICING_RULES.md). They are the checks a job that
+// is ready to invoice passes before Flow drafts its invoice, and how a checked
+// draft goes to the accounting system. Each rule is a setting of the
+// organisation; a customer can override some of them. The rules come from
+// the earlier lab app, where they were fixed in its code. When Flow drafts is
+// an automation (automations.js): Flow's own "ready to invoice" stage
+// triggers it, never another system's status.
+//
+// The ledger's own checks (ledger.js, draftBlockers) still guard every draft:
+// the job is not held, every line maps to a price item, it has a customer, the
+// accounting copy holds no invoice for it, and the work system's report is
+// recent. The lab's own checks are invoice rules it builds (invoice-rules.js);
+// the old job limit, practitioner and rush settings here only seed them.
+
+export const ACTOR = 'system:rules';
+const DRAFT_BATCH = 200;
+
+export const INVOICING_DEFAULTS = Object.freeze({
+  sendMode: 'accounting_draft',
+  staleDays: 90,
+  paymentTermsDays: 30,
+  requirePractitioner: false,
+  rushItemCode: null,
+  rushPercent: 20,
+});
+
+const CUSTOMER_DEFAULTS = Object.freeze({
+  billable: true, defaultPractitioner: null, autoDraft: null, sendMode: null, paymentTermsDays: null,
+});
+
+const pick = (row, keys) => Object.fromEntries(keys.map((k) => [k, row[k]]));
+const SETTING_KEYS = Object.keys(INVOICING_DEFAULTS);
+const CUSTOMER_KEYS = Object.keys(CUSTOMER_DEFAULTS);
+
+const invalid = (message) => new FlowError('invalid', message);
+
+function wholeNumber(value, name, min, max) {
+  if (!Number.isInteger(value) || value < min || value > max) throw invalid(`${name} must be a whole number from ${min} to ${max}`);
+  return value;
+}
+
+function flag(value, name) {
+  if (typeof value !== 'boolean') throw invalid(`${name} must be true or false`);
+  return value;
+}
+
+function shortText(value, name) {
+  if (value === null || value === '') return null;
+  if (typeof value !== 'string' || value.length > 200) throw invalid(`${name} must be text of 200 characters at most`);
+  return value.trim() || null;
+}
+
+function sendMode(value, name) {
+  if (!SEND_MODES.includes(value)) throw invalid(`${name} must be one of ${SEND_MODES.join(', ')}`);
+  return value;
+}
+
+// The organisation's settings as stored, or the defaults.
+export async function readInvoicingSettings(db, organisationId) {
+  const [row] = await db.select().from(invoicingSettings).where(eq(invoicingSettings.organisationId, organisationId));
+  return row ? pick(row, SETTING_KEYS) : { ...INVOICING_DEFAULTS };
+}
+
+function readSettingChanges(changes) {
+  if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw invalid('the settings must be an object');
+  const out = {};
+  for (const [key, value] of Object.entries(changes)) {
+    if (key === 'requirePractitioner') out[key] = flag(value, key);
+    else if (key === 'sendMode') out[key] = sendMode(value, key);
+    else if (key === 'staleDays') out[key] = wholeNumber(value, key, 1, 3650);
+    else if (key === 'paymentTermsDays') out[key] = wholeNumber(value, key, 0, 365);
+    else if (key === 'rushPercent') out[key] = wholeNumber(value, key, 0, 100);
+    else if (key === 'rushItemCode') out[key] = shortText(value, key);
+    else throw invalid(`unknown setting: ${key}`);
+  }
+  return out;
+}
+
+export async function saveInvoicingSettings(db, organisationId, changes, { personId = null } = {}) {
+  const fields = readSettingChanges(changes);
+  await db.insert(invoicingSettings)
+    .values({ organisationId, ...fields, updatedBy: personId })
+    .onConflictDoUpdate({ target: invoicingSettings.organisationId, set: { ...fields, updatedBy: personId, updatedAt: sql`now()` } });
+  return readInvoicingSettings(db, organisationId);
+}
+
+async function requireCustomer(db, organisationId, contactId) {
+  const [contact] = await db.select({ id: contacts.id, kind: contacts.kind }).from(contacts)
+    .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, contactId)));
+  if (!contact) throw notFound('customer');
+  if (contact.kind !== 'customer') throw invalid('invoicing settings are for a customer contact');
+}
+
+// One customer's own settings. A null value takes the organisation's setting.
+export async function readCustomerBilling(db, organisationId, contactId) {
+  await requireCustomer(db, organisationId, contactId);
+  const [row] = await db.select().from(customerBillingSettings)
+    .where(and(eq(customerBillingSettings.organisationId, organisationId), eq(customerBillingSettings.contactId, contactId)));
+  return row ? pick(row, CUSTOMER_KEYS) : { ...CUSTOMER_DEFAULTS };
+}
+
+export async function saveCustomerBilling(db, organisationId, contactId, changes, { personId = null } = {}) {
+  if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw invalid('the settings must be an object');
+  await requireCustomer(db, organisationId, contactId);
+  const fields = {};
+  for (const [key, value] of Object.entries(changes)) {
+    if (key === 'billable') fields[key] = flag(value, key);
+    else if (key === 'defaultPractitioner') fields[key] = shortText(value, key);
+    else if (key === 'autoDraft') fields[key] = value === null ? null : flag(value, key);
+    else if (key === 'sendMode') fields[key] = value === null ? null : sendMode(value, key);
+    else if (key === 'paymentTermsDays') fields[key] = value === null ? null : wholeNumber(value, key, 0, 365);
+    else throw invalid(`unknown setting: ${key}`);
+  }
+  await db.insert(customerBillingSettings)
+    .values({ organisationId, contactId, ...fields, updatedBy: personId })
+    .onConflictDoUpdate({
+      target: [customerBillingSettings.organisationId, customerBillingSettings.contactId],
+      set: { ...fields, updatedBy: personId, updatedAt: sql`now()` },
+    });
+  return readCustomerBilling(db, organisationId, contactId);
+}
+
+// The customers' own settings, by contact id.
+export async function customerBillingByContact(db, organisationId, contactIds) {
+  const ids = [...new Set(contactIds.filter(Boolean))];
+  if (!ids.length) return new Map();
+  const rows = await db.select().from(customerBillingSettings)
+    .where(and(eq(customerBillingSettings.organisationId, organisationId), inArray(customerBillingSettings.contactId, ids)));
+  return new Map(rows.map((r) => [r.contactId, pick(r, CUSTOMER_KEYS)]));
+}
+
+// The settings that apply to one customer: its own, else the organisation's.
+// `autoDraft` is the customer's own switch for the draft automation.
+export function effectiveSettings(settings, customer = CUSTOMER_DEFAULTS) {
+  const own = { ...CUSTOMER_DEFAULTS, ...customer };
+  return {
+    ...settings,
+    billable: own.billable,
+    defaultPractitioner: own.defaultPractitioner,
+    autoDraft: own.autoDraft ?? true,
+    sendMode: own.sendMode ?? settings.sendMode,
+    paymentTermsDays: own.paymentTermsDays ?? settings.paymentTermsDays,
+  };
+}
+
+// How one customer's checked drafts go to the accounting system.
+export async function sendModeFor(db, organisationId, contactId) {
+  const settings = await readInvoicingSettings(db, organisationId);
+  const customers = await customerBillingByContact(db, organisationId, [contactId]);
+  return effectiveSettings(settings, customers.get(contactId)).sendMode;
+}
+
+// What a job still waits on before Flow drafts it, as reasons a person can
+// read: Flow's own ready stage, then the lab's invoice rules (invoice-rules.js)
+// in their order. An empty list means the job may be drafted. `rules` is the
+// organisation's rules, read once per run with listRules.
+export function ruleBlockers(obligation, effective, { now = new Date(), rules = [] } = {}) {
+  const reasons = [];
+  if (!obligation.readyAt) reasons.push('the job is not marked ready to invoice');
+  return [...reasons, ...ruleReasons(rules, obligation, { customer: effective, now })];
+}
+
+function addDays(date, days) {
+  const at = new Date(`${date}T00:00:00Z`);
+  at.setUTCDate(at.getUTCDate() + days);
+  return at.toISOString().slice(0, 10);
+}
+
+const isoDay = (at) => `${at.getFullYear()}-${String(at.getMonth() + 1).padStart(2, '0')}-${String(at.getDate()).padStart(2, '0')}`;
+
+// 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) => {
+    const { complete, fresh, changedAt, invoices } = await accounting.capabilities.findInvoices({
+      organisationId,
+      numbers: obligation.sourceInvoiceRef ? [obligation.sourceInvoiceRef] : [],
+    });
+    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));
+    if (sales.length) return { state: sales[0].state, accountingRef: sales[0].id, matchedBy: 'copy' };
+    return { state: 'not_found', matchedBy: 'copy' };
+  };
+}
+
+// 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.
+// The draft automation (automations.js) runs it. Answers counts.
+// 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, now = new Date(), limit = DRAFT_BATCH, actor = ACTOR }) {
+  const result = { drafted: 0, waiting: 0, off: 0, refused: 0 };
+  const settings = await readInvoicingSettings(db, organisationId);
+  const rules = await listRules(db, organisationId);
+  if (accounting) {
+    const mirror = await accounting.capabilities.findInvoices({ organisationId });
+    if (!mirror.complete || !mirror.fresh) return { ...result, skipped: 'the accounting copy is not complete or not fresh' };
+  }
+
+  const candidates = await db.select().from(billingObligations).where(and(
+    eq(billingObligations.organisationId, organisationId),
+    isNull(billingObligations.invoiceId),
+    sql`${billingObligations.readyAt} is not null`,
+    eq(billingObligations.holdState, 'none'),
+    accounting
+      ? eq(billingObligations.accountingState, 'not_found')
+      : inArray(billingObligations.accountingState, ['not_found', 'unknown']),
+    eq(billingObligations.mappingComplete, true),
+    sql`${billingObligations.contactId} is not null`,
+    // Newest first: a backlog of jobs that wait on a rule never hides new work.
+  )).orderBy(sql`${billingObligations.jobDate} desc nulls last`, billingObligations.id).limit(limit);
+  const customers = await customerBillingByContact(db, organisationId, candidates.map((o) => o.contactId));
+  const liveCheck = accounting ? copyCheck(accounting, organisationId) : null;
+  const invoiceDate = isoDay(now);
+
+  for (const obligation of candidates) {
+    const effective = effectiveSettings(settings, customers.get(obligation.contactId));
+    if (!effective.autoDraft) {
+      result.off += 1;
+      continue;
+    }
+    if (ruleBlockers(obligation, effective, { now, rules }).length) {
+      result.waiting += 1;
+      continue;
+    }
+    try {
+      await draftInvoiceForObligation(db, organisationId, obligation.id, {
+        liveCheck,
+        actor,
+        now,
+        dueDate: addDays(invoiceDate, effective.paymentTermsDays),
+      });
+      result.drafted += 1;
+    } catch (error) {
+      if (error.code !== 'not_ready') throw error;
+      result.refused += 1;
+    }
+  }
+  return result;
+}

package/server/core/job-board.js

@@ -0,0 +1,130 @@
+import { and, eq, inArray, isNull } from 'drizzle-orm';
+import { contacts, invoices, priceItems } 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 { invoiceViews } from './sending.js';
+
+// The Jobs board (/jobs, server/ui/jobs.js). Its columns are the work
+// system's own job statuses, one to one. Its jobs come from the work
+// system's copy in Flow (the port's listWork: Seazona's open orders and the
+// ones finished lately), so jobs still in the lab show. A job that has a
+// billing obligation (ledger.js) carries it, with the state of its invoice,
+// for the job's detail panel. With no work system that offers listWork, the
+// board shows the ledger's jobs by the status the work system last reported.
+
+// The ledger's jobs with what the Jobs page shows: the customer's name, the
+// invoice's number, status, Invoices page view (sending.js) and problems,
+// and the invoicing rules a job with no invoice waits on. `listed` is
+// listObligations output. `accounting` is the accounting adapter, or null.
+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([
+    contactIds.length
+      ? db.select({ id: contacts.id, name: contacts.name }).from(contacts)
+        .where(and(eq(contacts.organisationId, organisationId), inArray(contacts.id, contactIds)))
+      : [],
+    invoiceIds.length
+      ? db.select({ id: invoices.id, number: invoices.number, status: invoices.status }).from(invoices)
+        .where(and(eq(invoices.organisationId, organisationId), inArray(invoices.id, invoiceIds)))
+      : [],
+    invoiceIds.length ? invoiceViews(db, organisationId, { accounting }) : null,
+  ]);
+  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);
+  const customers = await customerBillingByContact(db, organisationId, contactIds);
+  const rules = await listRules(db, organisationId);
+  const ready = new Set(views?.ready ?? []);
+  const toCheck = new Set(views?.toCheck ?? []);
+  const invoiceView = (id) => (!id || !views ? null
+    : views.problems.has(id) ? 'problem' : ready.has(id) ? 'ready' : toCheck.has(id) ? 'to_check'
+      : views.sending.has(id) ? 'sending' : null);
+  // The invoicing rules a job with no invoice waits on, for every view a
+  // 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 }) => ({
+    ...o,
+    contactName: nameOf.get(o.contactId) ?? null,
+    invoiceNumber: invoiceOf.get(o.invoiceId)?.number ?? null,
+    invoiceStatus: invoiceOf.get(o.invoiceId)?.status ?? null,
+    invoiceView: invoiceView(o.invoiceId),
+    invoiceProblems: (o.invoiceId && views?.problems.get(o.invoiceId)) || [],
+    view,
+    reasons,
+    waitingFor: waitingFor(o, view),
+  }));
+}
+
+const keyOf = (system, ref) => `${system}\u0000${ref}`;
+
+// The ledger's lines as the board shows them: whether each maps to a price item.
+const ledgerLines = (lines) => (lines ?? []).map((l) => ({
+  code: l.itemCode ?? null, description: l.description, amountCents: l.lineAmountCents ?? null, mapped: Boolean(l.priceItemId),
+}));
+
+// Answers { jobs, statuses }. `work` is the adapters that offer listWork;
+// `live` says an accounting system checks the ledger (ledgerView).
+export async function boardJobs(db, organisationId, { work = [], accounting = null, live = false, log = console } = {}) {
+  const listed = await listObligations(db, organisationId, { accounting: live });
+  const obligations = await describeObligations(db, organisationId, listed, { accounting });
+  const byJob = new Map(obligations.map((o) => [keyOf(o.sourceSystem, o.sourceJobRef), o]));
+
+  const reports = [];
+  for (const adapter of work) {
+    try {
+      reports.push(await adapter.capabilities.listWork({ organisationId }));
+    } catch (error) {
+      // The board still shows the ledger's jobs when the copy cannot be read.
+      log.error?.(`[jobs] ${adapter.id} listWork: ${error.message}`);
+    }
+  }
+  if (!reports.length) {
+    const statuses = new Map();
+    const jobs = obligations.map((o) => {
+      const status = o.sourceStatus?.trim() || null;
+      if (status && !statuses.has(status)) statuses.set(status, { label: status, final: false, firstSeenAt: null });
+      return {
+        sourceSystem: o.sourceSystem, sourceJobRef: o.sourceJobRef, caseRef: o.caseRef, status,
+        clientName: o.contactName, workClientName: null, practitioner: o.practitioner, department: null,
+        orderedOn: null, dueOn: null, jobDate: o.jobDate, shippedOn: o.shippedOn,
+        totalCents: o.totalCents, lines: ledgerLines(o.lines), obligation: o,
+      };
+    });
+    return { jobs, statuses: [...statuses.values()] };
+  }
+
+  const codes = new Set((await db.select({ code: priceItems.code }).from(priceItems)
+    .where(and(eq(priceItems.organisationId, organisationId), isNull(priceItems.archivedAt)))).map((p) => p.code));
+  const jobs = [];
+  const statuses = [];
+  for (const report of reports) {
+    statuses.push(...(report.statuses ?? []));
+    for (const item of report.items ?? []) {
+      const o = byJob.get(keyOf(item.sourceSystem, item.sourceJobRef)) ?? null;
+      jobs.push({
+        sourceSystem: item.sourceSystem,
+        sourceJobRef: item.sourceJobRef,
+        caseRef: item.caseRef ?? o?.caseRef ?? null,
+        status: item.status ?? null,
+        // The Flow customer once the work system's client is linked to one;
+        // until then the work system's own name for the client.
+        clientName: o?.contactName ?? item.clientName ?? null,
+        workClientName: item.clientName ?? null,
+        practitioner: item.practitioner ?? o?.practitioner ?? null,
+        department: item.department ?? null,
+        orderedOn: item.orderedOn ?? null,
+        dueOn: item.dueOn ?? null,
+        jobDate: o?.jobDate ?? null,
+        shippedOn: o?.shippedOn ?? null,
+        totalCents: o?.totalCents ?? item.totalCents ?? null,
+        lines: o ? ledgerLines(o.lines)
+          : (item.lines ?? []).map((l) => ({ code: l.code ?? null, description: l.description, amountCents: l.amountCents ?? null, mapped: Boolean(l.code && codes.has(l.code)) })),
+        obligation: o,
+      });
+    }
+  }
+  return { jobs, statuses };
+}

package/server/core/ledger.js

@@ -8,8 +8,8 @@ import { createDraftInvoice } from './invoices.js';
 import { invoiceTotals, lineTotals } from './money.js';
 
 // The billing obligation ledger. One billable job in a work system is one
-// obligation. Its view (Ready, Pending, Held, Drafted, Invoiced, Paid, Review
-// required) comes only from the evidence stored on it, never from a fresh
+// obligation. Its view (In work, Ready, Pending, Held, Drafted, Invoiced,
+// Paid, Review required) comes only from the evidence stored on it, never from a fresh
 // guess, and each change of evidence is an event. To make a draft invoice is a
 // guarded transition that fails closed.
 
@@ -32,8 +32,11 @@ async function loadObligation(tx, organisationId, obligationId, { lock = false }
   return row;
 }
 
+// clock_timestamp, not now(): events written in one transaction keep their
+// order when they are read back by time.
 async function addEvent(tx, obligation, kind, actor, evidence = {}) {
   await tx.insert(obligationEvents).values({
+    createdAt: sql`clock_timestamp()`,
     organisationId: obligation.organisationId,
     obligationId: obligation.id,
     kind,
@@ -82,14 +85,21 @@ async function normaliseLines(tx, organisationId, lines) {
     } catch (error) {
       throw new FlowError('invalid', `line ${index + 1}: ${error.message}`);
     }
-    normalised.push({ itemCode, priceItemId, description, quantity, unitAmountCents, taxCode, ...totals });
+    // A line mapped to an account (line-mapping.js) needs no price item.
+    const accountCode = priceItemId ? null : (line.accountCode?.trim() || null);
+    const extra = {
+      ...(accountCode ? { accountCode } : {}),
+      ...(line.label ? { label: line.label } : {}),
+      ...(line.mappedBy ? { mappedBy: line.mappedBy } : {}),
+    };
+    normalised.push({ itemCode, priceItemId, description, quantity, unitAmountCents, taxCode, ...extra, ...totals });
   }
   return normalised;
 }
 
 function fingerprint(lines) {
   const keys = lines
-    .map((l) => [l.itemCode ?? l.description.toLowerCase(), l.quantity, l.unitAmountCents, l.taxCode])
+    .map((l) => [l.itemCode ?? l.accountCode ?? l.description.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');
 }
@@ -110,10 +120,11 @@ export async function observeJob(db, organisationId, job) {
       practitioner: job.practitioner ?? null,
       shippedOn: job.shippedOn ?? null,
       jobDate: job.jobDate ?? null,
+      sourceStatus: job.sourceStatus ?? null,
       lines,
       lineFingerprint: fingerprint(lines),
       ...invoiceTotals(lines),
-      mappingComplete: lines.every((l) => l.priceItemId),
+      mappingComplete: lines.every((l) => l.priceItemId || l.accountCode),
     };
     const [existing] = await tx.select().from(billingObligations)
       .where(and(
@@ -138,7 +149,9 @@ 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, { sourceSeenAt: seenAt, mappingComplete: facts.mappingComplete, lines, jobDate: facts.jobDate });
+      return update(tx, existing, {
+        sourceSeenAt: seenAt, mappingComplete: facts.mappingComplete, lines, jobDate: facts.jobDate, sourceStatus: facts.sourceStatus,
+      });
     }
     const fields = { ...facts, sourceSeenAt: seenAt };
     if (existing.invoiceId && changed.some((key) => ['lineFingerprint', 'totalCents', 'contactId'].includes(key))) {
@@ -313,6 +326,20 @@ export async function recordWritebackResult(db, organisationId, writebackId, { o
   });
 }
 
+// Marks a job ready to invoice, or back in work. `actor` is a person or the
+// automation that decided. A job with an invoice stays as it is.
+export async function setReady(db, organisationId, obligationId, { ready = true, actor }) {
+  requireActor(actor);
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    if (Boolean(obligation.readyAt) === ready) return obligation;
+    if (!ready && obligation.invoiceId) throw new FlowError('invalid', 'the job has an invoice already');
+    const row = await update(tx, obligation, ready ? { readyAt: sql`now()`, readyBy: actor } : { readyAt: null, readyBy: null });
+    await addEvent(tx, row, ready ? 'ready' : 'in_work', actor, {});
+    return row;
+  });
+}
+
 // Puts an obligation on hold, sends it to review, or releases it.
 export async function setHold(db, organisationId, obligationId, { holdState, reason = null, actor }) {
   requireActor(actor);
@@ -329,7 +356,9 @@ export async function setHold(db, organisationId, obligationId, { holdState, rea
 }
 
 // The obligation's view and the reasons for it, from its stored evidence only.
-export function ledgerView(obligation, { now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS } = {}) {
+// `accounting` is false while no accounting system is connected: Flow's own
+// records are then the only check, so a job nobody checked in one can draft.
+export function ledgerView(obligation, { now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS, accounting = true } = {}) {
   const o = obligation;
   if (o.holdState === 'review') return { view: 'review_required', reasons: [o.holdReason ?? 'sent to review'] };
   if (['ambiguous', 'conflict'].includes(o.accountingState)) {
@@ -344,15 +373,20 @@ export function ledgerView(obligation, { now = new Date(), sourceMaxAgeMs = SOUR
     return { view: 'invoiced', reasons: [`invoice ${o.accountingRef} is ${o.accountingState.replace('_', ' ')}`] };
   }
   if (o.invoiceId || o.accountingState === 'drafted') return { view: 'drafted', reasons: ['a draft invoice exists'] };
-  const reasons = draftBlockers(o, { now, sourceMaxAgeMs });
+  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).
+  if (!o.readyAt) return { view: 'in_work', reasons: ['the job is not marked ready to invoice', ...reasons] };
   return reasons.length ? { view: 'pending', reasons } : { view: 'ready', reasons: ['all checks pass'] };
 }
 
-function draftBlockers(o, { now, sourceMaxAgeMs }) {
+function draftBlockers(o, { now, sourceMaxAgeMs, accounting = true }) {
   const reasons = [];
   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') reasons.push('the accounting system was not checked');
+  if (o.accountingState === 'unknown') {
+    if (accounting) reasons.push('the accounting system was not checked');
+  }
   else if (o.accountingState !== 'not_found') reasons.push(`the accounting system reports ${o.accountingState}`);
   if (!o.mappingComplete) reasons.push('a line does not map to a price item');
   if (!o.contactId) reasons.push('the job has no customer contact');
@@ -365,15 +399,17 @@ function draftBlockers(o, { now, sourceMaxAgeMs }) {
 // the write, finds no invoice for the job. Any doubt refuses the draft, and
 // the refusal is recorded.
 export async function draftInvoiceForObligation(db, organisationId, obligationId, {
-  liveCheck, actor, now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS,
+  liveCheck, actor, now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS, dueDate = null,
 }) {
   requireActor(actor);
-  if (typeof liveCheck !== 'function') throw new FlowError('invalid', 'liveCheck is required');
+  // A null liveCheck says no accounting system is connected (ledgerView).
+  if (liveCheck !== null && typeof liveCheck !== 'function') throw new FlowError('invalid', 'liveCheck must be a function, or null with no accounting system');
+  const accounting = liveCheck !== null;
   const outcome = await db.transaction(async (tx) => {
     const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
-    const reasons = draftBlockers(obligation, { now, sourceMaxAgeMs });
+    const reasons = draftBlockers(obligation, { now, sourceMaxAgeMs, accounting });
     let live = null;
-    if (!reasons.length) {
+    if (!reasons.length && accounting) {
       try {
         live = await liveCheck(obligation);
       } catch (error) {
@@ -388,11 +424,15 @@ export async function draftInvoiceForObligation(db, organisationId, obligationId
     const invoice = await createDraftInvoice(tx, organisationId, {
       contactId: obligation.contactId,
       reference: obligation.caseRef ?? obligation.sourceJobRef,
-      lines: obligation.lines.map(({ priceItemId, description, quantity, unitAmountCents, taxCode }) => (
-        { priceItemId, description, quantity, unitAmountCents, taxCode }
+      dueDate,
+      lines: obligation.lines.map(({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }) => (
+        { priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }
       )),
     });
-    const row = await update(tx, obligation, { invoiceId: invoice.id, accountingCheckedAt: now });
+    // 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 }),
+    });
     await addEvent(tx, row, 'drafted', actor, { invoiceId: invoice.id, totalCents: invoice.totalCents, live });
     return { obligation: row, invoice };
   });