js-bao-wss-client 2.2.0-alpha.7 → 2.2.0-alpha.9

package/dist/JsBaoClient.d.ts

@@ -6,6 +6,7 @@ import type { TypedModelConstructor } from "./types/typed-model-constructor";
 import { LogLevel } from "./internal/logger";
 import { type SubscribeOptions } from "./internal/databaseSubscriptions";
 import { type StorageConfig, type YjsPersistenceFactory } from "./internal/storage/index.js";
+import { type WorkflowStatusSlice } from "./internal/workflowSlice";
 import { BlobManager } from "./internal/blobManager";
 import { type AnalyticsEventInput } from "./internal/analyticsQueue";
 import { type GoogleClientsConfig } from "./internal/authController";
@@ -497,11 +498,23 @@ export interface SyncEvent {
  * loader that needs to reload on every remote write can subscribe here
  * instead of observing the underlying document directly.
  *
- * It also fires with `state: "error"` when a remote update for an open
- * document arrives but cannot be applied — currently when downloading a
- * large update from R2 is rejected (401/403), which leaves the document
- * behind the server. It does not fire at all for updates addressed to a
- * document this client does not have open.
+ * It also fires with `state: "error"` when an open document cannot be kept
+ * in sync:
+ *
+ * - a remote update for it arrives but cannot be applied — when downloading
+ *   a large update from R2 is rejected (401/403), which leaves the document
+ *   behind the server;
+ * - its sync handshake goes unanswered for the whole handshake budget
+ *   (`sync.handshakeTimeoutMs`, default 10s), so what the app is rendering
+ *   has stopped converging. The client keeps retrying underneath, at a
+ *   backoff that caps at 15s, and repeats `"error"` on each timeout it
+ *   hits. Once such a document does sync, the event fires `"synced"` once
+ *   more so the app can clear whatever it surfaced — but not for a
+ *   completion that only scheduled a stale-local-state reset, since that
+ *   document still has no server state.
+ *
+ * It does not fire at all for updates addressed to a document this client
+ * does not have open.
  *
  * `state` also carries `"syncing"` and `"stale"` for cross-client
  * compatibility; this client emits only `"synced"` and `"error"`. For a
@@ -1344,7 +1357,16 @@ export interface WorkflowStatusResult<O = any> {
     /** Why the run did not run, when `status === "skipped"`. */
     skipReason?: WorkflowRunSkipReason;
     run?: WorkflowRun;
+    /**
+     * The task slice's record, for a durable function run. Additive and present
+     * only when the run has one (a DSL run and a request invocation have none)
+     * and the client could read the block the server sent.
+     * `refreshCount` is how many times the slice's token was refreshed through
+     * the gateway instead of yielding to renew its budget.
+     */
+    slice?: WorkflowStatusSlice;
 }
+export type { WorkflowStatusSlice };
 /** Options for claiming a workflow apply */
 export interface ClaimApplyOptions {
     workflowKey: string;
@@ -1959,8 +1981,47 @@ export declare class JsBaoClient extends Observable<any> {
     private syncRetryBackoffMs;
     private syncRetryTimeoutHandles;
     private syncWatchdogTimeoutMs;
-    private readonly syncRetryInitialMs;
-    private readonly syncRetryMaxMs;
+    private syncRetryInitialMs;
+    private syncRetryMaxMs;
+    /**
+     * Documents whose failing sync has been reported to the app as a
+     * `documentSyncStateChanged` "error" (#3390). Kept so the matching
+     * "synced" recovery is emitted only for a document the app was actually
+     * warned about, and once.
+     */
+    private syncErrorReported;
+    /**
+     * The outcome of the `syncStep2` payload of a document's current cycle,
+     * still resolving or resolved (#3390). `syncStep2ReceivedFor` records the
+     * frame before its payload is fetched, so a `syncComplete` can pass the
+     * stale-state check while the download is in flight — or after it failed.
+     * The recovery report waits on this instead, so a cycle whose server state
+     * never reached the Y.Doc is not reported to the app as the recovery.
+     */
+    private syncStep2PayloadFor;
+    /**
+     * Consecutive handshake-budget timeouts per document, cleared when a cycle
+     * completes or the document closes (#3390).
+     */
+    private syncTimeoutStreak;
+    /**
+     * Documents whose stall has already asked for a fresh socket. It outlives
+     * the reconnect it triggers — only a completed sync or a close clears it —
+     * so one stalled document rebuilds the connection once rather than every
+     * few budgets (#3390).
+     */
+    private syncStallReconnectRequested;
+    /**
+     * Whether the current connection has already been rebuilt for a stalled
+     * document. Reset on connect, so a burst of stalled documents costs one
+     * reconnect between them (#3390).
+     */
+    private syncStallReconnectOnThisConnection;
+    /**
+     * Consecutive handshake-budget timeouts on a live socket before the client
+     * stops trusting the connection and rebuilds it (#3390).
+     */
+    private static readonly syncStallReconnectAfterTimeouts;
     private jsBaoGetModelDocumentId;
     private jsBaoSetDefaultDocumentIdRaw;
     private jsBaoClearDefaultDocumentIdRaw;
@@ -2382,7 +2443,7 @@ export declare class JsBaoClient extends Observable<any> {
     private runSyncWorkflow;
     private getWorkflowStatus;
     /**
-     * Unpack a `{ status, run }` status response into a
+     * Unpack a `{ status, run, slice? }` status response into a
      * {@link WorkflowStatusResult}. Shared by `getStatus` (workflowKey/runKey
      * route), `terminate`, and `waitFor`'s reconcile fetch (runId route).
      *
@@ -2583,6 +2644,71 @@ export declare class JsBaoClient extends Observable<any> {
     private clearSyncWatchdog;
     private clearAllSyncWatchdogs;
     private handleSyncWatchdogTimeout;
+    /**
+     * Rebuild the socket for a document that has missed the handshake budget
+     * several times in a row while the transport still reads as open (#3390).
+     *
+     * Retrying is only recovery while the connection still carries answers. A
+     * half-open socket reads as open from here — `isSocketOpen` is only
+     * `readyState`, and this transport sends no heartbeat of its own — so every
+     * `syncStep1` goes out, nothing comes back, and no amount of re-sending
+     * converges on it. So the client builds a new socket itself; the
+     * reconnect's document sweep re-syncs everything open.
+     *
+     * This is NOT what recovered the field report, and could not have been:
+     * the client keeps one `connectionId` for the life of the process, and the
+     * stall there was a server-side sync-in-progress marker keyed on that id,
+     * which a new socket carries along — only a process restart (a new id)
+     * ended it. That marker, and the broadcast mapping a reconnect lost, are
+     * fixed on the server (#3390). The rebuild stays for the transport failure
+     * it does address. Same shape and bounds as the Swift client's
+     * `rebuildConnectionForStalledSync`.
+     *
+     * Bounded on purpose. One document rebuilds the connection once — the
+     * claim outlives the reconnect and is only dropped when the document
+     * finally syncs or closes — and one connection is rebuilt once however
+     * many documents are stalled on it. A document that still cannot sync on
+     * the fresh socket is left to the retry chain rather than reconnected in a
+     * loop.
+     */
+    private rebuildConnectionForStalledSync;
+    /**
+     * Tell the app that a document's sync is failing (#3390).
+     *
+     * Before this the timeout only logged, so an app had no way to know that
+     * what it was rendering had stopped converging — the session just looked
+     * like a hung peer. The client keeps retrying underneath; this is what lets
+     * the app say so meanwhile. Emitted on every timeout: the retry cadence
+     * backs off to `syncRetryMaxMs`, so it is a slow repeat of "still not
+     * synced" rather than a flood. Mirrors the Swift client's `reportSyncError`.
+     */
+    private reportSyncError;
+    /**
+     * A document the app was warned about has synced. Report the recovery once
+     * so the app can clear the error it surfaced (#3390). Mirrors the Swift
+     * client's `reportSyncRecovered`.
+     */
+    private reportSyncRecovered;
+    /**
+     * Arm the next `syncStep1` for a document whose cycle did not complete,
+     * after the current backoff — then double it, capped.
+     *
+     * The retry keeps the chain alive (#3390). `sendSyncStep1` returns without
+     * arming anything whenever it cannot start a cycle: the transport is down,
+     * a claim from an earlier cycle is still held, the document is no longer
+     * open, or the send itself throws. Before this, `handleSyncWatchdogTimeout`
+     * scheduled exactly one retry, so an attempt that hit any of those left the
+     * document unsynced with no watchdog and no pending retry — nothing to
+     * re-drive it short of a reconnect, a remote update, an explicit
+     * `startNetworkSync` or a process restart. Here the retry checks whether
+     * its attempt actually put a cycle in flight and re-arms itself when it did
+     * not, so an open document keeps trying at the capped backoff until it
+     * syncs. Mirrors the Swift client's `scheduleSyncRetry`.
+     *
+     * Idempotent: a retry already armed for the document wins, so the re-arm
+     * and a concurrent watchdog timeout cannot stack two chains.
+     */
+    private scheduleSyncRetry;
     /** Compute a hash of the document's current state.
      * @param documentId - The document to hash
      * @group Documents */

package/dist/JsBaoClient.js

@@ -8,6 +8,7 @@ import { DatabaseSubscriptionRegistry, } from "./internal/databaseSubscriptions"
 import { OfflineStore } from "./internal/offlineStore";
 import { createStorageProvider, } from "./internal/storage/index.js";
 import { deleteIdbByName } from "./internal/storage/idbUtils.js";
+import { readWorkflowSlice, } from "./internal/workflowSlice";
 import { BlobManager } from "./internal/blobManager";
 import { BrowserConnectivityMonitor, CONNECTIVITY_LOST, CONNECTIVITY_RESTORED, USER_SET, } from "./internal/connectivityMonitor";
 import { createAnalyticsQueue, } from "./internal/analyticsQueue";
@@ -531,8 +532,44 @@ export class JsBaoClient extends Observable {
         this.syncRetryBackoffMs = new Map();
         this.syncRetryTimeoutHandles = new Map();
         this.syncWatchdogTimeoutMs = 10000;
+        // Not `readonly`: the #3390 tests run the same retry mechanism on a shorter
+        // cadence, as the Swift client's `internal var`s let its tests do.
         this.syncRetryInitialMs = 2000;
         this.syncRetryMaxMs = 15000;
+        /**
+         * Documents whose failing sync has been reported to the app as a
+         * `documentSyncStateChanged` "error" (#3390). Kept so the matching
+         * "synced" recovery is emitted only for a document the app was actually
+         * warned about, and once.
+         */
+        this.syncErrorReported = new Set();
+        /**
+         * The outcome of the `syncStep2` payload of a document's current cycle,
+         * still resolving or resolved (#3390). `syncStep2ReceivedFor` records the
+         * frame before its payload is fetched, so a `syncComplete` can pass the
+         * stale-state check while the download is in flight — or after it failed.
+         * The recovery report waits on this instead, so a cycle whose server state
+         * never reached the Y.Doc is not reported to the app as the recovery.
+         */
+        this.syncStep2PayloadFor = new Map();
+        /**
+         * Consecutive handshake-budget timeouts per document, cleared when a cycle
+         * completes or the document closes (#3390).
+         */
+        this.syncTimeoutStreak = new Map();
+        /**
+         * Documents whose stall has already asked for a fresh socket. It outlives
+         * the reconnect it triggers — only a completed sync or a close clears it —
+         * so one stalled document rebuilds the connection once rather than every
+         * few budgets (#3390).
+         */
+        this.syncStallReconnectRequested = new Set();
+        /**
+         * Whether the current connection has already been rebuilt for a stalled
+         * document. Reset on connect, so a burst of stalled documents costs one
+         * reconnect between them (#3390).
+         */
+        this.syncStallReconnectOnThisConnection = false;
         this.jsBaoGetModelDocumentId = null;
         this.jsBaoSetDefaultDocumentIdRaw = null;
         this.jsBaoClearDefaultDocumentIdRaw = null;
@@ -3016,7 +3053,7 @@ export class JsBaoClient extends Observable {
         return this.normalizeWorkflowStatusResponse(response);
     }
     /**
-     * Unpack a `{ status, run }` status response into a
+     * Unpack a `{ status, run, slice? }` status response into a
      * {@link WorkflowStatusResult}. Shared by `getStatus` (workflowKey/runKey
      * route), `terminate`, and `waitFor`'s reconcile fetch (runId route).
      *
@@ -3029,6 +3066,7 @@ export class JsBaoClient extends Observable {
     normalizeWorkflowStatusResponse(response) {
         const serverStatus = response?.status;
         const run = response?.run;
+        const slice = readWorkflowSlice(response?.slice);
         return {
             status: serverStatus?.status,
             output: serverStatus?.output,
@@ -3040,6 +3078,11 @@ export class JsBaoClient extends Observable {
                 run?.skipReason ??
                 undefined),
             run,
+            // #3388 — a function run IS a run row, so the run read through these
+            // surfaces is the same run `functions.getStatus` reads, and it answers
+            // the same slice block. Read by the shared reader, which drops a block
+            // it cannot vouch for rather than failing the status read.
+            ...(slice ? { slice } : {}),
         };
     }
     /**
@@ -4672,10 +4715,15 @@ export class JsBaoClient extends Observable {
         if (this.syncRetryBackoffMs.delete(documentId)) {
             debugLog("[dbg][sync] watchdog-reset-backoff", { documentId, reason });
         }
+        // The stall is over (the cycle completed, or the document closed), so
+        // both stall claims start fresh for the next one (#3390).
+        this.syncTimeoutStreak.delete(documentId);
+        this.syncStallReconnectRequested.delete(documentId);
     }
     clearAllSyncWatchdogs(reason) {
         for (const documentId of this.syncWatchdogTimers.keys()) {
-            this.clearSyncWatchdog(documentId, reason);
+            this.clearSyncWatchdogTimer(documentId);
+            this.clearSyncRetryTimer(documentId);
         }
         this.syncWatchdogTimers.clear();
         this.syncWatchdogStartedAt.clear();
@@ -4684,6 +4732,11 @@ export class JsBaoClient extends Observable {
         }
         this.syncRetryTimeoutHandles.clear();
         this.syncRetryBackoffMs.clear();
+        // No cycle is in flight to time out, so no document is carrying a
+        // streak. `syncStallReconnectRequested` is deliberately kept: a document
+        // that asked for this reconnect must not ask for another one as soon as
+        // it has counted up again on the new socket (#3390).
+        this.syncTimeoutStreak.clear();
         debugLog("[dbg][sync] watchdog-clear-all", { reason });
     }
     handleSyncWatchdogTimeout(documentId) {
@@ -4697,11 +4750,117 @@ export class JsBaoClient extends Observable {
         });
         this.docManager.completePendingSyncOperation(documentId);
         this._updateSynced(documentId, false);
-        const currentBackoff = this.syncRetryBackoffMs.get(documentId) ?? this.syncRetryInitialMs;
-        const nextBackoff = Math.min(currentBackoff * 2, this.syncRetryMaxMs);
-        this.syncRetryBackoffMs.set(documentId, nextBackoff);
+        this.reportSyncError(documentId);
+        // The timeout owns the next re-send, so a retry an earlier round armed
+        // gives way to the one scheduled below.
         this.clearSyncRetryTimer(documentId);
-        const retryHandle = setTimeout(() => {
+        this.scheduleSyncRetry(documentId);
+        const streak = (this.syncTimeoutStreak.get(documentId) ?? 0) + 1;
+        this.syncTimeoutStreak.set(documentId, streak);
+        if (streak >= JsBaoClient.syncStallReconnectAfterTimeouts) {
+            this.rebuildConnectionForStalledSync(documentId);
+        }
+    }
+    /**
+     * Rebuild the socket for a document that has missed the handshake budget
+     * several times in a row while the transport still reads as open (#3390).
+     *
+     * Retrying is only recovery while the connection still carries answers. A
+     * half-open socket reads as open from here — `isSocketOpen` is only
+     * `readyState`, and this transport sends no heartbeat of its own — so every
+     * `syncStep1` goes out, nothing comes back, and no amount of re-sending
+     * converges on it. So the client builds a new socket itself; the
+     * reconnect's document sweep re-syncs everything open.
+     *
+     * This is NOT what recovered the field report, and could not have been:
+     * the client keeps one `connectionId` for the life of the process, and the
+     * stall there was a server-side sync-in-progress marker keyed on that id,
+     * which a new socket carries along — only a process restart (a new id)
+     * ended it. That marker, and the broadcast mapping a reconnect lost, are
+     * fixed on the server (#3390). The rebuild stays for the transport failure
+     * it does address. Same shape and bounds as the Swift client's
+     * `rebuildConnectionForStalledSync`.
+     *
+     * Bounded on purpose. One document rebuilds the connection once — the
+     * claim outlives the reconnect and is only dropped when the document
+     * finally syncs or closes — and one connection is rebuilt once however
+     * many documents are stalled on it. A document that still cannot sync on
+     * the fresh socket is left to the retry chain rather than reconnected in a
+     * loop.
+     */
+    rebuildConnectionForStalledSync(documentId) {
+        // Nothing to rebuild on a transport that is already down: the reconnect
+        // path owns that case and its sweep re-syncs on the way back up.
+        if (this._destroyed || !this.isWebSocketOpen())
+            return;
+        if (this.syncStallReconnectOnThisConnection)
+            return;
+        if (this.syncStallReconnectRequested.has(documentId))
+            return;
+        this.syncStallReconnectRequested.add(documentId);
+        this.syncStallReconnectOnThisConnection = true;
+        logger.warn(`Repeated handshake-budget timeouts on a live socket; rebuilding the connection for doc ${documentId}`);
+        this.forceReconnect();
+    }
+    /**
+     * Tell the app that a document's sync is failing (#3390).
+     *
+     * Before this the timeout only logged, so an app had no way to know that
+     * what it was rendering had stopped converging — the session just looked
+     * like a hung peer. The client keeps retrying underneath; this is what lets
+     * the app say so meanwhile. Emitted on every timeout: the retry cadence
+     * backs off to `syncRetryMaxMs`, so it is a slow repeat of "still not
+     * synced" rather than a flood. Mirrors the Swift client's `reportSyncError`.
+     */
+    reportSyncError(documentId) {
+        this.syncErrorReported.add(documentId);
+        try {
+            this.emit("documentSyncStateChanged", [{ documentId, state: "error" }]);
+        }
+        catch (err) {
+            logger.debug("[dbg][sync] sync error emit failed", { documentId, error: err });
+        }
+    }
+    /**
+     * A document the app was warned about has synced. Report the recovery once
+     * so the app can clear the error it surfaced (#3390). Mirrors the Swift
+     * client's `reportSyncRecovered`.
+     */
+    reportSyncRecovered(documentId) {
+        if (!this.syncErrorReported.delete(documentId))
+            return;
+        try {
+            this.emit("documentSyncStateChanged", [{ documentId, state: "synced" }]);
+        }
+        catch (err) {
+            logger.debug("[dbg][sync] sync recovery emit failed", { documentId, error: err });
+        }
+    }
+    /**
+     * Arm the next `syncStep1` for a document whose cycle did not complete,
+     * after the current backoff — then double it, capped.
+     *
+     * The retry keeps the chain alive (#3390). `sendSyncStep1` returns without
+     * arming anything whenever it cannot start a cycle: the transport is down,
+     * a claim from an earlier cycle is still held, the document is no longer
+     * open, or the send itself throws. Before this, `handleSyncWatchdogTimeout`
+     * scheduled exactly one retry, so an attempt that hit any of those left the
+     * document unsynced with no watchdog and no pending retry — nothing to
+     * re-drive it short of a reconnect, a remote update, an explicit
+     * `startNetworkSync` or a process restart. Here the retry checks whether
+     * its attempt actually put a cycle in flight and re-arms itself when it did
+     * not, so an open document keeps trying at the capped backoff until it
+     * syncs. Mirrors the Swift client's `scheduleSyncRetry`.
+     *
+     * Idempotent: a retry already armed for the document wins, so the re-arm
+     * and a concurrent watchdog timeout cannot stack two chains.
+     */
+    scheduleSyncRetry(documentId) {
+        if (this._destroyed || this.syncRetryTimeoutHandles.has(documentId))
+            return;
+        const delayMs = this.syncRetryBackoffMs.get(documentId) ?? this.syncRetryInitialMs;
+        this.syncRetryBackoffMs.set(documentId, Math.min(delayMs * 2, this.syncRetryMaxMs));
+        const retryHandle = setTimeout(async () => {
             this.syncRetryTimeoutHandles.delete(documentId);
             if (!this.docManager.hasOpenDoc(documentId)) {
                 this.syncRetryBackoffMs.delete(documentId);
@@ -4711,12 +4870,25 @@ export class JsBaoClient extends Observable {
                 });
                 return;
             }
-            debugLog("[dbg][sync] watchdog-retry", {
-                documentId,
-                delayMs: currentBackoff,
-            });
-            void this.sendSyncStep1(documentId);
-        }, currentBackoff);
+            debugLog("[dbg][sync] watchdog-retry", { documentId, delayMs });
+            try {
+                await this.sendSyncStep1(documentId);
+            }
+            catch (err) {
+                logger.warn(`sendSyncStep1 retry failed for doc ${documentId}`, err);
+            }
+            // A watchdog armed for this document is the evidence that a cycle did
+            // go out; its own timeout then owns the next round. Without one, and
+            // with the document still open and unsynced, this attempt produced
+            // nothing and the chain has to re-arm.
+            if (this.syncWatchdogTimers.has(documentId) ||
+                !this.docManager.hasOpenDoc(documentId) ||
+                this.docManager.isSynced(documentId)) {
+                return;
+            }
+            debugLog("[dbg][sync] watchdog-retry-rearm", { documentId });
+            this.scheduleSyncRetry(documentId);
+        }, delayMs);
         this.syncRetryTimeoutHandles.set(documentId, retryHandle);
     }
     /** Compute a hash of the document's current state.
@@ -4863,15 +5035,31 @@ export class JsBaoClient extends Observable {
             }
             this.scheduleSyncWatchdog(documentId);
             this.syncStep2ReceivedFor.delete(documentId);
+            this.syncStep2PayloadFor.delete(documentId);
             this.docManager.clearSyncTimings(documentId);
             this.docManager.setSyncTiming(documentId, "syncStep1SentAt", Date.now());
-            this.ws.send(JSON.stringify(syncMessage));
+            try {
+                this.ws.send(JSON.stringify(syncMessage));
+            }
+            catch (err) {
+                logger.warn(`Failed to send syncStep1 for doc ${documentId}`, err);
+                // No frame went out, so no syncComplete will release the claim.
+                this.docManager.completePendingSyncOperation(documentId);
+                // Drop the timer this cycle armed — there is nothing for it to time
+                // out against — but keep the backoff and re-drive the document
+                // (#3390). A send that threw used to reject straight through to a
+                // `void` caller, leaving the document open, unsynced and with
+                // nothing scheduled to try again.
+                this.clearSyncWatchdogTimer(documentId);
+                this.scheduleSyncRetry(documentId);
+            }
         }
         else {
             logger.warn(`sendSyncStep1: Skipped send; socket not OPEN for doc ${documentId}`);
             this._logWsState(`sendSyncStep1: skipped for ${documentId}`);
-            // Ensure we do not leave a stale pending flag
-            this.clearSyncWatchdog(documentId, "sendStep1-not-open");
+            // Ensure we do not leave a stale pending flag. The backoff and any
+            // pending retry stay: this attempt started no cycle, and the chain
+            // re-drives the document at the capped cadence (#3390).
             this.docManager.completePendingSyncOperation(documentId);
             debugLog("[dbg][sync] skip-sendStep1 not-open", {
                 documentId,
@@ -5390,6 +5578,9 @@ export class JsBaoClient extends Observable {
         // socket's token was accepted in the handshake, so whatever the previous
         // one spent says nothing about this one.
         this.wsAuthChallengeRefreshes = 0;
+        // A fresh socket gets a fresh claim: whatever a stalled document spent
+        // on the previous connection says nothing about this one (#3390).
+        this.syncStallReconnectOnThisConnection = false;
         void this.flushAllLocalUpdates("ws-open");
         logger.debug("[WS Auth][debug] handleWebSocketOpen", {
             wsconnected: this.wsconnected,
@@ -6862,7 +7053,16 @@ export class JsBaoClient extends Observable {
             }
             else if (data.type === "syncStep2" || data.type === "update") {
                 logger.log(`📥 Handling ${data.type} message`);
-                const updateOutcome = await this.handleUpdate(data);
+                const payload = this.handleUpdate(data);
+                if (data.type === "syncStep2" && data.documentId) {
+                    // Frames are not processed one at a time, so the cycle's
+                    // `syncComplete` can be handled while this payload is still being
+                    // fetched. Recorded so the recovery report can wait for what the
+                    // payload actually did (#3390); a fetch that throws is a payload
+                    // that did not apply, and the throw still reaches the catch below.
+                    this.syncStep2PayloadFor.set(data.documentId, payload.then((outcome) => outcome, () => "error"));
+                }
+                const updateOutcome = await payload;
                 if (data.type === "update" &&
                     data.documentId &&
                     updateOutcome !== "skipped") {
@@ -6917,10 +7117,16 @@ export class JsBaoClient extends Observable {
                     catch { }
                     const receivedSyncStep2 = this.syncStep2ReceivedFor.has(data.documentId);
                     this.syncStep2ReceivedFor.delete(data.documentId);
+                    // Not consumed here: the server closes one cycle with more than one
+                    // syncComplete (another follows the client's answer to the server's
+                    // own syncStep1), and every one of them belongs to the cycle whose
+                    // payload this is. `sendSyncStep1` drops it when the next goes out.
+                    const syncStep2Payload = this.syncStep2PayloadFor.get(data.documentId);
                     logger.log("[load-debug] syncComplete received", {
                         documentId: data.documentId,
                         ydocSharedTypes: syncCompleteDebugInfo,
                     });
+                    let staleResetScheduled = false;
                     if (!receivedSyncStep2) {
                         logger.warn(`[sync] syncComplete WITHOUT syncStep2 doc=${data.documentId} ydocTypes=[${syncCompleteDebugInfo.join(",")}] ydocEmpty=${syncCompleteDebugInfo.length === 0}`);
                         // If this doc was flagged as suspected stale AND the server sent no data,
@@ -6928,6 +7134,7 @@ export class JsBaoClient extends Observable {
                         // the client is in sync. Reset the persistence and re-sync fresh.
                         if (this.suspectedStaleIdbDocs.has(data.documentId)) {
                             this.suspectedStaleIdbDocs.delete(data.documentId);
+                            staleResetScheduled = true;
                             void this.resetYjsPersistenceAndResync(data.documentId);
                         }
                     }
@@ -6941,6 +7148,27 @@ export class JsBaoClient extends Observable {
                         resolvedSynced,
                     });
                     this._updateSynced(data.documentId, resolvedSynced);
+                    // The document converged after the app was told its sync was
+                    // failing, so the app hears that it can drop the warning (#3390).
+                    // Not when this completion is the stale-state case: the document
+                    // is about to be reset and re-synced and still has no server
+                    // state, so the error it was warned about stands until the re-sync
+                    // completes for real. Nor when the cycle's syncStep2 carried an
+                    // `updateUrl` whose download failed: the frame counted as received
+                    // above, but no server state reached the document, so the app
+                    // would be told to clear its warning over a document still stale.
+                    // The error stands and a later cycle that applies reports it.
+                    if (resolvedSynced && !staleResetScheduled) {
+                        const payloadOutcome = syncStep2Payload
+                            ? await syncStep2Payload
+                            : "skipped";
+                        if (payloadOutcome === "error") {
+                            logger.warn(`[sync] syncComplete after a syncStep2 payload that did not apply; not reporting recovery doc=${data.documentId}`);
+                        }
+                        else {
+                            this.reportSyncRecovered(data.documentId);
+                        }
+                    }
                 }
             }
             else if (data.type === "availability") {
@@ -8056,6 +8284,9 @@ export class JsBaoClient extends Observable {
         });
         this.clearLocalUpdateState(documentId);
         this.clearSyncWatchdog(documentId, "closeDocument");
+        // A closed document has no sync error left to clear (#3390).
+        this.syncErrorReported.delete(documentId);
+        this.syncStep2PayloadFor.delete(documentId);
         // Free discovered-schema cache so the map doesn't grow unbounded across
         // document sessions.
         this.discoveredSchemas.delete(documentId);
@@ -9644,8 +9875,12 @@ export class JsBaoClient extends Observable {
         // Clear remaining user-scoped in-memory state
         this.lastEmittedPermission.clear();
         this.syncStep2ReceivedFor.clear();
+        this.syncStep2PayloadFor.clear();
         this.suspectedStaleIdbDocs.clear();
         this.yjsIdbResetInProgress.clear();
+        this.syncErrorReported.clear();
+        this.syncTimeoutStreak.clear();
+        this.syncStallReconnectRequested.clear();
         this.workflowApplyHandlers.clear();
         // Clear service worker bridge state
         this.serviceWorkerBridgePendingMessages.clear();
@@ -10381,6 +10616,11 @@ export class JsBaoClient extends Observable {
         return this.discoveredSchemas.get(documentId) ?? null;
     }
 }
+/**
+ * Consecutive handshake-budget timeouts on a live socket before the client
+ * stops trusting the connection and rebuilds it (#3390).
+ */
+JsBaoClient.syncStallReconnectAfterTimeouts = 3;
 /**
  * Documents per page for the whole-scope walk. The server caps `limit` at
  * 100 (`parseListLimitParam`), so asking for more buys nothing.

package/dist/api/functionsApi.js

@@ -1,4 +1,5 @@
 import { JsBaoError } from "../errors";
+import { readWorkflowSlice } from "../internal/workflowSlice";
 /**
  * Server functions, available as `client.functions`.
  *
@@ -78,9 +79,19 @@ export class FunctionsAPI {
         // The route nests the reconciled status under `status` and the row under
         // `run`; `workflows.getStatus` flattens the same shape, so this one does
         // too rather than exposing a second envelope for the same fact.
+        //
+        // The flatten stays local — spreading `status` passes a server-added key
+        // through, where the workflow normalizer names the fields it reads — but
+        // the SLICE is read by the one shared reader both surfaces use (#3388),
+        // so which method a caller read the run through cannot decide what the
+        // block means.
+        const slice = readWorkflowSlice(response?.slice);
         return {
             ...(response?.status ?? {}),
             run: response?.run,
+            // #3381 — the slice block is a sibling of `status` and `run`, additive,
+            // present only for a durable function run with a record.
+            ...(slice ? { slice } : {}),
         };
     }
     /**

package/dist/browser.umd.js

@@ -2426,6 +2426,101 @@
         });
     }
 
+    /**
+     * The task run's `slice` block, as the client is willing to publish it.
+     *
+     * `GET /workflows/runs/:runId/status` carries `slice` beside `status` and
+     * `run` for a task run that has a record (#3381). The block is
+     * OBSERVABILITY, never the answer, and that decides both halves of how it is
+     * read here (#3388):
+     *
+     *  - A block whose shape surprises the client is DROPPED, and the status read
+     *    still succeeds. Publishing a partial record would be worse than
+     *    publishing none: a `refreshCount` the client filled in with `0` because
+     *    the payload said `"three"` reads to the caller as "this run never
+     *    refreshed", which is telemetry the client does not have. It is the same
+     *    reading the server takes — `readSliceBlock` in `workflows-controller.ts`
+     *    returns null for a record it cannot read rather than 500ing the route —
+     *    and the same one the Swift client's `WorkflowSliceInfo` takes.
+     *  - The tolerance that is actually wanted stays: an absent or `null`
+     *    `refreshCount` reads `0`, and `null` timestamps read `null` without
+     *    costing the caller the record.
+     *
+     * Shared by `functions.getStatus` and by `normalizeWorkflowStatusResponse`,
+     * so which method a caller read the run through cannot decide whether they
+     * can see its slice.
+     */
+    /** A value the client cannot read, as distinct from one that is absent. */
+    const UNREADABLE = Symbol("unreadable slice value");
+    /**
+     * One epoch-millisecond field. Absent and `null` alike read `null`; a
+     * non-integral number is rounded rather than refused; anything that is not a
+     * number is UNREADABLE, and drops the block it belongs to.
+     */
+    function epochMillis(raw) {
+        if (raw === undefined || raw === null)
+            return null;
+        if (typeof raw !== "number")
+            return UNREADABLE;
+        // No timestamp is worth failing a status read for: a value JSON should not
+        // have been able to carry reads as "not recorded".
+        if (!Number.isFinite(raw))
+            return null;
+        return Math.round(raw);
+    }
+    /**
+     * Read the response's `slice` key into a record, or `undefined` when there is
+     * none to publish — an absent key (a request invocation, a DSL run) and a
+     * block the client cannot read are both "no record".
+     */
+    function readWorkflowSlice(raw) {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            return undefined;
+        }
+        const block = raw;
+        // `sliceId` is what makes this a record: a block without one is not a slice.
+        if (typeof block.sliceId !== "string")
+            return undefined;
+        const startedAt = epochMillis(block.startedAt);
+        const ceilingAt = epochMillis(block.ceilingAt);
+        const settledAt = epochMillis(block.settledAt);
+        const lastRefreshAt = epochMillis(block.lastRefreshAt);
+        if (startedAt === UNREADABLE ||
+            ceilingAt === UNREADABLE ||
+            settledAt === UNREADABLE ||
+            lastRefreshAt === UNREADABLE) {
+            return undefined;
+        }
+        // A plain string for the same reason every other status on this surface is
+        // one: a server-added spelling must never cost the caller the record.
+        const rawStatus = block.settledStatus;
+        if (rawStatus !== undefined &&
+            rawStatus !== null &&
+            typeof rawStatus !== "string") {
+            return undefined;
+        }
+        // Absent and `null` alike read 0 — the server always sends the count, so
+        // this is tolerance for a payload that predates it. A value that is not a
+        // whole number drops the block rather than being invented as `0`.
+        const rawCount = block.refreshCount;
+        let refreshCount = 0;
+        if (rawCount !== undefined && rawCount !== null) {
+            if (typeof rawCount !== "number" || !Number.isInteger(rawCount)) {
+                return undefined;
+            }
+            refreshCount = rawCount;
+        }
+        return {
+            sliceId: block.sliceId,
+            startedAt,
+            ceilingAt,
+            settledAt,
+            settledStatus: rawStatus ?? null,
+            lastRefreshAt,
+            refreshCount,
+        };
+    }
+
     /**
      * Normalizes a list response envelope to the unified pagination contract.
      *
@@ -15032,9 +15127,19 @@
             // The route nests the reconciled status under `status` and the row under
             // `run`; `workflows.getStatus` flattens the same shape, so this one does
             // too rather than exposing a second envelope for the same fact.
+            //
+            // The flatten stays local — spreading `status` passes a server-added key
+            // through, where the workflow normalizer names the fields it reads — but
+            // the SLICE is read by the one shared reader both surfaces use (#3388),
+            // so which method a caller read the run through cannot decide what the
+            // block means.
+            const slice = readWorkflowSlice(response?.slice);
             return {
                 ...(response?.status ?? {}),
                 run: response?.run,
+                // #3381 — the slice block is a sibling of `status` and `run`, additive,
+                // present only for a durable function run with a record.
+                ...(slice ? { slice } : {}),
             };
         }
         /**
@@ -16379,8 +16484,44 @@
             this.syncRetryBackoffMs = new Map();
             this.syncRetryTimeoutHandles = new Map();
             this.syncWatchdogTimeoutMs = 10000;
+            // Not `readonly`: the #3390 tests run the same retry mechanism on a shorter
+            // cadence, as the Swift client's `internal var`s let its tests do.
             this.syncRetryInitialMs = 2000;
             this.syncRetryMaxMs = 15000;
+            /**
+             * Documents whose failing sync has been reported to the app as a
+             * `documentSyncStateChanged` "error" (#3390). Kept so the matching
+             * "synced" recovery is emitted only for a document the app was actually
+             * warned about, and once.
+             */
+            this.syncErrorReported = new Set();
+            /**
+             * The outcome of the `syncStep2` payload of a document's current cycle,
+             * still resolving or resolved (#3390). `syncStep2ReceivedFor` records the
+             * frame before its payload is fetched, so a `syncComplete` can pass the
+             * stale-state check while the download is in flight — or after it failed.
+             * The recovery report waits on this instead, so a cycle whose server state
+             * never reached the Y.Doc is not reported to the app as the recovery.
+             */
+            this.syncStep2PayloadFor = new Map();
+            /**
+             * Consecutive handshake-budget timeouts per document, cleared when a cycle
+             * completes or the document closes (#3390).
+             */
+            this.syncTimeoutStreak = new Map();
+            /**
+             * Documents whose stall has already asked for a fresh socket. It outlives
+             * the reconnect it triggers — only a completed sync or a close clears it —
+             * so one stalled document rebuilds the connection once rather than every
+             * few budgets (#3390).
+             */
+            this.syncStallReconnectRequested = new Set();
+            /**
+             * Whether the current connection has already been rebuilt for a stalled
+             * document. Reset on connect, so a burst of stalled documents costs one
+             * reconnect between them (#3390).
+             */
+            this.syncStallReconnectOnThisConnection = false;
             this.jsBaoGetModelDocumentId = null;
             this.jsBaoSetDefaultDocumentIdRaw = null;
             this.jsBaoClearDefaultDocumentIdRaw = null;
@@ -18864,7 +19005,7 @@
             return this.normalizeWorkflowStatusResponse(response);
         }
         /**
-         * Unpack a `{ status, run }` status response into a
+         * Unpack a `{ status, run, slice? }` status response into a
          * {@link WorkflowStatusResult}. Shared by `getStatus` (workflowKey/runKey
          * route), `terminate`, and `waitFor`'s reconcile fetch (runId route).
          *
@@ -18877,6 +19018,7 @@
         normalizeWorkflowStatusResponse(response) {
             const serverStatus = response?.status;
             const run = response?.run;
+            const slice = readWorkflowSlice(response?.slice);
             return {
                 status: serverStatus?.status,
                 output: serverStatus?.output,
@@ -18888,6 +19030,11 @@
                     run?.skipReason ??
                     undefined),
                 run,
+                // #3388 — a function run IS a run row, so the run read through these
+                // surfaces is the same run `functions.getStatus` reads, and it answers
+                // the same slice block. Read by the shared reader, which drops a block
+                // it cannot vouch for rather than failing the status read.
+                ...(slice ? { slice } : {}),
             };
         }
         /**
@@ -20520,10 +20667,15 @@
             if (this.syncRetryBackoffMs.delete(documentId)) {
                 debugLog("[dbg][sync] watchdog-reset-backoff", { documentId, reason });
             }
+            // The stall is over (the cycle completed, or the document closed), so
+            // both stall claims start fresh for the next one (#3390).
+            this.syncTimeoutStreak.delete(documentId);
+            this.syncStallReconnectRequested.delete(documentId);
         }
         clearAllSyncWatchdogs(reason) {
             for (const documentId of this.syncWatchdogTimers.keys()) {
-                this.clearSyncWatchdog(documentId, reason);
+                this.clearSyncWatchdogTimer(documentId);
+                this.clearSyncRetryTimer(documentId);
             }
             this.syncWatchdogTimers.clear();
             this.syncWatchdogStartedAt.clear();
@@ -20532,6 +20684,11 @@
             }
             this.syncRetryTimeoutHandles.clear();
             this.syncRetryBackoffMs.clear();
+            // No cycle is in flight to time out, so no document is carrying a
+            // streak. `syncStallReconnectRequested` is deliberately kept: a document
+            // that asked for this reconnect must not ask for another one as soon as
+            // it has counted up again on the new socket (#3390).
+            this.syncTimeoutStreak.clear();
             debugLog("[dbg][sync] watchdog-clear-all", { reason });
         }
         handleSyncWatchdogTimeout(documentId) {
@@ -20545,11 +20702,117 @@
             });
             this.docManager.completePendingSyncOperation(documentId);
             this._updateSynced(documentId, false);
-            const currentBackoff = this.syncRetryBackoffMs.get(documentId) ?? this.syncRetryInitialMs;
-            const nextBackoff = Math.min(currentBackoff * 2, this.syncRetryMaxMs);
-            this.syncRetryBackoffMs.set(documentId, nextBackoff);
+            this.reportSyncError(documentId);
+            // The timeout owns the next re-send, so a retry an earlier round armed
+            // gives way to the one scheduled below.
             this.clearSyncRetryTimer(documentId);
-            const retryHandle = setTimeout(() => {
+            this.scheduleSyncRetry(documentId);
+            const streak = (this.syncTimeoutStreak.get(documentId) ?? 0) + 1;
+            this.syncTimeoutStreak.set(documentId, streak);
+            if (streak >= JsBaoClient.syncStallReconnectAfterTimeouts) {
+                this.rebuildConnectionForStalledSync(documentId);
+            }
+        }
+        /**
+         * Rebuild the socket for a document that has missed the handshake budget
+         * several times in a row while the transport still reads as open (#3390).
+         *
+         * Retrying is only recovery while the connection still carries answers. A
+         * half-open socket reads as open from here — `isSocketOpen` is only
+         * `readyState`, and this transport sends no heartbeat of its own — so every
+         * `syncStep1` goes out, nothing comes back, and no amount of re-sending
+         * converges on it. So the client builds a new socket itself; the
+         * reconnect's document sweep re-syncs everything open.
+         *
+         * This is NOT what recovered the field report, and could not have been:
+         * the client keeps one `connectionId` for the life of the process, and the
+         * stall there was a server-side sync-in-progress marker keyed on that id,
+         * which a new socket carries along — only a process restart (a new id)
+         * ended it. That marker, and the broadcast mapping a reconnect lost, are
+         * fixed on the server (#3390). The rebuild stays for the transport failure
+         * it does address. Same shape and bounds as the Swift client's
+         * `rebuildConnectionForStalledSync`.
+         *
+         * Bounded on purpose. One document rebuilds the connection once — the
+         * claim outlives the reconnect and is only dropped when the document
+         * finally syncs or closes — and one connection is rebuilt once however
+         * many documents are stalled on it. A document that still cannot sync on
+         * the fresh socket is left to the retry chain rather than reconnected in a
+         * loop.
+         */
+        rebuildConnectionForStalledSync(documentId) {
+            // Nothing to rebuild on a transport that is already down: the reconnect
+            // path owns that case and its sweep re-syncs on the way back up.
+            if (this._destroyed || !this.isWebSocketOpen())
+                return;
+            if (this.syncStallReconnectOnThisConnection)
+                return;
+            if (this.syncStallReconnectRequested.has(documentId))
+                return;
+            this.syncStallReconnectRequested.add(documentId);
+            this.syncStallReconnectOnThisConnection = true;
+            logger.warn(`Repeated handshake-budget timeouts on a live socket; rebuilding the connection for doc ${documentId}`);
+            this.forceReconnect();
+        }
+        /**
+         * Tell the app that a document's sync is failing (#3390).
+         *
+         * Before this the timeout only logged, so an app had no way to know that
+         * what it was rendering had stopped converging — the session just looked
+         * like a hung peer. The client keeps retrying underneath; this is what lets
+         * the app say so meanwhile. Emitted on every timeout: the retry cadence
+         * backs off to `syncRetryMaxMs`, so it is a slow repeat of "still not
+         * synced" rather than a flood. Mirrors the Swift client's `reportSyncError`.
+         */
+        reportSyncError(documentId) {
+            this.syncErrorReported.add(documentId);
+            try {
+                this.emit("documentSyncStateChanged", [{ documentId, state: "error" }]);
+            }
+            catch (err) {
+                logger.debug("[dbg][sync] sync error emit failed", { documentId, error: err });
+            }
+        }
+        /**
+         * A document the app was warned about has synced. Report the recovery once
+         * so the app can clear the error it surfaced (#3390). Mirrors the Swift
+         * client's `reportSyncRecovered`.
+         */
+        reportSyncRecovered(documentId) {
+            if (!this.syncErrorReported.delete(documentId))
+                return;
+            try {
+                this.emit("documentSyncStateChanged", [{ documentId, state: "synced" }]);
+            }
+            catch (err) {
+                logger.debug("[dbg][sync] sync recovery emit failed", { documentId, error: err });
+            }
+        }
+        /**
+         * Arm the next `syncStep1` for a document whose cycle did not complete,
+         * after the current backoff — then double it, capped.
+         *
+         * The retry keeps the chain alive (#3390). `sendSyncStep1` returns without
+         * arming anything whenever it cannot start a cycle: the transport is down,
+         * a claim from an earlier cycle is still held, the document is no longer
+         * open, or the send itself throws. Before this, `handleSyncWatchdogTimeout`
+         * scheduled exactly one retry, so an attempt that hit any of those left the
+         * document unsynced with no watchdog and no pending retry — nothing to
+         * re-drive it short of a reconnect, a remote update, an explicit
+         * `startNetworkSync` or a process restart. Here the retry checks whether
+         * its attempt actually put a cycle in flight and re-arms itself when it did
+         * not, so an open document keeps trying at the capped backoff until it
+         * syncs. Mirrors the Swift client's `scheduleSyncRetry`.
+         *
+         * Idempotent: a retry already armed for the document wins, so the re-arm
+         * and a concurrent watchdog timeout cannot stack two chains.
+         */
+        scheduleSyncRetry(documentId) {
+            if (this._destroyed || this.syncRetryTimeoutHandles.has(documentId))
+                return;
+            const delayMs = this.syncRetryBackoffMs.get(documentId) ?? this.syncRetryInitialMs;
+            this.syncRetryBackoffMs.set(documentId, Math.min(delayMs * 2, this.syncRetryMaxMs));
+            const retryHandle = setTimeout(async () => {
                 this.syncRetryTimeoutHandles.delete(documentId);
                 if (!this.docManager.hasOpenDoc(documentId)) {
                     this.syncRetryBackoffMs.delete(documentId);
@@ -20559,12 +20822,25 @@
                     });
                     return;
                 }
-                debugLog("[dbg][sync] watchdog-retry", {
-                    documentId,
-                    delayMs: currentBackoff,
-                });
-                void this.sendSyncStep1(documentId);
-            }, currentBackoff);
+                debugLog("[dbg][sync] watchdog-retry", { documentId, delayMs });
+                try {
+                    await this.sendSyncStep1(documentId);
+                }
+                catch (err) {
+                    logger.warn(`sendSyncStep1 retry failed for doc ${documentId}`, err);
+                }
+                // A watchdog armed for this document is the evidence that a cycle did
+                // go out; its own timeout then owns the next round. Without one, and
+                // with the document still open and unsynced, this attempt produced
+                // nothing and the chain has to re-arm.
+                if (this.syncWatchdogTimers.has(documentId) ||
+                    !this.docManager.hasOpenDoc(documentId) ||
+                    this.docManager.isSynced(documentId)) {
+                    return;
+                }
+                debugLog("[dbg][sync] watchdog-retry-rearm", { documentId });
+                this.scheduleSyncRetry(documentId);
+            }, delayMs);
             this.syncRetryTimeoutHandles.set(documentId, retryHandle);
         }
         /** Compute a hash of the document's current state.
@@ -20711,15 +20987,31 @@
                 }
                 this.scheduleSyncWatchdog(documentId);
                 this.syncStep2ReceivedFor.delete(documentId);
+                this.syncStep2PayloadFor.delete(documentId);
                 this.docManager.clearSyncTimings(documentId);
                 this.docManager.setSyncTiming(documentId, "syncStep1SentAt", Date.now());
-                this.ws.send(JSON.stringify(syncMessage));
+                try {
+                    this.ws.send(JSON.stringify(syncMessage));
+                }
+                catch (err) {
+                    logger.warn(`Failed to send syncStep1 for doc ${documentId}`, err);
+                    // No frame went out, so no syncComplete will release the claim.
+                    this.docManager.completePendingSyncOperation(documentId);
+                    // Drop the timer this cycle armed — there is nothing for it to time
+                    // out against — but keep the backoff and re-drive the document
+                    // (#3390). A send that threw used to reject straight through to a
+                    // `void` caller, leaving the document open, unsynced and with
+                    // nothing scheduled to try again.
+                    this.clearSyncWatchdogTimer(documentId);
+                    this.scheduleSyncRetry(documentId);
+                }
             }
             else {
                 logger.warn(`sendSyncStep1: Skipped send; socket not OPEN for doc ${documentId}`);
                 this._logWsState(`sendSyncStep1: skipped for ${documentId}`);
-                // Ensure we do not leave a stale pending flag
-                this.clearSyncWatchdog(documentId, "sendStep1-not-open");
+                // Ensure we do not leave a stale pending flag. The backoff and any
+                // pending retry stay: this attempt started no cycle, and the chain
+                // re-drives the document at the capped cadence (#3390).
                 this.docManager.completePendingSyncOperation(documentId);
                 debugLog("[dbg][sync] skip-sendStep1 not-open", {
                     documentId,
@@ -21238,6 +21530,9 @@
             // socket's token was accepted in the handshake, so whatever the previous
             // one spent says nothing about this one.
             this.wsAuthChallengeRefreshes = 0;
+            // A fresh socket gets a fresh claim: whatever a stalled document spent
+            // on the previous connection says nothing about this one (#3390).
+            this.syncStallReconnectOnThisConnection = false;
             void this.flushAllLocalUpdates("ws-open");
             logger.debug("[WS Auth][debug] handleWebSocketOpen", {
                 wsconnected: this.wsconnected,
@@ -22710,7 +23005,16 @@
                 }
                 else if (data.type === "syncStep2" || data.type === "update") {
                     logger.log(`📥 Handling ${data.type} message`);
-                    const updateOutcome = await this.handleUpdate(data);
+                    const payload = this.handleUpdate(data);
+                    if (data.type === "syncStep2" && data.documentId) {
+                        // Frames are not processed one at a time, so the cycle's
+                        // `syncComplete` can be handled while this payload is still being
+                        // fetched. Recorded so the recovery report can wait for what the
+                        // payload actually did (#3390); a fetch that throws is a payload
+                        // that did not apply, and the throw still reaches the catch below.
+                        this.syncStep2PayloadFor.set(data.documentId, payload.then((outcome) => outcome, () => "error"));
+                    }
+                    const updateOutcome = await payload;
                     if (data.type === "update" &&
                         data.documentId &&
                         updateOutcome !== "skipped") {
@@ -22765,10 +23069,16 @@
                         catch { }
                         const receivedSyncStep2 = this.syncStep2ReceivedFor.has(data.documentId);
                         this.syncStep2ReceivedFor.delete(data.documentId);
+                        // Not consumed here: the server closes one cycle with more than one
+                        // syncComplete (another follows the client's answer to the server's
+                        // own syncStep1), and every one of them belongs to the cycle whose
+                        // payload this is. `sendSyncStep1` drops it when the next goes out.
+                        const syncStep2Payload = this.syncStep2PayloadFor.get(data.documentId);
                         logger.log("[load-debug] syncComplete received", {
                             documentId: data.documentId,
                             ydocSharedTypes: syncCompleteDebugInfo,
                         });
+                        let staleResetScheduled = false;
                         if (!receivedSyncStep2) {
                             logger.warn(`[sync] syncComplete WITHOUT syncStep2 doc=${data.documentId} ydocTypes=[${syncCompleteDebugInfo.join(",")}] ydocEmpty=${syncCompleteDebugInfo.length === 0}`);
                             // If this doc was flagged as suspected stale AND the server sent no data,
@@ -22776,6 +23086,7 @@
                             // the client is in sync. Reset the persistence and re-sync fresh.
                             if (this.suspectedStaleIdbDocs.has(data.documentId)) {
                                 this.suspectedStaleIdbDocs.delete(data.documentId);
+                                staleResetScheduled = true;
                                 void this.resetYjsPersistenceAndResync(data.documentId);
                             }
                         }
@@ -22789,6 +23100,27 @@
                             resolvedSynced,
                         });
                         this._updateSynced(data.documentId, resolvedSynced);
+                        // The document converged after the app was told its sync was
+                        // failing, so the app hears that it can drop the warning (#3390).
+                        // Not when this completion is the stale-state case: the document
+                        // is about to be reset and re-synced and still has no server
+                        // state, so the error it was warned about stands until the re-sync
+                        // completes for real. Nor when the cycle's syncStep2 carried an
+                        // `updateUrl` whose download failed: the frame counted as received
+                        // above, but no server state reached the document, so the app
+                        // would be told to clear its warning over a document still stale.
+                        // The error stands and a later cycle that applies reports it.
+                        if (resolvedSynced && !staleResetScheduled) {
+                            const payloadOutcome = syncStep2Payload
+                                ? await syncStep2Payload
+                                : "skipped";
+                            if (payloadOutcome === "error") {
+                                logger.warn(`[sync] syncComplete after a syncStep2 payload that did not apply; not reporting recovery doc=${data.documentId}`);
+                            }
+                            else {
+                                this.reportSyncRecovered(data.documentId);
+                            }
+                        }
                     }
                 }
                 else if (data.type === "availability") {
@@ -23901,6 +24233,9 @@
             });
             this.clearLocalUpdateState(documentId);
             this.clearSyncWatchdog(documentId, "closeDocument");
+            // A closed document has no sync error left to clear (#3390).
+            this.syncErrorReported.delete(documentId);
+            this.syncStep2PayloadFor.delete(documentId);
             // Free discovered-schema cache so the map doesn't grow unbounded across
             // document sessions.
             this.discoveredSchemas.delete(documentId);
@@ -25489,8 +25824,12 @@
             // Clear remaining user-scoped in-memory state
             this.lastEmittedPermission.clear();
             this.syncStep2ReceivedFor.clear();
+            this.syncStep2PayloadFor.clear();
             this.suspectedStaleIdbDocs.clear();
             this.yjsIdbResetInProgress.clear();
+            this.syncErrorReported.clear();
+            this.syncTimeoutStreak.clear();
+            this.syncStallReconnectRequested.clear();
             this.workflowApplyHandlers.clear();
             // Clear service worker bridge state
             this.serviceWorkerBridgePendingMessages.clear();
@@ -26226,6 +26565,11 @@
             return this.discoveredSchemas.get(documentId) ?? null;
         }
     }
+    /**
+     * Consecutive handshake-budget timeouts on a live socket before the client
+     * stops trusting the connection and rebuilds it (#3390).
+     */
+    JsBaoClient.syncStallReconnectAfterTimeouts = 3;
     /**
      * Documents per page for the whole-scope walk. The server caps `limit` at
      * 100 (`parseListLimitParam`), so asking for more buys nothing.

package/dist/internal/workflowSlice.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The task run's `slice` block, as the client is willing to publish it.
+ *
+ * `GET /workflows/runs/:runId/status` carries `slice` beside `status` and
+ * `run` for a task run that has a record (#3381). The block is
+ * OBSERVABILITY, never the answer, and that decides both halves of how it is
+ * read here (#3388):
+ *
+ *  - A block whose shape surprises the client is DROPPED, and the status read
+ *    still succeeds. Publishing a partial record would be worse than
+ *    publishing none: a `refreshCount` the client filled in with `0` because
+ *    the payload said `"three"` reads to the caller as "this run never
+ *    refreshed", which is telemetry the client does not have. It is the same
+ *    reading the server takes — `readSliceBlock` in `workflows-controller.ts`
+ *    returns null for a record it cannot read rather than 500ing the route —
+ *    and the same one the Swift client's `WorkflowSliceInfo` takes.
+ *  - The tolerance that is actually wanted stays: an absent or `null`
+ *    `refreshCount` reads `0`, and `null` timestamps read `null` without
+ *    costing the caller the record.
+ *
+ * Shared by `functions.getStatus` and by `normalizeWorkflowStatusResponse`,
+ * so which method a caller read the run through cannot decide whether they
+ * can see its slice.
+ */
+/**
+ * A slice record the client can vouch for. Field for field with the Swift
+ * client's `WorkflowSliceInfo`.
+ *
+ * Timestamps are epoch milliseconds (what the route sends), not the ISO-8601
+ * strings a run record carries — the slice record is the platform's own
+ * bookkeeping, and the client passes its numbers through verbatim.
+ */
+export interface WorkflowStatusSlice {
+    /** Id of the slice record. The one field the server always fills. */
+    sliceId: string;
+    /** When this slice started, epoch ms. */
+    startedAt: number | null;
+    /**
+     * The 12-hour bound THIS slice ends at, epoch ms — `startedAt` plus the
+     * slice maximum, not a deadline for the run, which can continue in a later
+     * slice with a ceiling of its own.
+     */
+    ceilingAt: number | null;
+    /**
+     * When THIS slice settled, epoch ms; `null` while the slice is open. A
+     * settled slice is not a finished run: a slice that yielded settles here
+     * and the run continues in the next slice, so a caller watching a run
+     * still reads `status`, never this field.
+     */
+    settledAt: number | null;
+    /**
+     * How THIS slice settled (`"completed"`, `"failed"`, `"cpu-yield"`, …);
+     * `null` while the slice is open. `"cpu-yield"` is the slice that gave up
+     * its CPU budget for the run to carry on in another one.
+     */
+    settledStatus: string | null;
+    /** When the credential was last refreshed, epoch ms. */
+    lastRefreshAt: number | null;
+    /**
+     * How many times the credential was refreshed through the gateway instead
+     * of yielding. `0` for a run short enough never to need one.
+     */
+    refreshCount: number;
+}
+/**
+ * Read the response's `slice` key into a record, or `undefined` when there is
+ * none to publish — an absent key (a request invocation, a DSL run) and a
+ * block the client cannot read are both "no record".
+ */
+export declare function readWorkflowSlice(raw: unknown): WorkflowStatusSlice | undefined;

package/dist/internal/workflowSlice.js

@@ -0,0 +1,94 @@
+/**
+ * The task run's `slice` block, as the client is willing to publish it.
+ *
+ * `GET /workflows/runs/:runId/status` carries `slice` beside `status` and
+ * `run` for a task run that has a record (#3381). The block is
+ * OBSERVABILITY, never the answer, and that decides both halves of how it is
+ * read here (#3388):
+ *
+ *  - A block whose shape surprises the client is DROPPED, and the status read
+ *    still succeeds. Publishing a partial record would be worse than
+ *    publishing none: a `refreshCount` the client filled in with `0` because
+ *    the payload said `"three"` reads to the caller as "this run never
+ *    refreshed", which is telemetry the client does not have. It is the same
+ *    reading the server takes — `readSliceBlock` in `workflows-controller.ts`
+ *    returns null for a record it cannot read rather than 500ing the route —
+ *    and the same one the Swift client's `WorkflowSliceInfo` takes.
+ *  - The tolerance that is actually wanted stays: an absent or `null`
+ *    `refreshCount` reads `0`, and `null` timestamps read `null` without
+ *    costing the caller the record.
+ *
+ * Shared by `functions.getStatus` and by `normalizeWorkflowStatusResponse`,
+ * so which method a caller read the run through cannot decide whether they
+ * can see its slice.
+ */
+/** A value the client cannot read, as distinct from one that is absent. */
+const UNREADABLE = Symbol("unreadable slice value");
+/**
+ * One epoch-millisecond field. Absent and `null` alike read `null`; a
+ * non-integral number is rounded rather than refused; anything that is not a
+ * number is UNREADABLE, and drops the block it belongs to.
+ */
+function epochMillis(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== "number")
+        return UNREADABLE;
+    // No timestamp is worth failing a status read for: a value JSON should not
+    // have been able to carry reads as "not recorded".
+    if (!Number.isFinite(raw))
+        return null;
+    return Math.round(raw);
+}
+/**
+ * Read the response's `slice` key into a record, or `undefined` when there is
+ * none to publish — an absent key (a request invocation, a DSL run) and a
+ * block the client cannot read are both "no record".
+ */
+export function readWorkflowSlice(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        return undefined;
+    }
+    const block = raw;
+    // `sliceId` is what makes this a record: a block without one is not a slice.
+    if (typeof block.sliceId !== "string")
+        return undefined;
+    const startedAt = epochMillis(block.startedAt);
+    const ceilingAt = epochMillis(block.ceilingAt);
+    const settledAt = epochMillis(block.settledAt);
+    const lastRefreshAt = epochMillis(block.lastRefreshAt);
+    if (startedAt === UNREADABLE ||
+        ceilingAt === UNREADABLE ||
+        settledAt === UNREADABLE ||
+        lastRefreshAt === UNREADABLE) {
+        return undefined;
+    }
+    // A plain string for the same reason every other status on this surface is
+    // one: a server-added spelling must never cost the caller the record.
+    const rawStatus = block.settledStatus;
+    if (rawStatus !== undefined &&
+        rawStatus !== null &&
+        typeof rawStatus !== "string") {
+        return undefined;
+    }
+    // Absent and `null` alike read 0 — the server always sends the count, so
+    // this is tolerance for a payload that predates it. A value that is not a
+    // whole number drops the block rather than being invented as `0`.
+    const rawCount = block.refreshCount;
+    let refreshCount = 0;
+    if (rawCount !== undefined && rawCount !== null) {
+        if (typeof rawCount !== "number" || !Number.isInteger(rawCount)) {
+            return undefined;
+        }
+        refreshCount = rawCount;
+    }
+    return {
+        sliceId: block.sliceId,
+        startedAt,
+        ceilingAt,
+        settledAt,
+        settledStatus: rawStatus ?? null,
+        lastRefreshAt,
+        refreshCount,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-bao-wss-client",
-  "version": "2.2.0-alpha.7",
+  "version": "2.2.0-alpha.9",
   "description": "Client library for js-bao-wss Yjs WebSocket service",
   "author": "Primitive LLC",
   "license": "UNLICENSED",
@@ -36,7 +36,7 @@
   "peerDependencies": {
     "lib0": "^0.2.0",
     "yjs": "^13.6.0",
-    "js-bao": "0.7.0-alpha.2",
+    "js-bao": "0.7.0-alpha.4",
     "better-sqlite3": "^11.0.0",
     "y-sqlite3": "^0.1.0",
     "react": ">=17.0.0",