@arcforgelabs/flow 2026.10.33 → 2026.10.35

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

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

package/server/db/schema.js

@@ -177,7 +177,10 @@ export const PERSON_STATUSES = ['active', 'pending', 'disabled'];
 // are stored lower-case. `clerk_user_id` is set on the person's first verified
 // sign-in; until then the row is an invitation. `appearance` is the person's
 // own design system, light or dark and accent (server/auth/people.js,
-// normaliseAppearance); null until they first choose.
+// normaliseAppearance); null until they first choose. `views` is the
+// person's own view of each page, such as how the Jobs page groups, sorts
+// and filters ({ jobs: … }, server/ui/job-view.js); null until they first
+// change one.
 export const people = pgTable('people', {
   id: id(),
   email: text('email').notNull(),
@@ -188,6 +191,7 @@ export const people = pgTable('people', {
   invitedBy: uuid('invited_by').references(() => people.id, { onDelete: 'set null' }),
   linkedAt: timestamp('linked_at', { withTimezone: true }),
   appearance: jsonb('appearance'),
+  views: jsonb('views'),
   createdAt: createdAt(),
   updatedAt: updatedAt(),
 }, (t) => [
@@ -766,3 +770,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,12 @@ 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
+  'jobLink', // { url, exact } or null: the link to one job in the work system's own web app, for "Open in" on a job's problem; never a live call
+  '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 +38,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,11 +7,14 @@ 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, handOff, readPersonSettings, requestStageMove, settleStageMoves, waitingStageMoves, writePersonSetting,
+} from './stage-moves.js';
 import { orderPatient } from './patients.js';
 import { createSeazonaScheduler } from './scheduler.js';
 import { readSweepHealth } from './sweep.js';
 import { resetFailedLanes, resetStoppedLanes } from './store.js';
-import { describeSeazonaSettings, resolveSeazonaSettings } from './settings.js';
+import { describeSeazonaSettings, orderLink, resolveSeazonaSettings } from './settings.js';
 import { seazonaSchema } from './tables.js';
 
 // The Seazona adapter (docs/SEAZONA.md). FLOW_INTEGRATIONS=seazona turns it
@@ -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. Open any order in Seazona and paste its address here, or write {ref} where the order id goes. Stage moves on the Jobs board and Open in Seazona use 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,44 @@ 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.
+        // Each card also carries the link that opens its order in Seazona.
+        const { settings } = current();
+        for (const item of work.items) {
+          item.link = orderLink(settings, { sourceJobRef: item.sourceJobRef });
+          const move = waiting.get(item.sourceJobRef);
+          if (move) {
+            const { to, from, requestedAt, expiresAt, openUrl, openExact } = handOff(move, { settings });
+            item.pendingMove = { to, from, requestedAt, expiresAt, openUrl, openExact };
+          }
+        }
+        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, settings, 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
@@ -221,6 +273,12 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
         return historyJobIssues(current().db, refs);
       },
 
+      // The link to one order in Seazona's web app, for "Open in Seazona" on
+      // a job's problem (settings.js, orderLink). Never calls Seazona.
+      jobLink({ sourceJobRef }) {
+        return runtime ? orderLink(runtime.settings, { sourceJobRef }) : null;
+      },
+
       // Seazona's products, for the price list (server/core/price-list.js).
       // Reads Flow's copy only.
       async listPriceItems() {

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");