@arcforgelabs/flow 2026.10.30 → 2026.10.32

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

@@ -99,6 +99,27 @@
       "when": 1792414148360,
       "tag": "0013_line_mappings",
       "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1792448941014,
+      "tag": "0014_price_list",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1792452497948,
+      "tag": "0015_alert_dismissals",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1792456270558,
+      "tag": "0016_invoice_reference",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -64,8 +64,12 @@ export const priceItems = pgTable('price_items', {
   description: text('description'),
   unitAmountCents: integer('unit_amount_cents').notNull(),
   taxCode: text('tax_code').notNull().default('GST'),
+  // The sales account a line with this code books to, when the lab sets one.
+  accountCode: text('account_code'),
   archivedAt: timestamp('archived_at', { withTimezone: true }),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
   createdAt: createdAt(),
+  updatedAt: updatedAt(),
 }, (t) => [
   unique('price_items_org_id').on(t.organisationId, t.id),
   unique('price_items_org_code').on(t.organisationId, t.code),
@@ -494,6 +498,20 @@ export const reviewItems = pgTable('review_items', {
   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)`),
 ]);
 
+// Quiet alerts (issue 117, docs/ALERTS.md). An alert is worked out each time
+// from Flow's own records (server/core/alerts.js); only a person's dismissal
+// is stored. `members` are the things the alert was about when it was
+// dismissed: the alert stays hidden for that person until something new joins.
+export const alertDismissals = pgTable('alert_dismissals', {
+  organisationId: organisationId().references(() => organisations.id),
+  personId: uuid('person_id').notNull().references(() => people.id, { onDelete: 'cascade' }),
+  alertKey: text('alert_key').notNull(),
+  members: text('members').array().notNull().default(sql`'{}'::text[]`),
+  dismissedAt: timestamp('dismissed_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => [
+  primaryKey({ columns: [t.organisationId, t.personId, t.alertKey] }),
+]);
+
 // 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
@@ -606,6 +624,8 @@ export const invoicingSettings = pgTable('invoicing_settings', {
   // The price item code of a rush charge, and its share of the other lines.
   rushItemCode: text('rush_item_code'),
   rushPercent: integer('rush_percent').notNull().default(20),
+  // The invoice Reference, from tokens (server/core/references.js).
+  referenceTemplate: text('reference_template').notNull().default('{practitioner} - {patient}'),
   // The fixed checks above became invoice rules (invoice_rules). True once
   // this organisation's starter rules were made from them.
   rulesSeeded: boolean('rules_seeded').notNull().default(false),
@@ -717,3 +737,29 @@ export const lineMappings = pgTable('line_mappings', {
   check('line_mappings_price', sql`${t.kind} not in ('price_alias', 'saved') or ${t.unitAmountCents} is not null`),
   check('line_mappings_label_valid', sql`length(${t.label}) between 1 and 200`),
 ]);
+
+// The price list's links (server/core/price-list.js, docs/PRICE_LIST.md): one
+// row joins one record in a connected system's price list (a Xero item, a
+// Seazona product) to one Flow price item. Flow's price list stays the source
+// of truth; a link only says which record to compare and map. Many Seazona
+// products can share one price item; a price item has one accounting item at
+// most (the code checks it: the adapter says which kind it is).
+//   matched_by  code     the same code on both sides, linked by Flow
+//               person   a person chose it
+export const PRICE_LINK_MATCHES = ['code', 'person'];
+export const priceItemLinks = pgTable('price_item_links', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  priceItemId: uuid('price_item_id').notNull(),
+  system: text('system').notNull(),
+  externalId: text('external_id').notNull(),
+  externalCode: text('external_code'),
+  matchedBy: text('matched_by').notNull(),
+  createdBy: uuid('created_by').references(() => people.id, { onDelete: 'set null' }),
+  createdAt: createdAt(),
+}, (t) => [
+  foreignKey({ name: 'price_item_links_item_same_org', columns: [t.organisationId, t.priceItemId], foreignColumns: [priceItems.organisationId, priceItems.id] }).onDelete('cascade'),
+  uniqueIndex('price_item_links_external').on(t.organisationId, t.system, t.externalId),
+  check('price_item_links_matched_by_valid', sql`${t.matchedBy} in ('code', 'person')`),
+  check('price_item_links_system_valid', sql`${t.system} ~ '^[a-z][a-z0-9-]{1,31}$'`),
+]);

package/server/flow-server.js

@@ -4,6 +4,16 @@
 // 2026.10.18-beta.2), so GET /health shows it as build.release. A checkout
 // starts server/index.js (`npm start`) instead: its package.json holds the
 // upcoming version, which is not a release yet.
+//
+//   flow-server                          start Flow
+//   flow-server migrate                  bring DATABASE_URL up to this build
+//                                        (Flow's tables and every shipped
+//                                        adapter's), then stop
+//   flow-server doctor [--live <origin>] [--json]
+//                                        check DATABASE_URL against this build,
+//                                        and with --live, against the live
+//                                        app's GET /health (server/db/doctor.js);
+//                                        exit 1 when it is not at this build
 import { readFileSync } from 'node:fs';
 import { parseReleaseTag } from './release-channel.js';
 
@@ -12,4 +22,13 @@ if (!process.env.FLOW_RELEASE) {
   const release = parseReleaseTag(version);
   if (release) process.env.FLOW_RELEASE = release.tag;
 }
-await import('./index.js');
+const [command, ...args] = process.argv.slice(2);
+if (command === 'migrate' || command === 'doctor') {
+  const { runCommand } = await import('./db/commands.js');
+  process.exitCode = await runCommand(command, args);
+} else if (command) {
+  console.error(`flow-server: unknown command '${command}'. Use: flow-server, flow-server migrate, flow-server doctor`);
+  process.exitCode = 2;
+} else {
+  await import('./index.js');
+}

package/server/index.js

@@ -4,6 +4,7 @@ import { createClerkProxy, ensureClerkAccount, loadClerkAdapter, resolveClerkPro
 import { seedFirstOwner } from './auth/people.js';
 import { createPersonAuth } from './auth/session.js';
 import { resolveSignInSettings } from './auth/settings.js';
+import { expectedSchema } from './db/doctor.js';
 import { migrateDatabase, openDatabase } from './db/index.js';
 import {
   importEarlierAtStart, importEarlierLinksAtStart, importEarlierMappingsAtStart, resolveImportAtStart,
@@ -141,7 +142,7 @@ const trustProxy = process.env.REPL_ID || process.env.REPLIT_DEPLOYMENT ? 1 : fa
 
 const updates = createUpdateChecker();
 
-createApp({ database, auth, trustProxy, updates, integrations, secrets, defaultFamily, log }).listen(port, () => {
+createApp({ database, schemaJournals: expectedSchema({ adapters: shippedAdapters }).journals, auth, trustProxy, updates, integrations, secrets, defaultFamily, log }).listen(port, () => {
   console.log(`[flow] listening on ${port}; design system ${defaultFamily} (FLOW_THEME)`);
 });
 

package/server/integrations/call-guard.js

@@ -0,0 +1,362 @@
+import { sql } from 'drizzle-orm';
+
+// The call guard: one pattern every adapter that calls an outside system
+// follows (docs/INTEGRATIONS.md, "Outbound calls"). A provider can cut off an
+// installation's API access after many failed calls, even inside its rate
+// limit (issues #101 and #111). So, before each call, the guard says whether
+// a call may go, and after it, the guard records how it ended:
+//
+//   - a refused credential halts every call until a person acts (saves the
+//     settings or connects again, which calls resume());
+//   - a 401 or 403 on one resource, when the adapter's auth failures stop a
+//     resource only, stops that resource until a person acts;
+//   - `circuitFailures` failed calls inside `circuitWindowMs` open the
+//     circuit: no call for `circuitPauseMs`, then a probe; a failed probe opens
+//     it again for twice as long, to at most `maxCircuitPauseMs`, and a
+//     success closes it;
+//   - `dailyFailureBudget` failed calls in one UTC day stop calls until the
+//     next day.
+//
+// A stopped call fails at once with CallsStopped; it never waits. Each stop
+// is reported once with log.error, so the connected error service gets one
+// report per problem; a repeat is a warning.
+//
+// State lives in PostgreSQL, in two tables the adapter owns and creates in its
+// own migrations (CALL_GUARD_COLUMNS), so every process on one database
+// shares it and a restart does not reset it. Nothing here names a vendor.
+
+export const CALL_GUARD_POLICY = Object.freeze({
+  circuitFailures: 5,
+  circuitWindowMs: 10 * 60_000,
+  circuitPauseMs: 5 * 60_000,
+  maxCircuitPauseMs: 6 * 60 * 60_000,
+  dailyFailureBudget: 50,
+  // 'all': a 401 or 403 halts every call. 'resource': it stops only the
+  // resource it came from; halt() still stops everything.
+  authStops: 'all',
+  telemetryRetentionMs: 35 * 24 * 60 * 60_000,
+});
+
+// The columns each guard table must have. `key` and `at` may have other names
+// (the `columns` option), so an adapter that kept telemetry before the guard
+// existed can keep its tables.
+export const CALL_GUARD_COLUMNS = Object.freeze({
+  state: ['key', 'circuit_open_until', 'circuit_opens', 'halted_reason', 'halted_at', 'stopped_resources', 'updated_at'],
+  calls: ['key', 'at', 'resource', 'request_path', 'status_code', 'failure_kind', 'duration_ms'],
+});
+
+const DAY_MS = 24 * 60 * 60_000;
+const EPOCH = new Date(0);
+
+// A call that failed in a way a provider sees as a fault: no answer, a 5xx, a
+// 429, or a 4xx other than 404 (a 404 on one record means it was deleted).
+export function countsAsFailure({ statusCode = null, failureKind = null } = {}) {
+  if (failureKind) return true;
+  if (!Number.isInteger(statusCode)) return false;
+  return statusCode >= 500 || (statusCode >= 400 && statusCode !== 404);
+}
+
+export const isAuthRefusal = (statusCode) => statusCode === 401 || statusCode === 403;
+
+export function startOfUtcDay(ms) {
+  const date = new Date(ms);
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+
+// The pause after the circuit has opened `opens` times before.
+export function circuitPauseMs(opens, policy = CALL_GUARD_POLICY) {
+  return Math.min(policy.maxCircuitPauseMs, policy.circuitPauseMs * 2 ** Math.min(Math.max(0, opens), 10));
+}
+
+// Why no call may go now, or null. `state` is the guard row
+// ({ haltedReason, circuitOpenUntil, stoppedResources }); `failedToday`
+// counts failed calls since the start of the UTC day.
+export function stoppedReason(state, { nowMs, failedToday, resource = null }, policy = CALL_GUARD_POLICY) {
+  if (state?.haltedReason) return { reason: 'halted', retryAfterMs: null };
+  if (resource && state?.stoppedResources?.[resource]) return { reason: 'resource_stopped', retryAfterMs: null, resource };
+  const openUntil = state?.circuitOpenUntil ? new Date(state.circuitOpenUntil).getTime() : 0;
+  if (openUntil > nowMs) return { reason: 'circuit_open', retryAfterMs: openUntil - nowMs };
+  const dayStart = startOfUtcDay(nowMs);
+  if (failedToday >= policy.dailyFailureBudget) return { reason: 'budget_spent', retryAfterMs: dayStart + DAY_MS - nowMs };
+  return null;
+}
+
+// Whether a failed call opens the circuit. `recentFailures` counts failed
+// calls since max(now - circuitWindowMs, the end of the last pause), this one
+// included. Answers { pauseMs } or null.
+export function circuitAfterFailure(state, { nowMs, recentFailures }, policy = CALL_GUARD_POLICY) {
+  const opens = state?.circuitOpens ?? 0;
+  const openUntil = state?.circuitOpenUntil ? new Date(state.circuitOpenUntil).getTime() : 0;
+  // After a pause the next call is a probe: if it fails, open again at once.
+  const probeFailed = opens > 0 && openUntil <= nowMs;
+  if (!probeFailed && (recentFailures < policy.circuitFailures || openUntil > nowMs)) return null;
+  return { pauseMs: circuitPauseMs(opens, policy) };
+}
+
+const STOP_TEXT = {
+  halted: (name) => `${name} calls are stopped until a person checks the connection (it was refused)`,
+  resource_stopped: (name, resource) => `${name} calls to ${resource} are stopped until a person checks the connection (they were refused)`,
+  circuit_open: (name) => `${name} calls are paused after repeated failures`,
+  budget_spent: (name) => `${name} calls are stopped for today: the day's failed calls are spent`,
+};
+const STOP_CODE = {
+  halted: 'api_halted',
+  resource_stopped: 'api_resource_stopped',
+  circuit_open: 'api_circuit_open',
+  budget_spent: 'api_failure_budget_spent',
+};
+
+// Calls are stopped. `retryAfterMs` is null for a stop that only a person
+// clears. `code` is `<integration>_<what>`, for example api_circuit_open.
+export class CallsStopped extends Error {
+  constructor({ integration, name = integration, reason, retryAfterMs = null, resource = null }) {
+    super(STOP_TEXT[reason](name, resource));
+    this.name = 'CallsStopped';
+    this.code = `${integration}_${STOP_CODE[reason]}`;
+    this.kind = 'calls_stopped';
+    this.integration = integration;
+    this.reason = reason;
+    this.resource = resource;
+    this.retryAfterMs = retryAfterMs;
+    this.status = 503;
+  }
+}
+
+export const isCallsStopped = (error) => error?.kind === 'calls_stopped';
+
+// The quiet alerts a guard's status() makes (server/core/alerts.js): only the
+// stops a person must clear. A paused circuit or a spent day ends by itself,
+// so it is no alert. `name` is what a person reads; `fix` says how a person
+// clears the stop.
+export function guardAlerts(name, status, { fix = 'Check the connection, then connect again.' } = {}) {
+  const alerts = [];
+  if (status?.haltedReason) {
+    alerts.push({
+      id: 'calls-stopped',
+      tone: 'danger',
+      title: `${name} refused Flow. Flow stopped all ${name} calls. ${fix}`,
+      members: [`halted:${status.haltedAt ?? ''}`],
+    });
+  }
+  const resources = status?.stoppedResources ?? [];
+  if (resources.length) {
+    alerts.push({
+      id: 'resources-stopped',
+      tone: 'danger',
+      title: `${name} refused Flow for ${resources.map((r) => r.resource).join(', ')}. Flow stopped those calls. ${fix}`,
+      members: resources.map((r) => `${r.resource}:${r.at ?? ''}`),
+    });
+  }
+  return alerts;
+}
+
+// Path only: drop any host and query, and keep a safe character set.
+export function normaliseRequestPath(value) {
+  const path = String(value || '').split(/[?#]/)[0].replace(/^[a-z]+:\/\/[^/]+/i, '');
+  return path.replace(/[^A-Za-z0-9/_.:-]+/g, '').slice(0, 160) || null;
+}
+
+const cleanKey = (value) => String(value ?? '').trim().slice(0, 120);
+const cleanResource = (value) => (value ? String(value).replace(/[^A-Za-z0-9/_.:-]+/g, '').slice(0, 80) || null : null);
+const iso = (value) => (value ? new Date(value).toISOString() : null);
+
+// `integration` is the adapter id (codes, the advisory lock), `name` what a
+// person reads. `tables` names the adapter's two tables; `columns` renames
+// the `key` and `at` columns when an adapter's tables use other names, and
+// `callDefaults` fills other required columns of a new call row. An adapter
+// that admits its calls in its own transaction passes `lockName`, so the
+// guard takes the same lock. `report: false` leaves the reports to the
+// adapter, for one that already reports each stop once at a higher level.
+export function createCallGuard({
+  db,
+  integration,
+  name = integration,
+  tables,
+  columns = {},
+  callDefaults = {},
+  lockName = `${integration}-call-guard`,
+  report: reports = true,
+  policy: overrides = {},
+  now = Date.now,
+  log = console,
+} = {}) {
+  if (!db) throw new TypeError('createCallGuard: db is required');
+  if (!/^[a-z][a-z0-9-]{1,31}$/.test(integration ?? '')) throw new TypeError('createCallGuard: integration must be an adapter id');
+  if (!tables?.state || !tables?.calls) throw new TypeError('createCallGuard: tables.state and tables.calls are required');
+  const policy = { ...CALL_GUARD_POLICY, ...overrides };
+  if (!['all', 'resource'].includes(policy.authStops)) throw new TypeError('createCallGuard: authStops must be "all" or "resource"');
+  const T = { state: sql.identifier(tables.state), calls: sql.identifier(tables.calls) };
+  const C = { key: sql.identifier(columns.key ?? 'key'), at: sql.identifier(columns.at ?? 'at') };
+  const tag = `[${integration}]`;
+  const failed = sql`(failure_kind is not null or status_code >= 500 or (status_code >= 400 and status_code <> 404))`;
+
+  const lock = (tx, key) => tx.execute(sql`select pg_advisory_xact_lock(hashtext(${`${lockName}:${key}`}))`);
+  const extraColumns = Object.keys(callDefaults).map((column) => sql`, ${sql.identifier(column)}`);
+  const extraValues = Object.values(callDefaults).map((value) => sql`, ${value}`);
+
+  async function readState(runner, key) {
+    const { rows } = await runner.execute(sql`select circuit_open_until, circuit_opens, halted_reason, halted_at, stopped_resources
+      from ${T.state} where ${C.key} = ${key}`);
+    const row = rows[0];
+    if (!row) return { circuitOpenUntil: EPOCH, circuitOpens: 0, haltedReason: null, haltedAt: null, stoppedResources: {} };
+    return {
+      circuitOpenUntil: new Date(row.circuit_open_until),
+      circuitOpens: Number(row.circuit_opens),
+      haltedReason: row.halted_reason,
+      haltedAt: row.halted_at ? new Date(row.halted_at) : null,
+      stoppedResources: row.stopped_resources ?? {},
+    };
+  }
+
+  async function failuresSince(runner, key, fromMs) {
+    const { rows } = await runner.execute(sql`select count(*)::int as n from ${T.calls}
+      where ${C.key} = ${key} and ${C.at} >= ${new Date(fromMs)} and ${failed}`);
+    return Number(rows[0].n);
+  }
+
+  const ensureRow = (runner, key) => runner.execute(sql`insert into ${T.state} (${C.key}) values (${key}) on conflict do nothing`);
+
+  // Why no call may go to `resource` now, or null. `runner` is the database
+  // or a transaction the adapter holds (with the guard's lock).
+  async function stoppedNow(runner, rawKey, { resource = null } = {}) {
+    const key = cleanKey(rawKey);
+    const nowMs = Number(now());
+    const state = await readState(runner, key);
+    const failedToday = await failuresSince(runner, key, startOfUtcDay(nowMs));
+    return stoppedReason(state, { nowMs, failedToday, resource: cleanResource(resource) }, policy);
+  }
+
+  // Throws CallsStopped when no call may go to `resource` now.
+  async function check(rawKey, options = {}) {
+    const stopped = await stoppedNow(db, rawKey, options);
+    if (stopped) throw new CallsStopped({ integration, name, ...stopped });
+  }
+
+  // Records how one call ended, and what that does to the guard. Answers
+  // what this call stopped ({ halted, resourceStopped, opened, budgetSpent }),
+  // each of which was just reported once. `callId` names a call row the
+  // adapter wrote when it admitted the call: that row is updated, not added.
+  async function record(rawKey, { callId = null, resource = null, path = null, statusCode = null, failureKind = null, durationMs = null } = {}) {
+    const key = cleanKey(rawKey);
+    const where = cleanResource(resource);
+    const nowMs = Number(now());
+    const nowAt = new Date(nowMs);
+    const status = Number.isInteger(statusCode) ? statusCode : null;
+    const outcome = await db.transaction(async (tx) => {
+      await lock(tx, key);
+      await ensureRow(tx, key);
+      const kind = failureKind ? String(failureKind).slice(0, 40) : null;
+      const took = Number.isFinite(durationMs) ? Math.max(0, Math.round(durationMs)) : null;
+      if (callId !== null) {
+        await tx.execute(sql`update ${T.calls} set resource = ${where}, request_path = ${normaliseRequestPath(path)}, status_code = ${status},
+          failure_kind = ${kind}, duration_ms = ${took} where id = ${callId} and ${C.key} = ${key}`);
+      } else {
+        await tx.execute(sql`insert into ${T.calls} (${C.key}, ${C.at}, resource, request_path, status_code, failure_kind, duration_ms${sql.join(extraColumns, sql``)})
+          values (${key}, ${nowAt}, ${where}, ${normaliseRequestPath(path)}, ${status}, ${kind}, ${took}${sql.join(extraValues, sql``)})`);
+      }
+      const state = await readState(tx, key);
+      if (!countsAsFailure({ statusCode: status, failureKind })) {
+        if (state.circuitOpens > 0) {
+          await tx.execute(sql`update ${T.state} set circuit_opens = 0, updated_at = ${nowAt} where ${C.key} = ${key}`);
+          return { closed: true };
+        }
+        return {};
+      }
+      const result = {};
+      const dayStart = startOfUtcDay(nowMs);
+      if (await failuresSince(tx, key, dayStart) === policy.dailyFailureBudget) result.budgetSpent = { until: new Date(dayStart + DAY_MS).toISOString() };
+      if (isAuthRefusal(status)) {
+        if (policy.authStops === 'resource' && where) {
+          if (!state.stoppedResources[where]) {
+            await tx.execute(sql`update ${T.state} set stopped_resources = stopped_resources || ${JSON.stringify({ [where]: { statusCode: status, at: nowAt.toISOString() } })}::jsonb,
+              updated_at = ${nowAt} where ${C.key} = ${key}`);
+            result.resourceStopped = where;
+          }
+          return result;
+        }
+        if (!state.haltedReason) {
+          await tx.execute(sql`update ${T.state} set halted_reason = 'auth', halted_at = ${nowAt}, updated_at = ${nowAt} where ${C.key} = ${key}`);
+          result.halted = 'auth';
+        }
+        return result;
+      }
+      const recentFailures = await failuresSince(tx, key, Math.max(nowMs - policy.circuitWindowMs, state.circuitOpenUntil.getTime()));
+      const open = circuitAfterFailure(state, { nowMs, recentFailures }, policy);
+      if (open) {
+        const until = new Date(nowMs + open.pauseMs);
+        await tx.execute(sql`update ${T.state} set circuit_open_until = ${until}, circuit_opens = circuit_opens + 1, updated_at = ${nowAt} where ${C.key} = ${key}`);
+        result.opened = { until: until.toISOString(), pauseMs: open.pauseMs, opens: state.circuitOpens + 1 };
+      }
+      return result;
+    });
+    report(outcome, { status, failureKind, where });
+    await db.execute(sql`delete from ${T.calls} where ${C.key} = ${key} and ${C.at} < ${new Date(nowMs - policy.telemetryRetentionMs)}`);
+    return outcome;
+  }
+
+  // One log.error per stop, so the error service gets one report each. A
+  // circuit that opens again after a failed probe is a warning: the first
+  // opening was reported.
+  function report(outcome, { status, failureKind, where }) {
+    if (!reports) return;
+    const cause = status ? `HTTP ${status}` : failureKind;
+    if (outcome.halted) log.error?.(`${tag} ${name} refused the connection (${cause}). Calls are stopped until a person checks the ${name} settings or connects again.`);
+    if (outcome.resourceStopped) log.error?.(`${tag} ${name} refused calls to ${where} (${cause}). Calls to ${where} are stopped until a person checks the connection.`);
+    if (outcome.opened) {
+      const line = `${tag} ${name} calls failed repeatedly (last: ${cause}${where ? ` on ${where}` : ''}). Calls pause until ${outcome.opened.until}.`;
+      if (outcome.opened.opens === 1) log.error?.(line);
+      else log.warn?.(line);
+    }
+    if (outcome.budgetSpent) log.error?.(`${tag} ${policy.dailyFailureBudget} ${name} calls failed today (last: ${cause}). Calls stop until ${outcome.budgetSpent.until}.`);
+  }
+
+  // Stops every call until resume(): for a refusal found outside a call, for
+  // example a credential the provider no longer accepts. Reported once.
+  async function halt(rawKey, reason = 'auth', { detail = null } = {}) {
+    const key = cleanKey(rawKey);
+    const nowAt = new Date(Number(now()));
+    const changed = await db.transaction(async (tx) => {
+      await lock(tx, key);
+      await ensureRow(tx, key);
+      const { rows } = await tx.execute(sql`update ${T.state} set halted_reason = ${String(reason).slice(0, 40)}, halted_at = ${nowAt}, updated_at = ${nowAt}
+        where ${C.key} = ${key} and halted_reason is null returning 1`);
+      return rows.length > 0;
+    });
+    if (changed && reports) log.error?.(`${tag} ${name} calls are stopped until a person checks the ${name} settings or connects again${detail ? ` (${detail})` : ''}.`);
+    return changed;
+  }
+
+  // A person acted: clear a halt and stopped resources, and close the
+  // circuit. The day's failure budget stays. No key: every key.
+  async function resume(rawKey = null) {
+    const nowAt = new Date(Number(now()));
+    if (rawKey === null) {
+      await db.execute(sql`update ${T.state} set halted_reason = null, halted_at = null, stopped_resources = '{}'::jsonb,
+        circuit_open_until = ${EPOCH}, circuit_opens = 0, updated_at = ${nowAt}`);
+      return;
+    }
+    const key = cleanKey(rawKey);
+    await ensureRow(db, key);
+    await db.execute(sql`update ${T.state} set halted_reason = null, halted_at = null, stopped_resources = '{}'::jsonb,
+      circuit_open_until = ${EPOCH}, circuit_opens = 0, updated_at = ${nowAt} where ${C.key} = ${key}`);
+  }
+
+  // What Settings and /health show, the same for every adapter.
+  async function status(rawKey) {
+    const key = cleanKey(rawKey);
+    const nowMs = Number(now());
+    const state = await readState(db, key);
+    const openUntil = state.circuitOpenUntil.getTime();
+    return {
+      circuit: state.haltedReason ? 'halted' : openUntil > nowMs ? 'open' : state.circuitOpens > 0 ? 'half_open' : 'closed',
+      circuitOpenUntil: openUntil > nowMs ? iso(openUntil) : null,
+      haltedReason: state.haltedReason,
+      haltedAt: iso(state.haltedAt),
+      stoppedResources: Object.entries(state.stoppedResources).map(([resource, entry]) => ({ resource, ...entry })),
+      failedToday: await failuresSince(db, key, startOfUtcDay(nowMs)),
+      dailyFailureBudget: policy.dailyFailureBudget,
+    };
+  }
+
+  return { integration, policy, check, stoppedNow, record, halt, resume, status };
+}

package/server/integrations/port.js

@@ -11,17 +11,23 @@ import { isMissingTable, migrateAdapterSchema } from './schema.js';
 
 export const CAPABILITIES = Object.freeze([
   'pullWorkItems', // billable work since a cursor (Seazona: completed cases)
+  'pullHistoryJobs', // past work from a history import, as ledger jobs marked historical (Seazona: its API backfill)
   'pushInvoice', // send an issued invoice; the Flow record id is the idempotency key
   'pushInvoices', // send several issued invoices in one pass (Send all ready, server/core/sending.js)
   'checkDrafts', // the accounting system's problems with Flow drafts, from its copy; null while not connected
+  'documentFacts', // what the customer's copy of a sent invoice says (number, reference, dates), from the system's copy in Flow; never a live call
   'sendStatus', // { connected, writesAllowed }: may Flow send invoices now?
   'pushBill', // send an approved bill; the Flow record id is the idempotency key
   'pullPayments', // payments since a cursor, matched to invoices and bills
   'checkInvoice', // does the accounting system hold an invoice for a billable job? (the ledger's liveCheck)
+  'jobReferenceFields', // { patient }: the fields a job gives the invoice Reference (server/core/references.js)
   'listWork', // the work system's jobs from its copy in Flow, open and lately finished, for the Jobs board
+  'jobIssues', // open issues the integration holds for jobs, by job ref: a short phrase and the page where a person fixes it
   'listCustomers', // the system's customers, by id and name, for the identity map (Seazona: clients; Xero: contacts)
   'findInvoices', // sales invoices in the accounting system's copy, for the matcher; never a live call
+  'listPriceItems', // the system's own price list from its copy in Flow, for the price list's links and check; never a live call
   'health', // connection state for Settings
+  'alerts', // what only a person can clear (a refused sign-in, stopped calls), for the Integrations page; reads Flow's data only
   'captureError', // an error Flow logged, sent to the installation's own error service (Sentry)
   'browserMonitoring', // the public settings a browser needs to report errors and problems to that service
 ]);
@@ -71,7 +77,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, setup } = adapter;
+  const { id, name, bundled = false, capabilities, schema, start, stop, routes, setup, callGuard } = adapter;
   if (typeof id !== 'string' || !ID_PATTERN.test(id)) {
     throw new TypeError(`Adapter id must match ${ID_PATTERN}`);
   }
@@ -108,6 +114,16 @@ export function defineAdapter(adapter) {
       throw new TypeError(`Adapter ${id} setup field ${field?.name} needs an upper-case setting name and a label`);
     }
   }
+  if (callGuard !== undefined && callGuard !== null) {
+    const { integration, tables } = callGuard;
+    if (integration !== id || !tables?.state || !tables?.calls) {
+      throw new TypeError(`Adapter ${id} callGuard must name integration ${id} and its tables.state and tables.calls`);
+    }
+    const owned = new Set(schema?.tables ?? []);
+    if (!owned.has(tables.state) || !owned.has(tables.calls)) {
+      throw new TypeError(`Adapter ${id} callGuard tables must be among its own schema tables`);
+    }
+  }
   return Object.freeze({
     id,
     name,
@@ -120,6 +136,10 @@ export function defineAdapter(adapter) {
     // stop() ends that work (tests, shutdown).
     start: start ?? null,
     stop: stop ?? null,
+    // The call guard (./call-guard.js) every outbound call goes through: the
+    // integration id, its two tables, and its policy. An adapter that calls
+    // an outside system declares it (docs/INTEGRATIONS.md, "Outbound calls").
+    callGuard: callGuard ? Object.freeze({ ...callGuard }) : null,
     // Optional HTTP routes: routes({ db, personAuth, log, messagePage }) returns a router
     // mounted at /api/<id> (registry.routes).
     routes: routes ?? null,

package/server/integrations/seazona/feed.js

@@ -1,7 +1,7 @@
 import { and, desc, eq, gte, isNull, or, sql } from 'drizzle-orm';
 import { ledgerLinesFor, toLedgerHold, toLedgerJob } from './ledger.js';
 import { isFinalStatus, orderStatusLabel, parseSeazonaDate } from './map.js';
-import { seazonaClients, seazonaInvoices, seazonaOrders } from './schema.js';
+import { seazonaClients, seazonaInvoices, seazonaOrders, seazonaReference } from './schema.js';
 
 // The billing feed behind the port's pullWorkItems: every order that changed
 // since a cursor, oldest change first. A complete or shipped order is an
@@ -11,9 +11,16 @@ import { seazonaClients, seazonaInvoices, seazonaOrders } from './schema.js';
 //
 // The cursor is opaque; pass back `cursor` from the last page. A change to
 // the order or to its invoice moves the order to the end of the feed.
+//
+// A read that found no change moves the order to the end of the feed too, at
+// most once an hour (`SEEN_STEP`). Without it, an order that never changes
+// is reported once, its ledger report gets older than a day, and the ledger
+// refuses its draft as "out of date" for ever, though the lanes read the
+// order every few minutes.
 
 const BILLABLE = /\b(complete|completed|shipped|delivered)\b/i;
 const SHIPPED = /\b(shipped|delivered)\b/i;
+const SEEN_STEP = 'hour';
 
 function decodeCursor(cursor) {
   if (!cursor) return null;
@@ -31,7 +38,7 @@ function encodeCursor(at, id) {
 
 export async function readBillableWork(db, { cursor = null, limit = 200 } = {}) {
   const after = decodeCursor(cursor);
-  const changedAt = sql`greatest(${seazonaOrders.lastChangedAt}, coalesce(${seazonaInvoices.lastChangedAt}, ${seazonaOrders.lastChangedAt}))`;
+  const changedAt = sql`greatest(${seazonaOrders.lastChangedAt}, coalesce(${seazonaInvoices.lastChangedAt}, ${seazonaOrders.lastChangedAt}), date_trunc(${SEEN_STEP}, ${seazonaOrders.lastSyncedAt}))`;
   const pageSize = Math.max(1, Math.min(1000, limit));
   const rows = await db.select({
     order: seazonaOrders,
@@ -125,6 +132,28 @@ export async function listClients(db) {
   ];
 }
 
+// Seazona's products, from Flow's copy (the products lane reads them daily),
+// for the price list's links and price check (server/core/price-list.js).
+// Seazona says only whether a product is taxable: taxable reads as GST.
+export async function listProducts(db) {
+  const rows = await db.select({
+    id: seazonaReference.id, code: seazonaReference.code, name: seazonaReference.name,
+    priceCents: seazonaReference.priceCents, taxable: seazonaReference.taxable, syncedAt: seazonaReference.lastSyncedAt,
+  }).from(seazonaReference).where(eq(seazonaReference.resource, 'products'));
+  return {
+    kind: 'work',
+    syncedAt: rows.reduce((at, r) => (!at || r.syncedAt > at ? r.syncedAt : at), null),
+    items: rows.map((r) => ({
+      id: r.id,
+      code: r.code,
+      name: r.name,
+      unitAmountCents: r.priceCents === null ? null : Number(r.priceCents),
+      taxCode: r.taxable === null ? null : (r.taxable ? 'GST' : 'GST_FREE'),
+      sold: true,
+    })),
+  };
+}
+
 // A final order (shipped, delivered, cancelled; map.js isFinalStatus) stays on
 // the Jobs board this long after it last changed.
 export const WORK_FINISHED_DAYS = 30;