@syncular/client 0.25.2 → 0.26.1

package/README.md

@@ -195,14 +195,42 @@ flushed to the new leader on its announce; past the deadline they fail
 loudly with `client.follower_timeout` (never a silent hang), and an
 overflowing queue rejects rather than growing unbounded.
 
-Leader announcements continue as heartbeats while followers are attached. If
-a tab can acquire neither a response nor a new lock grant before the configured
-`followerCallTimeoutMs`, `handle.leadership` becomes
+**Leader liveness.** Followers probe the leader; the leader runs no liveness
+timer. A bound follower that has heard no announcement for a third of
+`followerCallTimeoutMs` (default 10 s) posts a `hello`, and the leader answers
+every `hello` with an announcement from its message handler. Browsers throttle
+the timers of hidden tabs (Chrome's intensive throttling wakes them about once
+a minute) but still dispatch their `BroadcastChannel` messages, so a leader in
+a background tab keeps its followers bound. When a probe stays unanswered for
+the rest of `followerCallTimeoutMs`, `handle.leadership` becomes
 `{ state: 'blocked', reason: 'leader-unreachable', code:
-'client.follower_timeout', retryable: true }`. Calls then reject immediately.
-A later announcement rebinds the same handle; a granted Web Lock promotes it.
-An unreachable `BroadcastChannel` is never treated as evidence that the lock
-owner is stale, so it never authorizes a second worker or database owner.
+'client.follower_timeout', retryable: true }` and calls reject immediately.
+A leader tab that processes no messages (hung or frozen) therefore blocks its
+followers within `followerCallTimeoutMs`; a closed leader releases its Web
+Lock and hands over without waiting for that deadline. A blocked follower keeps
+probing at the same interval: an answer rebinds the same handle, and a granted
+Web Lock promotes it. A single call that runs past `followerCallTimeoutMs`
+rejects with `client.follower_timeout` and leaves the handle bound, because
+reachability is decided by the probe alone. An unreachable `BroadcastChannel`
+is never treated as evidence that the lock owner is stale, so it never
+authorizes a second worker or database owner.
+
+**Upgrade note: reload every open tab.** Followers running 0.26.0 or older
+wait for a leader heartbeat that current leaders no longer send. Such a tab
+next to a current leader reports `leader-unreachable` with
+`client.follower_timeout` after `followerCallTimeoutMs`, unless a current
+follower's probe happens to make the leader announce, and stays that way
+until it reloads. A current follower next to an older leader works, because
+older leaders answer every `hello`. After upgrading, reload every open tab of
+the origin.
+
+**A hidden leader keeps leadership.** A visible tab does not take leadership
+from a hidden leader. Web Locks `steal` revokes the lease while the leader's
+worker still holds the OPFS database and may be mid-commit, so a transfer
+needs a cooperative close-and-release handshake, and every focus change
+between tabs would restart the worker, reopen the database, and reconnect the
+realtime socket. A hidden leader answers its followers from its message
+handler, so leadership moves only when the leader tab closes.
 
 **Presence semantics — one device, one peer.** All tabs share the leader's
 single connection, so a device is exactly ONE presence peer collectively:

package/dist/client.d.ts

@@ -11,7 +11,7 @@ import { type SyncProgress, type SyncProgressListener } from './progress.js';
 import { type ScopeMap, type WakeReason } from '@syncular/core';
 import { type BlobRef, type BlobTransport, type CachedBlob } from './blob.js';
 import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
-import { type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.js';
+import { type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
 import type { EncryptionConfig } from './encryption.js';
 import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
 import { type LeaderLock } from './leader-lock.js';
@@ -119,6 +119,15 @@ export interface SyncClientConfig {
      */
     readonly blobCacheMaxBytes?: number;
     readonly realtime?: RealtimeConnector;
+    /**
+     * SPEC §8.8: how sync rounds treat the realtime binding. `optional`
+     * (default) rides a connected socket and otherwise uses `POST /sync`.
+     * `required` refuses a round with `RealtimeUnavailableError` while the
+     * socket is not connected and never falls back to HTTP. `off` never uses
+     * realtime; an explicit `connectRealtime` fails with `sync.invalid_request`.
+     * `required` without a `realtime` connector is refused at construction.
+     */
+    readonly realtimePolicy?: RealtimePolicy;
     /** Stable per-device id (§1.5); defaults to a persisted random UUID. */
     readonly clientId?: string;
     readonly leaderLock?: LeaderLock;

package/dist/client.js

@@ -14,7 +14,7 @@ import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow,
 import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
 import { registerDevtools } from './devtools.js';
 import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
-import { ClientSyncError, classifySqliteFailure } from './errors.js';
+import { ClientSyncError, classifySqliteFailure, REALTIME_LOST_CODE, RealtimeUnavailableError, } from './errors.js';
 import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, } from './leader-lock.js';
 import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
@@ -117,6 +117,11 @@ function isFinalPushResult(frame) {
             result.code === 'sync.idempotency_cache_miss' &&
             result.retryable));
 }
+/** The stable `code` of a thrown realtime transport error, when it has one. */
+function realtimeErrorCode(error) {
+    const code = error?.code;
+    return typeof code === 'string' ? code : undefined;
+}
 export class SyncClient {
     #config;
     #db;
@@ -139,6 +144,11 @@ export class SyncClient {
     #conflicts = [];
     #rejections = [];
     #socket;
+    /** SPEC §8.8: the explicit realtime availability state and its evidence. */
+    #realtimePolicy;
+    #realtimeState;
+    #realtimeReasonCode;
+    #realtimeRetryDelayMs;
     #realtimeConnectPromise;
     #realtimeGeneration = 0;
     #pendingRound;
@@ -210,9 +220,25 @@ export class SyncClient {
         if (config.securityPreflight === true && config.encryption !== undefined) {
             throw new ClientSyncError('sync.invalid_request', 'securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight');
         }
-        this.#config = config;
         this.#db = config.database;
         this.#schema = compileClientSchema(config.schema);
+        const realtimePolicy = config.realtimePolicy ?? 'optional';
+        if (realtimePolicy !== 'required' &&
+            realtimePolicy !== 'optional' &&
+            realtimePolicy !== 'off') {
+            throw new ClientSyncError('sync.invalid_request', "realtimePolicy must be 'required', 'optional', or 'off'");
+        }
+        if (realtimePolicy === 'required' && config.realtime === undefined) {
+            throw new ClientSyncError('sync.invalid_request', "realtimePolicy 'required' needs a realtime connector");
+        }
+        this.#config = config;
+        this.#realtimePolicy = realtimePolicy;
+        this.#realtimeState =
+            realtimePolicy === 'off'
+                ? 'disabled'
+                : config.realtime === undefined
+                    ? 'unsupported'
+                    : 'disconnected';
         this.#encryption = config.encryption;
         this.#securityLifecycle =
             config.securityPreflight === true ? 'preflight' : 'active';
@@ -1013,11 +1039,14 @@ export class SyncClient {
                 kind: 'direct',
                 role: 'single',
                 connectivity,
-                realtime: this.#config.realtime === undefined
-                    ? 'unsupported'
-                    : this.#socket === undefined
-                        ? 'disconnected'
-                        : 'connected',
+                realtime: this.#realtimeState,
+                realtimePolicy: this.#realtimePolicy,
+                ...(this.#realtimeReasonCode !== undefined
+                    ? { realtimeReasonCode: this.#realtimeReasonCode }
+                    : {}),
+                ...(this.#realtimeRetryDelayMs !== undefined
+                    ? { realtimeRetryDelayMs: this.#realtimeRetryDelayMs }
+                    : {}),
             },
             securityLifecycle: this.#securityLifecycle,
             schema: {
@@ -2465,9 +2494,18 @@ export class SyncClient {
             const retryable = explicitlyRetryable === true ||
                 (explicitlyRetryable === undefined && typeof code !== 'string');
             if (retryable) {
+                const realtimeUnavailable = error instanceof RealtimeUnavailableError;
+                const delay = realtimeUnavailable
+                    ? error.retryDelayMs
+                    : this.#retryDelayMs;
+                if (realtimeUnavailable ||
+                    this.#realtimeState === 'lost' ||
+                    this.#realtimeState === 'refused') {
+                    this.#realtimeRetryDelayMs = delay;
+                }
                 const intent = {
                     kind: 'background',
-                    delayMs: this.#retryDelayMs,
+                    delayMs: delay,
                 };
                 this.#retryDelayMs = Math.min(this.#retryDelayMs * 2, 30_000);
                 this.#emitSyncIntent(intent);
@@ -2515,38 +2553,48 @@ export class SyncClient {
      * is connected (the socket IS the sync-round
      * transport, not a fallback pair), otherwise through the configured
      * `SyncTransport` seam (loopback/conformance hosts, HTTP-only
-     * producers).
+     * producers). Under `realtimePolicy: 'required'` an unconnected socket
+     * refuses the round with `RealtimeUnavailableError` instead of using the
+     * seam (SPEC §8.8).
      */
     #roundTrip(request) {
         const socket = this.#socket;
-        if (socket === undefined) {
-            return Promise.resolve()
-                .then(() => this.#config.transport(request))
-                .catch((error) => {
-                if (error instanceof ClientSyncError ||
-                    typeof error?.code === 'string') {
-                    throw error;
+        if (socket !== undefined && this.#realtimePolicy !== 'off') {
+            return new Promise((resolve, reject) => {
+                // sync() already enforces one round in flight (§8.7).
+                this.#pendingRound = {
+                    scanner: new MessageStreamScanner(),
+                    resolve,
+                    reject,
+                };
+                const tagged = new Uint8Array(request.length + 1);
+                tagged[0] = REALTIME_TAG_ROUND;
+                tagged.set(request, 1);
+                try {
+                    socket.sendBytes(tagged);
+                }
+                catch (error) {
+                    this.#pendingRound = undefined;
+                    // The socket could not carry the round: record the same loss the
+                    // Rust core records when its realtime round call fails (§8.8).
+                    this.#setRealtimeState('lost', 'sync.transport_failed');
+                    reject(new ClientSyncError('sync.transport_failed', `socket round send failed: ${error instanceof Error ? error.message : String(error)}`, true));
                 }
-                throw new ClientSyncError('sync.transport_failed', `transport round failed: ${error instanceof Error ? error.message : String(error)}`, true);
             });
         }
-        return new Promise((resolve, reject) => {
-            // sync() already enforces one round in flight (§8.7).
-            this.#pendingRound = {
-                scanner: new MessageStreamScanner(),
-                resolve,
-                reject,
-            };
-            const tagged = new Uint8Array(request.length + 1);
-            tagged[0] = REALTIME_TAG_ROUND;
-            tagged.set(request, 1);
-            try {
-                socket.sendBytes(tagged);
-            }
-            catch (error) {
-                this.#pendingRound = undefined;
-                reject(new ClientSyncError('sync.transport_failed', `socket round send failed: ${error instanceof Error ? error.message : String(error)}`, true));
+        if (this.#realtimePolicy === 'required') {
+            // §8.8: the designated realtime path is down. Refuse the round; the
+            // HTTP binding is not an alternative for a `required` client.
+            throw this.#realtimeUnavailableError();
+        }
+        return Promise.resolve()
+            .then(() => this.#config.transport(request))
+            .catch((error) => {
+            if (error instanceof ClientSyncError ||
+                typeof error?.code === 'string') {
+                throw error;
             }
+            throw new ClientSyncError('sync.transport_failed', `transport round failed: ${error instanceof Error ? error.message : String(error)}`, true);
         });
     }
     /** Abort the in-flight socket round (socket closed or disconnected). */
@@ -2558,14 +2606,39 @@ export class SyncClient {
         round.reject(new ClientSyncError('sync.transport_failed', reason, true));
     }
     // -- realtime (§8 client side) ----------------------------------------------
+    /**
+     * SPEC §8.8: record an availability transition and the evidence behind it.
+     * The reason and retry delay belong to the state that is no longer
+     * connected; `connected` and a policy-restricted state clear them.
+     */
+    #setRealtimeState(state, reasonCode) {
+        this.#realtimeState = state;
+        this.#realtimeReasonCode =
+            reasonCode === undefined ? undefined : this.#diagnosticCode(reasonCode);
+        if (state === 'connected' ||
+            state === 'disabled' ||
+            state === 'unsupported') {
+            this.#realtimeRetryDelayMs = undefined;
+        }
+        this.#emitDiagnostics();
+    }
+    #realtimeUnavailableError() {
+        this.#realtimeRetryDelayMs = this.#retryDelayMs;
+        return new RealtimeUnavailableError(this.#realtimeState, this.#realtimeReasonCode, this.#retryDelayMs);
+    }
     connectRealtime() {
         this.#requireActive();
+        if (this.#realtimePolicy === 'off') {
+            return Promise.reject(new ClientSyncError('sync.invalid_request', "realtimePolicy is 'off'; realtime connect is refused"));
+        }
         if (this.#socket !== undefined)
             return Promise.resolve();
         if (this.#realtimeConnectPromise !== undefined) {
             return this.#realtimeConnectPromise;
         }
         const generation = this.#realtimeGeneration;
+        // The attempt is visible synchronously; runners of the task share it.
+        this.#setRealtimeState('connecting');
         const task = this.#runProtectedAsync(() => this.#connectRealtime(generation));
         this.#realtimeConnectPromise = task;
         void task.then(() => {
@@ -2585,37 +2658,50 @@ export class SyncClient {
             throw new ClientSyncError('sync.invalid_request', 'no realtime connector configured');
         }
         let openedSocket;
-        const socket = await connector({
-            onText: (text) => {
-                if (generation !== this.#realtimeGeneration || !this.#started)
-                    return;
-                this.#handleRealtimeText(text);
-            },
-            onBinary: (bytes) => {
-                if (generation !== this.#realtimeGeneration || !this.#started)
-                    return;
-                this.#routeRealtimeBinary(bytes);
-            },
-            onClose: () => {
-                if (openedSocket === undefined || this.#socket !== openedSocket)
-                    return;
-                this.#socket = undefined;
-                this.#presence.clear(); // §8.6.1: presence is per-connection
-                this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
-                this.#emitDiagnostics();
-            },
-        });
-        openedSocket = socket;
-        if (this.#securityLifecycle === 'preflight') {
-            socket.close();
-            throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'realtime connected after the client entered security preflight');
+        try {
+            const socket = await connector({
+                onText: (text) => {
+                    if (generation !== this.#realtimeGeneration || !this.#started)
+                        return;
+                    this.#handleRealtimeText(text);
+                },
+                onBinary: (bytes) => {
+                    if (generation !== this.#realtimeGeneration || !this.#started)
+                        return;
+                    this.#routeRealtimeBinary(bytes);
+                },
+                onClose: () => {
+                    if (openedSocket === undefined || this.#socket !== openedSocket)
+                        return;
+                    this.#socket = undefined;
+                    this.#presence.clear(); // §8.6.1: presence is per-connection
+                    // §8.8: an undesired close is a visible lost state, not a silent
+                    // downgrade to HTTP rounds.
+                    this.#setRealtimeState('lost', REALTIME_LOST_CODE);
+                    this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
+                    this.#emitDiagnostics();
+                },
+            });
+            openedSocket = socket;
+            if (this.#securityLifecycle === 'preflight') {
+                socket.close();
+                throw new ClientSyncError(SECURITY_PREFLIGHT_REQUIRED_CODE, 'realtime connected after the client entered security preflight');
+            }
+            if (generation !== this.#realtimeGeneration || !this.#started) {
+                socket.close();
+                throw new ClientSyncError('client.realtime_cancelled', 'realtime connection was cancelled before activation');
+            }
+            this.#socket = socket;
+            this.#setRealtimeState('connected');
         }
-        if (generation !== this.#realtimeGeneration || !this.#started) {
-            socket.close();
-            throw new ClientSyncError('client.realtime_cancelled', 'realtime connection was cancelled before activation');
+        catch (error) {
+            // A superseded attempt leaves the successor's (or the deliberate
+            // disconnect's) state alone.
+            if (generation === this.#realtimeGeneration) {
+                this.#setRealtimeState('refused', realtimeErrorCode(error));
+            }
+            throw error;
         }
-        this.#socket = socket;
-        this.#emitDiagnostics();
     }
     disconnectRealtime() {
         this.#realtimeGeneration += 1;
@@ -2624,7 +2710,11 @@ export class SyncClient {
         this.#socket = undefined;
         this.#presence.clear(); // §8.6.1: presence is per-connection
         this.#abortPendingRound('realtime socket disconnected mid-round (§8.7)');
-        this.#emitDiagnostics();
+        this.#setRealtimeState(this.#realtimePolicy === 'off'
+            ? 'disabled'
+            : this.#config.realtime === undefined
+                ? 'unsupported'
+                : 'disconnected');
     }
     /**
      * §8.7 channel-tag routing (synchronous, so chunk order is preserved):

package/dist/diagnostics.d.ts

@@ -13,12 +13,23 @@ export declare const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
 export type ClientDiagnosticsHostKind = 'direct' | 'worker' | 'tauri' | 'react-native';
 export type ClientDiagnosticsHostRole = 'single' | 'leader' | 'follower' | 'unknown';
 export type ClientDiagnosticsConnectivity = 'online' | 'offline' | 'unknown';
-export type ClientDiagnosticsRealtime = 'connected' | 'disconnected' | 'unsupported' | 'unknown';
+/**
+ * SPEC §8.8: how a client treats the realtime binding for sync rounds. The
+ * default is `optional`.
+ */
+export type RealtimePolicy = 'required' | 'optional' | 'off';
+export type RealtimeState = 'connected' | 'connecting' | 'disconnected' | 'lost' | 'refused' | 'unsupported' | 'disabled' | 'unknown';
 export interface ClientDiagnosticsHost {
     readonly kind: ClientDiagnosticsHostKind;
     readonly role: ClientDiagnosticsHostRole;
     readonly connectivity: ClientDiagnosticsConnectivity;
-    readonly realtime: ClientDiagnosticsRealtime;
+    readonly realtime: RealtimeState;
+    /** Present on core-emitted snapshots; host wrappers may forward only `realtime`. */
+    readonly realtimePolicy?: RealtimePolicy;
+    /** Stable code behind a `lost` or `refused` state (SPEC §8.8). */
+    readonly realtimeReasonCode?: string;
+    /** Next retry delay in ms while the socket is not connected. */
+    readonly realtimeRetryDelayMs?: number;
 }
 export interface ExpectedDiagnosticSubscription {
     /** Application-owned stable identifier. It must never contain PHI. */

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import type { RealtimeState } from './diagnostics.js';
 /** A persistent local store is temporarily owned by another live engine. */
 export declare const STORAGE_BUSY_CODE = "client.storage_busy";
 /** The browser cannot provide the persistent storage APIs Syncular requires. */
@@ -6,17 +7,35 @@ export declare const STORAGE_UNAVAILABLE_CODE = "client.storage_unavailable";
 export declare const STORAGE_CORRUPT_CODE = "client.storage_corrupt";
 /** A local read hit SQLITE_IOERR (SPEC §7.5). */
 export declare const STORAGE_IO_CODE = "client.storage_io";
+/** SPEC §8.8: a round under `realtimePolicy: 'required'` found no socket. */
+export declare const REALTIME_UNAVAILABLE_CODE = "sync.realtime_unavailable";
+/** SPEC §8.8: a connected socket ended without a deliberate disconnect. */
+export declare const REALTIME_LOST_CODE = "client.realtime_lost";
 /**
  * Client-side errors. Protocol codes from the SPEC.md §10 catalog are surfaced
  * unchanged. Host/runtime-only conditions may use the separate `client.*`
  * namespace and never travel on the wire.
  */
 export declare class ClientSyncError extends Error {
-    readonly name = "ClientSyncError";
+    readonly name: string;
     readonly code: string;
     readonly retryable: boolean;
     constructor(code: string, message: string, retryable?: boolean);
 }
+/**
+ * SPEC §8.8: the `required` realtime policy refused a round because the
+ * socket is not connected. `state` is the availability state that refused
+ * (`connecting`, `lost`, `refused`, or `disconnected`), `reasonCode` is the
+ * stable code behind a `lost` or `refused` state, and `retryDelayMs` is the
+ * delay of the background retry intent the client scheduled with this throw.
+ */
+export declare class RealtimeUnavailableError extends ClientSyncError {
+    readonly name = "RealtimeUnavailableError";
+    readonly state: RealtimeState;
+    readonly reasonCode: string | undefined;
+    readonly retryDelayMs: number;
+    constructor(state: RealtimeState, reasonCode: string | undefined, retryDelayMs: number);
+}
 /**
  * SPEC §7.5: classify a local SQLite read failure by the numeric result code
  * the driver exposes (bun:sqlite `errno`, node:sqlite `errcode`, sqlite-wasm

package/dist/errors.js

@@ -6,6 +6,10 @@ export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
 export const STORAGE_CORRUPT_CODE = 'client.storage_corrupt';
 /** A local read hit SQLITE_IOERR (SPEC §7.5). */
 export const STORAGE_IO_CODE = 'client.storage_io';
+/** SPEC §8.8: a round under `realtimePolicy: 'required'` found no socket. */
+export const REALTIME_UNAVAILABLE_CODE = 'sync.realtime_unavailable';
+/** SPEC §8.8: a connected socket ended without a deliberate disconnect. */
+export const REALTIME_LOST_CODE = 'client.realtime_lost';
 /**
  * Client-side errors. Protocol codes from the SPEC.md §10 catalog are surfaced
  * unchanged. Host/runtime-only conditions may use the separate `client.*`
@@ -21,6 +25,25 @@ export class ClientSyncError extends Error {
         this.retryable = retryable;
     }
 }
+/**
+ * SPEC §8.8: the `required` realtime policy refused a round because the
+ * socket is not connected. `state` is the availability state that refused
+ * (`connecting`, `lost`, `refused`, or `disconnected`), `reasonCode` is the
+ * stable code behind a `lost` or `refused` state, and `retryDelayMs` is the
+ * delay of the background retry intent the client scheduled with this throw.
+ */
+export class RealtimeUnavailableError extends ClientSyncError {
+    name = 'RealtimeUnavailableError';
+    state;
+    reasonCode;
+    retryDelayMs;
+    constructor(state, reasonCode, retryDelayMs) {
+        super(REALTIME_UNAVAILABLE_CODE, 'realtime is required and the realtime socket is not connected', true);
+        this.state = state;
+        this.reasonCode = reasonCode;
+        this.retryDelayMs = retryDelayMs;
+    }
+}
 /**
  * SPEC §7.5: classify a local SQLite read failure by the numeric result code
  * the driver exposes (bun:sqlite `errno`, node:sqlite `errcode`, sqlite-wasm

package/dist/http.d.ts

@@ -7,7 +7,12 @@
 import type { BlobTransport } from './blob.js';
 import type { RealtimeConnector, RemoteOperationTransport, RemoteOperationRealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
 export interface HttpTransportOptions {
-    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Host auth headers. A function is read on every request, so a rotated
+     * token applies from the next request on. Signed-URL fetches never
+     * carry them (§5.4, §5.9.5).
+     */
+    readonly headers?: Readonly<Record<string, string>> | (() => Readonly<Record<string, string>>);
     readonly fetch?: typeof fetch;
 }
 /** POST `<mount>/sync` with SSP2 bodies (§1.1). */

package/dist/http.js

@@ -18,6 +18,10 @@ async function throwHttpError(response) {
     }
     throw new ClientSyncError(code, message, retryable);
 }
+function hostHeaders(options) {
+    const headers = options?.headers;
+    return typeof headers === 'function' ? headers() : headers;
+}
 /** POST `<mount>/sync` with SSP2 bodies (§1.1). */
 export function httpSyncTransport(syncUrl, options) {
     const doFetch = options?.fetch ?? fetch;
@@ -26,7 +30,7 @@ export function httpSyncTransport(syncUrl, options) {
             method: 'POST',
             headers: {
                 'Content-Type': SSP2_CONTENT_TYPE,
-                ...options?.headers,
+                ...hostHeaders(options),
             },
             body: request.slice().buffer,
         });
@@ -43,7 +47,7 @@ export function httpRemoteOperationTransport(operationsUrl, options) {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/vnd.syncular.operations.v1+json',
-                ...options?.headers,
+                ...hostHeaders(options),
             },
             body: request.slice().buffer,
         });
@@ -136,7 +140,7 @@ export function httpSegmentDownloader(segmentsBaseUrl, options) {
         const response = await doFetch(`${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`, {
             headers: {
                 'X-Syncular-Scopes': request.requestedScopesJson,
-                ...options?.headers,
+                ...hostHeaders(options),
             },
         });
         if (!response.ok)
@@ -168,7 +172,7 @@ export function httpBlobTransport(blobsBaseUrl, options) {
                 method: 'PUT',
                 headers: {
                     'Content-Type': mediaType ?? 'application/octet-stream',
-                    ...options?.headers,
+                    ...hostHeaders(options),
                 },
                 body: bytes.slice().buffer,
             });
@@ -177,7 +181,7 @@ export function httpBlobTransport(blobsBaseUrl, options) {
         },
         download: async (blobId) => {
             const response = await doFetch(blobUrl(blobId), {
-                headers: { ...options?.headers },
+                headers: { ...hostHeaders(options) },
             });
             if (!response.ok)
                 await throwHttpError(response);
@@ -215,7 +219,7 @@ export function httpBlobTransport(blobsBaseUrl, options) {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
-                    ...options?.headers,
+                    ...hostHeaders(options),
                 },
                 body: JSON.stringify({
                     byteLength,

package/dist/multi-tab.d.ts

@@ -28,14 +28,6 @@ interface HelloMessage {
      * advance even if it never saw the previous leader's announce). */
     readonly epoch?: number;
 }
-interface ByeMessage {
-    readonly t: 'bye';
-    readonly fromId: string;
-}
-interface BoundMessage {
-    readonly t: 'bound';
-    readonly fromId: string;
-}
 interface ReqMessage {
     readonly t: 'req';
     readonly epoch: number;
@@ -66,7 +58,7 @@ interface EventMessage {
     readonly epoch: number;
     readonly event: SyncWorkerEvent;
 }
-export type MultiTabMessage = HelloMessage | ByeMessage | BoundMessage | ReqMessage | AnnounceMessage | ResMessage | EventMessage;
+export type MultiTabMessage = HelloMessage | ReqMessage | AnnounceMessage | ResMessage | EventMessage;
 /**
  * The tiny cross-tab channel surface we depend on — the DOM `BroadcastChannel`
  * satisfies it. Injectable so bun tests can pair two instances by name.
@@ -100,20 +92,26 @@ export declare class LeaderBridge {
         epoch: number;
         clientId: string;
         invoke: (method: string, args: readonly unknown[]) => Promise<unknown>;
-        heartbeatMs?: number;
     });
-    /** Re-announce leadership (on promotion and on a follower `hello`). */
+    /** Announce leadership (on promotion and in answer to every `hello`). */
     announce(): void;
     /** Fan a worker event out to all followers on the current epoch. */
     broadcastEvent(event: SyncWorkerEvent): void;
     close(): void;
 }
+/**
+ * Timer seam for {@link FollowerLink}: run `callback` after `delayMs` and
+ * return a function that cancels it. Tests inject a manual clock.
+ */
+type FollowerSchedule = (callback: () => void, delayMs: number) => () => void;
 /**
  * Runs on a follower tab. Sends `req`s to the leader and settles them on the
  * matching `res`; queues calls (bounded, timed) while no leader is bound (the
  * handover gap) and flushes them once an `announce` binds a new leader.
  * Feeds fanned-out events to `onEvent`. Learns leadership changes and hands
- * the resolved leader `clientId` back through `onLeaderChange`.
+ * the resolved leader `clientId` back through `onLeaderChange`. Probes the
+ * bound leader with `hello` after a quiet period and reports `blocked` only
+ * when a probe goes unanswered (see the module comment).
  */
 export declare class FollowerLink {
     #private;
@@ -125,6 +123,7 @@ export declare class FollowerLink {
         onStateChange?: (state: LeadershipState) => void;
         callTimeoutMs?: number;
         queueLimit?: number;
+        schedule?: FollowerSchedule;
     });
     get epoch(): number;
     get maxEpochSeen(): number;