@arcforgelabs/flow 2026.10.33 → 2026.10.34

package/README.md

@@ -31,6 +31,9 @@ run a lab.
 | `CHANGELOG.md` | What changed in each release: an index of one file per release in `CHANGELOG/` |
 | `SECURITY.md` | How to report a security problem, the trust model, and the rules held hard |
 | `LICENSE` | MIT licence |
+| `docs/docs.json` | The docs site navigation. `docs/` is published at https://arcforgelabs.github.io/docs/flow/ by arcforgelabs/docs |
+| `docs/index.md` | The docs site home page |
+| `docs/releases/` | One release notes page per version (`<version>.md`), shown on the docs site |
 | `docs/DESIGN.md` | The design systems (theme families), how pages and Clerk's components take them, and the screens |
 | `docs/DATA_MODEL.md` | The PostgreSQL records, the rules the database holds, and how to change the schema |
 | `docs/DATA_SPINE.md` | The design of the tables and jobs every integration shares: mirror, identity map, job queue, outbox, review queue |
@@ -42,7 +45,10 @@ run a lab.
 | `docs/ALERTS.md` | Quiet alerts: the slim line on a page when something there needs a person, and how a person dismisses it |
 | `docs/AUTOMATIONS.md` | Automations: Flow routines that mark jobs ready to invoice and draft them, each on or off |
 | `docs/LINE_MAPPING.md` | Line mapping: how each work system line finds its price item, and Price codes in Settings |
+| `docs/CUSTOM_FIELDS.md` | Custom fields: the lab's own fields for its jobs, kept in Flow only, and how a board move checks for conflicts |
+| `docs/JOB_BOARD_MOVES.md` | Moving jobs on the Jobs board: custom field moves stay in Flow; Seazona stage moves become a hand-off |
 | `docs/PRICE_LIST.md` | The price list: Flow's own codes and prices, their links to Xero items and Seazona products, and the price check |
+| `docs/LOW_RISK_MERGE.md` | The low-risk merge lane: which pull requests merge themselves when green, with ClawSweeper's risk labels |
 | `docs/RELEASING.md` | Versions and channels, the release workflows, how to cut and roll back a release, and the one-time setup |
 | `docs/SELF_HOSTING.md` | Running a Flow release with Docker, Node or Replit, the update notice, and Clerk sign-in |
 | `docs/REPLIT.md` | A Replit workspace of this repository that follows a release channel (`FLOW_DEPLOY_REF`) |

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.33",
+  "version": "2026.10.34",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.33",
+      "version": "2026.10.34",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.23.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.33",
+  "version": "2026.10.34",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/api/custom-fields.js

@@ -0,0 +1,114 @@
+import express from 'express';
+import {
+  CUSTOM_FIELD_TYPES, GROUPABLE_TYPES, OPTION_COLORS, archiveField, createField, jobFieldHistory, listFields,
+  listJobFieldValues, orderFields, setJobFieldValue, updateField,
+} from '../core/custom-fields.js';
+import { FlowError } from '../core/errors.js';
+import { resolveOrganisation } from './invoicing.js';
+
+// Custom fields for jobs (server/core/custom-fields.js, docs/CUSTOM_FIELDS.md).
+//
+//   GET  /api/custom-fields[?archived=1]          the lab's fields, and the work systems' own fields (read only)
+//   POST /api/custom-fields { name, type[, options] }        owner or admin: make a field
+//   PUT  /api/custom-fields/order { ids }                   owner or admin: the field order
+//   PUT  /api/custom-fields/:id { name?, options? }         owner or admin: rename, change options
+//   POST /api/custom-fields/:id/archive { archived }        owner or admin: archive or bring back
+//   GET  /api/custom-fields/values                          every job's values
+//   PUT  /api/custom-fields/values { sourceSystem, sourceJobRef, fieldId, value[, expectedUpdatedAt] }
+//        set one job's value; a stale expectedUpdatedAt gives 409 with the current value
+//   GET  /api/custom-fields/history?sourceSystem=&sourceJobRef=   one job's changes, newest first
+//
+// Every route also takes `organisationId` (query or body) when the
+// installation has more than one organisation. A value lives only in Flow:
+// no route here writes to an integration.
+//
+// `work()` is the work system adapters that offer listWork; their job
+// statuses show as a read-only Stage field.
+const ERROR_STATUS = { not_found: 404, conflict: 409, organisation_required: 409 };
+
+export function createCustomFieldsRouter({ db, personAuth, work = () => [], log = console }) {
+  const router = express.Router();
+  router.use(express.json({ limit: '32kb' }));
+  const signedIn = [personAuth.requireSession];
+  const manager = [...signedIn, personAuth.requireRole('owner', 'admin')];
+
+  const handle = (fn) => async (req, res) => {
+    try {
+      res.set('Cache-Control', 'no-store');
+      await fn(req, res);
+    } catch (error) {
+      if (!(error instanceof FlowError)) {
+        log.error?.(`[custom-fields] ${error.message}`);
+        return res.status(500).json({ ok: false, code: 'internal', error: 'Something went wrong.' });
+      }
+      const body = { ok: false, code: error.code, error: error.message };
+      if (error.details !== undefined) body.details = error.details;
+      return res.status(ERROR_STATUS[error.code] ?? 400).json(body);
+    }
+  };
+  const organisationOf = (req) => resolveOrganisation(db, req.body?.organisationId ?? req.query.organisationId);
+
+  // The work systems' own fields: their job statuses, as the Stage lanes on
+  // the Jobs board. Read from Flow's copy; a work system that fails to answer
+  // is left out, not an error.
+  async function systemFields() {
+    const fields = [];
+    for (const adapter of work()) {
+      try {
+        const { statuses = [] } = await adapter.capabilities.listWork();
+        fields.push({
+          id: `${adapter.id}:stage`, source: adapter.id, sourceLabel: adapter.name ?? adapter.id, name: 'Stage',
+          type: 'dropdown', readOnly: true, options: statuses.map((s) => ({ id: s.label, name: s.label, final: Boolean(s.final) })),
+        });
+      } catch (error) {
+        log.warn?.(`[custom-fields] ${adapter.id} stages: ${error.message}`);
+      }
+    }
+    return fields;
+  }
+
+  router.get('/', ...signedIn, handle(async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const archived = req.query.archived === '1' || req.query.archived === 'true';
+    const [fields, system] = await Promise.all([listFields(db, organisationId, { archived }), systemFields()]);
+    res.json({ ok: true, fields, systemFields: system, types: CUSTOM_FIELD_TYPES, groupable: GROUPABLE_TYPES, colors: OPTION_COLORS });
+  }));
+
+  router.post('/', ...manager, handle(async (req, res) => {
+    const field = await createField(db, await organisationOf(req), req.body, { personId: req.person.id });
+    res.status(201).json({ ok: true, field });
+  }));
+
+  router.put('/order', ...manager, handle(async (req, res) => {
+    const fields = await orderFields(db, await organisationOf(req), req.body?.ids, { personId: req.person.id });
+    res.json({ ok: true, fields });
+  }));
+
+  router.get('/values', ...signedIn, handle(async (req, res) => {
+    res.json({ ok: true, values: await listJobFieldValues(db, await organisationOf(req)) });
+  }));
+
+  router.put('/values', ...signedIn, handle(async (req, res) => {
+    const value = await setJobFieldValue(db, await organisationOf(req), req.body, { personId: req.person.id });
+    res.json({ ok: true, value });
+  }));
+
+  router.get('/history', ...signedIn, handle(async (req, res) => {
+    const history = await jobFieldHistory(db, await organisationOf(req), req.query);
+    res.json({ ok: true, history });
+  }));
+
+  router.put('/:id', ...manager, handle(async (req, res) => {
+    const field = await updateField(db, await organisationOf(req), req.params.id, req.body, { personId: req.person.id });
+    res.json({ ok: true, field });
+  }));
+
+  router.post('/:id/archive', ...manager, handle(async (req, res) => {
+    const archived = req.body?.archived ?? true;
+    if (typeof archived !== 'boolean') throw new FlowError('invalid', 'archived must be true or false');
+    const field = await archiveField(db, await organisationOf(req), req.params.id, { archived, personId: req.person.id });
+    res.json({ ok: true, field });
+  }));
+
+  return router;
+}

package/server/api/invoicing.js

@@ -277,7 +277,8 @@ export function createInvoicingRouter({
     const rows = await db.select({
       id: organisations.id, name: organisations.name, invoicePrefix: organisations.invoicePrefix, nextInvoiceNumber: organisations.nextInvoiceNumber,
     }).from(organisations).orderBy(asc(organisations.name));
-    res.json({ ok: true, organisations: rows, canIssue: ['owner', 'admin'].includes(req.person.role) });
+    // sendsTo: the accounting system a sent invoice goes to, or null.
+    res.json({ ok: true, organisations: rows, canIssue: ['owner', 'admin'].includes(req.person.role), sendsTo: accounting()?.name ?? null });
   }));
 
   router.get('/invoices', ...signedIn, handle(log, async (req, res) => {

package/server/api/work-moves.js

@@ -0,0 +1,80 @@
+import express from 'express';
+import { FlowError } from '../core/errors.js';
+
+// Jobs board moves that belong to the work system (docs/JOB_BOARD_MOVES.md).
+//
+//   POST /api/work/moves { sourceSystem, sourceJobRef, toStatus }
+//        a person moved a job to another stage: the work system answers what
+//        happens. Seazona's API cannot change a stage, so it answers a
+//        hand-off: what to do in Seazona, and how long Flow waits.
+//   POST /api/work/moves/cancel { sourceSystem, sourceJobRef }   take back a waiting move
+//   GET  /api/work/my-settings[?integration=]                    this person's own integration choices
+//   PUT  /api/work/my-settings { integration, key, value }        change one
+//
+// A move of a Flow custom field never comes here: that is
+// PUT /api/custom-fields/values, and it stays in Flow.
+//
+// `adapters(capability)` is the enabled, ready adapters that offer it.
+const ERROR_STATUS = { not_found: 404, conflict: 409, not_supported: 409 };
+const SYSTEM = /^[a-z][a-z0-9-]{1,31}$/;
+
+export function createWorkMovesRouter({ adapters = () => [], personAuth, log = console }) {
+  const router = express.Router();
+  router.use(express.json({ limit: '8kb' }));
+  const signedIn = [personAuth.requireSession];
+
+  const handle = (fn) => async (req, res) => {
+    try {
+      res.set('Cache-Control', 'no-store');
+      await fn(req, res);
+    } catch (error) {
+      if (!(error instanceof FlowError)) {
+        log.error?.(`[work-moves] ${error.message}`);
+        return res.status(500).json({ ok: false, code: 'internal', error: 'Something went wrong.' });
+      }
+      return res.status(ERROR_STATUS[error.code] ?? 400).json({ ok: false, code: error.code, error: error.message });
+    }
+  };
+
+  // The enabled adapter `id` that offers `capability`.
+  const adapterFor = (id, capability) => {
+    if (typeof id !== 'string' || !SYSTEM.test(id)) throw new FlowError('invalid', 'name an integration');
+    const adapter = adapters(capability).find((a) => a.id === id) ?? null;
+    if (!adapter) throw new FlowError('not_supported', 'that integration is not on, or cannot do that');
+    return adapter;
+  };
+  const jobRef = (raw) => {
+    const ref = typeof raw === 'string' ? raw.trim() : '';
+    if (!ref || ref.length > 200) throw new FlowError('invalid', 'sourceJobRef is required');
+    return ref;
+  };
+
+  router.post('/moves', ...signedIn, handle(async (req, res) => {
+    const adapter = adapterFor(req.body?.sourceSystem, 'moveWork');
+    const move = await adapter.capabilities.moveWork({ sourceJobRef: jobRef(req.body?.sourceJobRef), toStatus: req.body?.toStatus, personId: req.person.id });
+    res.json({ ok: true, move });
+  }));
+
+  router.post('/moves/cancel', ...signedIn, handle(async (req, res) => {
+    const adapter = adapterFor(req.body?.sourceSystem, 'cancelMove');
+    res.json({ ok: true, ...(await adapter.capabilities.cancelMove({ sourceJobRef: jobRef(req.body?.sourceJobRef) })) });
+  }));
+
+  router.get('/my-settings', ...signedIn, handle(async (req, res) => {
+    const wanted = typeof req.query.integration === 'string' ? req.query.integration : null;
+    const out = [];
+    for (const adapter of adapters('personSettings')) {
+      if (wanted && adapter.id !== wanted) continue;
+      out.push({ integration: adapter.id, name: adapter.name, settings: await adapter.capabilities.personSettings({ personId: req.person.id }) });
+    }
+    res.json({ ok: true, integrations: out });
+  }));
+
+  router.put('/my-settings', ...signedIn, handle(async (req, res) => {
+    const adapter = adapterFor(req.body?.integration, 'setPersonSetting');
+    const settings = await adapter.capabilities.setPersonSetting({ personId: req.person.id, key: req.body?.key, value: req.body?.value });
+    res.json({ ok: true, integration: adapter.id, settings });
+  }));
+
+  return router;
+}

package/server/app.js

@@ -1,5 +1,7 @@
 import express from 'express';
 import { createAlertsRouter } from './api/alerts.js';
+import { createCustomFieldsRouter } from './api/custom-fields.js';
+import { createWorkMovesRouter } from './api/work-moves.js';
 import { createConnectorApi } from './api/connector.js';
 import { createInvoicingRouter } from './api/invoicing.js';
 import { createSignInRouter } from './auth/routes.js';
@@ -35,6 +37,8 @@ import { createUiAssetsRouter } from './ui/routes.js';
 // the migration journals this build ships (server/db/doctor.js): GET /health
 // reports how many of each the database has applied, so the workspace's
 // doctor can tell what Replit's publish step will offer (docs/REPLIT.md).
+// `tracing` (server/core/tracing.js) names each request's performance trace
+// by its route, while a tracing service is on.
 export function createApp({
   build = deployedBuildStatus(),
   database = null,
@@ -49,10 +53,12 @@ export function createApp({
   clerkProxyRateLimitPerMinute = 300,
   defaultFamily = DEFAULT_FAMILY,
   log = console,
+  tracing = null,
 } = {}) {
   const app = express();
   app.disable('x-powered-by');
   app.set('trust proxy', trustProxy);
+  if (tracing) app.use(tracing.requests());
 
   app.get('/health', async (_req, res) => {
     let databaseOk = null;
@@ -136,6 +142,12 @@ export function createApp({
     // items, Seazona products).
     const priceSystems = () => integrations?.with('listPriceItems') ?? [];
     app.use('/api/invoicing', createInvoicingRouter({ db: database.db, personAuth: auth.personAuth, log, liveCheckFor, accounting, work, priceSystems }));
+    // Custom fields for jobs (server/core/custom-fields.js): kept in Flow
+    // only; the work systems' statuses show beside them, read only.
+    app.use('/api/custom-fields', createCustomFieldsRouter({ db: database.db, personAuth: auth.personAuth, work, log }));
+    // Stage moves the work system must make, and each person's own
+    // integration choices (server/api/work-moves.js).
+    app.use('/api/work', createWorkMovesRouter({ adapters: (capability) => integrations?.with(capability) ?? [], personAuth: auth.personAuth, log }));
     // Quiet alerts (server/core/alerts.js): what needs a person on each page.
     // Integrations add their own through the `alerts` capability.
     app.use('/api/alerts', createAlertsRouter({

package/server/core/custom-fields.js

@@ -0,0 +1,300 @@
+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);
+}
+
+// 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,8 @@ 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,
         obligation: o,
       });
     }