@arcforgelabs/flow 2026.10.32 → 2026.10.34

package/server/integrations/seazona/lanes.js

@@ -11,6 +11,7 @@ import {
 } from './map.js';
 import { runHistoryBackfill } from './history/backfill.js';
 import { seazonaOrders } from './schema.js';
+import { runSweep } from './sweep.js';
 import {
   claimLane,
   clearOrderFailure,
@@ -22,6 +23,8 @@ import {
   readQuarantinedOrders,
   readQuarantinedRecordCounts,
   readQuarantinedRecords,
+  readRecordRereadCounts,
+  readRecordsDueForReread,
   recordOrderFailure,
   recordRecordFailure,
   selectActiveOrders,
@@ -41,6 +44,8 @@ import {
 //   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)
+//   sweep          whole lists again, slowly, for what the others missed
+//                  (issue #126, sweep.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
@@ -58,7 +63,7 @@ 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', 'history']);
+export const LANES = Object.freeze(['invoices', 'orders_recent', 'orders_active', 'clients', 'products', 'users', 'history', 'sweep']);
 
 const DAY_MS = 24 * 60 * 60_000;
 const MAX_REPORTED = 25;
@@ -237,6 +242,7 @@ async function syncListWithDetail(ctx, { mirror, what, items, keyOf, idOf, signa
           at,
           quarantineFailures: sync.orderQuarantineFailures,
           quarantineMs: sync.orderQuarantineMs,
+          detailId: id,
         });
         if (recorded.quarantinedUntil) newlyQuarantined += 1;
         failures.push({ id: key, ...failure, ...recorded });
@@ -257,6 +263,52 @@ async function syncListWithDetail(ctx, { mirror, what, items, keyOf, idOf, signa
   return { summary, detailReads, listCount: items.length, failureDetails, anyFailed, newlyQuarantined, quarantined: skipped.length };
 }
 
+// Issue #142: a quarantined invoice or client is in a later list only if it
+// changes again, so when its wait ends the lane reads its detail by id. A
+// success stores it and clears the failure; a 404 clears the failure (the
+// record is gone, issue #126); a failure quarantines it again, with no new
+// report. Each read goes through the call guard like any other.
+async function rereadReleased(ctx, { mirror, what, detailPath, map }) {
+  const { db, client, sync, at } = ctx;
+  const due = sync.recordRereadsPerRun ? await readRecordsDueForReread(db, mirror, { at, limit: sync.recordRereadsPerRun }) : [];
+  const result = { summary: { created: 0, changed: 0, unchanged: 0 }, detailReads: 0, reread: 0, gone: 0, failed: 0 };
+  for (const row of due) {
+    result.detailReads += 1;
+    try {
+      const detail = await client.get(detailPath(row.detailId));
+      if (!detail || typeof detail !== 'object' || Array.isArray(detail)) throw emptyResponse(`${what} ${row.recordKey}`);
+      addSummary(result.summary, await upsertRecords(db, mirror, [map(detail)], { at }));
+      await clearRecordFailures(db, mirror, [row.recordKey]);
+      result.reread += 1;
+    } catch (error) {
+      if (isLaneLevel(error)) throw error;
+      if (error?.statusCode === 404) {
+        await clearRecordFailures(db, mirror, [row.recordKey]);
+        result.gone += 1;
+        continue;
+      }
+      await recordRecordFailure(db, mirror, row.recordKey, describeReadFailure(error), {
+        at,
+        quarantineFailures: sync.orderQuarantineFailures,
+        quarantineMs: sync.orderQuarantineMs,
+      });
+      result.failed += 1;
+    }
+  }
+  return result;
+}
+
+// Adds the re-reads to a lane's result.
+function withRereads(result, reread) {
+  if (!reread.detailReads) return result;
+  addSummary(result.summary, reread.summary);
+  return {
+    ...result,
+    detailReads: result.detailReads + reread.detailReads,
+    rereads: { attempted: reread.detailReads, read: reread.reread, gone: reread.gone, failed: reread.failed },
+  };
+}
+
 // 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.
@@ -351,7 +403,13 @@ const laneRuns = {
     const { client, sync, at } = ctx;
     const firstSince = cursorSince(ctx, new Date(floorUtcDay(at.getTime()) - sync.invoiceLookbackDays * DAY_MS).toISOString());
     const mapOptions = { keepPatientReference: sync.keepPatientReference };
-    return walkChangedList(ctx, {
+    const reread = await rereadReleased(ctx, {
+      mirror: 'invoices',
+      what: 'invoice',
+      detailPath: (id) => `invoices/${encodeURIComponent(id)}`,
+      map: (detail) => mapInvoice({}, detail, mapOptions),
+    });
+    return withRereads(await walkChangedList(ctx, {
       what: 'invoice',
       firstSince,
       // The guide: on or after lastModified (inclusive).
@@ -367,7 +425,7 @@ const laneRuns = {
         detailPath: (id) => `invoices/${encodeURIComponent(id)}`,
         map: (item, detail) => mapInvoice(item, detail, mapOptions),
       }),
-    });
+    }), reread);
   },
 
   async orders_recent(ctx) {
@@ -485,10 +543,16 @@ const laneRuns = {
 
   async clients(ctx) {
     const { client } = ctx;
+    const reread = await rereadReleased(ctx, {
+      mirror: 'clients',
+      what: 'client',
+      detailPath: (id) => `clients/${encodeURIComponent(id)}`,
+      map: (detail) => mapClient({}, detail),
+    });
     // 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.
-    return walkChangedList(ctx, {
+    return withRereads(await walkChangedList(ctx, {
       what: 'client',
       firstSince: cursorSince(ctx, ''),
       // The guide says "modified after": step back a second so a row in the
@@ -505,10 +569,11 @@ const laneRuns = {
         detailPath: (id) => `clients/${encodeURIComponent(id)}`,
         map: (item, detail) => mapClient(item, detail),
       }),
-    });
+    }), reread);
   },
 
   history: (ctx) => runHistoryBackfill(ctx, { isLaneLevel, describeReadFailure, emptyResponse, LaneError }),
+  sweep: (ctx) => runSweep(ctx, { readOrder, isLaneLevel, describeReadFailure, emptyResponse, LaneError }),
   products: (ctx) => syncReference(ctx, 'products'),
   users: (ctx) => syncReference(ctx, 'users'),
 };
@@ -589,20 +654,27 @@ export async function runSeazonaSync(db, client, { settings, now = Date.now, onl
 // What /health shows for the sync: each lane's state, the failing and
 // quarantined orders by id and status, and how many orders are marked
 // deleted in Seazona. No patient data.
+//
+// Issue #143: a lane that ran before and has not succeeded within its
+// freshness limit (or two of its own cadences, if those are longer) is
+// stale, and a stale lane makes `ok` false like a failed one.
 export async function readSeazonaSyncHealth(db, settings, { now = Date.now } = {}) {
   const nowMs = Number(now());
   const states = await readLaneStates(db);
   const quarantinedOrders = await readQuarantinedOrders(db, { at: new Date(nowMs), limit: MAX_REPORTED });
   const [{ deleted }] = await db.select({ deleted: count() }).from(seazonaOrders).where(isNotNull(seazonaOrders.deletedInSourceAt));
   const quarantinedRecords = await readQuarantinedRecordCounts(db, { at: new Date(nowMs) });
+  const rereadDue = await readRecordRereadCounts(db, { at: new Date(nowMs) });
   const lanes = LANES.map((lane) => {
     const state = states.get(lane);
-    const { freshnessMs } = settings.sync.lanes[lane];
+    const { freshnessMs, cadenceMs } = settings.sync.lanes[lane];
+    const staleAfterMs = Math.max(freshnessMs, 2 * cadenceMs);
     const ageMs = state?.lastSuccessAt ? Math.max(0, nowMs - state.lastSuccessAt.getTime()) : null;
     return {
       lane,
       status: state?.status ?? 'never_run',
-      fresh: ageMs !== null && ageMs <= freshnessMs,
+      fresh: ageMs !== null && ageMs <= staleAfterMs,
+      stale: ageMs !== null && ageMs > staleAfterMs,
       ageMs,
       lastSuccessAt: state?.lastSuccessAt?.toISOString() ?? null,
       lastAttemptAt: state?.lastAttemptAt?.toISOString() ?? null,
@@ -613,10 +685,11 @@ export async function readSeazonaSyncHealth(db, settings, { now = Date.now } = {
       failureDetails: state?.failureDetails ?? null,
       ...(lane === 'orders_active' ? { quarantinedOrders } : {}),
       ...(quarantinedRecords[lane] ? { quarantinedRecords: quarantinedRecords[lane] } : {}),
+      ...(rereadDue[lane] ? { rereadDue: rereadDue[lane] } : {}),
     };
   });
   return {
-    ok: lanes.every((lane) => !['failed', 'held', 'stopped'].includes(lane.status)),
+    ok: lanes.every((lane) => !lane.stale && !['failed', 'held', 'stopped'].includes(lane.status)),
     lanes,
     deletedOrders: Number(deleted),
   };

package/server/integrations/seazona/ledger.js

@@ -2,8 +2,8 @@
 // issue #3). The adapter does not import the ledger: the core reads the
 // billing feed and passes these shapes to it.
 //
-//   item.ledgerJob       -> observeJob(db, organisationId, { ...item.ledgerJob, contactId })
-//   withdrawn.ledgerHold -> setHold(db, organisationId, <obligation id>, { ...ledgerHold, actor })
+//   item.ledgerJob            -> observeJob(db, organisationId, { ...item.ledgerJob, contactId })
+//   withdrawn.ledgerWithdrawn -> observeWithdrawn(db, organisationId, withdrawn.ledgerWithdrawn)
 //
 // One Seazona order is one billable job. The contact is Flow's, so the core
 // resolves it (from item.client) and adds contactId; the ledger keeps a job
@@ -56,15 +56,20 @@ export function toLedgerJob(item) {
   };
 }
 
-// An order deleted in Seazona sends its obligation, if there is one, to
-// review: a person decides what happens to any invoice already made. An order
-// that only stopped being billable needs nothing from the ledger.
-export function toLedgerHold(entry) {
-  if (entry.reason !== 'deleted_in_seazona') return null;
+// observeWithdrawn's input for an order that is no longer billable. An
+// order deleted in Seazona sends its obligation, if there is one, to review:
+// a person decides what happens to any invoice already made. An order whose
+// status moved back (for example from Shipped to In Production) loses an
+// unsent ready mark, and goes to review when its invoice was made.
+export function toLedgerWithdrawn(entry) {
+  const deleted = entry.reason === 'deleted_in_seazona';
   return {
     sourceSystem: SEAZONA_SOURCE_SYSTEM,
     sourceJobRef: entry.sourceId,
-    holdState: 'review',
-    reason: 'the order was deleted in Seazona',
+    sourceStatus: entry.status ?? null,
+    deleted,
+    reason: deleted ? 'the order was deleted in Seazona' : null,
+    observedAt: entry.syncedAt ?? null,
+    actor: `system:${SEAZONA_SOURCE_SYSTEM}`,
   };
 }

package/server/integrations/seazona/migrations/0005_record_reread.sql

@@ -0,0 +1 @@
+ALTER TABLE "seazona_record_read_failures" ADD COLUMN IF NOT EXISTS "detail_id" text;

package/server/integrations/seazona/migrations/0006_sweep_findings.sql

@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS "seazona_sweep_findings" (
+	"resource" text NOT NULL,
+	"record_key" text NOT NULL,
+	"kind" text NOT NULL,
+	"first_found_at" timestamp with time zone NOT NULL,
+	"last_found_at" timestamp with time zone NOT NULL,
+	"detail" jsonb,
+	CONSTRAINT "seazona_sweep_findings_resource_record_key_kind_pk" PRIMARY KEY("resource","record_key","kind")
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "seazona_sweep_findings_found" ON "seazona_sweep_findings" USING btree ("last_found_at");

package/server/integrations/seazona/migrations/0007_stage_moves.sql

@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS "seazona_person_settings" (
+	"person_id" text PRIMARY KEY NOT NULL,
+	"ask_before_stage_moves" boolean DEFAULT true NOT NULL,
+	"updated_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "seazona_stage_moves" (
+	"order_id" text PRIMARY KEY NOT NULL,
+	"from_status" text,
+	"to_status" text NOT NULL,
+	"requested_by" text,
+	"requested_at" timestamp with time zone NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"state" text DEFAULT 'waiting' NOT NULL,
+	"settled_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "seazona_stage_moves_state" ON "seazona_stage_moves" USING btree ("state","expires_at");