@arcforgelabs/flow 2026.10.32 → 2026.10.33

package/server/core/pipeline.js

@@ -6,7 +6,7 @@ import {
 import { FlowError } from './errors.js';
 import { listAutomations, runAutomations } from './automations.js';
 import { readInvoicingSettings } from './invoicing-rules.js';
-import { observeJob, recordAccountingEvidence, setHold } from './ledger.js';
+import { observeJob, observeWithdrawn, recordAccountingEvidence, setHold } from './ledger.js';
 import { loadMappingContext, mapLines } from './line-mapping.js';
 import { checkPrices, readCatalogues } from './price-list.js';
 import { linkRecord, priorLinkFor } from './links.js';
@@ -130,25 +130,38 @@ async function writeCursor(db, organisationId, name, cursor) {
     .onConflictDoUpdate({ target: [pipelineCursors.organisationId, pipelineCursors.name], set: { cursor, updatedAt: sql`now()` } });
 }
 
-// Reads the work system's billable jobs since the last run into the ledger.
-// `restart` reads every job again, for example after new customer links.
-export async function ingestWork(db, organisationId, { adapter, restart = false, pages = WORK_PAGES }) {
-  const name = `${adapter.id}.work`;
-  let cursor = restart ? null : await readCursor(db, organisationId, name);
+// Turns a work item into the job the ledger observes: its customer from the
+// identity map, and its lines mapped to price items when "Map lines" is on.
+// `mapped` says whether lines are mapped.
+export async function workJobMaker(db, organisationId, adapter) {
   const links = await activeLinks(db, organisationId, { system: adapter.id, entity: 'contact' });
   const contactOf = new Map(links.map((l) => [l.externalId, l.flowId]));
-  const result = { observed: 0, withoutCustomer: 0, skipped: 0, sentToReview: 0, unmappedLines: 0, more: false };
   // Line mapping (line-mapping.js): each line finds its price item first.
   const mapping = (await listAutomations(db, organisationId)).find((a) => a.key === 'map_lines');
   const context = mapping?.enabled ? await loadMappingContext(db, organisationId, mapping.config, { system: adapter.id }) : null;
+  const toJob = (item) => {
+    const job = context ? { ...item.ledgerJob, lines: mapLines(item.ledgerJob.lines ?? [], context) } : item.ledgerJob;
+    return { ...job, contactId: contactOf.get(String(item.clientId ?? '')) ?? null };
+  };
+  toJob.mapped = Boolean(context);
+  return toJob;
+}
+
+// Reads the work system's billable jobs since the last run into the ledger.
+// `restart` reads every job again, for example after new customer links.
+export async function ingestWork(db, organisationId, { adapter, restart = false, pages = WORK_PAGES }) {
+  const name = `${adapter.id}.work`;
+  let cursor = restart ? null : await readCursor(db, organisationId, name);
+  const toJob = await workJobMaker(db, organisationId, adapter);
+  const result = { observed: 0, withoutCustomer: 0, skipped: 0, sentToReview: 0, readyCleared: 0, unmappedLines: 0, more: false };
   for (let page = 0; page < pages; page += 1) {
     const { items, withdrawn, cursor: next, more } = await adapter.capabilities.pullWorkItems(cursor, { limit: 200 });
     for (const item of items) {
-      const contactId = contactOf.get(String(item.clientId ?? '')) ?? null;
-      const job = context ? { ...item.ledgerJob, lines: mapLines(item.ledgerJob.lines ?? [], context) } : item.ledgerJob;
-      if (context) result.unmappedLines += job.lines.filter((l) => !l.itemCode && !l.accountCode).length;
+      const job = toJob(item);
+      const { contactId } = job;
+      if (toJob.mapped) result.unmappedLines += job.lines.filter((l) => !l.itemCode && !l.accountCode).length;
       try {
-        await observeJob(db, organisationId, { ...job, contactId });
+        await observeJob(db, organisationId, job);
         result.observed += 1;
         if (!contactId) result.withoutCustomer += 1;
       } catch (error) {
@@ -157,17 +170,12 @@ export async function ingestWork(db, organisationId, { adapter, restart = false,
         result.skipped += 1;
       }
     }
+    // A job no longer billable: deleted, or its status moved back (ledger.js).
     for (const entry of withdrawn) {
-      if (!entry.ledgerHold) continue;
-      const { sourceSystem, sourceJobRef, holdState, reason } = entry.ledgerHold;
-      const [obligation] = await db.select().from(billingObligations).where(and(
-        eq(billingObligations.organisationId, organisationId),
-        eq(billingObligations.sourceSystem, sourceSystem),
-        eq(billingObligations.sourceJobRef, sourceJobRef),
-      ));
-      if (!obligation || obligation.holdState === holdState) continue;
-      await setHold(db, organisationId, obligation.id, { holdState, reason, actor: `system:${adapter.id}` });
-      result.sentToReview += 1;
+      if (!entry.ledgerWithdrawn) continue;
+      const { action } = await observeWithdrawn(db, organisationId, { ...entry.ledgerWithdrawn, actor: `system:${adapter.id}` });
+      if (action === 'review') result.sentToReview += 1;
+      if (action === 'ready_cleared') result.readyCleared += 1;
     }
     cursor = next;
     await writeCursor(db, organisationId, name, cursor);

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

@@ -0,0 +1,96 @@
+import { and, eq } from 'drizzle-orm';
+import { billingObligations } from '../db/schema.js';
+import { FlowError } from './errors.js';
+import { observeJob, observeWithdrawn } from './ledger.js';
+import { matchJobs, workJobMaker } from './pipeline.js';
+
+// Read before act (issue #141). Flow drafts and sends from its own copy of
+// the work system. Just before a draft, and before Send all ready, a job
+// whose work system report is older than READ_BEFORE_ACT_MS is read again
+// from the work system (its readWorkItem capability): one call per job. What
+// the read finds goes into the ledger as any report does (observeJob), so a
+// change after the invoice was made sends the job to review there.
+//
+// A job the work system deleted, or that is no longer billable, goes through
+// the ledger's observeWithdrawn like a feed report: review when it was
+// deleted or already has its invoice. A job that is not billable now, or a
+// read that cannot run, waits: Flow never drafts or sends from an old copy.
+//
+// The lanes re-report each job they read at most once an hour
+// (seazona/feed.js), so most reports are under two hours old and cost no
+// call here.
+
+export const READ_BEFORE_ACT_MS = 2 * 60 * 60 * 1000;
+// The most reads one pipeline run or one Send all ready press makes; the
+// other old jobs wait for the next one. Seazona's calls are spaced 2 s apart.
+export const READS_PER_PASS = 20;
+const NO_LONGER_BILLABLE = 'the work system no longer reports the job as billable';
+
+// Reads each job that needs it. `work` is the work integration, or null.
+// Answers Map(obligationId -> { outcome, obligation, reason? }), where
+// outcome is fresh (no read needed), read, review (sent to review) or
+// waiting (the read could not run).
+export async function readBeforeAct(db, organisationId, obligations, { work, now = new Date(), actor }) {
+  const outcomes = new Map();
+  let toJob = null;
+  for (const obligation of obligations) {
+    if (!needsRead(obligation, { work, now })) {
+      outcomes.set(obligation.id, { outcome: 'fresh', obligation });
+      continue;
+    }
+    const answer = await work.capabilities.readWorkItem({ sourceJobRef: obligation.sourceJobRef });
+    if (answer?.state === 'read') {
+      toJob ??= await workJobMaker(db, organisationId, work);
+      try {
+        await observeJob(db, organisationId, toJob(answer.item));
+      } catch (error) {
+        if (!(error instanceof FlowError) || error.code !== 'invalid') throw error;
+        outcomes.set(obligation.id, { outcome: 'waiting', obligation, reason: 'the work system job has no lines' });
+        continue;
+      }
+      const fresh = await reload(db, organisationId, obligation.id);
+      outcomes.set(obligation.id, { outcome: fresh.holdState === 'review' ? 'review' : 'read', obligation: fresh });
+    } else if (answer?.state === 'withdrawn') {
+      // The ledger decides as for the feed (observeWithdrawn): deleted, or
+      // moved back after its invoice, goes to review; moved back while only
+      // ready clears the ready mark.
+      if (answer.ledgerWithdrawn) await observeWithdrawn(db, organisationId, { ...answer.ledgerWithdrawn, actor });
+      const row = await reload(db, organisationId, obligation.id);
+      outcomes.set(obligation.id, row.holdState === 'review'
+        ? { outcome: 'review', obligation: row, reason: row.holdReason }
+        : { outcome: 'waiting', obligation: row, reason: NO_LONGER_BILLABLE });
+    } else {
+      outcomes.set(obligation.id, { outcome: 'waiting', obligation, reason: answer?.reason || 'the work system read failed' });
+    }
+  }
+  return outcomes;
+}
+
+// True when the job's report is old and its work system can read it now.
+export function needsRead(obligation, { work, now = new Date() }) {
+  return typeof work?.capabilities?.readWorkItem === 'function'
+    && obligation.sourceSystem === work.id
+    && now - new Date(obligation.sourceSeenAt) > READ_BEFORE_ACT_MS;
+}
+
+// The accounting side of read before act (issue #45, step 5): once per
+// automatic draft pass or Send all ready press, before the first draft or
+// send, the accounting system reads its latest changes into its copy (its
+// readChanges capability). When the copy changed, the matcher runs first, so
+// a job someone invoiced in the accounting system meanwhile is linked to that
+// invoice and never drafted or sent twice. Answers { outcome, reason? }:
+// fresh or read (act), or waiting (act on nothing now).
+export async function readAccountingFirst(db, organisationId, { accounting, now = new Date() }) {
+  if (typeof accounting?.capabilities?.readChanges !== 'function') return { outcome: 'fresh' };
+  const answer = await accounting.capabilities.readChanges({ organisationId });
+  if (answer?.state === 'fresh') return { outcome: 'fresh' };
+  if (answer?.state !== 'read') return { outcome: 'waiting', reason: answer?.reason || 'the accounting system read failed' };
+  if (answer.changed) await matchJobs(db, organisationId, { accounting, now });
+  return { outcome: 'read', changed: answer.changed ?? 0 };
+}
+
+async function reload(db, organisationId, id) {
+  const [row] = await db.select().from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, id)));
+  return row;
+}

package/server/core/reconcile.js

@@ -0,0 +1,350 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { and, desc, eq, gte, inArray, lte, sql } from 'drizzle-orm';
+import { backgroundJobs, billingObligations, invoices, reviewItems } from '../db/schema.js';
+import { HISTORY_ACTOR } from './history.js';
+import { soleOrganisation } from './pipeline.js';
+import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
+import { openReview, resolveReviewFor } from './review.js';
+
+// The daily reconcile (issue 129, docs/RECONCILE.md). Flow checks each record
+// as it moves; once a day it also checks the whole. For each of the last
+// `days` days it counts and totals the jobs in three places, from Flow's own
+// tables only (no call to any other system):
+//
+// 1. the work system's copy (each adapter's `billableJobs`);
+// 2. the billing obligation ledger;
+// 3. the Flow invoices the ledger made, and the accounting system's copy of
+//    the invoices linked to them (`findInvoices`).
+//
+// A day where they do not agree opens one review item (`reconcile.day`) with
+// the counts, the totals and up to 20 record ids for each difference. A
+// difference is an alert only: the reconcile never changes a record. The item
+// closes by itself when a later run agrees.
+//
+// A difference first seen is checked again an hour later, and opens an item
+// only when it is still there: a job the pipeline has not reached yet is not
+// a difference.
+
+export const RECONCILE_KIND = 'reconcile.daily';
+export const RECONCILE_REVIEW_KIND = 'reconcile.day';
+export const ACTOR = 'system:reconcile';
+export const RECONCILE_DAYS = 60;
+export const EVIDENCE_IDS = 20;
+const RUN_EVERY_MS = 24 * 60 * 60 * 1000;
+const RECHECK_MS = 60 * 60 * 1000;
+const TICK_MS = 10 * 60 * 1000;
+const LEASE_MS = 15 * 60 * 1000;
+const FIND_BATCH = 400;
+// Accounting states where the ledger holds a link to an invoice that exists.
+const LINKED = ['drafted', 'authorised', 'part_paid', 'paid'];
+
+const isoDay = (ms) => new Date(ms).toISOString().slice(0, 10);
+const withGst = (cents) => Math.round(cents * 1.1);
+
+// A stable id for one day's review item, so a repeat finding refreshes it.
+export function dayReviewId(organisationId, day) {
+  const hex = createHash('sha256').update(`${RECONCILE_REVIEW_KIND}:${organisationId}:${day}`).digest('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+
+function emptyDay(day) {
+  return {
+    day,
+    work: { count: 0, subtotalCents: 0, unpriced: 0 },
+    ledger: { count: 0, subtotalCents: 0, totalCents: 0 },
+    flowInvoices: { count: 0, totalCents: 0 },
+    accounting: { linked: 0, found: 0, totalCents: 0 },
+    differences: {
+      missingInLedger: [], missingInWork: [], missingInAccounting: [], accountingTotalDiffers: [],
+    },
+  };
+}
+
+const differenceCount = (entry) => Object.values(entry.differences).reduce((n, list) => n + list.length, 0);
+
+// The evidence a review item keeps: the counts, the totals, and up to
+// EVIDENCE_IDS ids for each difference with the full count beside them.
+function evidenceFor(entry) {
+  const differences = {};
+  for (const [key, list] of Object.entries(entry.differences)) {
+    if (list.length) differences[key] = { count: list.length, ids: list.slice(0, EVIDENCE_IDS).map((d) => d.id) };
+  }
+  return { ...entry, differences };
+}
+
+const moneyAtRisk = (entry) => Object.values(entry.differences).flat()
+  .reduce((cents, d) => cents + Math.abs(d.cents ?? 0), 0);
+
+// One pass over Flow's own tables. Answers one entry per day, oldest first.
+export async function reconcileDays(db, organisationId, { integrations, from, to }) {
+  const byDay = new Map();
+  const dayOf = (day) => {
+    if (!byDay.has(day)) byDay.set(day, emptyDay(day));
+    return byDay.get(day);
+  };
+
+  // 1. The work systems' copies.
+  const workAdapters = integrations?.with('billableJobs') ?? [];
+  const work = new Map(); // `${system}:${ref}` -> job
+  for (const adapter of workAdapters) {
+    const { jobs } = await adapter.capabilities.billableJobs({ organisationId, from, to });
+    for (const job of jobs) {
+      if (!job.day || job.day < from || job.day > to) continue;
+      work.set(`${adapter.id}:${job.ref}`, { ...job, system: adapter.id });
+      const entry = dayOf(job.day);
+      entry.work.count += 1;
+      if (Number.isInteger(job.subtotalCents)) entry.work.subtotalCents += job.subtotalCents;
+      else entry.work.unpriced += 1;
+    }
+  }
+
+  // 2. The ledger. A job only a history import reported is left out: the
+  // import keeps its own reconciliation record (docs/SEAZONA.md).
+  const obligations = await db.select({
+    id: billingObligations.id,
+    sourceSystem: billingObligations.sourceSystem,
+    sourceJobRef: billingObligations.sourceJobRef,
+    jobDate: billingObligations.jobDate,
+    subtotalCents: billingObligations.subtotalCents,
+    totalCents: billingObligations.totalCents,
+    accountingState: billingObligations.accountingState,
+    accountingRef: billingObligations.accountingRef,
+    invoiceId: billingObligations.invoiceId,
+    invoiceStatus: invoices.status,
+    invoiceTotalCents: invoices.totalCents,
+  })
+    .from(billingObligations)
+    .leftJoin(invoices, and(eq(invoices.organisationId, billingObligations.organisationId), eq(invoices.id, billingObligations.invoiceId)))
+    .where(and(
+      eq(billingObligations.organisationId, organisationId),
+      gte(billingObligations.jobDate, from),
+      lte(billingObligations.jobDate, to),
+      sql`exists (select 1 from obligation_events e
+        where e.organisation_id = ${billingObligations.organisationId} and e.obligation_id = ${billingObligations.id}
+          and e.kind in ('observed', 'source_changed') and e.actor <> ${HISTORY_ACTOR})`,
+    ));
+
+  const reported = new Set(workAdapters.map((a) => a.id));
+  const inLedger = new Set();
+  for (const o of obligations) {
+    const entry = dayOf(o.jobDate);
+    entry.ledger.count += 1;
+    entry.ledger.subtotalCents += o.subtotalCents;
+    entry.ledger.totalCents += o.totalCents;
+    if (o.invoiceId) {
+      entry.flowInvoices.count += 1;
+      entry.flowInvoices.totalCents += o.invoiceTotalCents ?? 0;
+    }
+    // Only a work system that is on can say a job is gone from its copy.
+    if (reported.has(o.sourceSystem)) {
+      const key = `${o.sourceSystem}:${o.sourceJobRef}`;
+      inLedger.add(key);
+      if (!work.has(key)) entry.differences.missingInWork.push({ id: o.id, cents: o.totalCents });
+    }
+  }
+  for (const [key, job] of work) {
+    if (!inLedger.has(key)) dayOf(job.day).differences.missingInLedger.push({ id: job.ref, cents: job.subtotalCents ?? 0 });
+  }
+
+  // 3. The accounting system's copy of each linked invoice.
+  const [accounting] = integrations?.with('findInvoices') ?? [];
+  const linked = obligations.filter((o) => o.accountingRef && LINKED.includes(o.accountingState));
+  if (accounting) {
+    const copies = new Map();
+    for (let i = 0; i < linked.length; i += FIND_BATCH) {
+      const invoiceIds = linked.slice(i, i + FIND_BATCH).map((o) => o.accountingRef);
+      const { invoices: found } = await accounting.capabilities.findInvoices({ organisationId, invoiceIds });
+      for (const invoice of found) copies.set(String(invoice.id), invoice);
+    }
+    for (const o of linked) {
+      const entry = dayOf(o.jobDate);
+      entry.accounting.linked += 1;
+      const copy = copies.get(String(o.accountingRef));
+      if (!copy) {
+        entry.differences.missingInAccounting.push({ id: o.id, cents: o.totalCents });
+        continue;
+      }
+      entry.accounting.found += 1;
+      entry.accounting.totalCents += copy.totalCents ?? 0;
+      // An invoice Flow issued must carry Flow's total. One Flow only matched
+      // may carry the job's total with or without GST, as the matcher allows.
+      const expected = o.invoiceId && o.invoiceStatus === 'issued'
+        ? [o.invoiceTotalCents]
+        : [o.totalCents, o.subtotalCents, withGst(o.subtotalCents)];
+      if (copy.totalCents !== null && !expected.includes(copy.totalCents)) {
+        entry.differences.accountingTotalDiffers.push({ id: o.id, cents: copy.totalCents - expected[0] });
+      }
+    }
+  }
+
+  return {
+    systems: { work: workAdapters.map((a) => a.id), accounting: accounting?.id ?? null },
+    days: [...byDay.values()].sort((a, b) => a.day.localeCompare(b.day)),
+  };
+}
+
+async function openDayItems(db, organisationId) {
+  const rows = await db.select({ flowId: reviewItems.flowId, evidence: reviewItems.evidence }).from(reviewItems).where(and(
+    eq(reviewItems.organisationId, organisationId),
+    eq(reviewItems.kind, RECONCILE_REVIEW_KIND),
+    eq(reviewItems.state, 'open'),
+  ));
+  return new Map(rows.map((r) => [r.evidence?.day, r.flowId]).filter(([day]) => day));
+}
+
+// One run: reconcile, open or refresh an item for each day that still
+// differs, and close the item of each day that now agrees. `unconfirmed` are
+// the days the last run found different for the first time. Answers the
+// summary the job keeps (GET /health shows it).
+export async function runReconcile(db, organisationId, {
+  integrations, now = Date.now(), days = RECONCILE_DAYS, unconfirmed = [],
+}) {
+  const to = isoDay(now);
+  const open = await openDayItems(db, organisationId);
+  // An open item older than the window is checked too, so it can close.
+  const oldest = [...open.keys()].reduce((min, day) => (day < min ? day : min), isoDay(now - (days - 1) * 86_400_000));
+  const { systems, days: entries } = await reconcileDays(db, organisationId, { integrations, from: oldest, to });
+  const differing = entries.filter((e) => differenceCount(e) > 0);
+  const recheck = new Set(unconfirmed);
+  const firstSeen = [];
+  let opened = 0;
+  for (const entry of differing) {
+    if (!open.has(entry.day) && !recheck.has(entry.day)) {
+      firstSeen.push(entry.day);
+      continue;
+    }
+    await openReview(db, organisationId, {
+      kind: RECONCILE_REVIEW_KIND,
+      entity: 'day',
+      flowId: dayReviewId(organisationId, entry.day),
+      systems: [...systems.work, ...(systems.accounting ? [systems.accounting] : [])],
+      evidence: evidenceFor(entry),
+      moneyAtRiskCents: moneyAtRisk(entry),
+    });
+    opened += 1;
+  }
+  const differs = new Set(differing.map((e) => e.day));
+  let closed = 0;
+  for (const [day, flowId] of open) {
+    if (differs.has(day)) continue;
+    await resolveReviewFor(db, organisationId, {
+      kind: RECONCILE_REVIEW_KIND, entity: 'day', flowId, resolution: 'a later run agreed', actor: ACTOR,
+    });
+    closed += 1;
+  }
+  return {
+    from: oldest,
+    to,
+    systems,
+    daysChecked: entries.length,
+    daysDifferent: differing.length,
+    openItems: (await openDayItems(db, organisationId)).size,
+    opened,
+    closed,
+    unconfirmed: firstSeen,
+  };
+}
+
+async function lastRun(db, organisationId) {
+  const [row] = await db.select().from(backgroundJobs).where(and(
+    eq(backgroundJobs.organisationId, organisationId),
+    eq(backgroundJobs.kind, RECONCILE_KIND),
+    inArray(backgroundJobs.state, ['succeeded', 'failed', 'dead']),
+  )).orderBy(desc(backgroundJobs.updatedAt)).limit(1);
+  return row ?? null;
+}
+
+// The last run and its result, for GET /health: counts only, no record ids.
+export async function reconcileHealth(db, { now = Date.now() } = {}) {
+  const organisationId = await soleOrganisation(db);
+  if (!organisationId) return null;
+  const row = await lastRun(db, organisationId);
+  if (!row) return { lastRunAt: null };
+  const result = row.state === 'succeeded' ? row.result ?? {} : {};
+  return {
+    lastRunAt: row.updatedAt.toISOString(),
+    state: row.state,
+    ...(row.state === 'succeeded' ? {
+      agrees: result.daysDifferent === 0,
+      daysChecked: result.daysChecked ?? null,
+      daysDifferent: result.daysDifferent ?? null,
+      openItems: result.openItems ?? null,
+      late: now - row.updatedAt.getTime() > RUN_EVERY_MS + 2 * TICK_MS + LEASE_MS,
+    } : { error: row.lastError }),
+  };
+}
+
+// Is a run due? Once a day, and an hour after a run that found a new difference.
+export function reconcileDue(last, nowMs) {
+  if (!last) return true;
+  const age = nowMs - last.updatedAt.getTime();
+  if (last.state !== 'succeeded') return age >= RECHECK_MS;
+  if ((last.result?.unconfirmed ?? []).length) return age >= RECHECK_MS;
+  return age >= RUN_EVERY_MS;
+}
+
+// The worker: every ten minutes it asks whether a run is due, and runs it on
+// the job queue, so two Flow processes never run it at once. It runs only
+// while an integration that feeds it is on.
+export function createReconcileWorker({
+  db, integrations, log = console, timers = { setTimeout, clearTimeout }, now = Date.now, everyMs = TICK_MS, firstDelayMs = 60_000,
+}) {
+  const workerId = `reconcile-${randomUUID()}`;
+  const startedAtMs = now();
+  let timer = null;
+  let running = null;
+  let stopped = true;
+
+  function schedule(delayMs) {
+    if (stopped) return;
+    timer = timers.setTimeout(tick, delayMs);
+    timer?.unref?.();
+  }
+
+  async function tick() {
+    timer = null;
+    if (stopped) return;
+    running = (async () => {
+      try {
+        if (!integrations?.with('billableJobs').length && !integrations?.with('findInvoices').length) return;
+        const organisationId = await soleOrganisation(db);
+        if (!organisationId) return;
+        const last = await lastRun(db, organisationId);
+        if (!reconcileDue(last, now())) return;
+        if (await deadSince(db, organisationId, { kind: RECONCILE_KIND, dedupeKey: 'all', since: deadHoldSince(startedAtMs, now()) })) return;
+        const unconfirmed = last?.state === 'succeeded' ? last.result?.unconfirmed ?? [] : [];
+        await enqueueJob(db, organisationId, { kind: RECONCILE_KIND, dedupeKey: 'all', maxAttempts: 3 });
+        const ran = await runNextJob(db, {
+          workerId,
+          leaseMs: LEASE_MS,
+          handlers: { [RECONCILE_KIND]: () => runReconcile(db, organisationId, { integrations, now: now(), unconfirmed }) },
+        });
+        if (!ran) return;
+        if (ran.outcome === 'dead') log.error?.('[reconcile] the daily reconcile gave up after its last attempt');
+        else if (ran.outcome === 'succeeded') {
+          const { daysChecked, daysDifferent, opened, closed } = ran.job.result;
+          (daysDifferent ? log.warn : log.info)?.(`[reconcile] ${daysChecked} days checked, ${daysDifferent} differ; ${opened} items open or refreshed, ${closed} closed`);
+        } else log.warn?.(`[reconcile] ${ran.outcome}: ${ran.job.lastError}`);
+      } catch (error) {
+        log.error?.(`[reconcile] ${error?.code ?? 'error'}: ${error?.message ?? error}`);
+      }
+    })();
+    await running;
+    running = null;
+    schedule(everyMs);
+  }
+
+  return {
+    start() {
+      stopped = false;
+      schedule(firstDelayMs);
+    },
+    async stop() {
+      stopped = true;
+      if (timer) timers.clearTimeout(timer);
+      timer = null;
+      await running;
+    },
+    tick,
+  };
+}

package/server/core/sending.js

@@ -1,9 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
-import { invoiceLines, invoices } from '../db/schema.js';
+import { billingObligations, invoiceLines, invoices } from '../db/schema.js';
 import { FlowError } from './errors.js';
 import { issueInvoice } from './invoices.js';
 import { soleOrganisation } from './pipeline.js';
+import { needsRead, readAccountingFirst, readBeforeAct, READS_PER_PASS } from './read-before-act.js';
 import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 
 // Drafts, Problem, Ready and Send all ready (docs/INVOICE_SENDING.md).
@@ -60,6 +61,15 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
     const found = draftProblems(draft, linesOf.get(draft.id) ?? []);
     if (found.length) problems.set(draft.id, found);
   }
+  // A draft whose job the ledger sent to review (the job changed after the
+  // draft was made, or the work system deleted it) waits for a person.
+  const reviewed = await db.select({ invoiceId: billingObligations.invoiceId, reason: billingObligations.holdReason })
+    .from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, ids), eq(billingObligations.holdState, 'review')));
+  for (const { invoiceId, reason } of reviewed) {
+    const found = problem('job_review', `The job needs a look before this invoice goes: ${reason ?? 'it was sent to review'}.`);
+    problems.set(invoiceId, [...(problems.get(invoiceId) ?? []), found]);
+  }
   if (accounting) {
     const outside = await accounting.capabilities.checkDrafts({ organisationId, invoiceIds: ids });
     for (const [id, found] of outside ?? []) {
@@ -146,18 +156,46 @@ async function assertCanSend(accounting, organisationId) {
   }
 }
 
+// Read before act (issue #141): the jobs behind these drafts whose work
+// system report is old are read again first. Answers the drafts that may go
+// now; a draft whose job went to review, or could not be read, waits.
+async function readJobsFirst(db, organisationId, invoiceIds, { work, now, personId }) {
+  if (!invoiceIds.length || typeof work?.capabilities?.readWorkItem !== 'function') return { go: invoiceIds, waiting: [] };
+  const jobs = await db.select().from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, invoiceIds)));
+  const old = jobs.filter((job) => needsRead(job, { work, now }));
+  const outcomes = await readBeforeAct(db, organisationId, old.slice(0, READS_PER_PASS), { work, now, actor: `person:${personId}` });
+  const held = new Set(old.slice(READS_PER_PASS).map((job) => job.invoiceId));
+  for (const { outcome, obligation } of outcomes.values()) {
+    if (outcome === 'waiting' || outcome === 'review') held.add(obligation.invoiceId);
+  }
+  return { go: invoiceIds.filter((id) => !held.has(id)), waiting: invoiceIds.filter((id) => held.has(id)) };
+}
+
 // Send all ready: issues each ready draft, then queues it for the accounting
 // system. With `invoiceIds`, only those drafts, and each must be ready (the
-// Send button on one invoice). Answers { issued, queued, remaining }.
-export async function sendAllReady(db, organisationId, { accounting = null, personId, issueDate, invoiceIds = null }) {
+// Send button on one invoice). `work` is the work integration, for the read
+// before act. Answers { issued, queued, remaining, waiting }.
+export async function sendAllReady(db, organisationId, { accounting = null, work = null, personId, issueDate, invoiceIds = null, now = new Date() }) {
   await assertCanSend(accounting, organisationId);
-  let { ready } = await invoiceViews(db, organisationId, { accounting });
+  // Issue #45: the accounting copy reads its latest changes first, so the
+  // draft checks below see an invoice someone made there meanwhile.
+  let views = await invoiceViews(db, organisationId, { accounting });
+  const accountingRead = views.ready.length ? await readAccountingFirst(db, organisationId, { accounting, now }) : { outcome: 'fresh' };
+  if (accountingRead.changed) views = await invoiceViews(db, organisationId, { accounting });
+  let { ready } = views;
   if (invoiceIds) {
     const wanted = new Set(invoiceIds);
     ready = ready.filter((id) => wanted.has(id));
     if (ready.length !== wanted.size) throw new FlowError('not_ready', 'Only a ready invoice can be sent. Mark it ready first.');
   }
-  const batch = ready.slice(0, SEND_BATCH);
+  const { go, waiting } = accountingRead.outcome === 'waiting'
+    ? { go: [], waiting: ready.slice(0, SEND_BATCH) }
+    : await readJobsFirst(db, organisationId, ready.slice(0, SEND_BATCH), { work, now, personId });
+  if (invoiceIds && waiting.length) {
+    throw new FlowError('not_ready', 'Flow could not confirm the job with the work system or the accounting system just now, or the job changed. Nothing was sent. Look at the invoice, then try again.');
+  }
+  const batch = go;
   let issued = 0;
   for (const invoiceId of batch) {
     // Queued first: the worker sends only issued invoices, so a stop between
@@ -173,7 +211,7 @@ export async function sendAllReady(db, organisationId, { accounting = null, pers
     }
     issued += 1;
   }
-  return { issued, queued: accounting ? issued : 0, remaining: ready.length - batch.length };
+  return { issued, queued: accounting ? issued : 0, remaining: Math.max(0, ready.length - SEND_BATCH), waiting: waiting.length };
 }
 
 // Send again: issued invoices that failed go back on the queue. With no ids,

package/server/db/migrations/0017_sync_basis.sql

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