@arcforgelabs/flow 2026.10.53 → 2026.11.1

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,17 +180,20 @@ 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,
       contactId: job.contactId ?? null,
       practitioner: job.practitioner ?? null,
-      shippedOn: job.shippedOn ?? null,
       jobDate: job.jobDate ?? null,
       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)
@@ -158,26 +204,36 @@ export async function observeJob(db, organisationId, job) {
       ))
       .for('update');
 
+    // A work system without a shipped date (Seazona) says only that the job
+    // is shipped: the day Flow sees its status move to a shipped one is its
+    // shipped day. A job Flow first sees already shipped (a first sync, or a
+    // job shipped before Flow kept this day) stays without one.
+    const statusMoved = existing && String(existing.sourceStatus ?? '') !== String(facts.sourceStatus ?? '');
+    facts.shippedOn = job.shippedOn ?? existing?.shippedOn
+      ?? (job.shipped && statusMoved ? localDay(seenAt) : null);
+
     if (!existing) {
       const [row] = await tx.insert(billingObligations)
         .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, sourceStatus: row.sourceStatus, 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;
+      await statusChanged(tx, organisationId, existing, row, actor);
+      return recordSourceReview(tx, row, actor);
     }
     const fields = { ...facts, sourceSeenAt: seenAt };
     let compare = null;
@@ -194,8 +250,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 } : {}),
     });
@@ -204,15 +260,28 @@ export async function observeJob(db, organisationId, job) {
     } else if (compare) {
       await openReview(tx, organisationId, changedReview(row, compare));
     }
-    await statusBillableAgain(tx, organisationId, existing, row, actor);
-    return row;
+    await statusChanged(tx, organisationId, existing, row, actor);
+    return recordSourceReview(tx, row, actor);
   });
 }
 
+// Each move of the work system status is an event, so "was the job shipped
+// in this range" has an answer after the status moves on.
+async function statusChanged(tx, organisationId, before, row, actor) {
+  if (String(before.sourceStatus ?? '') === String(row.sourceStatus ?? '')) return;
+  await addEvent(tx, row, 'status_changed', actor, { from: before.sourceStatus ?? null, to: row.sourceStatus ?? null });
+  await statusBillableAgain(tx, organisationId, before, row, actor);
+}
+
+// The calendar day of a time where the lab works (FLOW_TIME_ZONE).
+function localDay(at) {
+  return new Intl.DateTimeFormat('en-CA', { timeZone: process.env.FLOW_TIME_ZONE || 'Australia/Sydney' }).format(at);
+}
+
 // A job billable again after its status moved back (observeWithdrawn): the
 // alert is over when no invoice was made in the meantime.
 async function statusBillableAgain(tx, organisationId, before, row, actor) {
-  if (row.invoiceId || String(before.sourceStatus ?? '') === String(row.sourceStatus ?? '')) return;
+  if (row.invoiceId) return;
   await resolveReviewFor(tx, organisationId, { kind: REVIEW_STATUS_BACK, entity: 'obligation', flowId: row.id, resolution: 'status_billable_again', actor });
 }
 
@@ -313,6 +382,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 +857,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 +869,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/reconcile.js

@@ -124,6 +124,20 @@ export async function reconcileDays(db, organisationId, { integrations, from, to
           and e.kind in ('observed', 'source_changed') and e.actor <> ${HISTORY_ACTOR})`,
     ));
 
+  // A billable feed cannot prove absence. Check the remaining ledger refs
+  // against the source copy without billing filters. Older adapters retain
+  // the feed comparison until they declare workJobPresence.
+  const present = new Set(work.keys());
+  for (const adapter of workAdapters) {
+    if (!adapter.capabilities.workJobPresence) continue;
+    const jobRefs = [...new Set(obligations
+      .filter((o) => o.sourceSystem === adapter.id && !present.has(`${adapter.id}:${o.sourceJobRef}`))
+      .map((o) => o.sourceJobRef))];
+    for (let i = 0; i < jobRefs.length; i += FIND_BATCH) {
+      const { presentRefs } = await adapter.capabilities.workJobPresence({ organisationId, jobRefs: jobRefs.slice(i, i + FIND_BATCH) });
+      for (const ref of presentRefs) present.add(`${adapter.id}:${ref}`);
+    }
+  }
   const reported = new Set(workAdapters.map((a) => a.id));
   const inLedger = new Set();
   for (const o of obligations) {
@@ -139,7 +153,7 @@ export async function reconcileDays(db, organisationId, { integrations, from, to
     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 });
+      if (!present.has(key)) entry.differences.missingInWork.push({ id: o.id, cents: o.totalCents });
     }
   }
   for (const [key, job] of work) {

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;
@@ -439,7 +445,8 @@ export async function sendQueued(db, organisationId, { accounting, limit = WORKE
         summary.waiting += 1;
       } else {
         const error = result.error ?? { code: `send_${result.outcome}`, message: `Sending ended as ${result.outcome}.` };
-        await settle(db, organisationId, result.invoiceId, { sendState: 'failed', sendError: { code: error.code, message: error.message, ...(error.short ? { short: error.short } : {}) } });
+        const xero = xeroMatch(error);
+        await settle(db, organisationId, result.invoiceId, { sendState: 'failed', sendError: { code: error.code, message: error.message, ...(error.short ? { short: error.short } : {}), ...(xero ? { xero } : {}) } });
         summary.failed += 1;
         summary.refused = [...new Set([...(summary.refused ?? []), error.code])];
         const fact = refusalFact(known.get(result.invoiceId), error);
@@ -450,6 +457,17 @@ export async function sendQueued(db, organisationId, { accounting, limit = WORKE
   return summary;
 }
 
+// The Xero invoice a refusal matched, kept so the page can link to it.
+// Only an id, a number and a status. Anything else in the error stays out.
+function xeroMatch(error) {
+  const xero = error?.details?.xero;
+  if (!xero || typeof xero !== 'object') return null;
+  if (!INVOICE_ID.test(xero.invoiceId ?? '')) return null;
+  const number = INVOICE_NUMBER.test(xero.number ?? '') ? xero.number : null;
+  const status = /^[A-Z0-9_]{1,32}$/.test(xero.status ?? '') ? xero.status : null;
+  return { invoiceId: xero.invoiceId, ...(number ? { number } : {}), ...(status ? { status } : {}) };
+}
+
 function settle(db, organisationId, invoiceId, fields) {
   return db.update(invoices).set({ ...fields, sendUpdatedAt: sql`now()` })
     .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId), eq(invoices.sendState, 'queued')));

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

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

package/server/db/migrations/0026_bitter_sersi.sql

@@ -0,0 +1,38 @@
+CREATE TABLE IF NOT EXISTS "agent_audit" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"grant_id" uuid NOT NULL,
+	"person_id" uuid NOT NULL,
+	"tool" text NOT NULL,
+	"status" integer NOT NULL,
+	"row_count" integer DEFAULT 0 NOT NULL,
+	"duration_ms" integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "agent_grants" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"person_id" uuid NOT NULL,
+	"client_id" text NOT NULL,
+	"app_name" text NOT NULL,
+	"resource" text NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"access_level" text DEFAULT 'read' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"last_used_at" timestamp with time zone,
+	"revoked_at" timestamp with time zone,
+	"failure_day" date,
+	"failure_count" integer DEFAULT 0 NOT NULL,
+	"paused_at" timestamp with time zone,
+	CONSTRAINT "agent_grants_person_client_resource" UNIQUE("person_id","client_id","resource"),
+	CONSTRAINT "agent_grants_read_only" CHECK (access_level = 'read')
+);
+--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "agent_grants" ADD CONSTRAINT "agent_grants_person_id_people_id_fk" FOREIGN KEY ("person_id") REFERENCES "flow"."people"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "agent_grants" ADD CONSTRAINT "agent_grants_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "flow"."organisations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "agent_audit_created" ON "agent_audit" USING btree ("created_at");