@arcforgelabs/flow 2026.10.50 → 2026.10.52

package/server/core/invoice-rules.js

@@ -1,3 +1,6 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
 import { and, asc, eq, sql } from 'drizzle-orm';
 import { invoiceRules, invoicingSettings } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
@@ -26,6 +29,10 @@ const MAX_CONDITIONS = 10;
 const invalid = (message) => new FlowError('invalid', message);
 
 const MAX_NOTE = 200;
+// A rule's own icon: any Lucide name (the icon picker, server/ui/kit.js).
+// Null shows the mark of what the rule does.
+const ICON_DIR = join(dirname(createRequire(import.meta.url).resolve('lucide-static/package.json')), 'icons');
+const ICON_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const day = (date) => new Date(`${String(date).slice(0, 10)}T00:00:00Z`);
 const norm = (value) => String(value ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
 // A line's key: its price item code, else the label line mapping gave it (a
@@ -107,10 +114,14 @@ function readCondition(raw, index) {
 
 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));
+  const unknown = Object.keys(raw).filter((k) => !['name', 'icon', '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 icon = raw.icon ?? null;
+  if (icon !== null && (typeof icon !== 'string' || icon.length > 64 || !ICON_NAME.test(icon) || !existsSync(join(ICON_DIR, `${icon}.svg`)))) {
+    throw invalid('the icon must be a Lucide icon name');
+  }
   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) {
@@ -127,7 +138,7 @@ export function readRule(raw) {
     const early = conditions.find((c) => FIELDS[c.field].draftOnly);
     if (early) throw invalid(`${FIELDS[early.field].label} is on the draft only: use Then "Pending, with a note"`);
   }
-  return { name, enabled, conditions, action };
+  return { name, icon, enabled, conditions, action };
 }
 
 function matches(condition, job, context) {
@@ -270,7 +281,7 @@ async function seed(db, organisationId) {
 }
 
 const shape = (r) => ({
-  id: r.id, name: r.name, position: r.position, enabled: r.enabled, trigger: r.trigger,
+  id: r.id, name: r.name, icon: r.icon, position: r.position, enabled: r.enabled, trigger: r.trigger,
   conditions: r.conditions, action: r.action, starter: Boolean(r.starterKey), updatedAt: r.updatedAt,
 });
 
@@ -299,12 +310,12 @@ async function loadRule(db, organisationId, ruleId) {
   return row;
 }
 
-// Changes a rule. `changes` holds any of name, enabled, conditions, action;
+// Changes a rule. `changes` holds any of name, icon, 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 rule = readRule({ name: row.name, icon: row.icon, 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);

package/server/core/reader.js

@@ -0,0 +1,324 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { and, asc, eq, isNull, sql } from 'drizzle-orm';
+import { callCostMicros } from './ai.js';
+import { captures, jobFields } from '../db/schema.js';
+import { FlowError } from './errors.js';
+import { enqueueJob, runNextJob } from './queue.js';
+import { JOB_FIELDS } from '../ui/capture-fields.js';
+
+// The vision reader. A small model reads every capture. A larger model reads
+// again only when case number, practice or work is below the sure line.
+// Flow code decides that; the model does not see the jobs list and does not
+// write. The photo and the fields stay out of the log: a failure is a
+// capture id and an error code.
+//
+// A failed call is tried twice more (three calls). The capture is then
+// `problem` with a short reason. Type it still works. The module being off,
+// or the keys missing, is "reader turned off" and is set when the photo is
+// stored (server/core/captures.js), not here.
+
+export const CAPTURE_READ_KIND = 'capture.read';
+const CALLS = 3;
+const VALUE_MAX = 2000;
+
+
+const NEEDED = new Set(JOB_FIELDS.filter((field) => field.needed).map((field) => field.key));
+
+// One object, every property required. Bedrock rejects a schema that leaves
+// a property optional past its limit, or that omits additionalProperties: false.
+const FIELD_SCHEMA = Object.freeze({
+  type: 'object',
+  properties: {
+    fields: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          key: { type: 'string' },
+          value: { type: 'string' },
+          seen: { type: 'string' },
+          sure: { type: 'number' },
+        },
+        required: ['key', 'value', 'seen', 'sure'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['fields'],
+  additionalProperties: false,
+});
+
+const PROBLEM = new Set([
+  'the reader did not answer',
+  'could not read the form',
+  'photo type cannot be read',
+  'the photo is missing',
+]);
+
+const READABLE = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/gif']);
+
+function problemText(error) {
+  return PROBLEM.has(error?.message) ? error.message : 'the reader did not answer';
+}
+
+function blank(key) {
+  return { key, value: '', seen: '', sure: 0 };
+}
+
+function clip(value) {
+  return value.trim().slice(0, VALUE_MAX);
+}
+
+function sureOf(value) {
+  const number = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(number)) return 0;
+  return Math.min(1, Math.max(0, number));
+}
+
+// One field per key the lab asked for, in that order. A key that was not
+// asked for is dropped, so a patient name the model adds is not stored.
+// A value that is not text is empty: an unreadable field is never a guess.
+function parseFields(text, fieldList) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    const error = new FlowError('reader_unreadable', 'could not read the form');
+    error.retry = true;
+    throw error;
+  }
+  const rows = Array.isArray(parsed?.fields) ? parsed.fields : null;
+  if (!rows) {
+    const error = new FlowError('reader_unreadable', 'could not read the form');
+    error.retry = true;
+    throw error;
+  }
+  const byKey = new Map();
+  for (const row of rows) {
+    if (!row || typeof row.key !== 'string' || !row.key) continue;
+    if (typeof row.value !== 'string' || typeof row.seen !== 'string') {
+      byKey.set(row.key, blank(row.key));
+      continue;
+    }
+    byKey.set(row.key, { key: row.key, value: clip(row.value), seen: clip(row.seen), sure: sureOf(row.sure) });
+  }
+  return fieldList.map((field) => byKey.get(field.key) ?? blank(field.key));
+}
+
+function belowLine(fields, line) {
+  const byKey = new Map(fields.map((field) => [field.key, field]));
+  for (const key of NEEDED) {
+    if ((byKey.get(key)?.sure ?? 0) < line) return true;
+  }
+  return false;
+}
+
+function recorded(fields, calls, model = calls.at(-1).model) {
+  const inputTokens = calls.reduce((sum, call) => sum + call.inputTokens, 0);
+  const outputTokens = calls.reduce((sum, call) => sum + call.outputTokens, 0);
+  const costMicros = calls.some((call) => call.costMicros == null)
+    ? null
+    : calls.reduce((sum, call) => sum + call.costMicros, 0);
+  return { fields, model, inputTokens, outputTokens, costMicros, calls };
+}
+
+function instructionFor(fieldList) {
+  const lines = fieldList.map((field) => `- ${field.key}: ${field.label}`).join('\n');
+  return [
+    'Read this photo of a handwritten lab form.',
+    'Return one field for each key below.',
+    'value is what should be stored. Use an empty string when you cannot read it. Never guess a name, a number or a date.',
+    'seen is the exact text you saw, or an empty string when nothing was written.',
+    'sure is a number from 0 to 1: how sure you are that value matches what was written.',
+    'Ignore printed lab branding.',
+    'Do not add a key that is not in this list.',
+    lines,
+  ].join('\n');
+}
+
+async function captureFields(db, organisationId) {
+  const rows = await db.select({ id: jobFields.id, name: jobFields.name }).from(jobFields).where(and(
+    eq(jobFields.organisationId, organisationId),
+    isNull(jobFields.archivedAt),
+  )).orderBy(asc(jobFields.position), asc(jobFields.name));
+  const labels = new Set(JOB_FIELDS.map((field) => field.label.toLowerCase()));
+  const custom = rows
+    .filter((row) => row.name && !labels.has(row.name.trim().toLowerCase()))
+    .map((row) => ({ key: `custom_${row.id}`, label: row.name.trim(), needed: false }));
+  return [...JOB_FIELDS, ...custom];
+}
+
+// Three calls at most. A call that returned token counts is kept on the
+// error when every attempt fails, so the capture still records the cost.
+async function ask(port, { model, price, fieldList, mediaType, bytes, instruction }) {
+  const spent = [];
+  let last = new FlowError('reader_unavailable', 'the reader did not answer');
+  for (let attempt = 0; attempt < CALLS; attempt += 1) {
+    try {
+      const result = await port.readImage({
+        model, mediaType, bytes, instruction, schema: FIELD_SCHEMA, maxTokens: 4096,
+      });
+      spent.push({
+        model,
+        inputTokens: result.inputTokens,
+        outputTokens: result.outputTokens,
+        costMicros: callCostMicros({ inputTokens: result.inputTokens, outputTokens: result.outputTokens, price }),
+      });
+      return { fields: parseFields(result.text, fieldList), spent };
+    } catch (error) {
+      last = error;
+      if (error?.retry === false) break;
+    }
+  }
+  last.spent = spent;
+  throw last;
+}
+
+async function mark(db, row, fields) {
+  const [next] = await db.update(captures).set({ ...fields, updatedAt: sql`now()` }).where(and(
+    eq(captures.organisationId, row.organisationId),
+    eq(captures.id, row.id),
+    eq(captures.state, 'reading'),
+  )).returning();
+  return next ?? row;
+}
+
+// Reads one capture that is still `reading`. A capture that has moved on
+// (typed, decided) is left as it is. The model's answer is stored on the
+// row and is not written to the log.
+export async function readStoredCapture(db, storage, port, settings, { organisationId, captureId, log = console }) {
+  const [row] = await db.select().from(captures).where(and(
+    eq(captures.organisationId, organisationId),
+    eq(captures.id, captureId),
+  ));
+  if (!row || row.state !== 'reading') return row ?? null;
+
+  let stored;
+  try {
+    stored = await storage.get(row.fileKey);
+  } catch {
+    const error = new FlowError('reader_unavailable', 'the reader did not answer');
+    error.retry = true;
+    throw error;
+  }
+  if (!stored) {
+    log.error?.(`[reader] ${row.id} reader_missing`);
+    return mark(db, row, { state: 'problem', problem: 'the photo is missing' });
+  }
+  const sha = createHash('sha256').update(stored.body).digest('hex');
+  if (sha !== row.fileSha256) {
+    log.error?.(`[reader] ${row.id} hash_mismatch`);
+    return mark(db, row, { state: 'problem', problem: 'could not read the form' });
+  }
+  if (!READABLE.has(row.fileType)) {
+    log.error?.(`[reader] ${row.id} reader_type`);
+    return mark(db, row, { state: 'problem', problem: 'photo type cannot be read' });
+  }
+
+  const fieldList = await captureFields(db, organisationId);
+  const instruction = instructionFor(fieldList);
+  const photo = { fieldList, mediaType: row.fileType, bytes: stored.body, instruction };
+  const calls = [];
+  let fields = null;
+  try {
+    const first = await ask(port, { ...photo, model: settings.model, price: settings.prices.small });
+    calls.push(...first.spent);
+    fields = first.fields;
+    if (belowLine(fields, settings.sureLine)) {
+      const second = await ask(port, { ...photo, model: settings.large, price: settings.prices.large });
+      calls.push(...second.spent);
+      fields = second.fields;
+    }
+    return mark(db, row, { state: 'ready', problem: null, read: recorded(fields, calls) });
+  } catch (error) {
+    log.error?.(`[reader] ${row.id} ${error?.code ?? 'reader_unavailable'}`);
+    calls.push(...(error?.spent ?? []));
+    return mark(db, row, {
+      state: 'problem',
+      problem: problemText(error),
+      read: calls.length ? recorded(fields ?? [], calls, fields ? settings.model : calls.at(-1).model) : null,
+    });
+  }
+}
+
+// Queues the read, or runs it in the request when background jobs are off
+// (a Replit workspace). The worker only claims `capture.read` jobs. Two
+// processes can run: the lease keeps a capture to one of them.
+export function createCaptureReader({
+  db, storage, port, settings, log = console, jobsOn = true, timers = globalThis,
+}) {
+  async function handle(job) {
+    const captureId = job.payload?.captureId ?? null;
+    try {
+      await readStoredCapture(db, storage, port, settings, { organisationId: job.organisationId, captureId, log });
+      return { captureId };
+    } catch (error) {
+      log.error?.(`[reader] ${captureId ?? '-'} ${error?.code ?? 'reader_unavailable'}`);
+      const safe = new FlowError('reader_unavailable', 'the reader did not answer');
+      safe.retry = error?.retry !== false;
+      throw safe;
+    }
+  }
+
+  async function schedule(row) {
+    if (!settings?.on) return row;
+    if (!jobsOn) {
+      return readStoredCapture(db, storage, port, settings, { organisationId: row.organisationId, captureId: row.id, log });
+    }
+    await enqueueJob(db, row.organisationId, {
+      kind: CAPTURE_READ_KIND,
+      dedupeKey: row.id,
+      payload: { captureId: row.id },
+      maxAttempts: 2,
+    });
+    return row;
+  }
+
+  const workerId = `reader-${randomUUID()}`;
+  let timer = null;
+  let stopped = true;
+  let running = null;
+
+  function arm(delay) {
+    if (stopped) return;
+    timer = timers.setTimeout(async () => {
+      timer = null;
+      running = tick();
+      const again = await running;
+      running = null;
+      arm(again ? 0 : 1000);
+    }, delay);
+    timer?.unref?.();
+  }
+
+  async function tick() {
+    try {
+      const ran = await runNextJob(db, {
+        workerId,
+        leaseMs: 15 * 60 * 1000,
+        handlers: { [CAPTURE_READ_KIND]: handle },
+      });
+      return Boolean(ran);
+    } catch {
+      log.error?.('[reader] - reader_unavailable');
+      return false;
+    }
+  }
+
+  return {
+    schedule,
+    handle,
+    worker: {
+      start() {
+        stopped = false;
+        arm(1000);
+      },
+      async stop() {
+        stopped = true;
+        if (timer) timers.clearTimeout(timer);
+        timer = null;
+        await running;
+      },
+    },
+  };
+}

package/server/core/sending.js

@@ -53,6 +53,10 @@ const SENT = new Set(['created', 'reconciled', 'existing', 'already_in_xero']);
 // it. `extra` adds `fields` (the invoice fields to fix) and `line`.
 const problem = (code, message, short = null, extra = {}) => ({ code, message, ...(short ? { short } : {}), ...extra });
 
+// An issued invoice the accounting system refused. A refusal stored without
+// its few words (before 2026-10-28) shows "Not sent"; its message stays.
+const refusal = (sendError) => (sendError ? { short: 'Not sent', ...sendError } : problem('send_failed', 'Sending failed.', 'Not sent'));
+
 // Flow's own checks of one draft. `lines` are its invoice lines.
 export function draftProblems(invoice, lines) {
   const problems = [];
@@ -155,7 +159,7 @@ export async function invoiceViews(db, organisationId, { accounting = null } = {
     .orderBy(desc(invoices.sendUpdatedAt));
   for (const row of issued) {
     if (row.sendState === 'queued') sending.add(row.id);
-    else problems.set(row.id, [row.sendError ?? problem('send_failed', 'Sending failed.', 'Send failed')]);
+    else problems.set(row.id, [refusal(row.sendError)]);
   }
   // A draft whose checks pass is ready (Samuel, 2026-10-20): no person
   // needs to mark it. toCheck stays for callers that still read it.
@@ -174,7 +178,7 @@ export async function invoiceView(db, organisationId, invoice, { accounting = nu
   if (invoice.status === 'void') return { view: null, problems: [] };
   if (invoice.status === 'issued') {
     if (invoice.sendState === 'queued') return { view: 'sending', problems: [] };
-    if (invoice.sendState === 'failed') return { view: 'problem', problems: [invoice.sendError ?? problem('send_failed', 'Sending failed.', 'Send failed')] };
+    if (invoice.sendState === 'failed') return { view: 'problem', problems: [refusal(invoice.sendError)] };
     return { view: null, problems: [] };
   }
   const found = (await checkDrafts(db, organisationId, [invoice], accounting)).get(invoice.id) ?? [];
@@ -435,7 +439,7 @@ 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 } });
+        await settle(db, organisationId, result.invoiceId, { sendState: 'failed', sendError: { code: error.code, message: error.message, ...(error.short ? { short: error.short } : {}) } });
         summary.failed += 1;
         summary.refused = [...new Set([...(summary.refused ?? []), error.code])];
         const fact = refusalFact(known.get(result.invoiceId), error);