@arcforgelabs/flow 2026.10.18 → 2026.10.19-beta.1

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

@@ -22,6 +22,20 @@
       "when": 1792322911044,
       "tag": "0002_people",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1792329648463,
+      "tag": "0003_billing_ledger",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1792329649575,
+      "tag": "0004_ledger_events_append_only",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -1,5 +1,6 @@
 import { sql } from 'drizzle-orm';
 import {
+  boolean,
   check,
   date,
   foreignKey,
@@ -167,3 +168,139 @@ export const people = pgTable('people', {
   check('people_role_valid', sql`${t.role} in ('owner', 'admin', 'staff')`),
   check('people_status_valid', sql`${t.status} in ('active', 'pending', 'disabled')`),
 ]);
+
+// Billing obligations (issue 3). One billable job in a work system gives one
+// obligation. The obligation keeps the evidence for its state: what the work
+// system reported, what the accounting system reported, each payment, and each
+// status write-back to the work system. Flow is not the source of truth for
+// accounting; the ledger is its audit and workflow memory over what the
+// integrations report.
+
+export const ACCOUNTING_STATES = [
+  'unknown', 'not_found', 'drafted', 'authorised', 'part_paid', 'paid',
+  'voided', 'deleted', 'ambiguous', 'conflict',
+];
+export const HOLD_STATES = ['none', 'held', 'review'];
+export const WRITEBACK_STATES = ['pending', 'sent', 'failed', 'not_supported'];
+
+const inList = (column, values) => sql.raw(`${column} in (${values.map((v) => `'${v}'`).join(', ')})`);
+
+export const billingObligations = pgTable('billing_obligations', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  // The job's identity in the work system, for example `seazona` and its job id.
+  sourceSystem: text('source_system').notNull(),
+  sourceJobRef: text('source_job_ref').notNull(),
+  // The work system's own invoice identity for the job, when it has one.
+  sourceInvoiceRef: text('source_invoice_ref'),
+  // A case number only. Never patient data.
+  caseRef: text('case_ref'),
+  contactId: uuid('contact_id'),
+  practitioner: text('practitioner'),
+  shippedOn: date('shipped_on'),
+  // The lines as the work system reported them, normalised.
+  lines: jsonb('lines').notNull().default(sql`'[]'::jsonb`),
+  lineFingerprint: text('line_fingerprint').notNull(),
+  subtotalCents: integer('subtotal_cents').notNull(),
+  taxCents: integer('tax_cents').notNull(),
+  totalCents: integer('total_cents').notNull(),
+  // Every line maps to a price item.
+  mappingComplete: boolean('mapping_complete').notNull(),
+  sourceSeenAt: timestamp('source_seen_at', { withTimezone: true }).notNull(),
+  holdState: text('hold_state').notNull().default('none'),
+  holdReason: text('hold_reason'),
+  // The Flow invoice made for this job.
+  invoiceId: uuid('invoice_id'),
+  // What the accounting system reported, how it matched, and when Flow checked.
+  accountingState: text('accounting_state').notNull().default('unknown'),
+  accountingRef: text('accounting_ref'),
+  accountingUrl: text('accounting_url'),
+  accountingMatchedBy: text('accounting_matched_by'),
+  accountingCheckedAt: timestamp('accounting_checked_at', { withTimezone: true }),
+  paidCents: integer('paid_cents').notNull().default(0),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('billing_obligations_org_id').on(t.organisationId, t.id),
+  unique('billing_obligations_source_job').on(t.organisationId, t.sourceSystem, t.sourceJobRef),
+  unique('billing_obligations_invoice').on(t.organisationId, t.invoiceId),
+  foreignKey({
+    name: 'billing_obligations_contact_same_org',
+    columns: [t.organisationId, t.contactId],
+    foreignColumns: [contacts.organisationId, contacts.id],
+  }),
+  foreignKey({
+    name: 'billing_obligations_invoice_same_org',
+    columns: [t.organisationId, t.invoiceId],
+    foreignColumns: [invoices.organisationId, invoices.id],
+  }),
+  check('billing_obligations_hold_state_valid', inList('hold_state', HOLD_STATES)),
+  check('billing_obligations_accounting_state_valid', inList('accounting_state', ACCOUNTING_STATES)),
+  check('billing_obligations_paid_not_negative', sql`${t.paidCents} >= 0`),
+]);
+
+// Why each obligation is in its state. Append-only: a trigger in the
+// migrations refuses UPDATE and DELETE.
+export const obligationEvents = pgTable('obligation_events', {
+  id: id(),
+  organisationId: organisationId(),
+  obligationId: uuid('obligation_id').notNull(),
+  kind: text('kind').notNull(),
+  actor: text('actor').notNull(),
+  evidence: jsonb('evidence').notNull().default(sql`'{}'::jsonb`),
+  createdAt: createdAt(),
+}, (t) => [
+  foreignKey({
+    name: 'obligation_events_obligation_same_org',
+    columns: [t.organisationId, t.obligationId],
+    foreignColumns: [billingObligations.organisationId, billingObligations.id],
+  }),
+]);
+
+// Each payment the accounting system reported against the job's invoice.
+export const obligationPayments = pgTable('obligation_payments', {
+  id: id(),
+  organisationId: organisationId(),
+  obligationId: uuid('obligation_id').notNull(),
+  paymentRef: text('payment_ref').notNull(),
+  paidOn: date('paid_on').notNull(),
+  amountCents: integer('amount_cents').notNull(),
+  reference: text('reference'),
+  reconciled: boolean('reconciled').notNull(),
+  accountingUrl: text('accounting_url'),
+  observedAt: timestamp('observed_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => [
+  unique('obligation_payments_ref').on(t.organisationId, t.obligationId, t.paymentRef),
+  foreignKey({
+    name: 'obligation_payments_obligation_same_org',
+    columns: [t.organisationId, t.obligationId],
+    foreignColumns: [billingObligations.organisationId, billingObligations.id],
+  }),
+  check('obligation_payments_amount_positive', sql`${t.amountCents} > 0`),
+]);
+
+// Status sent back to the work system (for example "paid"), with the evidence
+// sent. A failed write-back stays here and is tried again; it never changes the
+// accounting record.
+export const obligationWritebacks = pgTable('obligation_writebacks', {
+  id: id(),
+  organisationId: organisationId(),
+  obligationId: uuid('obligation_id').notNull(),
+  targetSystem: text('target_system').notNull(),
+  status: text('status').notNull(),
+  state: text('state').notNull().default('pending'),
+  evidence: jsonb('evidence').notNull(),
+  attempts: integer('attempts').notNull().default(0),
+  lastError: text('last_error'),
+  sentAt: timestamp('sent_at', { withTimezone: true }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('obligation_writebacks_status').on(t.organisationId, t.obligationId, t.status),
+  foreignKey({
+    name: 'obligation_writebacks_obligation_same_org',
+    columns: [t.organisationId, t.obligationId],
+    foreignColumns: [billingObligations.organisationId, billingObligations.id],
+  }),
+  check('obligation_writebacks_state_valid', inList('state', WRITEBACK_STATES)),
+]);

package/server/import/earlier-flow.js

@@ -0,0 +1,230 @@
+import { sql } from 'drizzle-orm';
+import { contacts, organisations, priceItems } from '../db/schema.js';
+
+// A one-off move of an installation's records from the earlier Flow codebase
+// (its PostgreSQL database, read only) into a new, empty Flow database.
+//
+// What moves is only what the earlier database holds as a fact:
+// - contacts, from its copy of the accounting system's contacts;
+// - the price list, from its copy of the accounting system's sold items;
+// - the invoice prefix and next number, so the first invoice Flow issues
+//   follows the last one the accounting system holds.
+// Patient and case details, sync state and logins never move. Integrations
+// read their own records again from their source once they are on.
+//
+// planImport is pure: it turns the source rows into the rows to write and a
+// list of every source row it leaves out, with the reason. applyImport writes
+// the plan in one transaction and checks each table's count before it commits.
+
+const SOURCE_QUERIES = {
+  contacts: `SELECT contact_id, name, email_address, status, raw_json FROM xero_catalog_contacts ORDER BY contact_id`,
+  items: `SELECT item_code, name, description, sales_details_json, is_sold FROM xero_catalog_items ORDER BY item_code`,
+  invoices: `SELECT invoice_number, type FROM xero_catalog_invoices WHERE invoice_number IS NOT NULL`,
+};
+
+// Accounting tax types that charge GST on a sale. Every other set type is GST
+// free (exempt, export, outside the GST system).
+const GST_TAX_TYPES = new Set(['OUTPUT', 'OUTPUT2']);
+const SKIPPED_CONTACT_STATUSES = new Set(['ARCHIVED', 'GDPRREQUEST']);
+
+export async function readEarlierFlow(pool) {
+  const source = {};
+  for (const [name, query] of Object.entries(SOURCE_QUERIES)) {
+    source[name] = (await pool.query(query)).rows;
+  }
+  return source;
+}
+
+function parseJson(text) {
+  if (text === null || text === undefined || text === '') return {};
+  if (typeof text === 'object') return text;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function isTrue(value) {
+  return value === true || value === 1 || value === '1' || value === 'true';
+}
+
+// A decimal amount to whole cents, half away from zero, without float drift.
+export function toCents(amount) {
+  const text = String(amount ?? '').trim();
+  const match = /^(-?)(\d+)(?:\.(\d+))?$/.exec(text);
+  if (!match) return null;
+  const [, sign, whole, fraction = ''] = match;
+  const digits = (fraction + '000').slice(0, 3);
+  let cents = Number(whole) * 100 + Number(digits.slice(0, 2));
+  if (Number(digits[2]) >= 5) cents += 1;
+  if (!Number.isSafeInteger(cents)) return null;
+  return sign === '-' && cents !== 0 ? -cents : cents;
+}
+
+function planContacts(rows, skipped) {
+  const planned = [];
+  const seen = new Set();
+  for (const row of rows) {
+    const key = row.contact_id;
+    const name = String(row.name ?? '').trim();
+    const status = String(row.status ?? '').toUpperCase();
+    if (!name) {
+      skipped.push({ table: 'contacts', key, reason: 'no_name' });
+      continue;
+    }
+    if (SKIPPED_CONTACT_STATUSES.has(status)) {
+      skipped.push({ table: 'contacts', key, reason: `status_${status.toLowerCase()}` });
+      continue;
+    }
+    const raw = parseJson(row.raw_json);
+    if (raw === null) {
+      skipped.push({ table: 'contacts', key, reason: 'unreadable_raw_json' });
+      continue;
+    }
+    const customer = isTrue(raw.IsCustomer);
+    const supplier = isTrue(raw.IsSupplier);
+    // A contact the accounting system has never billed or paid is most often
+    // a new customer, so it comes across as one.
+    const kinds = supplier && !customer ? ['supplier'] : supplier ? ['customer', 'supplier'] : ['customer'];
+    const email = String(row.email_address ?? '').trim() || null;
+    for (const kind of kinds) {
+      const unique = `${kind}\u0000${name}`;
+      if (seen.has(unique)) {
+        skipped.push({ table: 'contacts', key, reason: `duplicate_${kind}_name` });
+        continue;
+      }
+      seen.add(unique);
+      planned.push({ sourceKey: key, kind, name, email });
+    }
+  }
+  return planned;
+}
+
+function planPriceItems(rows, skipped, defaulted) {
+  const planned = [];
+  for (const row of rows) {
+    const key = row.item_code;
+    const code = String(row.item_code ?? '').trim();
+    const name = String(row.name ?? '').trim() || String(row.description ?? '').trim();
+    if (!isTrue(row.is_sold)) {
+      skipped.push({ table: 'price_items', key, reason: 'not_sold' });
+      continue;
+    }
+    if (!code || !name) {
+      skipped.push({ table: 'price_items', key, reason: 'no_code_or_name' });
+      continue;
+    }
+    const sales = parseJson(row.sales_details_json);
+    if (sales === null) {
+      skipped.push({ table: 'price_items', key, reason: 'unreadable_sales_details' });
+      continue;
+    }
+    const unitAmountCents = toCents(sales.UnitPrice);
+    if (unitAmountCents === null) {
+      skipped.push({ table: 'price_items', key, reason: 'no_sales_price' });
+      continue;
+    }
+    const taxType = String(sales.TaxType ?? '').trim().toUpperCase();
+    if (!taxType) defaulted.push({ table: 'price_items', key, reason: 'no_tax_type_used_gst' });
+    const taxCode = !taxType || GST_TAX_TYPES.has(taxType) ? 'GST' : 'GST_FREE';
+    planned.push({ sourceKey: key, code, name, unitAmountCents, taxCode });
+  }
+  return planned;
+}
+
+// The prefix and next number after the highest sales invoice number, so Flow
+// never issues a number the accounting system already holds.
+function planNumbering(rows, fallbackPrefix) {
+  const byPrefix = new Map();
+  for (const row of rows) {
+    if (String(row.type ?? '').toUpperCase() !== 'ACCREC') continue;
+    const match = /^(.*?)(\d+)$/.exec(String(row.invoice_number ?? '').trim());
+    if (!match) continue;
+    const [, prefix, digits] = match;
+    const entry = byPrefix.get(prefix) ?? { count: 0, highest: 0 };
+    entry.count += 1;
+    entry.highest = Math.max(entry.highest, Number(digits));
+    byPrefix.set(prefix, entry);
+  }
+  // The prefix most invoices use is the organisation's numbering.
+  let best = null;
+  for (const [prefix, entry] of byPrefix) {
+    if (!best || entry.count > best.count) best = { prefix, ...entry };
+  }
+  if (!best) return { invoicePrefix: fallbackPrefix, nextInvoiceNumber: 1, basis: 'no_sales_invoices' };
+  return { invoicePrefix: best.prefix, nextInvoiceNumber: best.highest + 1, basis: 'highest_sales_invoice' };
+}
+
+export function planImport(source, { fallbackPrefix = 'INV-' } = {}) {
+  const skipped = [];
+  const defaulted = [];
+  return {
+    contacts: planContacts(source.contacts ?? [], skipped),
+    priceItems: planPriceItems(source.items ?? [], skipped, defaulted),
+    numbering: planNumbering(source.invoices ?? [], fallbackPrefix),
+    skipped,
+    defaulted,
+  };
+}
+
+// Counts and reasons only. Names, emails and amounts stay out of logs.
+export function summarisePlan(plan) {
+  const reasons = {};
+  for (const entry of [...plan.skipped, ...plan.defaulted]) {
+    const key = `${entry.table}: ${entry.reason}`;
+    reasons[key] = (reasons[key] ?? 0) + 1;
+  }
+  return {
+    contacts: {
+      customer: plan.contacts.filter((c) => c.kind === 'customer').length,
+      supplier: plan.contacts.filter((c) => c.kind === 'supplier').length,
+    },
+    priceItems: plan.priceItems.length,
+    numbering: plan.numbering,
+    leftOutOrDefaulted: reasons,
+  };
+}
+
+async function countRows(tx, table, organisationId) {
+  const [{ count }] = (await tx.execute(
+    sql`select count(*)::int as count from ${table} where organisation_id = ${organisationId}`,
+  )).rows;
+  return count;
+}
+
+// Writes the plan into a database that has no organisation yet. Everything
+// is one transaction: any error, or a count that does not match, writes
+// nothing.
+export async function applyImport(db, plan, { organisationName }) {
+  if (!organisationName?.trim()) throw new Error('organisationName is required');
+  return db.transaction(async (tx) => {
+    const [{ count: existing }] = (await tx.execute(sql`select count(*)::int as count from ${organisations}`)).rows;
+    if (existing > 0) throw new Error('the target database already has an organisation; import only into a new Flow database');
+
+    const [organisation] = await tx.insert(organisations).values({
+      name: organisationName.trim(),
+      invoicePrefix: plan.numbering.invoicePrefix,
+      nextInvoiceNumber: plan.numbering.nextInvoiceNumber,
+    }).returning();
+    const organisationId = organisation.id;
+
+    for (const contact of plan.contacts) {
+      await tx.insert(contacts).values({ organisationId, kind: contact.kind, name: contact.name, email: contact.email });
+    }
+    for (const item of plan.priceItems) {
+      await tx.insert(priceItems).values({
+        organisationId, code: item.code, name: item.name, unitAmountCents: item.unitAmountCents, taxCode: item.taxCode,
+      });
+    }
+
+    const counts = {
+      contacts: await countRows(tx, contacts, organisationId),
+      priceItems: await countRows(tx, priceItems, organisationId),
+    };
+    if (counts.contacts !== plan.contacts.length || counts.priceItems !== plan.priceItems.length) {
+      throw new Error(`row counts do not match the plan: ${JSON.stringify(counts)}`);
+    }
+    return { organisationId, counts };
+  });
+}

package/server/import-earlier-flow.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import pg from 'pg';
+import { migrateDatabase, openDatabase } from './db/index.js';
+import { applyImport, planImport, readEarlierFlow, summarisePlan } from './import/earlier-flow.js';
+
+// Moves an installation's records from the earlier Flow codebase into a new
+// Flow database (server/import/earlier-flow.js).
+//
+//   EARLIER_FLOW_DATABASE_URL=… DATABASE_URL=… \
+//     node server/import-earlier-flow.js --organisation "<lab name>" [--dry-run]
+//
+// The source is only read. Run it against a copy of the source first. The
+// target must be a new Flow database: the tool runs Flow's migrations on it
+// and refuses one that already has an organisation. It prints counts and
+// reasons only, never names, emails or amounts. Keep both connection strings
+// out of chat and shell history.
+
+function parseArgs(argv) {
+  const args = { dryRun: false, organisation: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--dry-run') args.dryRun = true;
+    else if (argv[i] === '--organisation') args.organisation = argv[++i] ?? null;
+    else throw new Error(`unknown argument: ${argv[i]}`);
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const sourceUrl = process.env.EARLIER_FLOW_DATABASE_URL;
+  if (!sourceUrl) throw new Error('EARLIER_FLOW_DATABASE_URL is not set');
+  if (!args.dryRun && !args.organisation?.trim()) throw new Error('--organisation "<lab name>" is required');
+
+  const source = new pg.Pool({ connectionString: sourceUrl, max: 2 });
+  let plan;
+  try {
+    // A read-only transaction: the source cannot change by mistake.
+    const client = await source.connect();
+    try {
+      await client.query('BEGIN TRANSACTION READ ONLY');
+      plan = planImport(await readEarlierFlow(client));
+      await client.query('COMMIT');
+    } finally {
+      client.release();
+    }
+  } finally {
+    await source.end();
+  }
+
+  console.log(JSON.stringify({ plan: summarisePlan(plan) }, null, 2));
+  if (args.dryRun) return;
+
+  const target = openDatabase({ max: 2 });
+  try {
+    await migrateDatabase(target.db);
+    const result = await applyImport(target.db, plan, { organisationName: args.organisation });
+    console.log(JSON.stringify({ imported: result.counts }, null, 2));
+  } finally {
+    await target.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(`[import] ${error.message}`);
+  process.exit(1);
+});

package/server/index.js

@@ -5,11 +5,12 @@ 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 { createIntegrations } from './integrations/index.js';
 import { createUpdateChecker, UPDATE_CHECK_INTERVAL_MS } from './update-check.js';
 
 const port = Number(process.env.FLOW_PORT || process.env.PORT || 19300);
 
-// Sign-in settings first: a malformed setting stops boot before anything runs.
+// Settings first: a malformed setting stops boot before anything runs.
 let settings;
 try {
   settings = resolveSignInSettings();
@@ -17,11 +18,22 @@ try {
   console.error(`[auth] ${error.message}`);
   process.exit(1);
 }
+let integrations;
+try {
+  integrations = createIntegrations();
+} catch (error) {
+  console.error(`[integrations] ${error.message}`);
+  process.exit(1);
+}
 
 // Flow's records live in PostgreSQL. Migrations run before the server accepts
-// requests, so a release never serves an older schema.
+// requests, so a release never serves an older schema. Then each enabled
+// integration's own tables, and no others (docs/INTEGRATIONS.md).
 const database = openDatabase();
 await migrateDatabase(database.db);
+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)`);
 
 let auth = null;
 if (settings.mode === 'clerk') {
@@ -49,7 +61,7 @@ if (settings.mode === 'clerk') {
     ...(settings.ownerGoogleDomains.length ? [`Google Workspace sign-in on ${settings.ownerGoogleDomains.join(', ')} with no password`] : []),
     `a Clerk second factor within ${settings.ownerMfaMaxAgeMinutes} min`,
   ];
-  console.log(`[auth] Clerk sign-in on (CLERK_SECRET_KEY, ${keys.publishableSource}); public sign-up ${settings.publicSignUp ? 'on' : 'off'}; owner actions: ${ownerPaths.join(', or ')}${proxyPath ? `; Clerk proxied at ${proxyPath}` : ''}`);
+  console.log(`[auth] Clerk sign-in on (CLERK_SECRET_KEY, ${keys.publishableSource}); public sign-up ${settings.publicSignUp ? 'on' : settings.signUpDomains.length ? `only ${settings.signUpDomains.join(', ')}` : 'off'}; owner actions: ${ownerPaths.join(', or ')}${proxyPath ? `; Clerk proxied at ${proxyPath}` : ''}`);
   // Replit's managed Clerk has no MFA, so there the Google Workspace path is
   // the only way an owner can manage people.
   if (!settings.ownerGoogleDomains.length && (process.env.REPL_ID || process.env.REPLIT_DEPLOYMENT)) {
@@ -64,7 +76,7 @@ const trustProxy = process.env.REPL_ID || process.env.REPLIT_DEPLOYMENT ? 1 : fa
 
 const updates = createUpdateChecker();
 
-createApp({ database, auth, trustProxy, updates }).listen(port, () => {
+createApp({ database, auth, trustProxy, updates, integrations }).listen(port, () => {
   console.log(`[flow] listening on ${port}`);
 });
 

package/server/integrations/adapters.js

@@ -0,0 +1,6 @@
+// The adapters this build of Flow ships. server/index.js registers each one;
+// FLOW_INTEGRATIONS chooses which are on (server/integrations/index.js).
+import { seazonaAdapter } from './seazona/index.js';
+import { xeroAdapter } from './xero/index.js';
+
+export const adapters = [seazonaAdapter, xeroAdapter];

package/server/integrations/health.js

@@ -0,0 +1,21 @@
+// What GET /health says about each integration: whether it is on, its state,
+// and, when it is ready, its own health() answer (issue #10: each adapter's
+// mode). An adapter's health reads Flow's own data and must answer quickly;
+// one that fails or takes longer than `timeoutMs` is reported, never thrown.
+export async function integrationsHealth(registry, { timeoutMs = 5_000 } = {}) {
+  return Promise.all(registry.list().map(async (adapter) => {
+    const entry = { id: adapter.id, name: adapter.name, enabled: adapter.enabled, state: adapter.state };
+    if (adapter.state !== 'ready' || !adapter.capabilities.includes('health')) return entry;
+    let timer;
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(() => resolve({ ok: false, error: `health did not answer within ${timeoutMs} ms` }), timeoutMs);
+    });
+    const answer = registry.whenEnabled(adapter.id, (defined) => defined.capabilities.health())
+      .catch((error) => ({ ok: false, error: error?.message || String(error) }));
+    try {
+      return { ...entry, health: await Promise.race([answer, timeout]) };
+    } finally {
+      clearTimeout(timer);
+    }
+  }));
+}

package/server/integrations/index.js

@@ -0,0 +1,26 @@
+import { adapters as shipped } from './adapters.js';
+import { createRegistry } from './port.js';
+
+// FLOW_INTEGRATIONS: the adapter ids to turn on, separated by commas
+// (`seazona,xero`). Unset or empty: none. An unknown id stops boot, so a typo
+// never leaves an integration silently off.
+export function resolveEnabledIntegrations(env = process.env, adapters = shipped) {
+  const known = new Set(adapters.map((a) => a.id));
+  const ids = [...new Set((env.FLOW_INTEGRATIONS ?? '').split(',').map((id) => id.trim().toLowerCase()).filter(Boolean))];
+  const unknown = ids.filter((id) => !known.has(id));
+  if (unknown.length) {
+    const offer = known.size ? `Known: ${[...known].join(', ')}.` : 'This build ships no integrations.';
+    throw new Error(`FLOW_INTEGRATIONS names an unknown integration: ${unknown.join(', ')}. ${offer}`);
+  }
+  return ids;
+}
+
+// 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 } = {}) {
+  const enabled = resolveEnabledIntegrations(env, adapters);
+  const registry = createRegistry({ log });
+  for (const adapter of adapters) registry.register(adapter);
+  for (const id of enabled) registry.enable(id);
+  return registry;
+}