@arcforgelabs/flow 2026.10.30 → 2026.10.32-beta.1

package/server/integrations/seazona/history/read.js

@@ -0,0 +1,196 @@
+import { hashOf, parseSeazonaDate, text } from '../map.js';
+
+// Seazona's CSV export, read into Flow fields and grouped into jobs. Pure: no
+// database and no network. docs/SEAZONA.md, "History import", lists the
+// headers Flow knows.
+
+// Flow field -> the headers Seazona's export may use for it. Headers compare
+// without case, spaces or punctuation, so "Invoice #" and "invoice no" match.
+// "Client Name" is left out on purpose: in Seazona it can mean the doctor or
+// the practice, so a person maps it with `columns` when the file has it.
+export const INVOICE_LINE_COLUMNS = Object.freeze({
+  invoiceNumber: ['invoice', 'invoice #', 'invoice number', 'invoice no', 'inv #', 'inv no'],
+  caseRef: ['case', 'case #', 'case number', 'case no', 'case id', 'order', 'order #', 'order number', 'order no', 'order id'],
+  jobDate: ['invoice date', 'date', 'date invoiced', 'invoiced'],
+  dueDate: ['due date', 'due'],
+  shippedDate: ['ship date', 'shipped', 'shipped date', 'date shipped'],
+  company: ['company name', 'company', 'practice', 'practice name', 'account name'],
+  accountNumber: ['account #', 'account number', 'account no'],
+  doctorName: ['doctor name', 'doctor', 'dentist', 'practitioner'],
+  patient: ['patient', 'patient name'],
+  status: ['status', 'case status'],
+  item: ['item', 'product', 'description', 'item description', 'product name', 'service'],
+  itemCode: ['item code', 'code', 'product code'],
+  quantity: ['qty', 'quantity', 'units'],
+  itemAmount: ['item amount', 'amount', 'line amount', 'line total', 'price'],
+  itemTaxable: ['item taxable', 'taxable'],
+  total: ['total', 'invoice total'],
+  tooth: ['tooth', 'teeth', 'tooth #'],
+});
+
+// A file is read only when it has these, and at least one date.
+const REQUIRED = ['company', 'item', 'itemAmount'];
+const DATES = ['jobDate', 'dueDate', 'shippedDate'];
+
+const squash = (header) => text(header).toLowerCase().replace(/[^a-z0-9#]/g, '').replace(/#/g, 'number');
+
+// Answers { columns: field -> header, ignored: [header], missing: [field] }.
+// `override` (field -> header) wins over the guess; a null value unmaps it.
+export function detectColumns(headers, override = {}) {
+  const byKey = new Map(headers.map((h) => [squash(h), h]));
+  const columns = {};
+  for (const [field, aliases] of Object.entries(INVOICE_LINE_COLUMNS)) {
+    const found = aliases.map((alias) => byKey.get(squash(alias))).find(Boolean);
+    if (found) columns[field] = found;
+  }
+  for (const [field, header] of Object.entries(override ?? {})) {
+    if (!(field in INVOICE_LINE_COLUMNS)) throw Object.assign(new Error(`Unknown field ${field}`), { code: 'invalid' });
+    if (header === null) delete columns[field];
+    else if (headers.includes(header)) columns[field] = header;
+    else throw Object.assign(new Error(`The file has no column "${header}"`), { code: 'invalid' });
+  }
+  const used = new Set(Object.values(columns));
+  const missing = REQUIRED.filter((field) => !columns[field]);
+  if (!DATES.some((field) => columns[field])) missing.push('date');
+  return { columns, ignored: headers.filter((h) => h && !used.has(h)), missing };
+}
+
+// "$1,234.50", "1234.5", "(12.00)" and "-12" to integer cents.
+export function moneyCents(value) {
+  const raw = text(value);
+  if (!raw) return null;
+  const negative = /^\(.*\)$/.test(raw) || raw.startsWith('-');
+  const digits = raw.replace(/[()$,\s-]/g, '').replace(/^[A-Z]{3}/i, '');
+  if (!/^\d*(\.\d+)?$/.test(digits) || digits === '' || digits === '.') return undefined;
+  const cents = Math.round(Number(digits) * 100);
+  return negative ? -cents : cents;
+}
+
+function yesNo(value) {
+  const raw = text(value).toLowerCase();
+  if (['y', 'yes', 'true', '1', 'taxable', 'gst'].includes(raw)) return true;
+  if (['n', 'no', 'false', '0', 'exempt', 'gst free', 'none'].includes(raw)) return false;
+  return null;
+}
+
+// One CSV row to Flow fields and the problems that stop it. The patient field
+// is read for grouping; the caller drops it unless the installation keeps a
+// patient reference.
+export function readRow(cells, headers, columns) {
+  const cell = (field) => {
+    const header = columns[field];
+    if (!header) return '';
+    return text(cells[headers.indexOf(header)]);
+  };
+  const problems = [];
+  const fields = {
+    invoiceNumber: cell('invoiceNumber') || null,
+    caseRef: cell('caseRef') || null,
+    company: cell('company') || null,
+    accountNumber: cell('accountNumber') || null,
+    doctorName: cell('doctorName') || null,
+    patient: cell('patient') || null,
+    status: cell('status') || null,
+    item: cell('item') || null,
+    itemCode: cell('itemCode') || null,
+    tooth: cell('tooth') || null,
+  };
+  for (const field of DATES) {
+    const raw = cell(field);
+    fields[field] = raw ? parseSeazonaDate(raw) : null;
+    if (raw && !fields[field]) problems.push(`bad_${field}`);
+  }
+  if (!DATES.some((field) => fields[field])) problems.push('missing_date');
+  if (!fields.company) problems.push('missing_company');
+  if (!fields.item) problems.push('missing_item');
+  const amount = moneyCents(cell('itemAmount'));
+  if (amount === undefined || amount === null) problems.push(amount === null ? 'missing_amount' : 'bad_amount');
+  fields.itemAmountCents = typeof amount === 'number' ? amount : null;
+  const total = moneyCents(cell('total'));
+  if (total === undefined) problems.push('bad_total');
+  fields.totalCents = typeof total === 'number' ? total : null;
+  const quantity = cell('quantity');
+  fields.quantity = quantity && Number.isFinite(Number(quantity)) ? Number(quantity) : null;
+  fields.itemTaxable = columns.itemTaxable ? yesNo(cell('itemTaxable')) : null;
+  return { fields, problems };
+}
+
+const sameText = (a, b) => text(a).toLowerCase() === text(b).toLowerCase();
+
+// Where a row's job is found: its invoice number, else its case number, else
+// the old app's grouping (date, practice, doctor and patient). The patient
+// only separates jobs inside this file; it is never part of the stored key.
+function groupOf(fields) {
+  if (fields.invoiceNumber) return `inv:${fields.invoiceNumber}`;
+  if (fields.caseRef) return `case:${fields.caseRef}`;
+  const date = fields.jobDate ?? fields.dueDate ?? fields.shippedDate;
+  return `grp:${[date, fields.company, fields.doctorName, fields.patient].map((v) => text(v).toLowerCase()).join('|')}`;
+}
+
+const withGst = (cents) => Math.round(cents * 1.1);
+
+// Rows (each { rowNumber, fields, problems }) to jobs. Rows with problems
+// join no job. Answers { jobs, rowKeys: Map(rowNumber -> jobKey) }. Each job
+// carries its findings: { code, blocking }.
+export function groupJobs(rows) {
+  const groups = new Map();
+  for (const row of rows) {
+    if (row.problems.length) continue;
+    const group = groupOf(row.fields);
+    if (!groups.has(group)) groups.set(group, []);
+    groups.get(group).push(row);
+  }
+  const jobs = [];
+  const rowKeys = new Map();
+  const taken = new Map();
+  for (const [group, members] of groups) {
+    const first = members[0].fields;
+    const findings = [];
+    for (const field of ['company', 'doctorName']) {
+      if (members.some((m) => !sameText(m.fields[field], first[field]))) findings.push({ code: `mixed_${field}`, blocking: true });
+    }
+    const totals = [...new Set(members.map((m) => m.fields.totalCents).filter((t) => t !== null))];
+    if (totals.length > 1) findings.push({ code: 'conflicting_totals', blocking: true });
+    const lines = members.map((m) => ({
+      description: m.fields.item,
+      code: m.fields.itemCode,
+      amountCents: m.fields.itemAmountCents,
+      ...(m.fields.quantity !== null ? { quantity: m.fields.quantity } : {}),
+      ...(m.fields.itemTaxable !== null ? { taxable: m.fields.itemTaxable } : {}),
+      ...(m.fields.tooth ? { tooth: m.fields.tooth } : {}),
+    }));
+    const subtotalCents = lines.reduce((sum, l) => sum + l.amountCents, 0);
+    const totalCents = totals.length === 1 ? totals[0] : null;
+    if (totalCents !== null && totalCents !== subtotalCents && totalCents !== withGst(subtotalCents)) {
+      const taxable = lines.filter((l) => l.taxable !== false).reduce((sum, l) => sum + l.amountCents, 0);
+      if (totalCents !== subtotalCents + Math.round(taxable * 0.1)) findings.push({ code: 'total_differs_from_lines', blocking: false });
+    }
+    const pick = (field) => members.map((m) => m.fields[field]).find(Boolean) ?? null;
+    const job = {
+      invoiceNumber: pick('invoiceNumber'),
+      caseRef: pick('caseRef'),
+      company: first.company,
+      accountNumber: pick('accountNumber'),
+      doctorName: first.doctorName,
+      status: pick('status'),
+      jobDate: pick('jobDate'),
+      dueDate: pick('dueDate'),
+      shippedDate: pick('shippedDate'),
+      lines,
+      subtotalCents,
+      totalCents,
+      patientReference: pick('patient'),
+    };
+    // A job with no Seazona number is keyed by what it is, without the patient.
+    let key = group;
+    if (group.startsWith('grp:')) {
+      const base = `grp:${hashOf({ ...job, patientReference: null }).slice(0, 24)}`;
+      const n = (taken.get(base) ?? 0) + 1;
+      taken.set(base, n);
+      key = n === 1 ? base : `${base}#${n}`;
+    }
+    jobs.push({ jobKey: key, job, findings });
+    for (const m of members) rowKeys.set(m.rowNumber, key);
+  }
+  return { jobs, rowKeys };
+}

package/server/integrations/seazona/index.js

@@ -1,6 +1,10 @@
+import { guardAlerts } from '../call-guard.js';
 import { createSeazonaClient } from './client.js';
-import { listClients, listWork, readBillableWork } from './feed.js';
+import { listClients, listProducts, listWork, readBillableWork } from './feed.js';
+import { historyJobIssues, historySummary, readHistoryWork } from './history/index.js';
 import { readSeazonaSyncHealth, runSeazonaSync } from './lanes.js';
+import { SEAZONA_CALL_GUARD } from './governor.js';
+import { createSeazonaRouter } from './routes.js';
 import { createSeazonaScheduler } from './scheduler.js';
 import { resetFailedLanes, resetStoppedLanes } from './store.js';
 import { describeSeazonaSettings, resolveSeazonaSettings } from './settings.js';
@@ -58,6 +62,11 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
     bundled: true,
     schema: seazonaSchema,
     setup: SEAZONA_SETUP,
+    // The history import's routes (routes.js), under /api/seazona.
+    routes: ({ db, personAuth, log }) => createSeazonaRouter({ db: runtime?.db ?? db, personAuth, settings: current().settings, log }),
+    // Every Seazona call goes through this call guard, inside the rate
+    // governor (governor.js; docs/INTEGRATIONS.md, "Outbound calls").
+    callGuard: SEAZONA_CALL_GUARD,
 
     // `reconfigured` is true when a person saved the settings or turned
     // Seazona on (issue #101): that clears a halt after a refused API client,
@@ -102,9 +111,18 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
           scheduler: scheduler ? scheduler.status() : null,
           governor: await client.governor.status(),
           ...sync,
+          history: await historySummary(db),
         };
       },
 
+      // What only a person can clear, for the Integrations page
+      // (server/core/alerts.js): a refused API client halts every call until
+      // a person saves the settings. Reads Flow's database only.
+      async alerts() {
+        if (!runtime?.client.governor) return [];
+        return guardAlerts('Seazona', await runtime.client.governor.status(), { fix: 'Check the API client in the Seazona settings, then save them.' });
+      },
+
       // Billable work since a cursor: complete and shipped orders that
       // changed, with the Seazona invoice that carries each one. Orders
       // deleted in Seazona are never billable; they come back in `withdrawn`
@@ -113,6 +131,12 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
         return readBillableWork(current().db, { cursor, ...options });
       },
 
+      // Past work from the history import (docs/SEAZONA.md, "History
+      // import"), as ledger jobs marked `historical`. Reads Flow's copy only.
+      async pullHistoryJobs(cursor = null, options = {}) {
+        return readHistoryWork(current().db, { cursor, ...options });
+      },
+
       // Seazona clients by id and company name, for the identity map. Reads
       // Flow's copy only.
       async listCustomers() {
@@ -124,6 +148,18 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
       async listWork() {
         return listWork(current().db, { now: now() });
       },
+
+      // History jobs a person must decide, as issues on their job cards,
+      // each with a link to the reconciliation. Reads Flow's copy only.
+      async jobIssues({ refs = [] } = {}) {
+        return historyJobIssues(current().db, refs);
+      },
+
+      // Seazona's products, for the price list (server/core/price-list.js).
+      // Reads Flow's copy only.
+      async listPriceItems() {
+        return listProducts(current().db);
+      },
     },
   };
 }

package/server/integrations/seazona/lanes.js

@@ -9,6 +9,7 @@ import {
   orderListSignature,
   text,
 } from './map.js';
+import { runHistoryBackfill } from './history/backfill.js';
 import { seazonaOrders } from './schema.js';
 import {
   claimLane,
@@ -38,12 +39,18 @@ import {
 //   clients        changed clients since a cursor, every 30 min
 //   products       the product list, daily
 //   users          the lab user list, daily
+//   history        past orders, a few calls per run, only while a person
+//                  has started a backfill (history/backfill.js)
 //
 // Issue #12 holds for every order read: a 404 marks the order deleted in
 // Seazona, an empty answer is a failure, each failure is recorded per order
 // and quarantines it after a few in a row, and a lane fails only when most of
 // its reads fail. Errors and /health name each failing order and its status.
 //
+// Issue #125: a list at the row cap is read on, not held: invoices and
+// clients from the last row they answered, orders page by page. A lane holds
+// only where Seazona gives no way on.
+//
 // Issue #101 holds for every lane: invoices and clients quarantine a record
 // after a few failed reads too, so one bad record never holds a cursor. A
 // list call that Seazona refuses (400, 401, 403, 404) means the path or the
@@ -51,36 +58,47 @@ import {
 // only after a person saves the settings or Flow restarts on a new release.
 // Calls the governor stopped (SeazonaCallsStopped) wait out its pause.
 
-export const LANES = Object.freeze(['invoices', 'orders_recent', 'orders_active', 'clients', 'products', 'users']);
+export const LANES = Object.freeze(['invoices', 'orders_recent', 'orders_active', 'clients', 'products', 'users', 'history']);
 
 const DAY_MS = 24 * 60 * 60_000;
 const MAX_REPORTED = 25;
 const FINAL_STATUS_PATTERN = 'shipped|delivered|cancelled|canceled|void|closed|archived|deleted';
 
 class LaneError extends Error {
-  constructor(message, { code, details = null, held = false, retryAfterMs = null } = {}) {
+  constructor(message, { code, details = null, held = false, retryAfterMs = null, progress = null } = {}) {
     super(message);
     this.code = code;
     this.details = details;
     this.held = held;
     this.retryAfterMs = retryAfterMs;
+    // What the lane read before it stopped: { cursor }, kept with the failure.
+    this.progress = progress;
   }
 }
 
-function listOrFail(list, what, sync) {
+function listOrFail(list, what) {
   if (!Array.isArray(list)) throw new LaneError(`Seazona ${what} answer was not a list`, { code: 'seazona_list_invalid' });
-  // Seazona documents no paging. A list exactly at the cap may be cut off,
-  // so hold the cursor rather than trust it.
-  if (list.length === sync.listCap) {
-    throw new LaneError(`Seazona ${what} answer has exactly ${sync.listCap} rows and may be cut off; the cursor is held`, {
-      code: 'seazona_list_at_cap',
-      held: true,
-      details: { observedCount: list.length, listCap: sync.listCap },
-    });
-  }
   return list;
 }
 
+// Issue #125: a list at the cap is read on, page by page or from its last
+// row. The lane holds only where it cannot go on.
+function cannotGoOn(what, sync, reason, progress) {
+  return new LaneError(`Seazona ${what} answer is full (${sync.listCap} rows) and cannot be read further (${reason}); the cursor is held`, {
+    code: 'seazona_list_at_cap',
+    held: true,
+    details: { listCap: sync.listCap, reason },
+    progress,
+  });
+}
+
+// Seazona writes lastModified in UTC with no zone suffix.
+function parseUtc(value) {
+  const stamp = text(value);
+  if (!stamp) return NaN;
+  return Date.parse(/[zZ]|[+-]\d\d:?\d\d$/.test(stamp) ? stamp : `${stamp}Z`);
+}
+
 // A failure that is about Seazona or the rate limit, not one record: the
 // whole lane stops and waits.
 function isLaneLevel(error) {
@@ -239,9 +257,67 @@ async function syncListWithDetail(ctx, { mirror, what, items, keyOf, idOf, signa
   return { summary, detailReads, listCount: items.length, failureDetails, anyFailed, newlyQuarantined, quarantined: skipped.length };
 }
 
-function cursorSince(ctx, fallbackMs) {
+// Where the next changed-list read starts. A run that stopped inside a
+// window keeps the exact start of the next part (`cursor.since`); otherwise
+// the last finished run's start, less the overlap.
+function cursorSince(ctx, fallback) {
+  const exact = ctx.state?.cursor?.since;
+  if (typeof exact === 'string') return exact;
   const cursorMs = ctx.state?.cursorTime?.getTime();
-  return new Date(Number.isFinite(cursorMs) ? cursorMs - ctx.sync.cursorOverlapMs : fallbackMs).toISOString();
+  return Number.isFinite(cursorMs) ? new Date(cursorMs - ctx.sync.cursorOverlapMs).toISOString() : fallback;
+}
+
+function mergeDetails(total, details) {
+  if (!details) return total;
+  if (!total) return details;
+  return {
+    ...total,
+    attempted: (total.attempted ?? 0) + (details.attempted ?? 0),
+    failed: (total.failed ?? 0) + (details.failed ?? 0),
+    failures: [...(total.failures ?? []), ...(details.failures ?? [])].slice(0, MAX_REPORTED),
+    ...(total.quarantinedIds || details.quarantinedIds
+      ? { quarantinedIds: [...(total.quarantinedIds ?? []), ...(details.quarantinedIds ?? [])].slice(0, MAX_REPORTED) }
+      : {}),
+  };
+}
+
+// Invoices and clients: Seazona answers changes since a time in one list,
+// with no paging, cut at the cap. The guide says the invoice list answers
+// changes on or after the time, oldest first, so a full list is one part of
+// the window: the next part starts at its last row (less `stepBackMs`, for a
+// list that answers strictly after). Rows out of order, or a full list inside
+// one second, cannot go on: the lane holds, and keeps where it got to. A run
+// reads at most `listPagesPerRun` parts; the next run goes on from the exact
+// start it stored.
+async function walkChangedList(ctx, { what, firstSince, stepBackMs, list, read }) {
+  const { sync, at, state } = ctx;
+  const total = { summary: { created: 0, changed: 0, unchanged: 0 }, detailReads: 0, listCount: 0, failureDetails: null, newlyQuarantined: 0, quarantined: 0 };
+  let since = firstSince;
+  for (let pages = 1; ; pages += 1) {
+    const items = listOrFail(await list(since), `${what} list`);
+    const result = await read(items);
+    addSummary(total.summary, result.summary);
+    total.detailReads += result.detailReads;
+    total.listCount += result.listCount;
+    total.newlyQuarantined += result.newlyQuarantined;
+    total.quarantined += result.quarantined;
+    total.failureDetails = mergeDetails(total.failureDetails, result.failureDetails);
+    const keep = { ...total, pages, since: firstSince || null };
+    // A failed read keeps this part's start, so the next run reads it again.
+    if (result.anyFailed) return { ...keep, anyFailed: true, cursorTime: state?.cursorTime ?? null, cursor: { since } };
+    if (items.length < sync.listCap) return { ...keep, cursorTime: at, cursor: {} };
+    const sinceMs = since ? parseUtc(since) : -Infinity;
+    let lastMs = -Infinity;
+    for (const item of items) {
+      const ms = parseUtc(item?.lastModified);
+      if (!Number.isFinite(ms) || ms < lastMs) throw cannotGoOn(`${what} list`, sync, 'rows are not oldest first', { cursor: { since } });
+      lastMs = ms;
+    }
+    const next = lastMs - stepBackMs;
+    if (!(next > sinceMs)) throw cannotGoOn(`${what} list`, sync, 'one second holds more than the cap', { cursor: { since } });
+    since = new Date(next).toISOString();
+    if (pages >= sync.listPagesPerRun) return { ...keep, cursorTime: state?.cursorTime ?? null, cursor: { since } };
+  }
 }
 
 const floorUtcDay = (ms) => {
@@ -255,24 +331,43 @@ export function formatOrderedDay(ms) {
   return new Date(floorUtcDay(ms)).toISOString().replace(/\.\d{3}Z$/, '');
 }
 
+// The guide's largest order page.
+const ORDER_PAGE_MAX = 500;
+
+// True when an order row was placed on a later day than `dayMs` (the start
+// of a UTC day). `ordered` is the lab's local time with no zone, written
+// yyyy-MM-ddTHH:mm:ss or dd/MM/yyyy; this compares calendar days only, so a
+// lab ahead of UTC never ends a day early. Unknown dates are not after.
+function placedAfter(item, dayMs) {
+  const raw = text(item?.ordered);
+  const iso = /^(\d{4})-(\d{2})-(\d{2})/.exec(raw);
+  const local = /^(\d{2})\/(\d{2})\/(\d{4})/.exec(raw);
+  const placed = iso ? Date.UTC(+iso[1], +iso[2] - 1, +iso[3]) : local ? Date.UTC(+local[3], +local[2] - 1, +local[1]) : NaN;
+  return Number.isFinite(placed) && placed > dayMs;
+}
+
 const laneRuns = {
   async invoices(ctx) {
     const { client, sync, at } = ctx;
-    const since = cursorSince(ctx, floorUtcDay(at.getTime()) - sync.invoiceLookbackDays * DAY_MS);
-    const items = listOrFail(await client.get('invoices/', { lastModified: since }), 'invoice list', sync);
+    const firstSince = cursorSince(ctx, new Date(floorUtcDay(at.getTime()) - sync.invoiceLookbackDays * DAY_MS).toISOString());
     const mapOptions = { keepPatientReference: sync.keepPatientReference };
-    const result = await syncListWithDetail(ctx, {
-      mirror: 'invoices',
+    return walkChangedList(ctx, {
       what: 'invoice',
-      items,
-      keyOf: (item) => text(item?.invoiceNumber),
-      idOf: (item) => text(item?.id),
-      signatureOf: invoiceListSignature,
-      detailPath: (id) => `invoices/${encodeURIComponent(id)}`,
-      map: (item, detail) => mapInvoice(item, detail, mapOptions),
+      firstSince,
+      // The guide: on or after lastModified (inclusive).
+      stepBackMs: 0,
+      list: (since) => client.get('invoices/', { lastModified: since }),
+      read: (items) => syncListWithDetail(ctx, {
+        mirror: 'invoices',
+        what: 'invoice',
+        items,
+        keyOf: (item) => text(item?.invoiceNumber),
+        idOf: (item) => text(item?.id),
+        signatureOf: invoiceListSignature,
+        detailPath: (id) => `invoices/${encodeURIComponent(id)}`,
+        map: (item, detail) => mapInvoice(item, detail, mapOptions),
+      }),
     });
-    // A failed invoice read keeps the cursor, so the next run reads it again.
-    return { ...result, cursorTime: result.anyFailed ? ctx.state?.cursorTime ?? null : at, since };
   },
 
   async orders_recent(ctx) {
@@ -280,15 +375,44 @@ const laneRuns = {
     const nowMs = at.getTime();
     const lookbackStart = floorUtcDay(nowMs - sync.orderLookbackDays * DAY_MS);
     const doneThrough = Date.parse(ctx.state?.cursor?.completedThrough ?? '');
-    // Re-read the last finished day as well, so late orders on it are seen.
-    const resume = Number.isFinite(doneThrough) ? Math.max(lookbackStart, doneThrough) : lookbackStart;
-    const days = [];
-    for (let day = floorUtcDay(resume); day <= floorUtcDay(nowMs) && days.length < sync.orderDaysPerRun; day += DAY_MS) days.push(day);
+    const partial = ctx.state?.cursor?.partial;
+    const partialDay = Date.parse(partial?.day ?? '');
+    // Go on inside a day a run did not finish; otherwise re-read the last
+    // finished day as well, so late orders on it are seen.
+    const resumeInside = Number.isFinite(partialDay) && partialDay >= lookbackStart;
+    const resume = resumeInside ? partialDay : Number.isFinite(doneThrough) ? Math.max(lookbackStart, doneThrough) : lookbackStart;
 
+    // Issue #125: the list is paged (page, pageSize). A full page goes on to
+    // the next page; a short page, or a page past the day, ends the day. The
+    // guide says the list answers orders on or after `ordered`; a list that
+    // answers one day works the same way.
+    const pageSize = Math.min(ORDER_PAGE_MAX, sync.listCap);
     const byId = new Map();
-    for (const day of days) {
-      const list = listOrFail(await client.get('orders/', { ordered: formatOrderedDay(day) }), `order list for ${formatOrderedDay(day)}`, sync);
-      for (const item of list) if (text(item?.id)) byId.set(text(item.id), item);
+    const days = [];
+    let calls = 0;
+    let lastDone = null;
+    let stoppedAt = null;
+    for (let day = floorUtcDay(resume); day <= floorUtcDay(nowMs) && days.length < sync.orderDaysPerRun && !stoppedAt; day += DAY_MS) {
+      const label = `order list for ${formatOrderedDay(day)}`;
+      let page = resumeInside && day === floorUtcDay(resume) ? Math.max(1, Number(partial.page) || 1) : 1;
+      let previous = null;
+      for (;;) {
+        if (calls >= sync.listPagesPerRun) {
+          stoppedAt = { day, page };
+          break;
+        }
+        calls += 1;
+        if (!days.includes(day)) days.push(day);
+        const list = listOrFail(await client.get('orders/', { ordered: formatOrderedDay(day), page, pageSize }), label);
+        const ids = list.map((item) => text(item?.id)).filter(Boolean);
+        // A Seazona that does not page answers the same rows again.
+        if (previous && ids.length && ids.every((id) => previous.has(id))) throw cannotGoOn(label, sync, 'the next page answers the same orders');
+        for (const item of list) if (text(item?.id)) byId.set(text(item.id), item);
+        if (list.length < pageSize || placedAfter(list[list.length - 1], day + DAY_MS)) break;
+        previous = new Set(ids);
+        page += 1;
+      }
+      if (!stoppedAt) lastDone = day;
     }
     const known = await readKnown(db, 'orders', [...byId.keys()]);
     const summary = { created: 0, changed: 0, unchanged: 0 };
@@ -312,16 +436,20 @@ const laneRuns = {
     await touchSynced(db, 'orders', unchanged, { at });
     summary.unchanged += unchanged.length;
     const failureDetails = judgeReads('recent order reads', detailReads, failures);
-    const lastDay = days.length ? days[days.length - 1] : floorUtcDay(nowMs);
+    const through = lastDone ?? (Number.isFinite(doneThrough) ? doneThrough : null);
     return {
       summary,
       detailReads,
       listCount: byId.size,
+      listCalls: calls,
       days: days.map(formatOrderedDay),
       deletedIds: deleted,
       failureDetails,
-      cursorTime: new Date(lastDay),
-      cursor: { completedThrough: new Date(lastDay).toISOString() },
+      cursorTime: through === null ? ctx.state?.cursorTime ?? null : new Date(through),
+      cursor: {
+        ...(through === null ? {} : { completedThrough: new Date(through).toISOString() }),
+        ...(stoppedAt ? { partial: { day: new Date(stoppedAt.day).toISOString(), page: stoppedAt.page } } : {}),
+      },
     };
   },
 
@@ -356,33 +484,40 @@ const laneRuns = {
   },
 
   async clients(ctx) {
-    const { client, sync, at } = ctx;
+    const { client } = ctx;
     // The first run reads the whole list; later runs read changes only.
     // Seazona answers the whole list only to an empty `?lastModified=`; a
     // bare path is a 404.
-    const since = ctx.state?.cursorTime ? cursorSince(ctx, 0) : '';
-    const reply = since ? await client.get('clients/', { lastModified: since }) : await client.get('clients/?lastModified=');
-    const items = listOrFail(reply, 'client list', sync);
-    const result = await syncListWithDetail(ctx, {
-      mirror: 'clients',
+    return walkChangedList(ctx, {
       what: 'client',
-      items,
-      keyOf: (item) => text(item?.id),
-      idOf: (item) => text(item?.id),
-      signatureOf: clientListSignature,
-      detailPath: (id) => `clients/${encodeURIComponent(id)}`,
-      map: (item, detail) => mapClient(item, detail),
+      firstSince: cursorSince(ctx, ''),
+      // The guide says "modified after": step back a second so a row in the
+      // last row's second is not lost.
+      stepBackMs: 1000,
+      list: (since) => (since ? client.get('clients/', { lastModified: since }) : client.get('clients/?lastModified=')),
+      read: (items) => syncListWithDetail(ctx, {
+        mirror: 'clients',
+        what: 'client',
+        items,
+        keyOf: (item) => text(item?.id),
+        idOf: (item) => text(item?.id),
+        signatureOf: clientListSignature,
+        detailPath: (id) => `clients/${encodeURIComponent(id)}`,
+        map: (item, detail) => mapClient(item, detail),
+      }),
     });
-    return { ...result, cursorTime: result.anyFailed ? ctx.state?.cursorTime ?? null : at, since: since || null };
   },
 
+  history: (ctx) => runHistoryBackfill(ctx, { isLaneLevel, describeReadFailure, emptyResponse, LaneError }),
   products: (ctx) => syncReference(ctx, 'products'),
   users: (ctx) => syncReference(ctx, 'users'),
 };
 
 async function syncReference(ctx, resource) {
   const { db, client, sync, at } = ctx;
-  const list = listOrFail(await client.get(`${resource}/`), `${resource} list`, sync);
+  const list = listOrFail(await client.get(`${resource}/`), `${resource} list`);
+  // The whole list in one answer, with no paging and no way to read on.
+  if (list.length === sync.listCap) throw cannotGoOn(`${resource} list`, sync, 'the list has no paging');
   const records = list.map((item) => mapReference(resource, item)).filter((record) => record.id);
   const { stored } = await upsertReference(db, resource, records, { at });
   return { listCount: list.length, stored, cursorTime: at };
@@ -439,6 +574,7 @@ export async function runSeazonaSync(db, client, { settings, now = Date.now, onl
         status,
         lastAttemptAt: at,
         nextRunAt: delayMs === null ? null : new Date(Number(now()) + delayMs),
+        ...(error?.progress?.cursor ? { cursor: error.progress.cursor } : {}),
         failureCount: (state?.failureCount ?? 0) + 1,
         lastError: message,
         failureDetails: error?.details ?? (Number.isInteger(error?.statusCode) ? { httpStatus: error.statusCode, path: error.path ?? null } : null),

package/server/integrations/seazona/migrations/0003_call_guard.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "seazona_api_governor" ADD COLUMN IF NOT EXISTS "stopped_resources" jsonb DEFAULT '{}'::jsonb NOT NULL;--> statement-breakpoint
+ALTER TABLE "seazona_api_requests" ADD COLUMN IF NOT EXISTS "resource" text;