@syncular/client 0.25.1 → 0.26.0

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/reactive-store.js

@@ -240,6 +240,27 @@ class ObservationCache {
         this.#active.clear();
     }
 }
+const EMPTY_ROWS = Object.freeze([]);
+const unreadQuerySnapshots = new Map();
+/** One frozen snapshot per phase and availability for entries that have no
+ * successful read, so switching between unread entries keeps the snapshot and
+ * `rows` identity. */
+function unreadQuerySnapshot(phase, availability) {
+    const key = canonicalValue([phase, availability]);
+    let snapshot = unreadQuerySnapshots.get(key);
+    if (snapshot === undefined) {
+        snapshot = Object.freeze({
+            rows: EMPTY_ROWS,
+            phase,
+            revision: undefined,
+            error: undefined,
+            isRefreshing: false,
+            availability,
+        });
+        unreadQuerySnapshots.set(key, snapshot);
+    }
+    return snapshot;
+}
 class QueryEntry {
     store;
     spec;
@@ -247,14 +268,9 @@ class QueryEntry {
     cache;
     #owner = Symbol('query-window-claim');
     #listeners = new Set();
-    #state = {
-        rows: [],
-        phase: 'loading',
-        revision: undefined,
-        error: undefined,
-        isRefreshing: false,
-        availability: { state: 'ready' },
-    };
+    #state = unreadQuerySnapshot('loading', {
+        state: 'ready',
+    });
     #delegate;
     #generation = 0;
     #scheduled = false;
@@ -351,14 +367,7 @@ class QueryEntry {
         this.#desiredRevision = 0n;
         this.#claimError = undefined;
         this.#claimPending = false;
-        this.#state = {
-            rows: [],
-            phase: 'loading',
-            revision: undefined,
-            error: undefined,
-            isRefreshing: false,
-            availability: { state: 'ready' },
-        };
+        this.#state = unreadQuerySnapshot('loading', { state: 'ready' });
     }
     dispose() {
         this.#listeners.clear();
@@ -385,7 +394,13 @@ class QueryEntry {
                 canonicalValue(this.#state.availability)) {
             return;
         }
-        this.#state = next;
+        this.#state =
+            next.revision === undefined &&
+                next.rows.length === 0 &&
+                next.error === undefined &&
+                !next.isRefreshing
+                ? unreadQuerySnapshot(next.phase, next.availability)
+                : next;
         for (const listener of this.#listeners)
             listener();
     }

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