@arcforgelabs/flow 2026.10.53-3 → 2026.10.53-4

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.53-3",
+  "version": "2026.10.53-4",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/core/ledger.js

@@ -100,12 +100,13 @@ async function normaliseLines(tx, organisationId, lines) {
     priceItemId = item?.archivedAt ? null : (item?.id ?? null);
     description = (description ?? item?.name ?? '').trim();
     unitAmountCents ??= item?.unitAmountCents;
-    taxCode ??= item?.taxCode ?? 'GST';
+    taxCode ??= item?.taxCode ?? (line.taxCode === null ? null : 'GST');
     const quantity = line.quantity ?? 1;
     if (!description) throw new FlowError('invalid', `line ${index + 1}: description is required`);
     let totals;
     try {
-      totals = lineTotals({ quantity, unitAmountCents, taxCode });
+      totals = lineTotals({ quantity, unitAmountCents, taxCode: taxCode ?? 'GST_FREE' });
+      if (taxCode === null) totals.taxCents = null;
     } catch (error) {
       throw new FlowError('invalid', `line ${index + 1}: ${error.message}`);
     }
@@ -128,6 +129,48 @@ function fingerprint(lines) {
   return createHash('sha256').update(JSON.stringify(keys)).digest('hex');
 }
 
+const SOURCE_TOTAL_FIELDS = ['subtotalCents', 'taxCents', 'totalCents'];
+const REVIEW_SOURCE_TOTALS = 'job.source_totals';
+
+function readSourceTotals(raw) {
+  if (raw == null) return null;
+  const totals = {};
+  for (const field of SOURCE_TOTAL_FIELDS) {
+    if (raw[field] == null) continue;
+    if (!Number.isSafeInteger(raw[field])) throw new FlowError('invalid', 'source ' + field + ' must be whole cents');
+    totals[field] = raw[field];
+  }
+  return Object.keys(totals).length ? totals : null;
+}
+
+// A source invoice total is evidence, not permission to allocate its tax.
+export function sourceBillingProblems(obligation) {
+  const reasons = [];
+  const lines = obligation.lines ?? [];
+  if (lines.some((line) => line.taxCode === null)) reasons.push('a source line has unknown tax treatment');
+  const calculated = invoiceTotals(lines);
+  if (SOURCE_TOTAL_FIELDS.some((field) => obligation.sourceTotals?.[field] != null && obligation.sourceTotals[field] !== calculated[field])) {
+    reasons.push('the source invoice totals differ from the reconstructed lines');
+  }
+  return reasons;
+}
+
+async function recordSourceReview(tx, row, actor) {
+  const reasons = sourceBillingProblems(row);
+  if (reasons.length) {
+    await openReview(tx, row.organisationId, {
+      kind: REVIEW_SOURCE_TOTALS, entity: 'obligation', flowId: row.id,
+      systems: [row.sourceSystem, 'flow'], moneyAtRiskCents: Math.abs(row.totalCents),
+      evidence: { reasons, sourceTotals: row.sourceTotals, reconstructed: invoiceTotals(row.lines),
+        unknownTaxLines: row.lines.flatMap((line, index) => line.taxCode === null ? [index + 1] : []),
+        sourceJobRef: row.sourceJobRef, invoiceId: row.invoiceId },
+    });
+  } else {
+    await resolveReviewFor(tx, row.organisationId, { kind: REVIEW_SOURCE_TOTALS, entity: 'obligation', flowId: row.id, resolution: 'source_totals_match', actor });
+  }
+  return row;
+}
+
 // Records what the work system reports about a billable job. The first report
 // makes the obligation; a later report with other lines or totals changes it.
 // If the job changes after Flow made its invoice, the obligation goes to review.
@@ -137,6 +180,9 @@ export async function observeJob(db, organisationId, job) {
   const seenAt = job.observedAt ? new Date(job.observedAt) : new Date();
   return db.transaction(async (tx) => {
     const lines = await normaliseLines(tx, organisationId, job.lines);
+    const sourceTotals = readSourceTotals(job.sourceTotals);
+    const totals = { ...invoiceTotals(lines), ...sourceTotals };
+    if (sourceTotals?.totalCents == null) totals.totalCents = totals.subtotalCents + totals.taxCents;
     const facts = {
       sourceInvoiceRef: job.sourceInvoiceRef ?? null,
       caseRef: job.caseRef ?? null,
@@ -147,7 +193,8 @@ export async function observeJob(db, organisationId, job) {
       sourceStatus: job.sourceStatus ?? null,
       lines,
       lineFingerprint: fingerprint(lines),
-      ...invoiceTotals(lines),
+      sourceTotals,
+      ...totals,
       mappingComplete: lines.every((l) => l.priceItemId || l.accountCode),
     };
     const [existing] = await tx.select().from(billingObligations)
@@ -163,21 +210,23 @@ export async function observeJob(db, organisationId, job) {
         .values({ organisationId, sourceSystem, sourceJobRef, sourceSeenAt: seenAt, ...facts })
         .returning();
       await addEvent(tx, row, 'observed', actor, {
-        lineFingerprint: row.lineFingerprint, totalCents: row.totalCents, mappingComplete: row.mappingComplete,
+        lineFingerprint: row.lineFingerprint, totalCents: row.totalCents, mappingComplete: row.mappingComplete, sourceTotals: row.sourceTotals,
       });
-      return row;
+      return recordSourceReview(tx, row, actor);
     }
 
     // An older report never replaces a newer one.
     if (seenAt < existing.sourceSeenAt) return existing;
-    const changed = ['sourceInvoiceRef', 'caseRef', 'contactId', 'practitioner', 'shippedOn', 'lineFingerprint', 'totalCents']
-      .filter((key) => String(existing[key] ?? '') !== String(facts[key] ?? ''));
+    const changed = ['sourceInvoiceRef', 'caseRef', 'contactId', 'practitioner', 'shippedOn', 'lineFingerprint', 'subtotalCents', 'taxCents', 'totalCents', 'sourceTotals']
+      .filter((key) => key === 'sourceTotals'
+        ? SOURCE_TOTAL_FIELDS.some((field) => (existing.sourceTotals?.[field] ?? null) !== (facts.sourceTotals?.[field] ?? null))
+        : String(existing[key] ?? '') !== String(facts[key] ?? ''));
     if (!changed.length) {
       const row = await update(tx, existing, {
         sourceSeenAt: seenAt, mappingComplete: facts.mappingComplete, lines, jobDate: facts.jobDate, sourceStatus: facts.sourceStatus,
       });
       await statusBillableAgain(tx, organisationId, existing, row, actor);
-      return row;
+      return recordSourceReview(tx, row, actor);
     }
     const fields = { ...facts, sourceSeenAt: seenAt };
     let compare = null;
@@ -194,8 +243,8 @@ export async function observeJob(db, organisationId, job) {
     const row = await update(tx, existing, fields);
     await addEvent(tx, row, 'source_changed', actor, {
       changed,
-      before: { lineFingerprint: existing.lineFingerprint, totalCents: existing.totalCents },
-      after: { lineFingerprint: row.lineFingerprint, totalCents: row.totalCents },
+      before: { lineFingerprint: existing.lineFingerprint, totalCents: existing.totalCents, sourceTotals: existing.sourceTotals },
+      after: { lineFingerprint: row.lineFingerprint, totalCents: row.totalCents, sourceTotals: row.sourceTotals },
       ...(compare ? { compare: { outcome: compare.outcome, fields: compare.fields.map(({ field, changedIn }) => ({ field, changedIn })) } } : {}),
       ...(fields.holdState === 'review' ? { holdReason: fields.holdReason } : {}),
     });
@@ -205,7 +254,7 @@ export async function observeJob(db, organisationId, job) {
       await openReview(tx, organisationId, changedReview(row, compare));
     }
     await statusBillableAgain(tx, organisationId, existing, row, actor);
-    return row;
+    return recordSourceReview(tx, row, actor);
   });
 }
 
@@ -313,6 +362,8 @@ export async function useSourceLines(db, organisationId, obligationId, { actor,
   return db.transaction(async (tx) => {
     const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
     if (!obligation.invoiceId) throw new FlowError('invalid', 'the job has no invoice');
+    const sourceProblems = sourceBillingProblems(obligation);
+    if (sourceProblems.length) throw new FlowError('not_ready', sourceProblems.join('; '));
     const compare = await compareWithDraft(tx, organisationId, obligation, obligation);
     if (compare.outcome === 'conflict' && (compare.sent || compare.missing || !accept)) {
       throw new FlowError('conflict', compare.missing ? 'the invoice was not found' : compare.sent ? 'the invoice has left Flow; change it where it is now' : 'the draft changed in Flow too; a person must compare them', { fields: compare.fields });
@@ -786,7 +837,10 @@ export function ledgerView(obligation, { now = new Date(), sourceMaxAgeMs = SOUR
   if (['authorised', 'part_paid'].includes(o.accountingState)) {
     return { view: 'invoiced', reasons: [`invoice ${o.accountingRef} is ${o.accountingState.replace('_', ' ')}`] };
   }
+  // Existing invoices own their stage. sending.js still checks source conflicts
+  // before approval or Send, after the non-chargeable rules.
   if (o.invoiceId || o.accountingState === 'drafted') return { view: 'drafted', reasons: ['a draft invoice exists'] };
+  if (sourceBillingProblems(o).length) return { view: 'review_required', reasons: draftBlockers(o, { now, sourceMaxAgeMs, accounting }) };
   const reasons = draftBlockers(o, { now, sourceMaxAgeMs, accounting });
   // Flow's own stage: a job is in work until a person or an automation marks
   // it ready to invoice (setReady).
@@ -795,7 +849,7 @@ export function ledgerView(obligation, { now = new Date(), sourceMaxAgeMs = SOUR
 }
 
 function draftBlockers(o, { now, sourceMaxAgeMs, accounting = true }) {
-  const reasons = [];
+  const reasons = sourceBillingProblems(o);
   if (o.holdState !== 'none') reasons.push(`the job is ${o.holdState}`);
   if (o.invoiceId) reasons.push('the job already has an invoice');
   if (o.accountingState === 'unknown') {

package/server/core/line-mapping.js

@@ -156,7 +156,7 @@ export function mapLine(line, context) {
     description: (item.description || item.name || original).trim(),
     quantity,
     unitAmountCents: config.linePrice === 'list' ? item.unitAmountCents : (price ?? item.unitAmountCents),
-    taxCode: taxCode ?? line.taxCode ?? item.taxCode,
+    taxCode: line.taxCode ?? taxCode ?? item.taxCode,
     mappedBy: step,
   });
   const fromRow = (row, step) => {
@@ -180,7 +180,7 @@ export function mapLine(line, context) {
         if (row) {
           return {
             ...base, itemCode: null, accountCode: row.accountCode, description: row.description || original, quantity,
-            unitAmountCents: price, taxCode: row.taxCode ?? line.taxCode, mappedBy: step,
+            unitAmountCents: price, taxCode: line.taxCode ?? row.taxCode ?? (line.taxCode === null ? null : undefined), mappedBy: step,
           };
         }
         break;

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

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

package/server/core/sending.js

@@ -5,7 +5,7 @@ import { FlowError } from './errors.js';
 import { listRules, ruleNonChargeable, rulePending, ruleSkip } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings } from './invoicing-rules.js';
 import { issueInvoice } from './invoices.js';
-import { CHANGED_REASON, diffJobLines, STATUS_BACK_REASON } from './ledger.js';
+import { CHANGED_REASON, diffJobLines, sourceBillingProblems, STATUS_BACK_REASON } from './ledger.js';
 import { soleOrganisation } from './pipeline.js';
 import { needsRead, readAccountingFirst, readBeforeAct, READS_PER_PASS } from './read-before-act.js';
 import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
@@ -116,6 +116,12 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
   }
   // A draft whose job the ledger sent to review (the job changed after the
   // draft was made, or the work system deleted it) waits for a person.
+  for (const { obligation } of jobs) {
+    for (const reason of sourceBillingProblems(obligation)) {
+      const found = problem('job_review', 'Check the source invoice: ' + reason + '.', 'Source tax');
+      problems.set(obligation.invoiceId, [...(problems.get(obligation.invoiceId) ?? []), found]);
+    }
+  }
   const reviewed = jobs.map((j) => j.obligation).filter((o) => o.holdState === 'review');
   for (const obligation of reviewed) {
     const { invoiceId, holdReason: reason } = obligation;

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

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