@syncular/client 0.25.1 → 0.26.0

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).
@@ -245,6 +256,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 }
             : {}),
@@ -691,7 +706,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);

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.1",
+  "version": "0.26.0",
   "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.1"
+    "@syncular/core": "0.26.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.25.1",
+    "@syncular/server": "0.26.0",
     "playwright": "1.63.0"
   }
 }

package/src/client.ts

@@ -82,9 +82,16 @@ import {
   MAX_DIAGNOSTIC_DOMAINS,
   MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS,
   MAX_DIAGNOSTIC_QUERY_FAILURES,
+  type RealtimePolicy,
+  type RealtimeState,
 } from './diagnostics';
 import type { EncryptionConfig } from './encryption';
-import { ClientSyncError, classifySqliteFailure } from './errors';
+import {
+  ClientSyncError,
+  classifySqliteFailure,
+  REALTIME_LOST_CODE,
+  RealtimeUnavailableError,
+} from './errors';
 import {
   ChangeAccumulator,
   ChangeEmitter,
@@ -344,6 +351,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;
@@ -672,6 +688,12 @@ function isFinalPushResult(frame: PushResultFrame): boolean {
   );
 }
 
+/** The stable `code` of a thrown realtime transport error, when it has one. */
+function realtimeErrorCode(error: unknown): string | undefined {
+  const code = (error as { code?: unknown } | undefined)?.code;
+  return typeof code === 'string' ? code : undefined;
+}
+
 /** Canonical client reads, shared by synchronous cores and promise hosts. */
 export type ClientSnapshotMethods = Pick<
   SyncClient,
@@ -725,6 +747,11 @@ export class SyncClient {
   #conflicts: ConflictRecord[] = [];
   #rejections: RejectionRecord[] = [];
   #socket: RealtimeSocket | undefined;
+  /** SPEC §8.8: the explicit realtime availability state and its evidence. */
+  readonly #realtimePolicy: RealtimePolicy;
+  #realtimeState: RealtimeState;
+  #realtimeReasonCode: string | undefined;
+  #realtimeRetryDelayMs: number | undefined;
   #realtimeConnectPromise: Promise<void> | undefined;
   #realtimeGeneration = 0;
   #pendingRound: PendingRound | undefined;
@@ -802,9 +829,33 @@ export class SyncClient {
         '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';
@@ -1751,12 +1802,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: {
@@ -3532,9 +3585,20 @@ export class SyncClient {
         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: SyncIntent = {
           kind: 'background',
-          delayMs: this.#retryDelayMs,
+          delayMs: delay,
         };
         this.#retryDelayMs = Math.min(this.#retryDelayMs * 2, 30_000);
         this.#emitSyncIntent(intent);
@@ -3593,50 +3657,60 @@ 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: Uint8Array): Promise<Uint8Array> {
     const socket = this.#socket;
-    if (socket === undefined) {
-      return Promise.resolve()
-        .then(() => this.#config.transport(request))
-        .catch((error: unknown) => {
-          if (
-            error instanceof ClientSyncError ||
-            typeof (error as { code?: unknown })?.code === 'string'
-          ) {
-            throw error;
-          }
-          throw new ClientSyncError(
-            'sync.transport_failed',
-            `transport round failed: ${error instanceof Error ? error.message : String(error)}`,
-            true,
+    if (socket !== undefined && this.#realtimePolicy !== 'off') {
+      return new Promise<Uint8Array>((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,
+            ),
           );
-        });
+        }
+      });
     }
-    return new Promise<Uint8Array>((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: unknown) => {
+        if (
+          error instanceof ClientSyncError ||
+          typeof (error as { code?: unknown })?.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). */
@@ -3649,13 +3723,51 @@ export class SyncClient {
 
   // -- 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: RealtimeState, reasonCode?: string): void {
+    this.#realtimeState = state;
+    this.#realtimeReasonCode =
+      reasonCode === undefined ? undefined : this.#diagnosticCode(reasonCode);
+    if (
+      state === 'connected' ||
+      state === 'disabled' ||
+      state === 'unsupported'
+    ) {
+      this.#realtimeRetryDelayMs = undefined;
+    }
+    this.#emitDiagnostics();
+  }
+
+  #realtimeUnavailableError(): RealtimeUnavailableError {
+    this.#realtimeRetryDelayMs = this.#retryDelayMs;
+    return new RealtimeUnavailableError(
+      this.#realtimeState,
+      this.#realtimeReasonCode,
+      this.#retryDelayMs,
+    );
+  }
+
   connectRealtime(): Promise<void> {
     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),
     );
@@ -3684,40 +3796,53 @@ export class SyncClient {
       );
     }
     let openedSocket: RealtimeSocket | undefined;
-    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',
-      );
-    }
-    if (generation !== this.#realtimeGeneration || !this.#started) {
-      socket.close();
-      throw new ClientSyncError(
-        'client.realtime_cancelled',
-        'realtime connection was cancelled before activation',
-      );
+    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');
+    } 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(): void {
@@ -3727,7 +3852,13 @@ 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',
+    );
   }
 
   /**

package/src/diagnostics.ts

@@ -23,17 +23,32 @@ export type ClientDiagnosticsHostRole =
   | 'follower'
   | 'unknown';
 export type ClientDiagnosticsConnectivity = 'online' | 'offline' | 'unknown';
-export type ClientDiagnosticsRealtime =
+/**
+ * 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 {