@steve31415/baselib 3.11.0 → 3.12.0

package/dist/sync-browser/client.d.ts

@@ -125,6 +125,11 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private refetchInFlight;
     private probeInFlight;
     private resyncTimes;
+    /** Forward-gap events delivered while a resync is reconciling; drained
+     * after the bootstrap installs. Non-null exactly while reconciling. */
+    private gapBuffer;
+    private resyncBackoffTimer;
+    private loopEscalated;
     private reconciliationTail;
     private initialization;
     private disposed;
@@ -169,6 +174,18 @@ export declare class SyncClient<B, C extends EventBody, S extends EventBody, Sum
     private onSyncEstablished;
     private requestReload;
     private resyncFromServer;
+    /** Applies the events delivered while the bootstrap was in flight. On a
+     * single socket they are contiguous with the install point, so this is
+     * where a resync under a live stream converges; a hole (socket replaced
+     * mid-fetch, buffer overflow) schedules a fresh resync via the normal gap
+     * path instead. */
+    private drainAfterResync;
+    /** A stall episode ends only on proven convergence: a resync whose drain
+     * scheduled nothing further, or a complete socket catch-up. A successful
+     * reconcile alone is not convergence — in a chronic diverge-reconverge
+     * cycle every reconcile succeeds. */
+    private endResyncEpisode;
+    private scheduleResyncRetry;
     private sendConnect;
     private sendRaw;
     private trySend;

package/dist/sync-browser/client.js

@@ -8,6 +8,11 @@ const FAILURE_TIMEOUT_MS = 60_000;
 // blips (Wi-Fi roam, VPN re-auth — observed 30-40 s) must not page as ERROR
 // (Steve, 2026-09-11; raised from 30 s, which flagged those blips).
 const OUTAGE_ESCALATE_MS = 120_000;
+const RESYNC_LOOP_WINDOW_MS = 60_000;
+const RESYNC_LOOP_MAX = 3;
+const RESYNC_RETRY_MS = 60_000;
+const GAP_BUFFER_MAX = 1_000;
+const RECONCILE_MOVED_MAX_REFETCHES = 3;
 const CLOSE_NO_USER = 4403;
 const PROBE_AFTER_ATTEMPTS = 2;
 const SOCKET_OPEN = 1;
@@ -49,6 +54,11 @@ export class SyncClient {
     refetchInFlight = false;
     probeInFlight = false;
     resyncTimes = [];
+    /** Forward-gap events delivered while a resync is reconciling; drained
+     * after the bootstrap installs. Non-null exactly while reconciling. */
+    gapBuffer = null;
+    resyncBackoffTimer = null;
+    loopEscalated = false;
     reconciliationTail = Promise.resolve();
     initialization = null;
     disposed = false;
@@ -423,7 +433,22 @@ export class SyncClient {
             return true;
         }
         if (event.seq > currentSeq + 1) {
-            this.requestReload('sequence-gap');
+            // An own-write echo proves the commit even when the gap prevents
+            // applying it: settle the pending (without a settlement reconcile —
+            // the resync below installs fresh state anyway) so the 60 s failure
+            // timer cannot report a committed write as failed.
+            if (this.pending.has(event.eventGuid))
+                this.confirmPending(event.eventGuid, false);
+            if (this.gapBuffer !== null) {
+                if (this.gapBuffer.length < GAP_BUFFER_MAX)
+                    this.gapBuffer.push(event);
+                // On overflow, drop the newest: the kept prefix stays contiguous
+                // with the install point; the drain then ends at a hole and
+                // schedules a fresh resync.
+            }
+            else {
+                this.requestReload('sequence-gap');
+            }
             return false;
         }
         this.options.store.applyServerEvent(event);
@@ -579,15 +604,24 @@ export class SyncClient {
         });
         await preceding;
         try {
-            while (true) {
+            for (let attempt = 0;; attempt++) {
                 if (this.stopBeforeStoreMutation())
                     return false;
                 const startingSeq = this.options.store.currentSeq();
                 const bootstrap = await this.abortable((signal) => this.options.fetchBootstrap(signal));
                 if (this.stopBeforeStoreMutation())
                     return false;
-                if (this.options.store.currentSeq() !== startingSeq)
-                    continue;
+                if (this.options.store.currentSeq() !== startingSeq) {
+                    // The store advanced mid-fetch: live contiguous events are
+                    // applying, so the client is converged-and-advancing. Refetch a
+                    // bounded number of times for a quiescent snapshot; past that,
+                    // keep the live state — installing the older bootstrap would
+                    // rewind it. Any residual divergence surfaces as a normal gap
+                    // and a fresh, detector-counted resync.
+                    if (attempt < RECONCILE_MOVED_MAX_REFETCHES)
+                        continue;
+                    return true;
+                }
                 this.options.store.installBootstrap(bootstrap);
                 for (const [eventGuid, entry] of this.pending) {
                     if (this.settledPending.has(eventGuid))
@@ -641,9 +675,18 @@ export class SyncClient {
                 this.trySend(entry);
             }
         }
+        // A complete catch-up IS convergence: end any stall episode and cancel
+        // its pending backoff retry.
+        this.endResyncEpisode();
         this.updateConnectedState();
     }
     requestReload(reason) {
+        // While a resync is reconciling or backing off, further triggers are
+        // absorbed: the in-flight/scheduled attempt already covers them, and
+        // per-event callbacks were the WARN/ERROR spam of the 2026-09-10
+        // incident. The callback fires once per resync attempt.
+        if (this.refetchInFlight || this.resyncBackoffTimer !== null)
+            return;
         this.options.onReloadRequired(reason);
         void this.resyncFromServer(reason === 'server' ? 'server requested reload' : 'sequence gap');
     }
@@ -651,23 +694,35 @@ export class SyncClient {
         if (this.refetchInFlight || this.halted || this.disposed)
             return;
         const now = this.options.runtime.now();
-        this.resyncTimes = [...this.resyncTimes.filter((time) => now - time < 60_000), now];
-        if (this.resyncTimes.length > 3) {
-            this.options.logger.error('resync loop detected', { reason });
+        // `time <= now` drops entries stranded in the future by a backward
+        // clock jump, which would otherwise pin the detector tripped.
+        this.resyncTimes = [
+            ...this.resyncTimes.filter((time) => time <= now && now - time < RESYNC_LOOP_WINDOW_MS),
+            now,
+        ];
+        if (this.resyncTimes.length > RESYNC_LOOP_MAX) {
+            if (!this.loopEscalated) {
+                this.loopEscalated = true;
+                this.options.logger.error('resync loop detected', { reason });
+            }
             this.publish({
                 kind: 'error',
                 pending: this.pendingCount(),
-                message: 'Repeated resyncs require a page reload',
+                message: 'Repeated resyncs; retrying automatically',
             });
+            this.scheduleResyncRetry();
             return;
         }
         this.refetchInFlight = true;
+        this.gapBuffer = [];
+        let reconciled = false;
         try {
             this.options.logger.info('resyncing from server', { reason });
-            if (!(await this.reconcileStore()))
-                return;
-            for (const entry of this.pending.values())
-                this.trySend(entry);
+            reconciled = await this.reconcileStore();
+            if (reconciled) {
+                for (const entry of this.pending.values())
+                    this.trySend(entry);
+            }
         }
         catch (error) {
             if (!isLifecycleAbort(error) && !this.disposed && !this.halted) {
@@ -675,9 +730,54 @@ export class SyncClient {
             }
         }
         finally {
+            // Ordering matters: take the buffer and release the flag before the
+            // drain, so a drain-triggered nested resync owns `refetchInFlight`
+            // (and a fresh buffer) alone — this finally has nothing left to clear.
+            const buffered = this.gapBuffer ?? [];
+            this.gapBuffer = null;
             this.refetchInFlight = false;
+            if (reconciled)
+                this.drainAfterResync(buffered);
         }
     }
+    /** Applies the events delivered while the bootstrap was in flight. On a
+     * single socket they are contiguous with the install point, so this is
+     * where a resync under a live stream converges; a hole (socket replaced
+     * mid-fetch, buffer overflow) schedules a fresh resync via the normal gap
+     * path instead. */
+    drainAfterResync(buffered) {
+        for (const event of buffered) {
+            if (this.halted || this.disposed)
+                return;
+            if (!this.handleServerEvent(event))
+                return;
+        }
+        this.endResyncEpisode();
+    }
+    /** A stall episode ends only on proven convergence: a resync whose drain
+     * scheduled nothing further, or a complete socket catch-up. A successful
+     * reconcile alone is not convergence — in a chronic diverge-reconverge
+     * cycle every reconcile succeeds. */
+    endResyncEpisode() {
+        if (this.resyncBackoffTimer !== null) {
+            this.options.runtime.clearTimeout(this.resyncBackoffTimer);
+            this.resyncBackoffTimer = null;
+        }
+        if (!this.loopEscalated)
+            return;
+        this.loopEscalated = false;
+        this.updateConnectedState();
+    }
+    scheduleResyncRetry() {
+        if (this.resyncBackoffTimer !== null || this.halted || this.disposed)
+            return;
+        // A hidden tab's timer throttling may stretch this well past the nominal
+        // delay; that only postpones recovery, it never breaks it.
+        this.resyncBackoffTimer = this.options.runtime.setTimeout(() => {
+            this.resyncBackoffTimer = null;
+            void this.resyncFromServer('retry after resync backoff');
+        }, RESYNC_RETRY_MS);
+    }
     sendConnect() {
         this.sendRaw({
             type: 'connect',
@@ -800,11 +900,14 @@ export class SyncClient {
             this.options.runtime.clearInterval(this.countdownTimer);
         if (this.escalateTimer !== null)
             this.options.runtime.clearTimeout(this.escalateTimer);
+        if (this.resyncBackoffTimer !== null)
+            this.options.runtime.clearTimeout(this.resyncBackoffTimer);
         for (const timer of this.failureTimers.values())
             this.options.runtime.clearTimeout(timer);
         this.reconnectTimer = null;
         this.countdownTimer = null;
         this.escalateTimer = null;
+        this.resyncBackoffTimer = null;
         this.failureTimers.clear();
     }
     detachSocket(socket) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",