@syncular/client 0.25.2 → 0.26.1

package/dist/multi-tab.js

@@ -11,11 +11,12 @@
  * survive `postMessage` on a BroadcastChannel):
  *
  *   follower → leader
- *     hello  {t,epoch?,fromId}                — "who's the leader?" on join
+ *     hello  {t,epoch?,fromId}                — "who's the leader?" on join,
+ *                                                and the follower's liveness probe
  *     req    {t,epoch,fromId,reqId,method,args}
- *     bye    {t,fromId}                        — follower leaving (best effort)
  *   leader → all
- *     announce {t,epoch,clientId}             — "I am the leader, this epoch"
+ *     announce {t,epoch,clientId}             — "I am the leader, this epoch";
+ *                                                the answer to every hello
  *     res      {t,epoch,reqId,ok,value|error} — reply to one req
  *     event    {t,epoch,event}                — fan-out (invalidate/presence/…)
  *
@@ -29,6 +30,16 @@
  * promoter reads the highest epoch it has seen and adds one, so successive
  * leaders always strictly increase it even across the lock-handover gap.
  *
+ * Liveness is follower-driven: the leader runs no timer. Browsers throttle
+ * the timers of a hidden tab (Chrome's intensive throttling wakes them about
+ * once a minute) but still dispatch its BroadcastChannel messages, so a leader
+ * heartbeat misses its schedule in a background leader tab while that tab is
+ * alive. Instead, a bound follower that has heard no `announce` for a third of
+ * its call timeout posts a `hello`, and goes `blocked` only when that probe
+ * stays unanswered for the rest of the timeout. A leader tab whose main thread
+ * processes no messages (hung or frozen) therefore still blocks its followers
+ * within `callTimeoutMs`, and a closed leader hands over through the lock.
+ *
  * Presence identity: all tabs share the leader's one connection, so a device
  * is exactly ONE presence peer collectively — `(actorId, leaderClientId)`.
  * A follower's `setPresence` forwards to the leader's single publisher; there
@@ -73,23 +84,17 @@ export class LeaderBridge {
     #clientId;
     #invoke;
     #onMessage;
-    #heartbeatMs;
-    #followers = new Set();
-    #heartbeat;
     #closed = false;
     constructor(options) {
         this.#channel = options.channel;
         this.#epoch = options.epoch;
         this.#clientId = options.clientId;
         this.#invoke = options.invoke;
-        this.#heartbeatMs =
-            options.heartbeatMs ??
-                Math.max(50, Math.floor(DEFAULT_FOLLOWER_CALL_TIMEOUT_MS / 3));
         this.#onMessage = (event) => this.#handle(event.data);
         this.#channel.addEventListener('message', this.#onMessage);
         this.announce();
     }
-    /** Re-announce leadership (on promotion and on a follower `hello`). */
+    /** Announce leadership (on promotion and in answer to every `hello`). */
     announce() {
         if (this.#closed)
             return;
@@ -109,23 +114,10 @@ export class LeaderBridge {
         if (this.#closed)
             return;
         if (message.t === 'hello') {
-            // A follower joined (or is contesting) — tell it who leads.
-            this.#trackFollower(message.fromId);
+            // A follower joined or probes liveness: tell it who leads.
             this.announce();
             return;
         }
-        if (message.t === 'bound') {
-            this.#trackFollower(message.fromId);
-            return;
-        }
-        if (message.t === 'bye') {
-            this.#followers.delete(message.fromId);
-            if (this.#followers.size === 0 && this.#heartbeat !== undefined) {
-                clearInterval(this.#heartbeat);
-                this.#heartbeat = undefined;
-            }
-            return;
-        }
         if (message.t !== 'req')
             return;
         // Ignore requests stamped for a different (dead/older) leader; that
@@ -162,19 +154,10 @@ export class LeaderBridge {
             });
         });
     }
-    #trackFollower(fromId) {
-        this.#followers.add(fromId);
-        if (this.#heartbeat !== undefined)
-            return;
-        this.#heartbeat = setInterval(() => this.announce(), this.#heartbeatMs);
-    }
     close() {
         if (this.#closed)
             return;
         this.#closed = true;
-        if (this.#heartbeat !== undefined)
-            clearInterval(this.#heartbeat);
-        this.#heartbeat = undefined;
         this.#channel.removeEventListener('message', this.#onMessage);
         this.#channel.close();
     }
@@ -184,7 +167,9 @@ export class LeaderBridge {
  * 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 class FollowerLink {
     #channel;
@@ -193,7 +178,10 @@ export class FollowerLink {
     #onLeaderChange;
     #onStateChange;
     #callTimeoutMs;
+    /** Quiet period before a bound follower probes; also the blocked re-probe interval. */
+    #probeAfterMs;
     #queueLimit;
+    #schedule;
     #onMessage;
     /** -1 until the first `announce` binds us to a leader. */
     #epoch = -1;
@@ -208,8 +196,8 @@ export class FollowerLink {
         state: 'waiting',
         reason: 'leader-announcement',
     };
-    #waitingTimer;
-    #blockedTimer;
+    #cancelProbe;
+    #cancelBlocked;
     /** Resolvers waiting for the first `announce` to bind a leader. */
     #bindWaiters = [];
     constructor(options) {
@@ -220,12 +208,19 @@ export class FollowerLink {
         this.#onStateChange = options.onStateChange ?? (() => { });
         this.#callTimeoutMs =
             options.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
+        this.#probeAfterMs = Math.max(1, Math.floor(this.#callTimeoutMs / 3));
         this.#queueLimit = options.queueLimit ?? DEFAULT_FOLLOWER_QUEUE_LIMIT;
+        this.#schedule =
+            options.schedule ??
+                ((callback, delayMs) => {
+                    const timer = setTimeout(callback, delayMs);
+                    return () => clearTimeout(timer);
+                });
         this.#onMessage = (event) => this.#handle(event.data);
         this.#channel.addEventListener('message', this.#onMessage);
-        // Ask the current leader to announce itself.
-        this.#channel.postMessage({ t: 'hello', fromId: this.#fromId });
         this.#armUnboundDeadline();
+        // Ask the current leader to announce itself.
+        this.#probe();
     }
     get epoch() {
         return this.#epoch;
@@ -260,13 +255,13 @@ export class FollowerLink {
             return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'the follower link is closed'));
         }
         return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
+            const cancelTimer = this.#schedule(() => {
                 this.#dropBindWaiter(settle);
                 this.#setBlocked();
                 reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader announced within the follower bind timeout', true));
             }, timeoutMs);
             const settle = () => {
-                clearTimeout(timer);
+                cancelTimer();
                 resolve();
             };
             this.#bindWaiters.push(settle);
@@ -299,7 +294,7 @@ export class FollowerLink {
                 args,
                 resolve,
                 reject,
-                timer: undefined,
+                cancelTimer: undefined,
             };
             if (this.#epoch < 0) {
                 // No leader bound yet — queue with a deadline so we never hang.
@@ -308,7 +303,7 @@ export class FollowerLink {
                     reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'follower call queue overflow while awaiting a leader', true));
                     return;
                 }
-                queued.timer = setTimeout(() => {
+                queued.cancelTimer = this.#schedule(() => {
                     this.#dropQueued(queued);
                     this.#setBlocked();
                     reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'no leader answered within the follower call timeout', true));
@@ -321,16 +316,17 @@ export class FollowerLink {
     }
     #send(queued) {
         const reqId = this.#nextReqId++;
-        const inflight = {
+        // The deadline fails this one call. Leader reachability is decided by the
+        // liveness probe alone, so a slow call against a live leader leaves the
+        // link bound.
+        this.#inFlight.set(reqId, {
             resolve: queued.resolve,
             reject: queued.reject,
-            timer: setTimeout(() => {
+            cancelTimer: this.#schedule(() => {
                 this.#inFlight.delete(reqId);
-                this.#setBlocked();
                 queued.reject(new ClientSyncError(FOLLOWER_TIMEOUT_CODE, 'the leader did not answer within the follower call timeout', true));
             }, this.#callTimeoutMs),
-        };
-        this.#inFlight.set(reqId, inflight);
+        });
         this.#channel.postMessage({
             t: 'req',
             epoch: this.#epoch,
@@ -366,10 +362,7 @@ export class FollowerLink {
                 leaderClientId: message.clientId,
                 epoch: message.epoch,
             });
-            this.#armBoundDeadline();
-            if (changed) {
-                this.#channel.postMessage({ t: 'bound', fromId: this.#fromId });
-            }
+            this.#armLivenessProbe();
             this.#resolveBindWaiters();
             this.#flushQueue();
             return;
@@ -383,8 +376,7 @@ export class FollowerLink {
             if (inflight === undefined)
                 return;
             this.#inFlight.delete(message.reqId);
-            if (inflight.timer !== undefined)
-                clearTimeout(inflight.timer);
+            inflight.cancelTimer();
             if (message.ok) {
                 inflight.resolve(message.value);
             }
@@ -406,9 +398,8 @@ export class FollowerLink {
         const pending = this.#queue;
         this.#queue = [];
         for (const queued of pending) {
-            if (queued.timer !== undefined)
-                clearTimeout(queued.timer);
-            queued.timer = undefined;
+            queued.cancelTimer?.();
+            queued.cancelTimer = undefined;
             this.#send(queued);
         }
     }
@@ -425,11 +416,7 @@ export class FollowerLink {
         this.#leaderClientId = '';
         this.#setState({ state: 'waiting', reason: 'handover' });
         this.#armUnboundDeadline();
-        this.#channel.postMessage({
-            t: 'hello',
-            fromId: this.#fromId,
-            epoch: this.#maxEpochSeen,
-        });
+        this.#probe();
     }
     close() {
         if (this.#closed)
@@ -437,17 +424,14 @@ export class FollowerLink {
         this.#closed = true;
         this.#clearReachabilityTimers();
         this.#channel.removeEventListener('message', this.#onMessage);
-        this.#channel.postMessage({ t: 'bye', fromId: this.#fromId });
         const closedError = new ClientSyncError(WORKER_FAILED_CODE, 'the follower link was closed');
         for (const inflight of this.#inFlight.values()) {
-            if (inflight.timer !== undefined)
-                clearTimeout(inflight.timer);
+            inflight.cancelTimer();
             inflight.reject(closedError);
         }
         this.#inFlight.clear();
         for (const queued of this.#queue) {
-            if (queued.timer !== undefined)
-                clearTimeout(queued.timer);
+            queued.cancelTimer?.();
             queued.reject(closedError);
         }
         this.#queue = [];
@@ -477,6 +461,18 @@ export class FollowerLink {
             // A status listener must never break cross-tab coordination.
         }
     }
+    /** Ask the leader to announce itself; every live leader answers a `hello`. */
+    #probe() {
+        this.#channel.postMessage({
+            t: 'hello',
+            fromId: this.#fromId,
+            epoch: this.#maxEpochSeen,
+        });
+    }
+    /**
+     * No leader answered in time. Calls reject immediately from here on; keep
+     * probing so a leader that answers again rebinds this link.
+     */
     #setBlocked() {
         this.#clearReachabilityTimers();
         this.#setState({
@@ -485,24 +481,36 @@ export class FollowerLink {
             code: FOLLOWER_TIMEOUT_CODE,
             retryable: true,
         });
+        const reprobe = () => {
+            this.#cancelProbe = this.#schedule(() => {
+                reprobe();
+                this.#probe();
+            }, this.#probeAfterMs);
+        };
+        reprobe();
     }
     #armUnboundDeadline() {
         this.#clearReachabilityTimers();
-        this.#blockedTimer = setTimeout(() => this.#setBlocked(), this.#callTimeoutMs);
+        this.#cancelBlocked = this.#schedule(() => this.#setBlocked(), this.#callTimeoutMs);
     }
-    #armBoundDeadline() {
+    /**
+     * An announce just proved the leader alive. After a quiet period, probe it;
+     * block only if that probe stays unanswered for the rest of the call
+     * timeout. The deadline is armed before the probe is posted so a reply that
+     * arrives synchronously clears it.
+     */
+    #armLivenessProbe() {
         this.#clearReachabilityTimers();
-        this.#waitingTimer = setTimeout(() => {
-            this.#setState({ state: 'waiting', reason: 'leader-announcement' });
-        }, Math.max(1, Math.floor((this.#callTimeoutMs * 2) / 3)));
-        this.#blockedTimer = setTimeout(() => this.#setBlocked(), this.#callTimeoutMs);
+        this.#cancelProbe = this.#schedule(() => {
+            this.#cancelProbe = undefined;
+            this.#cancelBlocked = this.#schedule(() => this.#setBlocked(), this.#callTimeoutMs - this.#probeAfterMs);
+            this.#probe();
+        }, this.#probeAfterMs);
     }
     #clearReachabilityTimers() {
-        if (this.#waitingTimer !== undefined)
-            clearTimeout(this.#waitingTimer);
-        if (this.#blockedTimer !== undefined)
-            clearTimeout(this.#blockedTimer);
-        this.#waitingTimer = undefined;
-        this.#blockedTimer = undefined;
+        this.#cancelProbe?.();
+        this.#cancelBlocked?.();
+        this.#cancelProbe = undefined;
+        this.#cancelBlocked = undefined;
     }
 }

package/dist/realtime-supervisor.js

@@ -384,7 +384,8 @@ export class RealtimeSupervisor {
             return;
         this.#diagnosticConnectivity = snapshot.host.connectivity;
         this.#diagnosticSecurity = snapshot.securityLifecycle;
-        if (snapshot.host.realtime === 'unsupported') {
+        if (snapshot.host.realtime === 'unsupported' ||
+            snapshot.host.realtime === 'disabled') {
             const disconnect = this.#connected || this.#transportConnected || this.#connecting;
             this.#realtimeSupported = false;
             this.#generation += 1;
@@ -420,7 +421,16 @@ export class RealtimeSupervisor {
             void this.#adoptConnectedTransport();
             return;
         }
-        if (snapshot.host.realtime === 'disconnected') {
+        if (snapshot.host.realtime === 'connecting') {
+            // An attempt is already in flight; the supervisor's own #connect (or
+            // the host's direct call) owns the outcome.
+            this.#transportConnected = false;
+            this.#connected = false;
+            return;
+        }
+        if (snapshot.host.realtime === 'disconnected' ||
+            snapshot.host.realtime === 'lost' ||
+            snapshot.host.realtime === 'refused') {
             this.#transportConnected = false;
             this.#connected = false;
             if (this.#connecting)

package/dist/worker-entry.d.ts

@@ -8,7 +8,11 @@ export interface SyncWorkerOverrides {
     readonly waitForStorageRetry?: (delayMs: number) => Promise<void>;
     readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
     readonly createSegments?: (config: WorkerInitConfig) => SegmentDownloader | undefined;
-    readonly createRealtime?: (config: WorkerInitConfig, clientId: string) => RealtimeConnector | undefined;
+    /**
+     * Custom realtime connector, e.g. one that mints a fresh ticket per
+     * connection attempt. `headers` reads the current host auth set.
+     */
+    readonly createRealtime?: (config: WorkerInitConfig, clientId: string, headers: () => Readonly<Record<string, string>>) => RealtimeConnector | undefined;
 }
 /**
  * Register the RPC server on the current worker scope. Call this once

package/dist/worker-entry.js

@@ -74,6 +74,7 @@ export function startSyncWorker(overrides = {}) {
     let client;
     let database;
     let offline = false;
+    let headers = {};
     let closed = false;
     // -- one sync loop: RPC-driven and auto-driven rounds serialize ----------
     let syncChain = Promise.resolve();
@@ -183,6 +184,8 @@ export function startSyncWorker(overrides = {}) {
             throw new ClientSyncError(WORKER_FAILED_CODE, 'the worker is already initialized');
         }
         autoSync = config.autoSync ?? true;
+        headers = config.headers ?? {};
+        const http = { headers: () => headers };
         for (let attempt = 0;; attempt++) {
             try {
                 database =
@@ -212,15 +215,15 @@ export function startSyncWorker(overrides = {}) {
         }
         const transport = gateOffline(overrides.createTransport !== undefined
             ? overrides.createTransport(config)
-            : httpSyncTransport(config.endpoints.syncUrl));
+            : httpSyncTransport(config.endpoints.syncUrl, http));
         const segments = overrides.createSegments !== undefined
             ? overrides.createSegments(config)
             : config.endpoints.segmentsUrl !== undefined
-                ? httpSegmentDownloader(config.endpoints.segmentsUrl)
+                ? httpSegmentDownloader(config.endpoints.segmentsUrl, http)
                 : undefined;
         // §5.9 blob transport: only when a blobs URL is configured.
         const blobs = config.endpoints.blobsUrl !== undefined
-            ? httpBlobTransport(config.endpoints.blobsUrl)
+            ? httpBlobTransport(config.endpoints.blobsUrl, http)
             : undefined;
         // Realtime needs the (possibly persisted) clientId for the
         // `{clientId}` URL placeholder — start the client first, then attach
@@ -245,6 +248,9 @@ export function startSyncWorker(overrides = {}) {
             },
             ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
             ...(config.limits !== undefined ? { limits: config.limits } : {}),
+            ...(config.realtimePolicy !== undefined
+                ? { realtimePolicy: config.realtimePolicy }
+                : {}),
             ...(config.encryption !== undefined
                 ? { encryption: encryptionConfigFromKeyring(config.encryption) }
                 : {}),
@@ -299,7 +305,7 @@ export function startSyncWorker(overrides = {}) {
         await started.start();
         realtimeConnector =
             overrides.createRealtime !== undefined
-                ? overrides.createRealtime(config, started.clientId)
+                ? overrides.createRealtime(config, started.clientId, http.headers)
                 : config.endpoints.realtimeUrl !== undefined
                     ? webSocketRealtimeConnector(config.endpoints.realtimeUrl.replace('{clientId}', encodeURIComponent(started.clientId)))
                     : undefined;
@@ -383,6 +389,9 @@ export function startSyncWorker(overrides = {}) {
         presence: (scopeKey) => requireClient().presence(scopeKey),
         uploadBlob: (bytes, options) => requireClient().uploadBlob(bytes, options),
         fetchBlob: (blobIdOrRef) => requireClient().fetchBlob(blobIdOrRef),
+        setHeaders: (next) => {
+            headers = next;
+        },
         setOffline: (value) => {
             offline = value;
             if (offline)

package/dist/worker-host.d.ts

@@ -27,7 +27,7 @@ import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
 import type { ConflictRecord, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
-import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.js';
+import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
 import { ClientSyncError } from './errors.js';
 import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
@@ -75,12 +75,23 @@ export interface SyncClientHandleConfig {
     readonly schema: ClientSchema;
     readonly database: WorkerDatabaseInit;
     readonly endpoints: WorkerEndpoints;
+    /**
+     * Host auth headers for sync, segment, and blob requests (e.g.
+     * `Authorization`). Rotate with `setHeaders`. Realtime authenticates
+     * through `realtimeUrl`, because WebSockets cannot carry headers.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
     /** Structured-clone-safe E2EE keyring installed only in the leader worker. */
     readonly encryption?: EncryptionKeyringConfig;
     /** Open the worker-owned replica behind the fail-closed security gate. */
     readonly securityPreflight?: boolean;
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
+    /**
+     * SPEC §8.8 realtime policy for the worker-owned core, forwarded into
+     * `WorkerInitConfig`. Absent ⇒ `optional`.
+     */
+    readonly realtimePolicy?: RealtimePolicy;
     /**
      * RFC 0005 previous-version context, forwarded into the worker's
      * `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
@@ -103,7 +114,11 @@ export interface SyncClientHandleConfig {
     readonly multiTab?: boolean;
     /** Cross-tab channel factory (default `BroadcastChannel`); injectable for tests. */
     readonly channelFactory?: (name: string) => CrossTabChannel;
-    /** Deadline for a follower call (covers the leader-handover gap). */
+    /**
+     * Deadline for a follower call (covers the leader-handover gap), and the
+     * bound on leader silence: a follower probes after a third of it and goes
+     * `blocked` when the probe stays unanswered for the rest. Default 10 s.
+     */
     readonly followerCallTimeoutMs?: number;
     /** Fires when this handle's role changes (follower → leader on promotion). */
     readonly onRoleChange?: (role: HandleRole) => void;
@@ -245,6 +260,14 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
         readonly name?: string;
     }): Promise<BlobRef>;
     fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
+    /**
+     * Replace the full host auth header set. The next HTTP request uses it;
+     * a live realtime socket keeps its handshake credentials. A follower
+     * forwards to the leader and keeps the set for its own promotion.
+     */
+    setHeaders(headers: Readonly<Record<string, string>>): Promise<void>;
+    /** @internal — the latest `setHeaders` set, carried into a promotion. */
+    __headers: Readonly<Record<string, string>> | undefined;
     /** Sever/restore transport + realtime inside the worker (demos). */
     setOffline(offline: boolean): Promise<void>;
     /** Close the core (leader) or unbind the link (follower), release leadership. */

package/dist/worker-host.js

@@ -361,6 +361,17 @@ export class SyncClientHandle {
     fetchBlob(blobIdOrRef) {
         return this.#call('fetchBlob', [blobIdOrRef]);
     }
+    /**
+     * Replace the full host auth header set. The next HTTP request uses it;
+     * a live realtime socket keeps its handshake credentials. A follower
+     * forwards to the leader and keeps the set for its own promotion.
+     */
+    setHeaders(headers) {
+        this.__headers = headers;
+        return this.#call('setHeaders', [headers]);
+    }
+    /** @internal — the latest `setHeaders` set, carried into a promotion. */
+    __headers;
     /** Sever/restore transport + realtime inside the worker (demos). */
     setOffline(offline) {
         return this.#call('setOffline', [offline]);
@@ -487,11 +498,12 @@ async function startWorkerCore(options) {
         throw error;
     }
 }
-function buildInitConfig(config) {
+function buildInitConfig(config, headers = config.headers) {
     return {
         schema: config.schema,
         database: config.database,
         endpoints: config.endpoints,
+        ...(headers !== undefined ? { headers } : {}),
         ...(config.encryption !== undefined
             ? { encryption: config.encryption }
             : {}),
@@ -500,6 +512,9 @@ function buildInitConfig(config) {
             : {}),
         ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
         ...(config.limits !== undefined ? { limits: config.limits } : {}),
+        ...(config.realtimePolicy !== undefined
+            ? { realtimePolicy: config.realtimePolicy }
+            : {}),
         ...(config.previousVersionContext !== undefined
             ? { previousVersionContext: config.previousVersionContext }
             : {}),
@@ -615,7 +630,6 @@ async function bootLeader(config, lockName, lease, parts) {
                 epoch: parts.epoch ?? 0,
                 clientId,
                 invoke,
-                heartbeatMs: Math.max(10, Math.floor((config.followerCallTimeoutMs ?? 10_000) / 3)),
             });
         }
         : undefined;
@@ -691,7 +705,7 @@ async function bootFollower(config, lockName, lock, parts) {
         try {
             const core = await startWorkerCore({
                 config,
-                initConfig: buildInitConfig(config),
+                initConfig: buildInitConfig(config, handle.__headers ?? config.headers),
                 lease,
                 dispatchEvent: (event) => {
                     fireConfigCallbacks(config, event);
@@ -706,7 +720,6 @@ async function bootFollower(config, lockName, lock, parts) {
                                 epoch: nextEpoch,
                                 clientId,
                                 invoke,
-                                heartbeatMs: Math.max(10, Math.floor((config.followerCallTimeoutMs ?? 10_000) / 3)),
                             });
                         },
                     }

package/dist/worker-protocol.d.ts

@@ -21,7 +21,7 @@ import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob.js';
 import type { ConflictRecord, ClientSnapshotMethods, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, SecurityLifecycle, SubscribeInput, SyncClientConfig, SyncClientLimits, SyncSummary, WindowState } from './client.js';
 import type { SqlRow, SqlValue } from './database.js';
-import type { ClientDiagnosticsSnapshot } from './diagnostics.js';
+import type { ClientDiagnosticsSnapshot, RealtimePolicy } from './diagnostics.js';
 import type { EncryptionKeyringConfig } from './encryption.js';
 import type { ClientChangeBatch, LocalRevision } from './invalidation.js';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
@@ -68,12 +68,23 @@ export interface WorkerInitConfig {
     readonly schema: ClientSchema;
     readonly database: WorkerDatabaseInit;
     readonly endpoints: WorkerEndpoints;
+    /**
+     * Host auth headers for sync, segment, and blob requests. `setHeaders`
+     * replaces the whole set at runtime. WebSockets cannot carry headers, so
+     * realtime authenticates through `realtimeUrl` (cookie or ticket).
+     */
+    readonly headers?: Readonly<Record<string, string>>;
     /** Portable raw keyring installed inside the worker-owned client core. */
     readonly encryption?: EncryptionKeyringConfig;
     /** Open the worker-owned replica behind the fail-closed security gate. */
     readonly securityPreflight?: boolean;
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
+    /**
+     * SPEC §8.8 realtime policy for the worker-owned core; forwarded verbatim.
+     * Absent ⇒ `optional` (a connected socket, otherwise `POST /sync`).
+     */
+    readonly realtimePolicy?: RealtimePolicy;
     /**
      * RFC 0005 previous-version context, forwarded verbatim into the worker's
      * `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
@@ -142,6 +153,8 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
         readonly name?: string;
     }): Promise<BlobRef>;
     fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
+    /** Replace the host auth header set; the next HTTP request uses it. */
+    setHeaders(headers: Readonly<Record<string, string>>): void;
     /** Sever/restore the transport + realtime (offline simulation, demos). */
     setOffline(offline: boolean): void;
     close(): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.25.2",
+  "version": "0.26.1",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.25.2"
+    "@syncular/core": "0.26.1"
   },
   "devDependencies": {
-    "@syncular/server": "0.25.2",
+    "@syncular/server": "0.26.1",
     "playwright": "1.63.0"
   }
 }