@arcforgelabs/flow 2026.10.33 → 2026.10.34

package/server/db/migrations/meta/_journal.json

@@ -127,6 +127,13 @@
       "when": 1792458167234,
       "tag": "0017_sync_basis",
       "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1792472460808,
+      "tag": "0018_custom_fields",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -766,3 +766,62 @@ export const priceItemLinks = pgTable('price_item_links', {
   check('price_item_links_matched_by_valid', sql`${t.matchedBy} in ('code', 'person')`),
   check('price_item_links_system_valid', sql`${t.system} ~ '^[a-z][a-z0-9-]{1,31}$'`),
 ]);
+
+// Custom fields (server/core/custom-fields.js, docs/CUSTOM_FIELDS.md): fields
+// a lab makes for its jobs in Flow, in Settings, Custom fields. Only an owner
+// or admin makes or changes one. A dropdown's options are
+// [{ id, name, color }] in lane order; an option a person removes stays in
+// `options` with `archived: true`, so old values and history still read.
+// The type never changes after a field is made.
+export const CUSTOM_FIELD_TYPES = ['dropdown', 'person', 'checkbox', 'date', 'number', 'text'];
+export const jobFields = pgTable('job_fields', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  name: text('name').notNull(),
+  type: text('type').notNull(),
+  options: jsonb('options').notNull().default(sql`'[]'::jsonb`),
+  position: integer('position').notNull(),
+  archivedAt: timestamp('archived_at', { withTimezone: true }),
+  createdBy: uuid('created_by').references(() => people.id, { onDelete: 'set null' }),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('job_fields_org_id').on(t.organisationId, t.id),
+  check('job_fields_type_valid', sql`${t.type} in ('dropdown', 'person', 'checkbox', 'date', 'number', 'text')`),
+  check('job_fields_name_valid', sql`length(${t.name}) between 1 and 60`),
+]);
+
+// A job's value for one custom field. A job is the work system's job
+// (source_system, source_job_ref), the same key the Jobs board uses, so a
+// value needs no Flow copy of the job. `value` is JSON: an option id, a person
+// id, true or false, a YYYY-MM-DD date, a number or text. No row means empty.
+export const jobFieldValues = pgTable('job_field_values', {
+  organisationId: organisationId().references(() => organisations.id),
+  fieldId: uuid('field_id').notNull(),
+  sourceSystem: text('source_system').notNull(),
+  sourceJobRef: text('source_job_ref').notNull(),
+  value: jsonb('value').notNull(),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  updatedAt: updatedAt(),
+}, (t) => [
+  primaryKey({ columns: [t.organisationId, t.fieldId, t.sourceSystem, t.sourceJobRef] }),
+  foreignKey({ name: 'job_field_values_field_same_org', columns: [t.organisationId, t.fieldId], foreignColumns: [jobFields.organisationId, jobFields.id] }).onDelete('cascade'),
+  index('job_field_values_job').on(t.organisationId, t.sourceSystem, t.sourceJobRef),
+]);
+
+// Every change of a job's custom field value: who, when, from and to.
+export const jobFieldEvents = pgTable('job_field_events', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  fieldId: uuid('field_id').notNull(),
+  sourceSystem: text('source_system').notNull(),
+  sourceJobRef: text('source_job_ref').notNull(),
+  fromValue: jsonb('from_value'),
+  toValue: jsonb('to_value'),
+  actor: uuid('actor').references(() => people.id, { onDelete: 'set null' }),
+  createdAt: createdAt(),
+}, (t) => [
+  foreignKey({ name: 'job_field_events_field_same_org', columns: [t.organisationId, t.fieldId], foreignColumns: [jobFields.organisationId, jobFields.id] }).onDelete('cascade'),
+  index('job_field_events_job').on(t.organisationId, t.sourceSystem, t.sourceJobRef, t.createdAt),
+]);

package/server/index.js

@@ -10,6 +10,7 @@ import {
   importEarlierAtStart, importEarlierLinksAtStart, importEarlierMappingsAtStart, resolveImportAtStart,
 } from './import/at-start.js';
 import { createMonitoredLog } from './core/monitoring.js';
+import { createTracing, traceQueries } from './core/tracing.js';
 import { createPipelineWorker } from './core/pipeline.js';
 import { createReconcileWorker } from './core/reconcile.js';
 import { createSendWorker } from './core/sending.js';
@@ -78,6 +79,10 @@ await importEarlierMappingsAtStart({ db: database.db, pool: database.pool, setti
 // own error service while one is on (docs/SENTRY.md).
 let integrations;
 const log = createMonitoredLog({ log: console, reporters: () => integrations?.with('captureError') ?? [] });
+// Performance traces, while a tracing service is on (docs/SENTRY.md, "Traces"):
+// each request, and each database query inside one.
+const tracing = createTracing({ tracers: () => integrations?.with('traceRequest') ?? [] });
+traceQueries(database.pool, tracing);
 try {
   const stored = await readStoredSettings(database.db);
   const { env: settingsEnv, unreadable } = settingsEnvironment({ env: process.env, stored, adapters: shippedAdapters, secrets });
@@ -147,7 +152,7 @@ const trustProxy = process.env.REPL_ID || process.env.REPLIT_DEPLOYMENT ? 1 : fa
 
 const updates = createUpdateChecker();
 
-createApp({ database, schemaJournals: expectedSchema({ adapters: shippedAdapters }).journals, auth, trustProxy, updates, integrations, secrets, defaultFamily, log }).listen(port, () => {
+createApp({ database, schemaJournals: expectedSchema({ adapters: shippedAdapters }).journals, auth, trustProxy, updates, integrations, secrets, defaultFamily, log, tracing }).listen(port, () => {
   console.log(`[flow] listening on ${port}; design system ${defaultFamily} (FLOW_THEME)`);
 });
 

package/server/integrations/port.js

@@ -23,7 +23,11 @@ export const CAPABILITIES = Object.freeze([
   'checkInvoice', // does the accounting system hold an invoice for a billable job? (the ledger's liveCheck)
   'billableJobs', // billable jobs by day from the work system's copy in Flow, for the daily reconcile; never a live call
   'jobReferenceFields', // { patient }: the fields a job gives the invoice Reference (server/core/references.js)
-  'listWork', // the work system's jobs from its copy in Flow, open and lately finished, for the Jobs board
+  'listWork', // the work system's jobs from its copy in Flow, open and lately finished, for the Jobs board; a job may carry `pendingMove`
+  'moveWork', // { sourceJobRef, toStatus, personId }: a person moved a job to another stage on the Jobs board; answers what happens (a hand-off when the system's API cannot change it)
+  'cancelMove', // { sourceJobRef }: take back a move the work system has not made yet
+  'personSettings', // { personId }: each person's own choices in this integration, as [{ key, label, hint, kind, value }]
+  'setPersonSetting', // { personId, key, value }: change one, answers the new list
   'jobIssues', // open issues the integration holds for jobs, by job ref: a short phrase and the page where a person fixes it
   'listCustomers', // the system's customers, by id and name, for the identity map (Seazona: clients; Xero: contacts)
   'findInvoices', // sales invoices in the accounting system's copy, for the matcher; never a live call
@@ -33,6 +37,8 @@ export const CAPABILITIES = Object.freeze([
   'alerts', // what only a person can clear (a refused sign-in, stopped calls), for the Integrations page; reads Flow's data only
   'captureError', // an error Flow logged, sent to the installation's own error service (Sentry)
   'browserMonitoring', // the public settings a browser needs to report errors and problems to that service
+  'traceSpan', // runs work inside a span of the current performance trace (server/core/tracing.js)
+  'traceRequest', // names a request's performance trace by its route, once the route is known
 ]);
 
 const ID_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;

package/server/integrations/seazona/index.js

@@ -7,6 +7,9 @@ import { readSeazonaSyncHealth, runSeazonaSync } from './lanes.js';
 import { readBillableJobs } from './reconcile.js';
 import { SEAZONA_CALL_GUARD } from './governor.js';
 import { createSeazonaRouter } from './routes.js';
+import {
+  cancelStageMove, expiredStageMoves, readPersonSettings, requestStageMove, settleStageMoves, waitingStageMoves, writePersonSetting,
+} from './stage-moves.js';
 import { orderPatient } from './patients.js';
 import { createSeazonaScheduler } from './scheduler.js';
 import { readSweepHealth } from './sweep.js';
@@ -48,6 +51,7 @@ export const SEAZONA_SETUP = {
     { name: 'SEAZONA_API_BASE_URL', label: 'API address', kind: 'url', help: 'The API root of your account, https://…' },
     { name: 'SEAZONA_API_CLIENT_ID', label: 'Client id' },
     { name: 'SEAZONA_API_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },
+    { name: 'SEAZONA_ORDER_URL', label: 'Order address', kind: 'url', help: 'Optional. The address of one order in Seazona, with {ref} for the order number. Stage moves on the Jobs board open it.' },
     { name: 'SEAZONA_KEEP_PATIENT_REFERENCE', label: 'Keep patient names', kind: 'onoff', help: 'On: Flow keeps the patient name of each job for the invoice Reference.' },
   ],
 };
@@ -144,6 +148,17 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
         if (!runtime?.client.governor) return [];
         const status = await runtime.client.governor.status();
         const alerts = guardAlerts('Seazona', status, { fix: 'Check the API client in the Seazona settings, then save them.' });
+        // Stage moves nobody made in Seazona within a day (stage-moves.js).
+        await settleStageMoves(runtime.db, { now: now() });
+        const expired = await expiredStageMoves(runtime.db, { now: now() });
+        if (expired.length) {
+          alerts.push({
+            id: 'stage-moves-expired',
+            tone: 'warn',
+            title: `${expired.length === 1 ? 'One stage move was' : `${expired.length} stage moves were`} not made in Seazona within a day: ${expired.slice(0, 5).map((m) => `${m.orderId} to ${m.toStatus}`).join(', ')}${expired.length > 5 ? ', …' : ''}. The cards went back to their Seazona stage.`,
+            members: expired.map((m) => `${m.orderId}:${m.settledAt?.toISOString() ?? ''}`),
+          });
+        }
         // Issue #143: what the lanes cannot fix by themselves. A refused API
         // client already has its own alert above, so it stops no lane here.
         if (!runtime.settings.scheduled) return alerts;
@@ -205,7 +220,38 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
       // Open orders and orders finished lately, with their statuses, for the
       // Jobs board. Reads Flow's copy only.
       async listWork() {
-        return listWork(current().db, { now: now() });
+        const { db } = current();
+        await settleStageMoves(db, { now: now() });
+        const [work, waiting] = await Promise.all([listWork(db, { now: now() }), waitingStageMoves(db)]);
+        // A stage move Seazona has not made yet (stage-moves.js): the card
+        // shows in its new lane, waiting for Seazona.
+        for (const item of work.items) {
+          const move = waiting.get(item.sourceJobRef);
+          if (move) item.pendingMove = { to: move.toStatus, from: move.fromStatus, requestedAt: move.requestedAt.toISOString(), expiresAt: move.expiresAt.toISOString() };
+        }
+        return work;
+      },
+
+      // A person's move of a job to another Seazona stage. Seazona's API
+      // cannot change an order's status, so this never calls Seazona: it
+      // records a hand-off and answers what the person does in Seazona.
+      async moveWork({ sourceJobRef, toStatus, personId = null }) {
+        const { db, settings } = current();
+        return requestStageMove(db, { orderId: sourceJobRef, toStatus, personId, orderUrlTemplate: settings.orderUrlTemplate, now: now() });
+      },
+
+      async cancelMove({ sourceJobRef }) {
+        return cancelStageMove(current().db, { orderId: sourceJobRef, now: now() });
+      },
+
+      // Each person's own Seazona choices: today, whether the board asks
+      // before a stage move.
+      async personSettings({ personId }) {
+        return readPersonSettings(current().db, personId);
+      },
+
+      async setPersonSetting({ personId, key, value }) {
+        return writePersonSetting(current().db, personId, { key, value }, { now: now() });
       },
 
       // The fields a job gives the invoice Reference: the patient name, when

package/server/integrations/seazona/migrations/0007_stage_moves.sql

@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS "seazona_person_settings" (
+	"person_id" text PRIMARY KEY NOT NULL,
+	"ask_before_stage_moves" boolean DEFAULT true NOT NULL,
+	"updated_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "seazona_stage_moves" (
+	"order_id" text PRIMARY KEY NOT NULL,
+	"from_status" text,
+	"to_status" text NOT NULL,
+	"requested_by" text,
+	"requested_at" timestamp with time zone NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"state" text DEFAULT 'waiting' NOT NULL,
+	"settled_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "seazona_stage_moves_state" ON "seazona_stage_moves" USING btree ("state","expires_at");