@arcforgelabs/flow 2026.10.26 → 2026.10.27

package/server/core/invoice-rules.js

@@ -0,0 +1,224 @@
+import { and, asc, eq, sql } from 'drizzle-orm';
+import { invoiceRules, invoicingSettings } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+
+// Invoice rules (docs/INVOICE_RULES.md): a lab's own checks on a job before
+// Flow drafts its invoice. Each rule is When, If and Then, and a lab owner
+// builds it from menus, so no lab's checks are fixed in Flow's code.
+//
+//   When  job_ready: the job is ready to invoice and has no invoice yet.
+//   If    every condition matches: a field of the job, its customer or its
+//         lines, a test, and a value.
+//   Then  wait: the job waits for a person; skip: rules never draft it.
+//
+// The rules read only Flow's own records, so they work with or without an
+// accounting integration. The earlier fixed settings (old job limit, required
+// practitioner, rush share) become starter rules, once per organisation.
+
+const MAX_RULES = 100;
+const MAX_CONDITIONS = 10;
+const invalid = (message) => new FlowError('invalid', message);
+
+const day = (date) => new Date(`${String(date).slice(0, 10)}T00:00:00Z`);
+const norm = (value) => String(value ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+const code = (line) => norm(line.itemCode);
+const cents = (lines) => lines.reduce((sum, l) => sum + (l.lineAmountCents ?? 0), 0);
+
+// The share of the item's lines in the job's other lines, as the charged and
+// the expected cents for `percent`.
+function share(lines, item, percent) {
+  const own = lines.filter((l) => code(l) === norm(item));
+  if (!own.length) return null;
+  const others = cents(lines.filter((l) => code(l) !== norm(item)));
+  return { charged: cents(own), others, expected: Math.round((others * percent) / 100) };
+}
+
+// Each field: what it reads from a job, its kind, and the tests it allows.
+export const FIELDS = Object.freeze({
+  job_age_days: { label: 'Job age (days)', kind: 'number', read: (j, { now }) => (j.jobDate ? Math.floor((now - day(j.jobDate)) / 86_400_000) : null) },
+  job_total: { label: 'Job total', kind: 'money', read: (j) => (j.totalCents ?? 0) / 100 },
+  job_status: { label: 'Job status', kind: 'choice', options: 'statuses', read: (j) => norm(j.sourceStatus) || null },
+  practitioner: { label: 'Practitioner', kind: 'text', read: (j, { customer }) => j.practitioner || customer.defaultPractitioner || null },
+  customer: { label: 'Customer', kind: 'choice', options: 'customers', read: (j) => j.contactId },
+  customer_billable: { label: 'Customer is billable', kind: 'boolean', read: (j, { customer }) => customer.billable !== false },
+  line_item: { label: 'Line item', kind: 'items', options: 'items', read: (j) => (j.lines ?? []).map(code) },
+  line_share: { label: 'Line share of other lines (%)', kind: 'share', options: 'items', read: (j) => j.lines ?? [] },
+});
+
+export const TESTS = Object.freeze({
+  number: ['more_than', 'at_most', 'is', 'is_not', 'is_empty'],
+  money: ['more_than', 'at_most', 'is', 'is_not'],
+  choice: ['is', 'is_not', 'is_one_of', 'is_empty'],
+  text: ['is', 'is_not', 'is_empty', 'is_not_empty'],
+  boolean: ['is'],
+  items: ['has', 'has_not'],
+  share: ['is', 'is_not'],
+});
+
+export const ACTIONS = Object.freeze(['wait', 'skip']);
+
+function readCondition(raw, index) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw invalid(`condition ${index + 1} must be an object`);
+  const field = FIELDS[raw.field];
+  if (!field) throw invalid(`condition ${index + 1}: unknown field ${raw.field}`);
+  if (!TESTS[field.kind].includes(raw.test)) throw invalid(`condition ${index + 1}: ${field.label} takes ${TESTS[field.kind].join(', ')}`);
+  const out = { field: raw.field, test: raw.test };
+  if (['is_empty', 'is_not_empty'].includes(raw.test)) return out;
+  const { value } = raw;
+  if (field.kind === 'boolean') {
+    if (typeof value !== 'boolean') throw invalid(`condition ${index + 1}: the value must be true or false`);
+  } else if (['number', 'money', 'share'].includes(field.kind)) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1e9) throw invalid(`condition ${index + 1}: the value must be a number`);
+  } else if (raw.test === 'is_one_of') {
+    if (!Array.isArray(value) || !value.length || value.length > 50 || value.some((v) => typeof v !== 'string' || !v.trim() || v.length > 200)) {
+      throw invalid(`condition ${index + 1}: pick 1 to 50 values`);
+    }
+  } else if (typeof value !== 'string' || !value.trim() || value.length > 200) {
+    throw invalid(`condition ${index + 1}: the value must be short text`);
+  }
+  out.value = typeof value === 'string' ? value.trim() : value;
+  if (field.kind === 'share') {
+    if (typeof raw.item !== 'string' || !raw.item.trim() || raw.item.length > 100) throw invalid(`condition ${index + 1}: pick the line item`);
+    out.item = raw.item.trim();
+  }
+  return out;
+}
+
+export function readRule(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw invalid('the rule must be an object');
+  const unknown = Object.keys(raw).filter((k) => !['name', 'enabled', 'conditions', 'action'].includes(k));
+  if (unknown.length) throw invalid(`unknown field: ${unknown[0]}`);
+  const name = typeof raw.name === 'string' ? raw.name.trim() : '';
+  if (!name || name.length > 120) throw invalid('the rule needs a name of 120 characters at most');
+  const enabled = raw.enabled ?? true;
+  if (typeof enabled !== 'boolean') throw invalid('enabled must be true or false');
+  if (!Array.isArray(raw.conditions) || !raw.conditions.length || raw.conditions.length > MAX_CONDITIONS) {
+    throw invalid(`the rule needs 1 to ${MAX_CONDITIONS} conditions`);
+  }
+  if (!ACTIONS.includes(raw.action?.kind)) throw invalid(`the action must be one of ${ACTIONS.join(', ')}`);
+  return { name, enabled, conditions: raw.conditions.map(readCondition), action: { kind: raw.action.kind } };
+}
+
+function matches(condition, job, context) {
+  const field = FIELDS[condition.field];
+  const have = field.read(job, context);
+  const { test, value } = condition;
+  if (test === 'is_empty') return have === null || have === '' || have === undefined;
+  if (test === 'is_not_empty') return !(have === null || have === '' || have === undefined);
+  switch (field.kind) {
+    case 'items': {
+      const found = have.includes(norm(value));
+      return test === 'has' ? found : !found;
+    }
+    case 'share': {
+      const s = share(have, condition.item, value);
+      if (!s) return false;
+      const right = Math.abs(s.charged - s.expected) <= 1;
+      return test === 'is' ? right : !right;
+    }
+    case 'number':
+    case 'money':
+      if (have === null) return false;
+      if (test === 'more_than') return have > value;
+      if (test === 'at_most') return have <= value;
+      if (test === 'is') return have === value;
+      return have !== value;
+    case 'boolean':
+      return have === value;
+    default: {
+      const left = norm(have);
+      if (test === 'is_one_of') return value.some((v) => norm(v) === left);
+      return test === 'is' ? left === norm(value) : left !== norm(value);
+    }
+  }
+}
+
+// The reasons the enabled rules give for one job, in rule order. An empty list
+// means no rule stops its draft. `customer` is the customer's own billing
+// settings (invoicing-rules.js).
+export function ruleReasons(rules, job, { customer = {}, now = new Date() } = {}) {
+  const context = { customer, now };
+  const reasons = [];
+  for (const rule of rules) {
+    if (!rule.enabled || rule.trigger !== 'job_ready') continue;
+    if (!rule.conditions.every((c) => matches(c, job, context))) continue;
+    reasons.push(rule.action.kind === 'skip' ? `rule "${rule.name}": not drafted by rule` : `rule "${rule.name}": waits for a person`);
+  }
+  return reasons;
+}
+
+// The starter rules made from the earlier fixed settings.
+export function starterRules(settings) {
+  const rules = [
+    { starterKey: 'not_billable', name: 'Customer not billable', enabled: true, conditions: [{ field: 'customer_billable', test: 'is', value: false }], action: { kind: 'skip' } },
+    { starterKey: 'zero_total', name: 'No amount', enabled: true, conditions: [{ field: 'job_total', test: 'at_most', value: 0 }], action: { kind: 'wait' } },
+    { starterKey: 'old_job', name: 'Old job', enabled: true, conditions: [{ field: 'job_age_days', test: 'more_than', value: settings.staleDays ?? 90 }], action: { kind: 'wait' } },
+    { starterKey: 'practitioner', name: 'Practitioner required', enabled: Boolean(settings.requirePractitioner), conditions: [{ field: 'practitioner', test: 'is_empty' }], action: { kind: 'wait' } },
+  ];
+  if (settings.rushItemCode) {
+    rules.push({
+      starterKey: 'rush_share', name: 'Rush charge share', enabled: true,
+      conditions: [{ field: 'line_share', item: settings.rushItemCode, test: 'is_not', value: settings.rushPercent ?? 20 }],
+      action: { kind: 'wait' },
+    });
+  }
+  return rules.map((r) => ({ trigger: 'job_ready', ...r }));
+}
+
+// Makes this organisation's starter rules once, from its fixed settings.
+async function seed(db, organisationId) {
+  await db.transaction(async (tx) => {
+    await tx.insert(invoicingSettings).values({ organisationId }).onConflictDoNothing();
+    const [settings] = await tx.select().from(invoicingSettings).where(eq(invoicingSettings.organisationId, organisationId)).for('update');
+    if (settings.rulesSeeded) return;
+    const rules = starterRules(settings);
+    await tx.insert(invoiceRules).values(rules.map((r, position) => ({ organisationId, position, ...r }))).onConflictDoNothing();
+    await tx.update(invoicingSettings).set({ rulesSeeded: true }).where(eq(invoicingSettings.organisationId, organisationId));
+  });
+}
+
+const shape = (r) => ({
+  id: r.id, name: r.name, position: r.position, enabled: r.enabled, trigger: r.trigger,
+  conditions: r.conditions, action: r.action, starter: Boolean(r.starterKey), updatedAt: r.updatedAt,
+});
+
+// The organisation's rules, in order. The first read makes the starter rules.
+export async function listRules(db, organisationId) {
+  const [settings] = await db.select({ seeded: invoicingSettings.rulesSeeded }).from(invoicingSettings)
+    .where(eq(invoicingSettings.organisationId, organisationId));
+  if (!settings?.seeded) await seed(db, organisationId);
+  const rows = await db.select().from(invoiceRules).where(eq(invoiceRules.organisationId, organisationId))
+    .orderBy(asc(invoiceRules.position), asc(invoiceRules.createdAt));
+  return rows.map(shape);
+}
+
+export async function createRule(db, organisationId, raw, { personId = null } = {}) {
+  const rule = readRule(raw);
+  const existing = await listRules(db, organisationId);
+  if (existing.length >= MAX_RULES) throw invalid(`an organisation can have ${MAX_RULES} rules at most`);
+  const position = existing.length ? Math.max(...existing.map((r) => r.position)) + 1 : 0;
+  const [row] = await db.insert(invoiceRules).values({ organisationId, position, ...rule, updatedBy: personId }).returning();
+  return shape(row);
+}
+
+async function loadRule(db, organisationId, ruleId) {
+  const [row] = await db.select().from(invoiceRules).where(and(eq(invoiceRules.organisationId, organisationId), eq(invoiceRules.id, ruleId)));
+  if (!row) throw notFound('rule');
+  return row;
+}
+
+// Changes a rule. `changes` holds any of name, enabled, conditions, action;
+// the result must be a whole valid rule.
+export async function updateRule(db, organisationId, ruleId, changes, { personId = null } = {}) {
+  const row = await loadRule(db, organisationId, ruleId);
+  if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw invalid('the change must be an object');
+  const rule = readRule({ name: row.name, enabled: row.enabled, conditions: row.conditions, action: row.action, ...changes });
+  const [saved] = await db.update(invoiceRules).set({ ...rule, updatedBy: personId, updatedAt: sql`now()` })
+    .where(eq(invoiceRules.id, row.id)).returning();
+  return shape(saved);
+}
+
+export async function deleteRule(db, organisationId, ruleId) {
+  const row = await loadRule(db, organisationId, ruleId);
+  await db.delete(invoiceRules).where(eq(invoiceRules.id, row.id));
+}

package/server/core/invoices.js

@@ -96,6 +96,8 @@ export async function updateDraftInvoice(db, organisationId, invoiceId, changes)
     }
     if ('reference' in changes) fields.reference = changes.reference;
     if ('dueDate' in changes) fields.dueDate = changes.dueDate;
+    // A changed draft needs a person to check it again.
+    if (Object.keys(fields).length || 'lines' in changes) Object.assign(fields, { readyAt: null, readyBy: null });
     let row = invoice;
     if (Object.keys(fields).length) {
       [row] = await tx.update(invoices).set({ ...fields, updatedAt: sql`now()` })
@@ -160,7 +162,8 @@ export async function reviseInvoice(db, organisationId, invoiceId) {
   return db.transaction(async (tx) => {
     const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
     if (invoice.status !== 'issued') throw new FlowError('not_issued', 'only an issued invoice can be revised');
-    const [row] = await tx.update(invoices).set({ status: 'draft', updatedAt: sql`now()` })
+    // A revision is a new version: what happened to the last send no longer applies.
+    const [row] = await tx.update(invoices).set({ status: 'draft', readyAt: null, readyBy: null, sendState: null, sendError: null, updatedAt: sql`now()` })
       .where(eq(invoices.id, invoice.id)).returning();
     return row;
   });

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/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,
@@ -110,6 +113,7 @@ 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),
@@ -138,7 +142,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 +319,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 +349,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 +366,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 +392,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 +417,15 @@ export async function draftInvoiceForObligation(db, organisationId, obligationId
     const invoice = await createDraftInvoice(tx, organisationId, {
       contactId: obligation.contactId,
       reference: obligation.caseRef ?? obligation.sourceJobRef,
+      dueDate,
       lines: obligation.lines.map(({ priceItemId, description, quantity, unitAmountCents, taxCode }) => (
         { priceItemId, 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 };
   });