@syncular/client 0.0.1 → 0.0.2-126

package/src/pull-engine.ts

@@ -6,11 +6,14 @@ import type {
   SyncBootstrapState,
   SyncPullRequest,
   SyncPullResponse,
+  SyncSnapshot,
   SyncSubscriptionRequest,
   SyncTransport,
 } from '@syncular/core';
-import { type Kysely, sql } from 'kysely';
+import { decodeSnapshotRows } from '@syncular/core';
+import { type Kysely, sql, type Transaction } from 'kysely';
 import type { ClientTableRegistry } from './handlers/registry';
+import type { ClientTableHandler } from './handlers/types';
 import type {
   SyncClientPlugin,
   SyncClientPluginContext,
@@ -22,6 +25,9 @@ import type { SyncClientDb, SyncSubscriptionStateTable } from './schema';
 const jsonCache = new WeakMap<object, string>();
 const jsonCacheStats = { hits: 0, misses: 0 };
 const SNAPSHOT_CHUNK_CONCURRENCY = 8;
+const SNAPSHOT_APPLY_BATCH_ROWS = 500;
+const SNAPSHOT_ROW_FRAME_MAGIC = new Uint8Array([0x53, 0x52, 0x46, 0x31]); // "SRF1"
+const FRAME_LENGTH_BYTES = 4;
 
 function serializeJsonCached(obj: object): string {
   if (obj === null || typeof obj !== 'object') {
@@ -45,63 +51,238 @@ function isGzipBytes(bytes: Uint8Array): boolean {
   return bytes.length >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b;
 }
 
-async function maybeGunzip(bytes: Uint8Array): Promise<Uint8Array> {
-  if (!isGzipBytes(bytes)) return bytes;
+function bytesToReadableStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
 
-  // Prefer Web Streams decompression when available (browser/modern runtimes).
-  if (typeof DecompressionStream !== 'undefined') {
-    const stream = new ReadableStream({
-      start(controller) {
-        controller.enqueue(new Uint8Array(bytes));
-        controller.close();
-      },
-    });
+function concatBytes(chunks: readonly Uint8Array[]): Uint8Array {
+  if (chunks.length === 1) {
+    return chunks[0] ?? new Uint8Array();
+  }
+  let total = 0;
+  for (const chunk of chunks) total += chunk.length;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
 
-    const decompressed = stream.pipeThrough(
-      new DecompressionStream('gzip')
-    ) as ReadableStream<Uint8Array>;
-    const reader = decompressed.getReader();
-
-    try {
-      const chunks: Uint8Array[] = [];
-      let total = 0;
-      while (true) {
-        const { value, done } = await reader.read();
-        if (done) break;
-        if (!value) continue;
-        chunks.push(value);
-        total += value.length;
-      }
+function appendBytes(base: Uint8Array, next: Uint8Array): Uint8Array {
+  if (base.length === 0) return next;
+  if (next.length === 0) return base;
+  const out = new Uint8Array(base.length + next.length);
+  out.set(base, 0);
+  out.set(next, base.length);
+  return out;
+}
+
+function toOwnedUint8Array(chunk: Uint8Array): Uint8Array<ArrayBuffer> {
+  const out = new ArrayBuffer(chunk.byteLength);
+  const bytes = new Uint8Array(out);
+  bytes.set(chunk);
+  return bytes;
+}
 
-      const out = new Uint8Array(total);
-      let offset = 0;
-      for (const chunk of chunks) {
-        out.set(chunk, offset);
-        offset += chunk.length;
+async function streamToBytes(
+  stream: ReadableStream<Uint8Array>
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  try {
+    const chunks: Uint8Array[] = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value || value.length === 0) continue;
+      chunks.push(value);
+    }
+    return concatBytes(chunks);
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function maybeGunzipStream(
+  stream: ReadableStream<Uint8Array>
+): Promise<ReadableStream<Uint8Array>> {
+  const reader = stream.getReader();
+  const prefetched: Uint8Array[] = [];
+  let prefetchedBytes = 0;
+
+  while (prefetchedBytes < 2) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value || value.length === 0) continue;
+    prefetched.push(value);
+    prefetchedBytes += value.length;
+  }
+
+  const prefetchedCombined = concatBytes(prefetched);
+  const gzip = isGzipBytes(prefetchedCombined);
+
+  const replayStream = new ReadableStream<Uint8Array<ArrayBuffer>>({
+    start(controller) {
+      if (prefetchedCombined.length > 0) {
+        controller.enqueue(toOwnedUint8Array(prefetchedCombined));
+      }
+    },
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        controller.close();
+        reader.releaseLock();
+        return;
       }
-      return out;
-    } finally {
+      if (!value || value.length === 0) return;
+      controller.enqueue(toOwnedUint8Array(value));
+    },
+    async cancel(reason) {
+      await reader.cancel(reason);
       reader.releaseLock();
-    }
+    },
+  });
+
+  if (!gzip) return replayStream;
+
+  if (typeof DecompressionStream !== 'undefined') {
+    return replayStream.pipeThrough(new DecompressionStream('gzip'));
   }
 
-  // If the runtime didn't auto-decompress `Content-Encoding: gzip`, and doesn't
-  // support DecompressionStream, we can't safely decode the chunk.
   throw new Error(
     'Snapshot chunk appears gzip-compressed but gzip decompression is not available in this runtime'
   );
 }
 
-function parseNdjsonRows(text: string): unknown[] {
-  const rows: unknown[] = [];
-  for (const line of text.split('\n')) {
-    if (!line) continue;
-    rows.push(JSON.parse(line));
+async function maybeGunzip(bytes: Uint8Array): Promise<Uint8Array> {
+  if (!isGzipBytes(bytes)) return bytes;
+  const decompressedStream = await maybeGunzipStream(
+    bytesToReadableStream(bytes)
+  );
+  return streamToBytes(decompressedStream);
+}
+
+async function* decodeSnapshotRowStreamBatches(
+  stream: ReadableStream<Uint8Array>,
+  batchSize: number
+): AsyncGenerator<unknown[]> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let pending: Uint8Array = new Uint8Array(0);
+  let headerValidated = false;
+  let rows: unknown[] = [];
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value || value.length === 0) continue;
+      pending = appendBytes(pending, value);
+
+      if (!headerValidated) {
+        if (pending.length < SNAPSHOT_ROW_FRAME_MAGIC.length) {
+          continue;
+        }
+        for (let index = 0; index < SNAPSHOT_ROW_FRAME_MAGIC.length; index++) {
+          if (pending[index] !== SNAPSHOT_ROW_FRAME_MAGIC[index]) {
+            throw new Error('Unexpected snapshot chunk format');
+          }
+        }
+        pending = pending.subarray(SNAPSHOT_ROW_FRAME_MAGIC.length);
+        headerValidated = true;
+      }
+
+      while (pending.length >= FRAME_LENGTH_BYTES) {
+        const view = new DataView(
+          pending.buffer,
+          pending.byteOffset,
+          pending.byteLength
+        );
+        const payloadLength = view.getUint32(0, false);
+        if (pending.length < FRAME_LENGTH_BYTES + payloadLength) {
+          break;
+        }
+
+        const payload = pending.subarray(
+          FRAME_LENGTH_BYTES,
+          FRAME_LENGTH_BYTES + payloadLength
+        );
+        rows.push(JSON.parse(decoder.decode(payload)));
+        pending = pending.subarray(FRAME_LENGTH_BYTES + payloadLength);
+
+        if (rows.length >= batchSize) {
+          yield rows;
+          rows = [];
+        }
+      }
+    }
+
+    if (!headerValidated) {
+      throw new Error('Snapshot chunk payload is too small');
+    }
+
+    if (pending.length > 0) {
+      if (pending.length < FRAME_LENGTH_BYTES) {
+        throw new Error('Snapshot chunk payload ended mid-frame header');
+      }
+      const view = new DataView(
+        pending.buffer,
+        pending.byteOffset,
+        pending.byteLength
+      );
+      const payloadLength = view.getUint32(0, false);
+      if (pending.length < FRAME_LENGTH_BYTES + payloadLength) {
+        throw new Error('Snapshot chunk payload ended mid-frame body');
+      }
+      while (pending.length >= FRAME_LENGTH_BYTES) {
+        const nextView = new DataView(
+          pending.buffer,
+          pending.byteOffset,
+          pending.byteLength
+        );
+        const nextLength = nextView.getUint32(0, false);
+        if (pending.length < FRAME_LENGTH_BYTES + nextLength) {
+          break;
+        }
+        const payload = pending.subarray(
+          FRAME_LENGTH_BYTES,
+          FRAME_LENGTH_BYTES + nextLength
+        );
+        rows.push(JSON.parse(decoder.decode(payload)));
+        pending = pending.subarray(FRAME_LENGTH_BYTES + nextLength);
+        if (rows.length >= batchSize) {
+          yield rows;
+          rows = [];
+        }
+      }
+      if (pending.length > 0) {
+        throw new Error('Snapshot chunk payload ended mid-frame body');
+      }
+    }
+
+    if (rows.length > 0) {
+      yield rows;
+    }
+  } finally {
+    reader.releaseLock();
   }
-  return rows;
 }
 
-async function computeSha256Hex(bytes: Uint8Array): Promise<string> {
+async function computeSha256Hex(
+  bytes: Uint8Array,
+  sha256Override?: (bytes: Uint8Array) => Promise<string>
+): Promise<string> {
+  // Use injected implementation if provided (e.g. expo-crypto on React Native)
+  if (sha256Override) {
+    return sha256Override(bytes);
+  }
+
   // Use crypto.subtle if available (browsers, modern Node/Bun)
   if (typeof crypto !== 'undefined' && crypto.subtle) {
     // Create a fresh ArrayBuffer to satisfy crypto.subtle's type requirements
@@ -114,19 +295,23 @@ async function computeSha256Hex(bytes: Uint8Array): Promise<string> {
     );
   }
 
-  // Fallback for Node.js/Bun without crypto.subtle
-  if (typeof globalThis.require === 'function') {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { createHash } = await import('node:crypto');
-    return createHash('sha256').update(Buffer.from(bytes)).digest('hex');
-  }
-
   throw new Error(
     'No crypto implementation available for SHA-256. ' +
-      'Ensure crypto.subtle is available or running in Node.js/Bun.'
+      'Provide a sha256 function via options or ensure crypto.subtle is available.'
   );
 }
 
+async function fetchSnapshotChunkStream(
+  transport: SyncTransport,
+  chunkId: string
+): Promise<ReadableStream<Uint8Array>> {
+  if (transport.fetchSnapshotChunkStream) {
+    return transport.fetchSnapshotChunkStream({ chunkId });
+  }
+  const bytes = await transport.fetchSnapshotChunk({ chunkId });
+  return bytesToReadableStream(bytes);
+}
+
 async function mapWithConcurrency<T, U>(
   items: readonly T[],
   concurrency: number,
@@ -154,10 +339,10 @@ async function mapWithConcurrency<T, U>(
 
 async function materializeChunkedSnapshots(
   transport: SyncTransport,
-  response: SyncPullResponse
+  response: SyncPullResponse,
+  sha256Override?: (bytes: Uint8Array) => Promise<string>
 ): Promise<SyncPullResponse> {
   const chunkCache = new Map<string, Promise<Uint8Array>>();
-  const decoder = new TextDecoder();
 
   const subscriptions = await Promise.all(
     response.subscriptions.map(async (sub) => {
@@ -187,7 +372,10 @@ async function materializeChunkedSnapshots(
 
               // Verify chunk integrity using sha256 hash
               if (chunk.sha256) {
-                const actualHash = await computeSha256Hex(bytes);
+                const actualHash = await computeSha256Hex(
+                  bytes,
+                  sha256Override
+                );
                 if (actualHash !== chunk.sha256) {
                   throw new Error(
                     `Snapshot chunk integrity check failed: expected sha256 ${chunk.sha256}, got ${actualHash}`
@@ -195,8 +383,7 @@ async function materializeChunkedSnapshots(
                 }
               }
 
-              const text = decoder.decode(bytes);
-              return parseNdjsonRows(text);
+              return decodeSnapshotRows(bytes);
             }
           );
 
@@ -219,6 +406,69 @@ async function materializeChunkedSnapshots(
   return { ...response, subscriptions };
 }
 
+async function applyChunkedSnapshot<DB extends SyncClientDb>(
+  transport: SyncTransport,
+  handler: Pick<ClientTableHandler<DB>, 'applySnapshot'>,
+  trx: Transaction<DB>,
+  snapshot: SyncSnapshot
+): Promise<void> {
+  const chunks = snapshot.chunks ?? [];
+  if (chunks.length === 0) {
+    await handler.applySnapshot({ trx }, snapshot);
+    return;
+  }
+
+  let nextIsFirstPage = snapshot.isFirstPage;
+
+  for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex += 1) {
+    const chunk = chunks[chunkIndex];
+    if (!chunk) continue;
+
+    const rawStream = await fetchSnapshotChunkStream(transport, chunk.id);
+    const decodedStream = await maybeGunzipStream(rawStream);
+    const rowBatchIterator = decodeSnapshotRowStreamBatches(
+      decodedStream,
+      SNAPSHOT_APPLY_BATCH_ROWS
+    );
+
+    let pendingBatch: unknown[] | null = null;
+    // eslint-disable-next-line no-await-in-loop
+    for await (const batch of rowBatchIterator) {
+      if (pendingBatch) {
+        // eslint-disable-next-line no-await-in-loop
+        await handler.applySnapshot(
+          { trx },
+          {
+            ...snapshot,
+            rows: pendingBatch,
+            chunks: undefined,
+            isFirstPage: nextIsFirstPage,
+            isLastPage: false,
+          }
+        );
+        nextIsFirstPage = false;
+      }
+      pendingBatch = batch;
+    }
+
+    if (pendingBatch) {
+      const isLastChunk = chunkIndex === chunks.length - 1;
+      // eslint-disable-next-line no-await-in-loop
+      await handler.applySnapshot(
+        { trx },
+        {
+          ...snapshot,
+          rows: pendingBatch,
+          chunks: undefined,
+          isFirstPage: nextIsFirstPage,
+          isLastPage: isLastChunk ? snapshot.isLastPage : false,
+        }
+      );
+      nextIsFirstPage = false;
+    }
+  }
+}
+
 function parseBootstrapState(
   value: string | object | null | undefined
 ): SyncBootstrapState | null {
@@ -255,21 +505,34 @@ export interface SyncPullOnceOptions {
   maxSnapshotPages?: number;
   dedupeRows?: boolean;
   stateId?: string;
+  /**
+   * Custom SHA-256 hash function for snapshot chunk integrity verification.
+   * Provide this on platforms where `crypto.subtle` is unavailable (e.g. React Native).
+   * Must return the hex-encoded hash string.
+   */
+  sha256?: (bytes: Uint8Array) => Promise<string>;
 }
 
-export async function syncPullOnce<DB extends SyncClientDb>(
+/**
+ * Build a pull request from subscription state. Exported for use
+ * by the combined sync path in sync-loop.ts.
+ */
+export async function buildPullRequest<DB extends SyncClientDb>(
   db: Kysely<DB>,
-  transport: SyncTransport,
-  shapes: ClientTableRegistry<DB>,
   options: SyncPullOnceOptions
-): Promise<SyncPullResponse> {
+): Promise<{
+  request: SyncPullRequest;
+  existing: SyncSubscriptionStateTable[];
+  existingById: Map<string, SyncSubscriptionStateTable>;
+  stateId: string;
+}> {
   const stateId = options.stateId ?? 'default';
 
   const existingResult = await sql<SyncSubscriptionStateTable>`
     select
       ${sql.ref('state_id')},
       ${sql.ref('subscription_id')},
-      ${sql.ref('shape')},
+      ${sql.ref('table')},
       ${sql.ref('scopes_json')},
       ${sql.ref('params_json')},
       ${sql.ref('cursor')},
@@ -300,16 +563,40 @@ export async function syncPullOnce<DB extends SyncClientDb>(
     })),
   };
 
-  const res = await transport.pull(request);
-  const hydrated = await materializeChunkedSnapshots(transport, res);
+  return { request, existing, existingById, stateId };
+}
+
+/**
+ * Apply a pull response (run plugins + write to local DB).
+ * Exported for use by the combined sync path in sync-loop.ts.
+ */
+export async function applyPullResponse<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  transport: SyncTransport,
+  handlers: ClientTableRegistry<DB>,
+  options: SyncPullOnceOptions,
+  pullState: {
+    request: SyncPullRequest;
+    existing: SyncSubscriptionStateTable[];
+    existingById: Map<string, SyncSubscriptionStateTable>;
+    stateId: string;
+  },
+  rawResponse: SyncPullResponse
+): Promise<SyncPullResponse> {
+  const { request, existing, existingById, stateId } = pullState;
 
   const ctx: SyncClientPluginContext = {
     actorId: options.actorId ?? 'unknown',
     clientId: options.clientId,
   };
   const plugins = options.plugins ?? [];
+  const requiresMaterializedSnapshots = plugins.some(
+    (plugin) => !!plugin.afterPull
+  );
 
-  let responseToApply = hydrated;
+  let responseToApply = requiresMaterializedSnapshots
+    ? await materializeChunkedSnapshots(transport, rawResponse, options.sha256)
+    : rawResponse;
   for (const plugin of plugins) {
     if (!plugin.afterPull) continue;
     responseToApply = await plugin.afterPull(ctx, {
@@ -325,17 +612,17 @@ export async function syncPullOnce<DB extends SyncClientDb>(
     for (const row of existing) {
       if (desiredIds.has(row.subscription_id)) continue;
 
-      // Clear data for this shape matching the subscription's scopes
-      if (row.shape) {
+      // Clear data for this table matching the subscription's scopes
+      if (row.table) {
         try {
           const scopes = row.scopes_json
             ? typeof row.scopes_json === 'string'
               ? JSON.parse(row.scopes_json)
               : row.scopes_json
             : {};
-          await shapes.getOrThrow(row.shape).clearAll({ trx, scopes });
+          await handlers.getOrThrow(row.table).clearAll({ trx, scopes });
         } catch {
-          // ignore missing shape handler
+          // ignore missing table handler
         }
       }
 
@@ -355,14 +642,14 @@ export async function syncPullOnce<DB extends SyncClientDb>(
 
       // Revoked: clear data and drop the subscription row.
       if (sub.status === 'revoked') {
-        if (prev?.shape) {
+        if (prev?.table) {
           try {
             const scopes = prev.scopes_json
               ? typeof prev.scopes_json === 'string'
                 ? JSON.parse(prev.scopes_json)
                 : prev.scopes_json
               : {};
-            await shapes.getOrThrow(prev.shape).clearAll({ trx, scopes });
+            await handlers.getOrThrow(prev.table).clearAll({ trx, scopes });
           } catch {
             // ignore missing handler
           }
@@ -379,7 +666,9 @@ export async function syncPullOnce<DB extends SyncClientDb>(
       // Apply snapshots (bootstrap mode)
       if (sub.bootstrap) {
         for (const snapshot of sub.snapshots ?? []) {
-          const handler = shapes.getOrThrow(snapshot.table);
+          const handler = handlers.getOrThrow(snapshot.table);
+          const hasChunkRefs =
+            Array.isArray(snapshot.chunks) && snapshot.chunks.length > 0;
 
           // Call onSnapshotStart hook when starting a new snapshot
           if (snapshot.isFirstPage && handler.onSnapshotStart) {
@@ -390,7 +679,11 @@ export async function syncPullOnce<DB extends SyncClientDb>(
             });
           }
 
-          await handler.applySnapshot({ trx }, snapshot);
+          if (hasChunkRefs) {
+            await applyChunkedSnapshot(transport, handler, trx, snapshot);
+          } else {
+            await handler.applySnapshot({ trx }, snapshot);
+          }
 
           // Call onSnapshotEnd hook when snapshot is complete
           if (snapshot.isLastPage && handler.onSnapshotEnd) {
@@ -405,7 +698,7 @@ export async function syncPullOnce<DB extends SyncClientDb>(
         // Apply incremental changes
         for (const commit of sub.commits) {
           for (const change of commit.changes) {
-            const handler = shapes.getOrThrow(change.table);
+            const handler = handlers.getOrThrow(change.table);
             await handler.applyChange({ trx }, change);
           }
         }
@@ -422,13 +715,13 @@ export async function syncPullOnce<DB extends SyncClientDb>(
           : null
         : null;
 
-      const shape = def?.shape ?? 'unknown';
+      const table = def?.table ?? 'unknown';
       await sql`
 	        insert into ${sql.table('sync_subscription_state')} (
 	          ${sql.join([
               sql.ref('state_id'),
               sql.ref('subscription_id'),
-              sql.ref('shape'),
+              sql.ref('table'),
               sql.ref('scopes_json'),
               sql.ref('params_json'),
               sql.ref('cursor'),
@@ -441,7 +734,7 @@ export async function syncPullOnce<DB extends SyncClientDb>(
 	          ${sql.join([
               sql.val(stateId),
               sql.val(sub.id),
-              sql.val(shape),
+              sql.val(table),
               sql.val(scopesJson),
               sql.val(paramsJson),
               sql.val(sub.nextCursor),
@@ -453,7 +746,7 @@ export async function syncPullOnce<DB extends SyncClientDb>(
 	        )
 	        on conflict (${sql.join([sql.ref('state_id'), sql.ref('subscription_id')])})
 	        do update set
-	          ${sql.ref('shape')} = ${sql.val(shape)},
+	          ${sql.ref('table')} = ${sql.val(table)},
 	          ${sql.ref('scopes_json')} = ${sql.val(scopesJson)},
 	          ${sql.ref('params_json')} = ${sql.val(paramsJson)},
 	          ${sql.ref('cursor')} = ${sql.val(sub.nextCursor)},
@@ -466,3 +759,25 @@ export async function syncPullOnce<DB extends SyncClientDb>(
 
   return responseToApply;
 }
+
+export async function syncPullOnce<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  transport: SyncTransport,
+  handlers: ClientTableRegistry<DB>,
+  options: SyncPullOnceOptions
+): Promise<SyncPullResponse> {
+  const pullState = await buildPullRequest(db, options);
+  const { clientId, ...pullBody } = pullState.request;
+  const combined = await transport.sync({ clientId, pull: pullBody });
+  if (!combined.pull) {
+    return { ok: true, subscriptions: [] };
+  }
+  return applyPullResponse(
+    db,
+    transport,
+    handlers,
+    options,
+    pullState,
+    combined.pull
+  );
+}

package/src/push-engine.ts

@@ -32,6 +32,16 @@ export interface SyncPushOnceResult {
   response?: SyncPushResponse;
 }
 
+interface TransportWithWsPush extends SyncTransport {
+  pushViaWs(request: SyncPushRequest): Promise<SyncPushResponse | null>;
+}
+
+function hasPushViaWs(
+  transport: SyncTransport
+): transport is TransportWithWsPush {
+  return 'pushViaWs' in transport && typeof transport.pushViaWs === 'function';
+}
+
 function clonePushRequest(request: SyncPushRequest): SyncPushRequest {
   if (typeof structuredClone === 'function') return structuredClone(request);
   return JSON.parse(JSON.stringify(request)) as SyncPushRequest;
@@ -76,7 +86,29 @@ export async function syncPushOnce<DB extends SyncClientDb>(
 
   let res: SyncPushResponse;
   try {
-    res = await transport.push(requestToSend);
+    // Try WS push first if the transport supports it
+    let wsResponse: SyncPushResponse | null = null;
+    if (hasPushViaWs(transport)) {
+      wsResponse = await transport.pushViaWs(requestToSend);
+    }
+
+    if (wsResponse) {
+      res = wsResponse;
+    } else {
+      // Fall back to HTTP
+      const combined = await transport.sync({
+        clientId: requestToSend.clientId,
+        push: {
+          clientCommitId: requestToSend.clientCommitId,
+          operations: requestToSend.operations,
+          schemaVersion: requestToSend.schemaVersion,
+        },
+      });
+      if (!combined.push) {
+        throw new Error('Server returned no push response');
+      }
+      res = combined.push;
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : 'Unknown error';
     // Treat transport exceptions as retryable. The sync loop already applies backoff,