@arcforgelabs/flow 2026.10.33 → 2026.10.35

package/server/core/custom-fields.js

@@ -0,0 +1,308 @@
+import { randomUUID } from 'node:crypto';
+import { and, asc, eq, inArray, isNull, sql } from 'drizzle-orm';
+import { CUSTOM_FIELD_TYPES, jobFieldEvents, jobFields, jobFieldValues, people } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+
+// Custom fields (docs/CUSTOM_FIELDS.md): fields a lab makes for its jobs in
+// Flow, like ClickUp's custom fields. An owner or admin makes them in
+// Settings, Custom fields; everyone can set a job's value. A job is the work
+// system's job (sourceSystem, sourceJobRef). A value lives only in Flow: a
+// change never writes to the work system or the accounting system.
+
+export { CUSTOM_FIELD_TYPES };
+// The types that make lanes on the Jobs board: one lane per option, per
+// person, or yes and no.
+export const GROUPABLE_TYPES = ['dropdown', 'person', 'checkbox'];
+export const OPTION_COLORS = ['gray', 'blue', 'teal', 'green', 'amber', 'red', 'purple', 'pink'];
+
+const MAX_FIELDS = 50;
+const MAX_OPTIONS = 50;
+const MAX_NAME = 60;
+const MAX_OPTION_NAME = 40;
+const MAX_TEXT = 500;
+const MAX_NUMBER = 1e12;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SYSTEM = /^[a-z][a-z0-9-]{1,31}$/;
+
+const invalid = (message) => new FlowError('invalid', message);
+
+function readName(raw, what, max) {
+  if (typeof raw !== 'string' || !raw.trim()) throw invalid(`${what} is required`);
+  const name = raw.trim().replace(/\s+/g, ' ');
+  if (name.length > max) throw invalid(`${what} is too long (${max} characters at most)`);
+  return name;
+}
+
+// A dropdown's options as a person sends them: [{ id?, name, color? }], in
+// lane order. An option with no id is new. An earlier option that is not in
+// the list is kept as archived, so its old values still read.
+export function readOptions(raw, previous = []) {
+  if (!Array.isArray(raw)) throw invalid('options must be a list');
+  if (!raw.length) throw invalid('a dropdown needs at least one option');
+  if (raw.length > MAX_OPTIONS) throw invalid(`a dropdown has ${MAX_OPTIONS} options at most`);
+  const known = new Map(previous.map((o) => [o.id, o]));
+  const names = new Set();
+  const active = raw.map((option, i) => {
+    if (!option || typeof option !== 'object') throw invalid(`option ${i + 1} must be an object`);
+    const name = readName(option.name, `option ${i + 1} name`, MAX_OPTION_NAME);
+    const key = name.toLowerCase();
+    if (names.has(key)) throw invalid(`two options are named ${name}`);
+    names.add(key);
+    const color = option.color === undefined || option.color === null ? 'gray' : option.color;
+    if (!OPTION_COLORS.includes(color)) throw invalid(`option ${name}: color must be one of ${OPTION_COLORS.join(', ')}`);
+    if (option.id !== undefined && option.id !== null) {
+      if (!known.has(option.id)) throw invalid(`option ${name}: unknown id`);
+      return { id: option.id, name, color };
+    }
+    return { id: randomUUID(), name, color };
+  });
+  const kept = new Set(active.map((o) => o.id));
+  const archived = previous.filter((o) => !kept.has(o.id)).map((o) => ({ ...o, archived: true }));
+  return [...active, ...archived];
+}
+
+// A new field, or the part of one a person changes. The type is fixed once
+// the field exists.
+export function readField(raw, { partial = false, previous = null } = {}) {
+  const input = raw && typeof raw === 'object' ? raw : {};
+  const out = {};
+  if (!partial || input.name !== undefined) out.name = readName(input.name, 'name', MAX_NAME);
+  if (!partial) {
+    if (!CUSTOM_FIELD_TYPES.includes(input.type)) throw invalid(`type must be one of ${CUSTOM_FIELD_TYPES.join(', ')}`);
+    out.type = input.type;
+  } else if (input.type !== undefined && input.type !== previous?.type) {
+    throw invalid('the type of a field cannot change; make a new field instead');
+  }
+  const type = out.type ?? previous?.type;
+  if (type === 'dropdown' && (!partial || input.options !== undefined)) out.options = readOptions(input.options, previous?.options ?? []);
+  else if (type !== 'dropdown' && input.options !== undefined && input.options !== null && !(Array.isArray(input.options) && !input.options.length)) {
+    throw invalid('only a dropdown has options');
+  }
+  return out;
+}
+
+export const publicField = (row) => ({
+  id: row.id,
+  name: row.name,
+  type: row.type,
+  options: row.options ?? [],
+  position: row.position,
+  groupable: GROUPABLE_TYPES.includes(row.type),
+  archived: Boolean(row.archivedAt),
+  createdBy: row.createdBy ?? null,
+  createdAt: row.createdAt?.toISOString?.() ?? row.createdAt,
+  updatedAt: row.updatedAt?.toISOString?.() ?? row.updatedAt,
+});
+
+export async function listFields(db, organisationId, { archived = false } = {}) {
+  const where = [eq(jobFields.organisationId, organisationId)];
+  if (!archived) where.push(isNull(jobFields.archivedAt));
+  const rows = await db.select().from(jobFields).where(and(...where)).orderBy(asc(jobFields.position), asc(jobFields.createdAt));
+  return rows.map(publicField);
+}
+
+async function readRow(db, organisationId, id) {
+  if (!UUID.test(id ?? '')) throw notFound('field');
+  const [row] = await db.select().from(jobFields).where(and(eq(jobFields.organisationId, organisationId), eq(jobFields.id, id)));
+  if (!row) throw notFound('field');
+  return row;
+}
+
+async function checkNameFree(db, organisationId, name, exceptId = null) {
+  const rows = await db.select({ id: jobFields.id }).from(jobFields).where(and(
+    eq(jobFields.organisationId, organisationId), isNull(jobFields.archivedAt),
+    sql`lower(${jobFields.name}) = ${name.toLowerCase()}`,
+  ));
+  if (rows.some((r) => r.id !== exceptId)) throw new FlowError('conflict', `a field named ${name} already exists`);
+}
+
+export async function createField(db, organisationId, raw, { personId = null } = {}) {
+  const field = readField(raw);
+  return db.transaction(async (tx) => {
+    const [{ count, last }] = await tx.select({
+      count: sql`count(*) filter (where ${jobFields.archivedAt} is null)`.mapWith(Number),
+      last: sql`coalesce(max(${jobFields.position}), -1)`.mapWith(Number),
+    }).from(jobFields).where(eq(jobFields.organisationId, organisationId));
+    if (count >= MAX_FIELDS) throw invalid(`an organisation has ${MAX_FIELDS} fields at most`);
+    await checkNameFree(tx, organisationId, field.name);
+    const [row] = await tx.insert(jobFields).values({
+      organisationId, ...field, options: field.options ?? [], position: last + 1, createdBy: personId, updatedBy: personId,
+    }).returning();
+    return publicField(row);
+  });
+}
+
+export async function updateField(db, organisationId, id, raw, { personId = null } = {}) {
+  const previous = await readRow(db, organisationId, id);
+  if (previous.archivedAt) throw new FlowError('conflict', 'the field is archived; bring it back first');
+  const change = readField(raw, { partial: true, previous });
+  if (change.name) await checkNameFree(db, organisationId, change.name, id);
+  const [row] = await db.update(jobFields).set({ ...change, updatedBy: personId, updatedAt: new Date() })
+    .where(and(eq(jobFields.organisationId, organisationId), eq(jobFields.id, id))).returning();
+  return publicField(row);
+}
+
+// Archive a field, or bring it back. Its values stay, so bringing it back
+// restores them.
+export async function archiveField(db, organisationId, id, { archived = true, personId = null } = {}) {
+  const previous = await readRow(db, organisationId, id);
+  if (!archived) await checkNameFree(db, organisationId, previous.name, id);
+  const [row] = await db.update(jobFields).set({ archivedAt: archived ? new Date() : null, updatedBy: personId, updatedAt: new Date() })
+    .where(and(eq(jobFields.organisationId, organisationId), eq(jobFields.id, id))).returning();
+  return publicField(row);
+}
+
+// Put the fields in this order. `ids` lists every field that is not archived.
+export async function orderFields(db, organisationId, ids, { personId = null } = {}) {
+  if (!Array.isArray(ids) || ids.some((i) => typeof i !== 'string')) throw invalid('ids must be a list of field ids');
+  const current = await listFields(db, organisationId);
+  const want = new Set(ids);
+  if (want.size !== ids.length || current.length !== ids.length || current.some((f) => !want.has(f.id))) {
+    throw invalid('ids must list every field that is not archived, once each');
+  }
+  await db.transaction(async (tx) => {
+    for (const [position, id] of ids.entries()) {
+      await tx.update(jobFields).set({ position, updatedBy: personId, updatedAt: new Date() })
+        .where(and(eq(jobFields.organisationId, organisationId), eq(jobFields.id, id)));
+    }
+  });
+  return listFields(db, organisationId);
+}
+
+function readJob(raw) {
+  const sourceSystem = typeof raw?.sourceSystem === 'string' ? raw.sourceSystem.trim() : '';
+  const sourceJobRef = typeof raw?.sourceJobRef === 'string' ? raw.sourceJobRef.trim() : '';
+  if (!SYSTEM.test(sourceSystem)) throw invalid('sourceSystem must be an integration id');
+  if (!sourceJobRef || sourceJobRef.length > 200) throw invalid('sourceJobRef is required (200 characters at most)');
+  return { sourceSystem, sourceJobRef };
+}
+
+function isRealDate(value) {
+  if (typeof value !== 'string' || !DATE.test(value)) return false;
+  const d = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === value;
+}
+
+// A value checked against its field. null clears the value.
+export async function readValue(db, field, raw) {
+  if (raw === null || raw === undefined || raw === '') return null;
+  switch (field.type) {
+    case 'dropdown': {
+      const option = (field.options ?? []).find((o) => o.id === raw && !o.archived);
+      if (!option) throw invalid(`${field.name}: choose one of its options`);
+      return option.id;
+    }
+    case 'person': {
+      if (typeof raw !== 'string' || !UUID.test(raw)) throw invalid(`${field.name}: choose a person`);
+      const [row] = await db.select({ id: people.id }).from(people).where(and(eq(people.id, raw), eq(people.status, 'active')));
+      if (!row) throw invalid(`${field.name}: that person cannot be chosen`);
+      return row.id;
+    }
+    case 'checkbox':
+      if (typeof raw !== 'boolean') throw invalid(`${field.name} must be true or false`);
+      return raw;
+    case 'date':
+      if (!isRealDate(raw)) throw invalid(`${field.name} must be a date, YYYY-MM-DD`);
+      return raw;
+    case 'number':
+      if (typeof raw !== 'number' || !Number.isFinite(raw) || Math.abs(raw) >= MAX_NUMBER) throw invalid(`${field.name} must be a number`);
+      return raw;
+    default:
+      if (typeof raw !== 'string') throw invalid(`${field.name} must be text`);
+      if (raw.length > MAX_TEXT) throw invalid(`${field.name} is too long (${MAX_TEXT} characters at most)`);
+      return raw.trim() || null;
+  }
+}
+
+const publicValue = (row) => ({
+  fieldId: row.fieldId,
+  sourceSystem: row.sourceSystem,
+  sourceJobRef: row.sourceJobRef,
+  value: row.value,
+  updatedBy: row.updatedBy ?? null,
+  updatedAt: row.updatedAt?.toISOString?.() ?? row.updatedAt,
+});
+
+// Set one job's value for one field, as a drag between lanes does.
+// `expectedUpdatedAt` is the updatedAt of the value the person last saw
+// (null when they saw none). When someone changed it since, nothing changes
+// and the error carries the current value, so the board can show it.
+export async function setJobFieldValue(db, organisationId, raw, { personId = null } = {}) {
+  const job = readJob(raw);
+  const field = await readRow(db, organisationId, raw?.fieldId);
+  if (field.archivedAt) throw new FlowError('conflict', 'the field is archived');
+  const value = await readValue(db, field, raw?.value);
+  const checkVersion = raw && Object.hasOwn(raw, 'expectedUpdatedAt');
+  const expected = checkVersion && raw.expectedUpdatedAt ? new Date(raw.expectedUpdatedAt) : null;
+  if (expected && Number.isNaN(expected.getTime())) throw invalid('expectedUpdatedAt must be a time');
+  const key = and(
+    eq(jobFieldValues.organisationId, organisationId), eq(jobFieldValues.fieldId, field.id),
+    eq(jobFieldValues.sourceSystem, job.sourceSystem), eq(jobFieldValues.sourceJobRef, job.sourceJobRef),
+  );
+  return db.transaction(async (tx) => {
+    // One change at a time per job and field, also while no row exists yet.
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtext(${`${organisationId}:${field.id}:${job.sourceSystem}:${job.sourceJobRef}`}))`);
+    const [current] = await tx.select().from(jobFieldValues).where(key);
+    if (checkVersion) {
+      const seen = current?.updatedAt?.getTime() ?? null;
+      if (seen !== (expected?.getTime() ?? null)) {
+        throw new FlowError('conflict', 'someone changed this value since you saw it', { current: current ? publicValue(current) : null });
+      }
+    }
+    const from = current?.value ?? null;
+    if (JSON.stringify(from) === JSON.stringify(value)) return current ? publicValue(current) : { fieldId: field.id, ...job, value: null, updatedBy: null, updatedAt: null };
+    let saved = null;
+    if (value === null) {
+      await tx.delete(jobFieldValues).where(key);
+    } else {
+      [saved] = await tx.insert(jobFieldValues).values({ organisationId, fieldId: field.id, ...job, value, updatedBy: personId, updatedAt: new Date() })
+        .onConflictDoUpdate({
+          target: [jobFieldValues.organisationId, jobFieldValues.fieldId, jobFieldValues.sourceSystem, jobFieldValues.sourceJobRef],
+          set: { value, updatedBy: personId, updatedAt: new Date() },
+        }).returning();
+    }
+    await tx.insert(jobFieldEvents).values({ organisationId, fieldId: field.id, ...job, fromValue: from, toValue: value, actor: personId });
+    return saved ? publicValue(saved) : { fieldId: field.id, ...job, value: null, updatedBy: personId, updatedAt: null };
+  });
+}
+
+// Every value of the fields that are not archived, optionally for some jobs
+// only (`jobs`: [{ sourceSystem, sourceJobRef }]).
+export async function listJobFieldValues(db, organisationId, { jobs = null } = {}) {
+  const where = [eq(jobFieldValues.organisationId, organisationId), isNull(jobFields.archivedAt)];
+  if (jobs) {
+    if (!jobs.length) return [];
+    const refs = [...new Set(jobs.map((j) => j.sourceJobRef))];
+    where.push(inArray(jobFieldValues.sourceJobRef, refs));
+  }
+  const rows = await db.select({
+    fieldId: jobFieldValues.fieldId, sourceSystem: jobFieldValues.sourceSystem, sourceJobRef: jobFieldValues.sourceJobRef,
+    value: jobFieldValues.value, updatedBy: jobFieldValues.updatedBy, updatedAt: jobFieldValues.updatedAt,
+  }).from(jobFieldValues)
+    .innerJoin(jobFields, and(eq(jobFields.organisationId, jobFieldValues.organisationId), eq(jobFields.id, jobFieldValues.fieldId)))
+    .where(and(...where));
+  const wanted = jobs ? new Set(jobs.map((j) => `${j.sourceSystem}\u0000${j.sourceJobRef}`)) : null;
+  return rows.filter((r) => !wanted || wanted.has(`${r.sourceSystem}\u0000${r.sourceJobRef}`)).map(publicValue);
+}
+
+// The people a person field can name: every active person, by id and name
+// (the part of the email before @ when they have no name), A to Z.
+export async function choosablePeople(db) {
+  const rows = await db.select({ id: people.id, name: people.name, email: people.email }).from(people).where(eq(people.status, 'active'));
+  return rows.map((r) => ({ id: r.id, name: r.name?.trim() || r.email.replace(/@.*/, '') }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// What happened to one job's custom field values, newest first.
+export async function jobFieldHistory(db, organisationId, raw, { limit = 50 } = {}) {
+  const job = readJob(raw);
+  const rows = await db.select().from(jobFieldEvents).where(and(
+    eq(jobFieldEvents.organisationId, organisationId),
+    eq(jobFieldEvents.sourceSystem, job.sourceSystem), eq(jobFieldEvents.sourceJobRef, job.sourceJobRef),
+  )).orderBy(sql`${jobFieldEvents.createdAt} desc`).limit(limit);
+  return rows.map((r) => ({
+    fieldId: r.fieldId, from: r.fromValue, to: r.toValue, actor: r.actor ?? null,
+    at: r.createdAt?.toISOString?.() ?? r.createdAt,
+  }));
+}

package/server/core/job-board.js

@@ -136,6 +136,10 @@ export async function boardJobs(db, organisationId, { work = [], accounting = nu
         totalCents: o?.totalCents ?? item.totalCents ?? null,
         lines: o ? ledgerLines(o.lines)
           : (item.lines ?? []).map((l) => ({ code: l.code ?? null, description: l.description, amountCents: l.amountCents ?? null, mapped: Boolean(l.code && codes.has(l.code)) })),
+        // A stage move the work system has not made yet (moveWork).
+        pendingMove: item.pendingMove ?? null,
+        // The link to the job in the work system's own web app ({ url, exact }).
+        link: item.link ?? null,
         obligation: o,
       });
     }

package/server/core/ledger.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
 import {
-  billingObligations, obligationEvents, obligationPayments, obligationWritebacks, priceItems,
+  billingObligations, invoices, obligationEvents, obligationPayments, obligationWritebacks, priceItems,
 } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 import { createDraftInvoice, getInvoice, updateDraftInvoice } from './invoices.js';
@@ -325,9 +325,16 @@ export async function useSourceLines(db, organisationId, obligationId, { actor }
         ));
       } else changes[field] = obligation[field];
     }
-    const invoice = Object.keys(changes).length
+    let invoice = Object.keys(changes).length
       ? await updateDraftInvoice(tx, organisationId, obligation.invoiceId, changes)
       : await getInvoice(tx, organisationId, obligation.invoiceId);
+    // The draft now matches a job that is ready to invoice, so it goes to
+    // Ready on its own; Flow's checks still hold it in Problem if one fails.
+    if (obligation.readyAt && !invoice.readyAt) {
+      await tx.update(invoices).set({ readyAt: sql`now()`, readyBy: null })
+        .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoice.id), eq(invoices.status, 'draft')));
+      invoice = await getInvoice(tx, organisationId, invoice.id);
+    }
     const fields = { draftBasis: basisOf(obligation) };
     if (obligation.holdState === 'review' && obligation.holdReason === CHANGED_REASON) Object.assign(fields, { holdState: 'none', holdReason: null });
     const row = await update(tx, obligation, fields);
@@ -337,6 +344,79 @@ export async function useSourceLines(db, organisationId, obligationId, { actor }
   });
 }
 
+// What changed in a job after its invoice was made, for the invoice page:
+// each line as it was (the draft basis) and as the work system has it now.
+// Lines pair by price item, else item code, account or description; an
+// unpaired old line and an unpaired new line at the same place pair as a
+// replaced item. Answers [{ change, position, was, now, fields }], where
+// `change` is changed, replaced, added or removed and `fields` names what
+// differs on a changed or replaced line (item, description, quantity, price).
+export function diffJobLines(wasLines = [], nowLines = []) {
+  const keyOf = (l) => l.priceItemId ?? l.itemCode ?? l.accountCode ?? String(l.description ?? '').trim().toLowerCase();
+  const show = (l) => ({
+    code: l.itemCode ?? l.accountCode ?? null, description: l.description ?? '', quantity: Number(l.quantity), unitAmountCents: l.unitAmountCents ?? null,
+  });
+  const differs = (a, b) => [
+    keyOf(a) !== keyOf(b) ? 'item' : null,
+    String(a.description ?? '').trim() !== String(b.description ?? '').trim() && keyOf(a) === keyOf(b) ? 'description' : null,
+    Number(a.quantity) !== Number(b.quantity) ? 'quantity' : null,
+    (a.unitAmountCents ?? null) !== (b.unitAmountCents ?? null) ? 'price' : null,
+  ].filter(Boolean);
+  const wasLeft = wasLines.map((line, index) => ({ line, index }));
+  const pairs = [];
+  const added = [];
+  nowLines.forEach((line, index) => {
+    const at = wasLeft.findIndex((w) => keyOf(w.line) === keyOf(line));
+    if (at === -1) { added.push({ line, index }); return; }
+    pairs.push({ was: wasLeft.splice(at, 1)[0], now: { line, index } });
+  });
+  // What is left over: an old line and a new line in the same place are one
+  // replaced item; the rest were added or removed.
+  for (const now of [...added]) {
+    const at = wasLeft.findIndex((w) => w.index === now.index);
+    if (at === -1) continue;
+    pairs.push({ was: wasLeft.splice(at, 1)[0], now });
+    added.splice(added.indexOf(now), 1);
+  }
+  const changes = [];
+  for (const { was, now } of pairs) {
+    const fields = differs(was.line, now.line);
+    if (!fields.length) continue;
+    changes.push({ change: fields.includes('item') ? 'replaced' : 'changed', position: now.index + 1, was: show(was.line), now: show(now.line), fields });
+  }
+  for (const { line, index } of added) changes.push({ change: 'added', position: index + 1, was: null, now: show(line), fields: [] });
+  for (const { line, index } of wasLeft) changes.push({ change: 'removed', position: index + 1, was: show(line), now: null, fields: [] });
+  return changes.sort((a, b) => a.position - b.position || (a.change === 'removed' ? -1 : 1));
+}
+
+// The open "job changed" problem of an invoice, for the invoice page, or
+// null: the job as it was when the invoice was made, as the work system has
+// it now, and whether a person can adopt the change into Flow's own draft
+// ("Adopt changes", useSourceLines). An invoice drafted before the basis was
+// kept compares with the invoice's own lines.
+export async function jobChangeFor(db, organisationId, invoiceId) {
+  const [obligation] = await db.select().from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoiceId),
+      eq(billingObligations.holdState, 'review'), eq(billingObligations.holdReason, CHANGED_REASON)));
+  if (!obligation) return null;
+  const compare = await compareWithDraft(db, organisationId, obligation, obligation);
+  const was = obligation.draftBasis
+    ?? (compare.flow ? { lines: compare.flow.lines, contactId: compare.flow.contactId, totalCents: null } : basisOf(obligation));
+  return {
+    jobId: obligation.id,
+    sourceSystem: obligation.sourceSystem,
+    sourceJobRef: obligation.sourceJobRef,
+    sourceInvoiceRef: obligation.sourceInvoiceRef,
+    seenAt: obligation.sourceSeenAt,
+    outcome: compare.outcome,
+    sent: compare.sent,
+    canAdopt: compare.outcome === 'offer',
+    lines: diffJobLines(was.lines ?? [], obligation.lines ?? []),
+    contact: (was.contactId ?? null) === (obligation.contactId ?? null) ? null : { was: was.contactId ?? null, now: obligation.contactId ?? null },
+    total: { was: was.totalCents ?? null, now: obligation.totalCents },
+  };
+}
+
 // Records that a job the ledger knows is no longer billable in the work
 // system: deleted there, or its status moved back (for example from Shipped
 // to In production). Flow writes nothing to another system:

package/server/core/tracing.js

@@ -0,0 +1,64 @@
+import { routePattern } from '../ui/monitoring.js';
+
+// Performance traces for the installation's own tracing service
+// (docs/SENTRY.md, "Traces"). The first integration that is on and offers the
+// `traceSpan` and `traceRequest` capabilities gets them. With none on, each
+// function here runs the work as it is and adds nothing.
+//
+// `tracers()` answers the adapters to trace with; it is read at each call,
+// so an integration turned on or off later is followed.
+export function createTracing({ tracers = () => [] } = {}) {
+  const first = () => tracers()[0]?.capabilities ?? null;
+  return {
+    // Runs `work` inside a span named `name`, of kind `op`.
+    span(name, op, work, attributes = {}) {
+      const tracer = first();
+      return tracer ? tracer.traceSpan({ name, op, attributes }, work) : work();
+    },
+    // Express middleware: names each request's trace by its route pattern
+    // ("GET /api/invoicing/invoices/:id"), never by its URL, so the same
+    // click on another invoice is the same name.
+    requests() {
+      return (req, res, next) => {
+        const rename = first()?.traceRequest() ?? null;
+        if (rename) res.once('finish', () => rename(requestName(req)));
+        next();
+      };
+    },
+  };
+}
+
+// The route Express matched, else the path with its ids as ":id".
+export function requestName(req) {
+  const route = typeof req.route?.path === 'string' ? `${req.baseUrl ?? ''}${req.route.path}` : null;
+  return `${req.method} ${route ?? routePattern(req.originalUrl ?? req.url)}`;
+}
+
+// A span for each database query the pool runs. The span's name is the SQL
+// with its values left out: Flow passes values as parameters, and any quoted
+// text or number in the SQL itself becomes "?".
+export function traceQueries(pool, tracing) {
+  const wrap = (target) => {
+    const query = target.query.bind(target);
+    target.query = (...args) => {
+      // Callback calls are pg's own (the pool's query runs through a
+      // client's): the promise call around them already has its span.
+      if (typeof args.at(-1) === 'function') return query(...args);
+      return tracing.span(sqlName(args[0]), 'db', () => query(...args), { 'db.system': 'postgresql', 'db.system.name': 'postgresql' });
+    };
+  };
+  wrap(pool);
+  // A client a transaction holds (pool.connect()) queries directly.
+  pool.on('connect', wrap);
+  return pool;
+}
+
+export function sqlName(statement) {
+  const text = typeof statement === 'string' ? statement : String(statement?.text ?? '');
+  return text
+    .replace(/'(?:[^']|'')*'/g, '?')
+    .replace(/(?<![\w$])\d+(\.\d+)?\b/g, '?')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 300) || 'query';
+}

package/server/db/migrations/0018_custom_fields.sql

@@ -0,0 +1,78 @@
+CREATE TABLE IF NOT EXISTS "job_field_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"field_id" uuid NOT NULL,
+	"source_system" text NOT NULL,
+	"source_job_ref" text NOT NULL,
+	"from_value" jsonb,
+	"to_value" jsonb,
+	"actor" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "job_field_values" (
+	"organisation_id" uuid NOT NULL,
+	"field_id" uuid NOT NULL,
+	"source_system" text NOT NULL,
+	"source_job_ref" text NOT NULL,
+	"value" jsonb NOT NULL,
+	"updated_by" uuid,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "job_field_values_organisation_id_field_id_source_system_source_job_ref_pk" PRIMARY KEY("organisation_id","field_id","source_system","source_job_ref")
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "job_fields" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"type" text NOT NULL,
+	"options" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"position" integer NOT NULL,
+	"archived_at" timestamp with time zone,
+	"created_by" uuid,
+	"updated_by" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "job_fields_org_id" UNIQUE("organisation_id","id"),
+	CONSTRAINT "job_fields_type_valid" CHECK ("job_fields"."type" in ('dropdown', 'person', 'checkbox', 'date', 'number', 'text')),
+	CONSTRAINT "job_fields_name_valid" CHECK (length("job_fields"."name") between 1 and 60)
+);
+--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "job_field_events" ADD CONSTRAINT "job_field_events_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."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
+DO $flow_guard$ BEGIN
+	ALTER TABLE "job_field_events" ADD CONSTRAINT "job_field_events_actor_people_id_fk" FOREIGN KEY ("actor") REFERENCES "public"."people"("id") ON DELETE set null 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 "job_field_events" ADD CONSTRAINT "job_field_events_field_same_org" FOREIGN KEY ("organisation_id","field_id") REFERENCES "public"."job_fields"("organisation_id","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 "job_field_values" ADD CONSTRAINT "job_field_values_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."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
+DO $flow_guard$ BEGIN
+	ALTER TABLE "job_field_values" ADD CONSTRAINT "job_field_values_updated_by_people_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."people"("id") ON DELETE set null 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 "job_field_values" ADD CONSTRAINT "job_field_values_field_same_org" FOREIGN KEY ("organisation_id","field_id") REFERENCES "public"."job_fields"("organisation_id","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 "job_fields" ADD CONSTRAINT "job_fields_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."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
+DO $flow_guard$ BEGIN
+	ALTER TABLE "job_fields" ADD CONSTRAINT "job_fields_created_by_people_id_fk" FOREIGN KEY ("created_by") REFERENCES "public"."people"("id") ON DELETE set null 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 "job_fields" ADD CONSTRAINT "job_fields_updated_by_people_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."people"("id") ON DELETE set null 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 "job_field_events_job" ON "job_field_events" USING btree ("organisation_id","source_system","source_job_ref","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "job_field_values_job" ON "job_field_values" USING btree ("organisation_id","source_system","source_job_ref");

package/server/db/migrations/0019_people_views.sql

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