@arcforgelabs/flow 2026.10.21 → 2026.10.23

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

@@ -36,6 +36,27 @@
       "when": 1792329649575,
       "tag": "0004_ledger_events_append_only",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1792388648997,
+      "tag": "0005_data_spine",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1792390491235,
+      "tag": "0006_prior_links",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1792391146736,
+      "tag": "0007_integration_settings",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -1,19 +1,23 @@
 import { sql } from 'drizzle-orm';
 import {
+  bigint,
   boolean,
   check,
   date,
   foreignKey,
+  index,
   integer,
   jsonb,
   pgTable,
   text,
   timestamp,
   unique,
+  uniqueIndex,
   uuid,
 } from 'drizzle-orm/pg-core';
 
-// Every table except `organisations` carries `organisation_id`. Child rows
+// Every table except `organisations` and the installation-wide tables (people,
+// integration settings) carries `organisation_id`. Child rows
 // point at their parent through (organisation_id, id), so the database itself
 // refuses a row that joins two organisations. Money is integer cents.
 
@@ -304,3 +308,185 @@ export const obligationWritebacks = pgTable('obligation_writebacks', {
   }),
   check('obligation_writebacks_state_valid', inList('state', WRITEBACK_STATES)),
 ]);
+
+// The data spine (docs/DATA_SPINE.md, issue 56): the tables every integration
+// shares. Each row changes state; the spine never deletes one.
+
+// Identity map (issue 57). Which external record is each Flow record. At most
+// one active link per external record and per Flow record, in each system. A
+// link that is not exact stays `proposed` until a person confirms it.
+export const LINK_ENTITIES = ['contact', 'price_item', 'obligation', 'invoice', 'payment', 'credit_note'];
+export const LINK_MATCHES = ['created_by_flow', 'exact_id', 'imported', 'name', 'person'];
+export const LINK_STATES = ['active', 'proposed', 'superseded'];
+
+export const externalLinks = pgTable('external_links', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  entity: text('entity').notNull(),
+  flowId: uuid('flow_id').notNull(),
+  system: text('system').notNull(),
+  externalId: text('external_id').notNull(),
+  matchedBy: text('matched_by').notNull(),
+  state: text('state').notNull(),
+  confirmedBy: uuid('confirmed_by').references(() => people.id, { onDelete: 'set null' }),
+  confirmedAt: timestamp('confirmed_at', { withTimezone: true }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('external_links_org_id').on(t.organisationId, t.id),
+  uniqueIndex('external_links_active_external')
+    .on(t.organisationId, t.system, t.entity, t.externalId).where(sql`state = 'active'`),
+  uniqueIndex('external_links_active_flow')
+    .on(t.organisationId, t.system, t.entity, t.flowId).where(sql`state = 'active'`),
+  index('external_links_flow').on(t.organisationId, t.entity, t.flowId),
+  check('external_links_entity_valid', inList('entity', LINK_ENTITIES)),
+  check('external_links_matched_by_valid', inList('matched_by', LINK_MATCHES)),
+  check('external_links_state_valid', inList('state', LINK_STATES)),
+  check('external_links_name_needs_person', sql`${t.matchedBy} <> 'name' or ${t.state} <> 'active' or ${t.confirmedAt} is not null`),
+]);
+
+// Links between a work system's job and an accounting record, carried over
+// from an earlier installation (server/import/at-start.js). They wait here
+// until the job becomes an obligation; then they are evidence for its link.
+// `person` means a person made the link there; `imported` means the earlier
+// app matched it by itself.
+export const PRIOR_LINK_MATCHES = ['person', 'imported'];
+
+export const priorLinks = pgTable('prior_links', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  sourceSystem: text('source_system').notNull(),
+  sourceJobRef: text('source_job_ref').notNull(),
+  system: text('system').notNull(),
+  externalId: text('external_id').notNull(),
+  externalNumber: text('external_number'),
+  matchedBy: text('matched_by').notNull(),
+  matchedAt: timestamp('matched_at', { withTimezone: true }),
+  origin: text('origin').notNull(),
+  createdAt: createdAt(),
+}, (t) => [
+  uniqueIndex('prior_links_job').on(t.organisationId, t.sourceSystem, t.sourceJobRef, t.system),
+  index('prior_links_external').on(t.organisationId, t.system, t.externalId),
+  check('prior_links_matched_by_valid', inList('matched_by', PRIOR_LINK_MATCHES)),
+]);
+
+// Background job queue (issue 6). Workers claim with FOR UPDATE SKIP LOCKED and
+// hold a lease; a lease that runs out makes the job claimable again. One queued
+// or running job per (organisation, kind, dedupe key).
+export const BACKGROUND_JOB_STATES = ['queued', 'running', 'succeeded', 'failed', 'dead'];
+
+export const backgroundJobs = pgTable('background_jobs', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  kind: text('kind').notNull(),
+  dedupeKey: text('dedupe_key').notNull().default(''),
+  payload: jsonb('payload').notNull().default(sql`'{}'::jsonb`),
+  state: text('state').notNull().default('queued'),
+  runAfter: timestamp('run_after', { withTimezone: true }).notNull().defaultNow(),
+  attempts: integer('attempts').notNull().default(0),
+  maxAttempts: integer('max_attempts').notNull().default(8),
+  lockedBy: text('locked_by'),
+  lockedUntil: timestamp('locked_until', { withTimezone: true }),
+  result: jsonb('result'),
+  lastError: text('last_error'),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  uniqueIndex('background_jobs_one_open')
+    .on(t.organisationId, t.kind, t.dedupeKey).where(sql`state in ('queued', 'running')`),
+  index('background_jobs_due').on(t.state, t.runAfter),
+  check('background_jobs_state_valid', inList('state', BACKGROUND_JOB_STATES)),
+  check('background_jobs_attempts_valid', sql`${t.attempts} >= 0 and ${t.maxAttempts} > 0`),
+]);
+
+// Outbox. Every write to another system is a row here before the call
+// leaves, written in the same transaction as the Flow change it reports. The
+// idempotency key is unique, so a retry never makes a second record.
+export const OUTBOX_STATES = ['pending', 'sending', 'ambiguous', 'sent', 'failed', 'cancelled'];
+
+export const outbox = pgTable('outbox', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  system: text('system').notNull(),
+  action: text('action').notNull(),
+  entity: text('entity').notNull(),
+  flowId: uuid('flow_id').notNull(),
+  idempotencyKey: text('idempotency_key').notNull(),
+  request: jsonb('request').notNull(),
+  state: text('state').notNull().default('pending'),
+  externalId: text('external_id'),
+  attempts: integer('attempts').notNull().default(0),
+  lastError: text('last_error'),
+  createdBy: text('created_by').notNull(),
+  sentAt: timestamp('sent_at', { withTimezone: true }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('outbox_org_id').on(t.organisationId, t.id),
+  unique('outbox_idempotency_key').on(t.idempotencyKey),
+  index('outbox_pending').on(t.system, t.state, t.createdAt),
+  check('outbox_state_valid', inList('state', OUTBOX_STATES)),
+  check('outbox_sent_has_id', sql`${t.state} <> 'sent' or ${t.externalId} is not null`),
+]);
+
+// Review queue (issue 59). One list of everything a person must decide. One
+// open item per (organisation, kind, entity, Flow id); a repeat finding
+// updates its evidence.
+export const REVIEW_STATES = ['open', 'resolved', 'dismissed'];
+
+export const reviewItems = pgTable('review_items', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  kind: text('kind').notNull(),
+  entity: text('entity').notNull(),
+  flowId: uuid('flow_id').notNull(),
+  systems: text('systems').array().notNull().default(sql`'{}'::text[]`),
+  evidence: jsonb('evidence').notNull().default(sql`'{}'::jsonb`),
+  moneyAtRiskCents: bigint('money_at_risk_cents', { mode: 'number' }).notNull().default(0),
+  state: text('state').notNull().default('open'),
+  seenCount: integer('seen_count').notNull().default(1),
+  resolution: text('resolution'),
+  note: text('note'),
+  resolvedBy: text('resolved_by'),
+  resolvedAt: timestamp('resolved_at', { withTimezone: true }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('review_items_org_id').on(t.organisationId, t.id),
+  uniqueIndex('review_items_one_open')
+    .on(t.organisationId, t.kind, t.entity, t.flowId).where(sql`state = 'open'`),
+  index('review_items_queue').on(t.organisationId, t.state, t.moneyAtRiskCents),
+  check('review_items_state_valid', inList('state', REVIEW_STATES)),
+  check('review_items_money_not_negative', sql`${t.moneyAtRiskCents} >= 0`),
+  check('review_items_closed_has_resolution', sql`${t.state} = 'open' or (${t.resolution} is not null and ${t.resolvedBy} is not null and ${t.resolvedAt} is not null)`),
+]);
+
+// Integration settings an owner enters in Settings (server/integrations/setup.js).
+// One row per adapter for the installation. `config` holds plain settings by
+// their environment name; `secrets` holds credentials sealed with Flow's
+// secrets key (server/core/secrets.js), never in clear. A host's own
+// environment setting wins over a value here.
+export const integrationSettings = pgTable('integration_settings', {
+  adapterId: text('adapter_id').primaryKey(),
+  enabled: boolean('enabled').notNull().default(false),
+  config: jsonb('config').notNull().default(sql`'{}'::jsonb`),
+  secrets: jsonb('secrets').notNull().default(sql`'{}'::jsonb`),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+});
+
+// Who changed which integration setting, and when. Names only, never a value.
+export const INTEGRATION_SETTING_EVENTS = ['turned_on', 'turned_off', 'setting_changed', 'secret_set', 'secret_removed'];
+
+export const integrationSettingEvents = pgTable('integration_setting_events', {
+  id: id(),
+  adapterId: text('adapter_id').notNull(),
+  kind: text('kind').notNull(),
+  settings: text('settings').array().notNull().default(sql`'{}'::text[]`),
+  actor: uuid('actor').references(() => people.id, { onDelete: 'set null' }),
+  createdAt: createdAt(),
+}, (t) => [
+  index('integration_setting_events_adapter').on(t.adapterId, t.createdAt),
+  check('integration_setting_events_kind_valid', inList('kind', INTEGRATION_SETTING_EVENTS)),
+]);

package/server/import/at-start.js

@@ -1,5 +1,5 @@
 import { sql } from 'drizzle-orm';
-import { organisations } from '../db/schema.js';
+import { organisations, priorLinks } from '../db/schema.js';
 import { applyImport, planImport, readEarlierFlow, summarisePlan } from './earlier-flow.js';
 
 // The import from the earlier codebase, run once by the server itself. On a
@@ -50,3 +50,71 @@ export async function importEarlierAtStart({ db, pool, settings, log = console }
   log.info?.(`[import] imported: ${JSON.stringify(result.counts)}`);
   return result.counts;
 }
+
+// The earlier app's table of jobs bound to accounting invoices. Each row ties a
+// Seazona order to the Xero invoice that already bills it.
+const EARLIER_LINKS = 'seazona_order_xero_match_overrides';
+const LINK_ORIGIN = `earlier:${EARLIER_LINKS}`;
+const LINK_BATCH = 500;
+
+function matchedAt(text) {
+  const at = text ? new Date(text) : null;
+  return at && !Number.isNaN(at.getTime()) ? at : null;
+}
+
+// Carries the earlier app's order -> invoice links into `prior_links`, at
+// every start while the import settings are set. It reads in a read-only
+// transaction and only adds links it does not hold, so a repeat costs one read
+// and changes nothing. It copies ids and how each link was made; never the
+// earlier notes or who made it, which can name people. Answers counts, or null
+// when there is nothing to read.
+export async function importEarlierLinksAtStart({ db, pool, settings, log = console }) {
+  if (!settings) return null;
+  // The lab the import made, by name; or the only organisation, if renamed since.
+  const { rows: labs } = await db.execute(sql`select id, name from ${organisations}`);
+  const organisation = labs.find((lab) => lab.name === settings.organisationName) ?? (labs.length === 1 ? labs[0] : null);
+  if (!organisation) return null;
+
+  let rows;
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN TRANSACTION READ ONLY');
+    await client.query(`SET LOCAL search_path TO "${settings.schema}"`);
+    const { rows: [found] } = await client.query('select to_regclass($1) is not null as present', [EARLIER_LINKS]);
+    if (found.present) {
+      ({ rows } = await client.query(`select seazona_order_id, xero_invoice_id, xero_invoice_number, match_source, matched_at
+        from ${EARLIER_LINKS} where coalesce(xero_invoice_id, '') <> '' and coalesce(seazona_order_id, '') <> ''`));
+    }
+    await client.query('COMMIT');
+  } catch (error) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw new Error(`could not read links from schema "${settings.schema}": ${error.message}`);
+  } finally {
+    client.release();
+  }
+  if (!rows) {
+    log.info?.(`[import] links: schema "${settings.schema}" has no ${EARLIER_LINKS}`);
+    return null;
+  }
+
+  const values = rows.map((row) => ({
+    organisationId: organisation.id,
+    sourceSystem: 'seazona',
+    sourceJobRef: String(row.seazona_order_id).trim(),
+    system: 'xero',
+    externalId: String(row.xero_invoice_id).trim(),
+    externalNumber: row.xero_invoice_number?.trim() || null,
+    matchedBy: row.match_source === 'operator_link' ? 'person' : 'imported',
+    matchedAt: matchedAt(row.matched_at),
+    origin: LINK_ORIGIN,
+  }));
+  let added = 0;
+  for (let start = 0; start < values.length; start += LINK_BATCH) {
+    const written = await db.insert(priorLinks).values(values.slice(start, start + LINK_BATCH))
+      .onConflictDoNothing().returning({ id: priorLinks.id });
+    added += written.length;
+  }
+  const counts = { read: values.length, added };
+  log.info?.(`[import] links from schema "${settings.schema}": ${JSON.stringify(counts)}`);
+  return counts;
+}

package/server/index.js

@@ -5,8 +5,11 @@ import { seedFirstOwner } from './auth/people.js';
 import { createPersonAuth } from './auth/session.js';
 import { resolveSignInSettings } from './auth/settings.js';
 import { migrateDatabase, openDatabase } from './db/index.js';
-import { importEarlierAtStart, resolveImportAtStart } from './import/at-start.js';
-import { createIntegrations } from './integrations/index.js';
+import { importEarlierAtStart, importEarlierLinksAtStart, resolveImportAtStart } from './import/at-start.js';
+import { resolveSecretsKey } from './core/secrets.js';
+import { adapters as shippedAdapters } from './integrations/adapters.js';
+import { createIntegrations, resolveEnabledIntegrations } from './integrations/index.js';
+import { readStoredSettings, settingsEnvironment, storedEnabled } from './integrations/setup.js';
 import { resolveDefaultFamily } from './theme/themes.js';
 import { createUpdateChecker, UPDATE_CHECK_INTERVAL_MS } from './update-check.js';
 
@@ -27,9 +30,10 @@ try {
   console.error(`[ui] ${error.message}`);
   process.exit(1);
 }
-let integrations;
+let secrets;
 try {
-  integrations = createIntegrations();
+  resolveEnabledIntegrations();
+  secrets = resolveSecretsKey();
 } catch (error) {
   console.error(`[integrations] ${error.message}`);
   process.exit(1);
@@ -55,9 +59,25 @@ try {
   console.error(`[import] ${error.message}`);
   process.exit(1);
 }
-await integrations.start(database.db);
-const integrationsOn = integrations.list().filter((a) => a.enabled).map((a) => a.id);
-console.log(`[integrations] on: ${integrationsOn.join(', ') || 'none'} (FLOW_INTEGRATIONS)`);
+// The earlier links are evidence to add, not records Flow needs to open, so a
+// failure is logged and the start goes on.
+await importEarlierLinksAtStart({ db: database.db, pool: database.pool, settings: importAtStart })
+  .catch((error) => console.error(`[import] ${error.message}`));
+// What an owner set in Settings, Integrations, with the host's own
+// environment over it (server/integrations/setup.js).
+let integrations;
+try {
+  const stored = await readStoredSettings(database.db);
+  const { env: settingsEnv, unreadable } = settingsEnvironment({ env: process.env, stored, adapters: shippedAdapters, secrets });
+  if (unreadable.length) console.warn(`[integrations] stored credentials Flow cannot read with this secrets key: ${unreadable.join(', ')}. An owner enters them again in Settings.`);
+  integrations = createIntegrations({ turnedOnInFlow: storedEnabled(stored, process.env), settingsEnv });
+  await integrations.start(database.db);
+} catch (error) {
+  console.error(`[integrations] ${error.message}`);
+  process.exit(1);
+}
+const integrationsOn = integrations.list().filter((a) => a.enabled).map((a) => `${a.id}${a.state === 'ready' ? '' : ` (${a.state})`}`);
+console.log(`[integrations] on: ${integrationsOn.join(', ') || 'none'}; secrets key ${secrets ? `from ${secrets.source}` : 'not set (FLOW_SECRETS_KEY)'}`);
 
 let auth = null;
 if (settings.mode === 'clerk') {
@@ -100,7 +120,7 @@ const trustProxy = process.env.REPL_ID || process.env.REPLIT_DEPLOYMENT ? 1 : fa
 
 const updates = createUpdateChecker();
 
-createApp({ database, auth, trustProxy, updates, integrations, defaultFamily }).listen(port, () => {
+createApp({ database, auth, trustProxy, updates, integrations, secrets, defaultFamily }).listen(port, () => {
   console.log(`[flow] listening on ${port}; design system ${defaultFamily} (FLOW_THEME)`);
 });
 

package/server/integrations/index.js

@@ -16,11 +16,17 @@ export function resolveEnabledIntegrations(env = process.env, adapters = shipped
 }
 
 // The registry for one Flow process: every shipped adapter registered, the
-// chosen ones enabled. Call registry.start(db) after the core migrations.
-export function createIntegrations({ env = process.env, adapters = shipped, log = console } = {}) {
+// chosen ones enabled. `turnedOnInFlow` are the ids an owner turned on in
+// Settings (server/integrations/setup.js): one of those that cannot start is
+// reported, not fatal. `settingsEnv` is what adapters read as their settings.
+// Call registry.start(db) after the core migrations.
+export function createIntegrations({ env = process.env, adapters = shipped, log = console, turnedOnInFlow = [], settingsEnv = env } = {}) {
   const enabled = resolveEnabledIntegrations(env, adapters);
-  const registry = createRegistry({ log });
+  const registry = createRegistry({ log, env: settingsEnv });
   for (const adapter of adapters) registry.register(adapter);
   for (const id of enabled) registry.enable(id);
+  for (const id of turnedOnInFlow) {
+    if (!enabled.includes(id) && registry.get(id)) registry.enable(id, { optional: true });
+  }
   return registry;
 }

package/server/integrations/port.js

@@ -53,6 +53,7 @@ export function turnedOff(adapter, reason = 'disabled') {
     disabled: `${adapter.name} is turned off on this installation.`,
     restart_needed: `${adapter.name} was turned on after Flow started. Restart Flow to finish turning it on.`,
     tables_missing: `${adapter.name} has no tables on this installation. Restart Flow to create them.`,
+    failed: `${adapter.name} could not start. An owner can check its settings in Settings, Integrations.`,
   }[reason];
   return { ok: false, code: 'integration_off', integration: adapter.id, reason, error };
 }
@@ -61,7 +62,7 @@ export function defineAdapter(adapter) {
   if (!adapter || typeof adapter !== 'object') {
     throw new TypeError('An adapter must be an object');
   }
-  const { id, name, bundled = false, capabilities, schema, start, stop, routes } = adapter;
+  const { id, name, bundled = false, capabilities, schema, start, stop, routes, setup } = adapter;
   if (typeof id !== 'string' || !ID_PATTERN.test(id)) {
     throw new TypeError(`Adapter id must match ${ID_PATTERN}`);
   }
@@ -90,6 +91,14 @@ export function defineAdapter(adapter) {
   if (routes !== undefined && typeof routes !== 'function') {
     throw new TypeError(`Adapter ${id} routes must be a function that returns a router`);
   }
+  if (setup !== undefined && (!setup || !Array.isArray(setup.fields))) {
+    throw new TypeError(`Adapter ${id} setup must list its fields`);
+  }
+  for (const field of setup?.fields ?? []) {
+    if (!/^[A-Z][A-Z0-9_]{1,63}$/.test(field?.name ?? '') || !field.label) {
+      throw new TypeError(`Adapter ${id} setup field ${field?.name} needs an upper-case setting name and a label`);
+    }
+  }
   return Object.freeze({
     id,
     name,
@@ -105,12 +114,24 @@ export function defineAdapter(adapter) {
     // Optional HTTP routes: routes({ db, personAuth, log, messagePage }) returns a router
     // mounted at /api/<id> (registry.routes).
     routes: routes ?? null,
+    // Optional: the settings an owner may enter in Settings, Integrations
+    // (server/integrations/setup.js). `fields` name environment settings;
+    // `derivedKeys` name key settings Flow derives from its secrets key.
+    setup: setup ? Object.freeze({ fields: Object.freeze(setup.fields.map((f) => Object.freeze({ ...f }))), derivedKeys: Object.freeze([...(setup.derivedKeys ?? [])]), guide: setup.guide ?? null }) : null,
   });
 }
 
-export function createRegistry({ log = console } = {}) {
+export function createRegistry({ log = console, env = process.env } = {}) {
   const adapters = new Map();
   const enabled = new Set();
+  // Adapters turned on in Settings, not by the host: one that cannot start
+  // is reported, and Flow starts without it.
+  const optional = new Set();
+  const failures = new Map(); // id -> message
+  const generation = new Map(); // id -> count of (re)starts, for its router
+  const routers = new Map(); // id -> { generation, router }
+  let settingsEnv = env;
+  let database = null;
   // Adapters whose tables this process created or found at start. An adapter
   // without a schema needs none, so it is ready as soon as it is enabled.
   const tablesReady = new Set();
@@ -119,6 +140,7 @@ export function createRegistry({ log = console } = {}) {
 
   const state = (adapter) => {
     if (!enabled.has(adapter.id)) return 'disabled';
+    if (failures.has(adapter.id)) return 'failed';
     if (!adapter.schema || tablesReady.has(adapter.id)) return 'ready';
     return started ? 'restart_needed' : 'not_started';
   };
@@ -133,9 +155,11 @@ export function createRegistry({ log = console } = {}) {
       adapters.set(defined.id, defined);
       return defined;
     },
-    enable(id) {
+    enable(id, { optional: isOptional = false } = {}) {
       if (!adapters.has(id)) throw new Error(`No adapter ${id}`);
       enabled.add(id);
+      if (isOptional) optional.add(id);
+      else optional.delete(id);
     },
     // Turning an adapter off never drops its tables. Removing them is a
     // separate step (removeAdapterTables in server/integrations/schema.js).
@@ -149,6 +173,7 @@ export function createRegistry({ log = console } = {}) {
     async start(db) {
       if (started) throw new Error('The integration registry has already started');
       started = true;
+      database = db;
       const migrated = [];
       for (const id of enabled) {
         const adapter = adapters.get(id);
@@ -160,11 +185,66 @@ export function createRegistry({ log = console } = {}) {
       for (const id of enabled) {
         const adapter = adapters.get(id);
         if (!adapter.start) continue;
-        await adapter.start({ db, log });
+        try {
+          await adapter.start({ db, log, env: settingsEnv });
+        } catch (error) {
+          if (!optional.has(id)) throw error;
+          failures.set(id, error.message);
+          log.error?.(`[integrations] ${id} could not start: ${error.message}`);
+          continue;
+        }
         running.push(adapter);
       }
       return migrated;
     },
+    // Applies new settings to one adapter while Flow runs: stops it, then,
+    // when it stays on, creates its tables and starts it with `env`. Its
+    // routes are built again on the next request. A start that fails leaves
+    // it `failed` with the reason, and the rest of Flow running.
+    async reconfigure(id, { enabled: on, env: next }) {
+      const adapter = adapters.get(id);
+      if (!adapter) throw new Error(`No adapter ${id}`);
+      if (!started) throw new Error('The integration registry has not started');
+      if (next) settingsEnv = next;
+      const index = running.indexOf(adapter);
+      if (index >= 0) {
+        running.splice(index, 1);
+        await adapter.stop?.();
+      }
+      failures.delete(id);
+      generation.set(id, (generation.get(id) ?? 0) + 1);
+      if (!on) {
+        enabled.delete(id);
+        return state(adapter);
+      }
+      enabled.add(id);
+      optional.add(id);
+      try {
+        if (adapter.schema && !tablesReady.has(id)) {
+          await migrateAdapterSchema(database, adapter);
+          tablesReady.add(id);
+        }
+        if (adapter.start) {
+          await adapter.start({ db: database, log, env: settingsEnv });
+          running.push(adapter);
+        }
+      } catch (error) {
+        failures.set(id, error.message);
+        log.error?.(`[integrations] ${id} could not start: ${error.message}`);
+      }
+      return state(adapter);
+    },
+    get(id) {
+      return adapters.get(id) ?? null;
+    },
+    // Why an enabled adapter is not running, or null. The message names
+    // settings, never their values.
+    failure(id) {
+      return failures.get(id) ?? null;
+    },
+    env() {
+      return settingsEnv;
+    },
     // Calls stop() on every adapter whose start() ran, newest first.
     async stop() {
       while (running.length) {
@@ -180,6 +260,7 @@ export function createRegistry({ log = console } = {}) {
         enabled: enabled.has(a.id),
         state: state(a),
         tables: a.schema ? [...a.schema.tables] : [],
+        ...(failures.has(a.id) ? { error: failures.get(a.id) } : {}),
         capabilities: Object.keys(a.capabilities),
       }));
     },
@@ -202,10 +283,21 @@ export function createRegistry({ log = console } = {}) {
     routes(context) {
       return [...adapters.values()].filter((a) => a.routes).map((adapter) => {
         const path = `/api/${adapter.id}`;
-        if (!ready(adapter)) {
-          return { path, handler: (_req, res) => res.status(503).json(turnedOff(adapter, state(adapter) === 'disabled' ? 'disabled' : 'restart_needed')) };
-        }
-        return { path, handler: adapter.routes(context) };
+        const handler = (req, res, next) => {
+          const now = state(adapter);
+          if (now !== 'ready') {
+            const reason = now === 'disabled' || now === 'failed' ? now : 'restart_needed';
+            return res.status(503).json(turnedOff(adapter, reason));
+          }
+          const current = generation.get(adapter.id) ?? 0;
+          let built = routers.get(adapter.id);
+          if (!built || built.generation !== current) {
+            built = { generation: current, router: adapter.routes(context) };
+            routers.set(adapter.id, built);
+          }
+          return built.router(req, res, next);
+        };
+        return { path, handler };
       });
     },
     // The one way to read or write an adapter's tables: runs fn(adapter) when
@@ -216,7 +308,7 @@ export function createRegistry({ log = console } = {}) {
       const adapter = adapters.get(id);
       if (!adapter) throw new Error(`No adapter ${id}`);
       const now = state(adapter);
-      if (now === 'disabled') return turnedOff(adapter, 'disabled');
+      if (now === 'disabled' || now === 'failed') return turnedOff(adapter, now);
       if (now !== 'ready') return turnedOff(adapter, 'restart_needed');
       try {
         return await fn(adapter);

package/server/integrations/seazona/index.js

@@ -22,7 +22,27 @@ export function requireSeazonaSettings(env = process.env) {
 
 // `env`, `fetchImpl`, `now` and `timers` are for tests. Otherwise start()
 // reads the environment, so a turned-off adapter never reads its settings.
-export function createSeazonaAdapter({ env = process.env, fetchImpl = null, now = Date.now, timers } = {}) {
+// What an owner enters in Settings, Integrations (server/integrations/setup.js).
+export const SEAZONA_SETUP = {
+  guide: {
+    title: 'Get a Seazona API client',
+    link: null,
+    steps: [
+      'In Seazona, create an API client for Flow. If you cannot find the option, ask Seazona support for API access.',
+      'Copy the API address, the client id and the client secret.',
+      'Paste them below, choose the mode, and turn Seazona on.',
+      'Live mode starts the background sync. Flow only reads from Seazona.',
+    ],
+  },
+  fields: [
+    { name: 'SEAZONA_MODE', label: 'Mode', kind: 'choice', choices: [{ value: 'live', label: 'Live: your Seazona account' }, { value: 'sandbox', label: 'Sandbox: a Seazona test account' }] },
+    { 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.' },
+  ],
+};
+
+export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.now, timers } = {}) {
   let runtime = null; // { settings, db, client, scheduler }
 
   function current() {
@@ -36,9 +56,10 @@ export function createSeazonaAdapter({ env = process.env, fetchImpl = null, now
     // VISION.md: Seazona is bundled and on in the dental preset.
     bundled: true,
     schema: seazonaSchema,
+    setup: SEAZONA_SETUP,
 
-    async start({ db, log = console }) {
-      const settings = requireSeazonaSettings(env);
+    async start({ db, log = console, env: settingsEnv }) {
+      const settings = requireSeazonaSettings(env ?? settingsEnv ?? process.env);
       const client = createSeazonaClient({ settings, db, fetchImpl: fetchImpl ?? undefined, workflow: 'seazona-sync', now });
       const run = (options = {}) => runSeazonaSync(db, client, { settings, now, ...options });
       // The background sync starts in live mode only. A sandbox or replay
@@ -51,6 +72,7 @@ export function createSeazonaAdapter({ env = process.env, fetchImpl = null, now
 
     async stop() {
       await runtime?.scheduler?.stop();
+      runtime = null;
     },
 
     capabilities: {