@syncular/client 0.1.2 → 0.2.0

package/src/worker-entry.ts

@@ -1,584 +1,430 @@
-import { resolveSyncularClientConfig } from './client-config';
-import { syncularDiagnosticAttemptFields } from './diagnostics';
+/**
+ * Worker-side bootstrap (Direction decision 2): constructs the WHOLE
+ * client core — SyncClient + transports + realtime + SQLite — inside the
+ * worker and serves the `worker-protocol` RPC over postMessage.
+ *
+ * Browsers get the defaults: opfs-sahpool persistence and the fetch/WS
+ * transports from `./http`, wired from `WorkerInitConfig.endpoints`.
+ * Tests inject a database factory (bun:sqlite) through `overrides` — the
+ * same bootstrap, the same RPC, a different SQLite.
+ *
+ * The §8.4 host loop lives HERE: wake-ups (hello/`sync` events, delta
+ * drops) coalesce into one jittered `syncUntilIdle` round in the worker;
+ * RPC-driven and auto-driven sync rounds serialize on one queue because
+ * the core owns exactly one loop.
+ */
+import { SyncClient } from './client';
+import type { ClientDatabase } from './database';
+import { ClientSyncError } from './errors';
 import {
-  classifySyncularError,
-  SyncularClientError,
-  syncularErrorDetails,
-  syncularErrorMessage,
-  syncularErrorStatus,
-} from './errors';
-import {
-  dispatchGeneratedSyncularWorkerRequest,
-  generatedSyncularWorkerRequestDiagnosticSource,
-  isGeneratedSyncularAbortableWorkerRequestType,
-  isGeneratedSyncularDiagnosedSuccessWorkerRequestType,
-} from './generated-bridge';
-import { createSyncularRuntimeInfo } from './runtime-contract';
-import { openSyncularRustClient, type SyncularRustClient } from './rust-client';
-import type {
-  ResolvedSyncularClientConfig,
-  SyncularDiagnosticEvent,
-} from './types';
-import {
-  getSyncularRustRuntimeInfo,
-  getSyncularWasmGlueUrl,
-  getSyncularWasmUrl,
-  type SyncularWasmGlue,
-} from './wasm-runtime';
+  httpBlobTransport,
+  httpSegmentDownloader,
+  httpSyncTransport,
+  webSocketRealtimeConnector,
+} from './http';
 import type {
-  SyncularWorkerErrorPayload,
-  SyncularWorkerOutboundMessage,
-  SyncularWorkerRequest,
-  SyncularWorkerRuntimeArtifact,
-} from './worker-protocol';
+  RealtimeConnector,
+  SegmentDownloader,
+  SyncTransport,
+} from './transport';
+import { openPersistentWasmDatabase } from './wasm-database';
 import {
-  createSyncularWorkerErrorPayload,
-  SYNCULAR_WORKER_PROTOCOL_VERSION,
+  type MainToWorkerMessage,
+  WORKER_FAILED_CODE,
+  type WorkerApi,
+  type WorkerCallMessage,
+  type WorkerErrorShape,
+  type WorkerInitConfig,
+  type WorkerInitResult,
+  type WorkerToMainMessage,
 } from './worker-protocol';
-import { SyncularWorkerRealtimeController } from './worker-realtime';
-
-let client: SyncularRustClient | undefined;
-let openedConfig: ResolvedSyncularClientConfig | undefined;
-let openedRuntime: SyncularWorkerRuntimeArtifact | undefined;
-let removeRowsChangedListener: (() => void) | undefined;
-const canceledRequests = new Set<number>();
-const abortControllers = new Map<number, AbortController>();
-const realtime = new SyncularWorkerRealtimeController({
-  getClient: requireClient,
-  getConfig: () => openedConfig,
-  getLocationOrigin: () =>
-    typeof self.location?.origin === 'string'
-      ? self.location.origin
-      : 'http://localhost',
-  createWebSocket: (url) => new WebSocket(url),
-  postEvent: (event) => self.postMessage(event),
-  postDiagnostic,
-});
-
-self.onmessage = (event: MessageEvent<SyncularWorkerRequest>) => {
-  void handleRequest(event.data);
-};
-
-async function handleRequest(request: SyncularWorkerRequest): Promise<void> {
-  if (request.protocolVersion !== SYNCULAR_WORKER_PROTOCOL_VERSION) {
-    post({
-      id: request.id,
-      protocolVersion: SYNCULAR_WORKER_PROTOCOL_VERSION,
-      ok: false,
-      error: createSyncularWorkerErrorPayload(
-        'worker.protocol_mismatch',
-        `Unsupported Syncular worker protocol ${request.protocolVersion}`,
-        { details: { supported: SYNCULAR_WORKER_PROTOCOL_VERSION } }
-      ),
-    });
-    return;
-  }
-
-  if (request.type === 'cancel') {
-    canceledRequests.add(request.requestId);
-    const controller = abortControllers.get(request.requestId);
-    controller?.abort();
-    if (controller) {
-      postDiagnostic({
-        level: 'warn',
-        source: 'worker',
-        code: 'worker.request_aborted',
-        message: 'Syncular worker request aborted',
-        details: { requestId: request.requestId },
-      });
-    }
-    post({
-      id: request.id,
-      protocolVersion: request.protocolVersion,
-      ok: true,
-    });
-    return;
-  }
-
-  const startedAt = Date.now();
-  const abortController = createAbortController(request.type);
-  if (abortController) {
-    abortControllers.set(request.id, abortController);
-  }
-  try {
-    if (abortController) client?.setAbortSignal(abortController.signal);
-    const value = await dispatch(request);
-    if (canceledRequests.delete(request.id)) return;
-    post({
-      id: request.id,
-      protocolVersion: request.protocolVersion,
-      ok: true,
-      value,
-    });
-    postRequestSuccessDiagnostic(request, value, Date.now() - startedAt);
-  } catch (err) {
-    if (canceledRequests.delete(request.id)) return;
-    const source = requestDiagnosticSource(request.type);
-    const resyncRequired = errorRequiresFullRefresh(err);
-    const encodedError = encodeWorkerError(err);
-    const diagnosticCode = resyncRequired
-      ? `${source}.resync_required`
-      : encodedError.code.startsWith(`${source}.`)
-        ? encodedError.code
-        : `${source}.${request.type}.failed`;
-    postDiagnostic({
-      level: requestDiagnosticLevel(request.type, err),
-      source,
-      code: diagnosticCode,
-      message: resyncRequired
-        ? `Syncular worker request ${request.type} requires full resync`
-        : `Syncular worker request ${request.type} failed`,
-      details: {
-        requestType: request.type,
-        durationMs: Date.now() - startedAt,
-        error: errorMessage(err),
-        errorCode: encodedError.code,
-        ...(encodedError.category ? { category: encodedError.category } : {}),
-        ...(encodedError.retryable != null
-          ? { retryable: encodedError.retryable }
-          : {}),
-        ...(encodedError.recommendedAction
-          ? { recommendedAction: encodedError.recommendedAction }
-          : {}),
-        ...(resyncRequired ? { resyncRequired: true } : {}),
-        ...diagnosticStatus(err),
-      },
-      ...requestSyncAttemptDiagnosticFields(request),
-    });
-    post({
-      id: request.id,
-      protocolVersion: request.protocolVersion,
-      ok: false,
-      error: encodedError,
-    });
-  } finally {
-    abortControllers.delete(request.id);
-    if (abortController) clearClientAbortSignal();
-  }
-}
-
-async function dispatch(request: SyncularWorkerRequest): Promise<unknown> {
-  return dispatchGeneratedSyncularWorkerRequest(
-    {
-      requireClient,
-      openClient,
-      startRealtime: (options) => {
-        realtime.start(options);
-        return true;
-      },
-      stopRealtime: () => {
-        realtime.stop();
-        return true;
-      },
-      sendPresence: (action, scopeKey, metadata) => {
-        realtime.sendPresence(action, scopeKey, metadata);
-        return true;
-      },
-      runtimeInfo,
-      closeClient,
-    },
-    request
-  );
-}
-
-async function openClient(
-  request: Extract<SyncularWorkerRequest, { type: 'open' }>
-): Promise<boolean> {
-  const config = resolveSyncularClientConfig(request.config);
-  realtime.stop();
-  detachRowsChangedListener();
-  client?.close();
-  client = undefined;
-  openedConfig = undefined;
-  openedRuntime = undefined;
-  const runtime = request.runtime;
-  client = await openSyncularRustClient({
-    config,
-    module: runtime?.wasmGlueUrl
-      ? loadWorkerWasmGlue(runtime.wasmGlueUrl)
-      : undefined,
-    wasmGlueUrl: runtime?.wasmGlueUrl,
-    wasmUrl: runtime?.wasmUrl,
-  });
-  attachRowsChangedListener(client);
-  openedConfig = config;
-  openedRuntime = runtime;
-  return true;
-}
-
-function closeClient(): boolean {
-  realtime.stop();
-  detachRowsChangedListener();
-  client?.close();
-  client = undefined;
-  openedConfig = undefined;
-  openedRuntime = undefined;
-  return true;
-}
 
-async function runtimeInfo(): Promise<
-  ReturnType<typeof createSyncularRuntimeInfo>
-> {
-  const wasmUrl = getSyncularWasmUrl();
-  const selectedWasmUrl = openedRuntime?.wasmUrl ?? wasmUrl;
-  const selectedWasmGlueUrl =
-    openedRuntime?.wasmGlueUrl ?? getSyncularWasmGlueUrl();
-  return createSyncularRuntimeInfo({
-    storage: openedConfig?.storage,
-    workerUrl:
-      typeof self.location?.href === 'string' ? self.location.href : '',
-    wasmGlueUrl: selectedWasmGlueUrl,
-    wasmUrl: selectedWasmUrl,
-    rust: await getSyncularRustRuntimeInfo(
-      openedRuntime?.wasmGlueUrl
-        ? loadWorkerWasmGlue(openedRuntime.wasmGlueUrl)
-        : undefined,
-      selectedWasmUrl
-    ),
-  });
+export interface SyncWorkerOverrides {
+  /** Database factory indirection: tests inject bun:sqlite here. */
+  readonly openDatabase?: (
+    config: WorkerInitConfig,
+  ) => Promise<ClientDatabase> | ClientDatabase;
+  readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
+  readonly createSegments?: (
+    config: WorkerInitConfig,
+  ) => SegmentDownloader | undefined;
+  readonly createRealtime?: (
+    config: WorkerInitConfig,
+    clientId: string,
+  ) => RealtimeConnector | undefined;
 }
 
-function loadWorkerWasmGlue(wasmGlueUrl: string): Promise<SyncularWasmGlue> {
-  return import(/* @vite-ignore */ wasmGlueUrl) as Promise<SyncularWasmGlue>;
+/** Minimal structural view of the dedicated-worker global scope. */
+interface WorkerScope {
+  postMessage(message: unknown, transfer?: Transferable[]): void;
+  addEventListener(
+    type: 'message',
+    listener: (event: MessageEvent) => void,
+  ): void;
 }
 
-function requireClient(): SyncularRustClient {
-  if (!client) {
-    throw createSyncularWorkerErrorPayload(
-      'worker.not_open',
-      'Syncular worker client is not open'
-    );
+function toErrorShape(error: unknown): WorkerErrorShape {
+  if (error instanceof ClientSyncError) {
+    return {
+      code: error.code,
+      message: error.message,
+      retryable: error.retryable,
+    };
   }
-  return client;
-}
-
-function attachRowsChangedListener(nextClient: SyncularRustClient): void {
-  removeRowsChangedListener = nextClient.addRowsChangedListener((event) => {
-    post({
-      protocolVersion: SYNCULAR_WORKER_PROTOCOL_VERSION,
-      type: 'rowsChanged',
-      source: event.source,
-      changedTables: event.changedTables,
-      changedRows: event.changedRows,
-      changedRowsTruncated: event.changedRowsTruncated,
-    });
-  });
-}
-
-function detachRowsChangedListener(): void {
-  removeRowsChangedListener?.();
-  removeRowsChangedListener = undefined;
-}
-
-function post(message: SyncularWorkerOutboundMessage): void {
-  self.postMessage(message);
+  return {
+    code: WORKER_FAILED_CODE,
+    message: error instanceof Error ? error.message : String(error),
+    retryable: false,
+  };
 }
 
-function createAbortController(
-  type: SyncularWorkerRequest['type']
-): AbortController | undefined {
-  if (!isAbortableRequest(type) || typeof AbortController === 'undefined') {
-    return undefined;
+/**
+ * ArrayBuffers safe to transfer out of a query result: whole-buffer
+ * views only (a view into a larger/pooled buffer is cloned instead —
+ * transferring would detach unrelated data), deduplicated because a
+ * buffer may only appear once in a transfer list.
+ */
+function queryTransferables(rows: readonly unknown[]): Transferable[] {
+  const buffers = new Set<ArrayBuffer>();
+  for (const row of rows) {
+    if (row === null || typeof row !== 'object') continue;
+    for (const value of Object.values(row)) {
+      if (
+        value instanceof Uint8Array &&
+        value.buffer instanceof ArrayBuffer &&
+        value.byteOffset === 0 &&
+        value.byteLength === value.buffer.byteLength
+      ) {
+        buffers.add(value.buffer);
+      }
+    }
   }
-  return new AbortController();
+  return [...buffers];
 }
 
-function isAbortableRequest(type: SyncularWorkerRequest['type']): boolean {
-  return isGeneratedSyncularAbortableWorkerRequestType(type);
-}
+/**
+ * Register the RPC server on the current worker scope. Call this once
+ * from a worker entry script; the main-thread handle drives everything
+ * else through `init`/`call` messages.
+ */
+export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
+  const scope = globalThis as unknown as WorkerScope;
+  const post = (message: WorkerToMainMessage, transfer?: Transferable[]) => {
+    if (transfer !== undefined && transfer.length > 0) {
+      scope.postMessage(message, transfer);
+    } else {
+      scope.postMessage(message);
+    }
+  };
 
-function clearClientAbortSignal(): void {
-  try {
-    client?.setAbortSignal(null);
-  } catch {
-    // Best effort after a request completed, failed, or closed the client.
+  let client: SyncClient | undefined;
+  let database: ClientDatabase | undefined;
+  let offline = false;
+  let closed = false;
+
+  // -- one sync loop: RPC-driven and auto-driven rounds serialize ----------
+  let syncChain: Promise<unknown> = Promise.resolve();
+  function serializedSync<T>(fn: () => Promise<T>): Promise<T> {
+    const next = syncChain.then(fn, fn);
+    syncChain = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    return next;
   }
-}
 
-function postDiagnostic(
-  event: Omit<SyncularDiagnosticEvent, 'at'> & { at?: number }
-): void {
-  self.postMessage({
-    protocolVersion: SYNCULAR_WORKER_PROTOCOL_VERSION,
-    type: 'diagnostic',
-    event: {
-      at: event.at ?? Date.now(),
-      level: event.level,
-      source: event.source,
-      code: event.code,
-      message: event.message,
-      ...(event.syncAttemptId ? { syncAttemptId: event.syncAttemptId } : {}),
-      ...(event.traceId ? { traceId: event.traceId } : {}),
-      ...(event.spanId ? { spanId: event.spanId } : {}),
-      ...(event.clientId ? { clientId: event.clientId } : {}),
-      ...(event.subscriptionId ? { subscriptionId: event.subscriptionId } : {}),
-      ...(event.table ? { table: event.table } : {}),
-      ...(event.rowId ? { rowId: event.rowId } : {}),
-      ...(event.cursor !== undefined ? { cursor: event.cursor } : {}),
-      ...(event.details ? { details: event.details } : {}),
-    },
-  });
-}
-
-function postRequestSuccessDiagnostic(
-  request: SyncularWorkerRequest,
-  value: unknown,
-  durationMs: number
-): void {
-  if (!isDiagnosedSuccessRequest(request.type)) return;
-  const syncRevocation = syncScopeRevocationDetails(value);
-  postDiagnostic({
-    level: 'info',
-    source: requestDiagnosticSource(request.type),
-    code: `${requestDiagnosticSource(request.type)}.${request.type}.completed`,
-    message: `Syncular worker request ${request.type} completed`,
-    ...requestSyncAttemptDiagnosticFields(request),
-    details: {
-      requestType: request.type,
-      durationMs,
-      ...requestSuccessDetails(request, value),
-    },
-  });
-  if (
-    syncRevocation &&
-    (request.type === 'syncPull' ||
-      request.type === 'syncPush' ||
-      request.type === 'syncOnce')
-  ) {
-    postDiagnostic({
-      level: 'warn',
-      source: 'sync',
-      code: 'sync.scope_revoked',
-      message: 'Syncular subscription scope revoked',
-      ...requestSyncAttemptDiagnosticFields(request),
-      details: {
-        requestType: request.type,
-        ...syncRevocation,
+  // -- §8.4 host loop: coalesced, jittered, inside the worker --------------
+  let autoSync = true;
+  let wakeJitterMs = 200;
+  let autoSyncScheduled = false;
+  function scheduleAutoSync(): void {
+    if (!autoSync || autoSyncScheduled || closed || client === undefined) {
+      return;
+    }
+    autoSyncScheduled = true;
+    setTimeout(
+      () => {
+        autoSyncScheduled = false;
+        if (closed || client === undefined) return;
+        const running = client;
+        void serializedSync(() => running.syncUntilIdle())
+          .then((summary) => {
+            if (!closed)
+              post({ t: 'event', event: { kind: 'synced', summary } });
+          })
+          .catch((error: unknown) => {
+            if (!closed) {
+              post({
+                t: 'event',
+                event: { kind: 'synced', error: toErrorShape(error) },
+              });
+            }
+          });
       },
-    });
+      Math.floor(Math.random() * wakeJitterMs),
+    );
   }
-}
 
-function requestSyncAttemptDiagnosticFields(
-  request: SyncularWorkerRequest
-): Pick<SyncularDiagnosticEvent, 'syncAttemptId' | 'traceId' | 'spanId'> {
-  if (
-    request.type !== 'syncPull' &&
-    request.type !== 'syncPush' &&
-    request.type !== 'syncOnce'
-  ) {
-    return {};
+  function requireClient(): SyncClient {
+    if (client === undefined) {
+      throw new ClientSyncError(
+        WORKER_FAILED_CODE,
+        'the worker received a call before init completed',
+      );
+    }
+    return client;
   }
-  return syncularDiagnosticAttemptFields(request.syncAttempt);
-}
 
-function isDiagnosedSuccessRequest(
-  type: SyncularWorkerRequest['type']
-): boolean {
-  return isGeneratedSyncularDiagnosedSuccessWorkerRequestType(type);
-}
+  function assertOnline(): void {
+    if (offline) {
+      throw new ClientSyncError(
+        'sync.transport_failed',
+        'the worker transport is offline (setOffline(true))',
+        true,
+      );
+    }
+  }
 
-function requestDiagnosticSource(
-  type: SyncularWorkerRequest['type']
-): SyncularDiagnosticEvent['source'] {
-  return generatedSyncularWorkerRequestDiagnosticSource(type);
-}
+  function gateOffline<T>(inner: (request: T) => Promise<Uint8Array>) {
+    return (request: T): Promise<Uint8Array> => {
+      assertOnline();
+      return inner(request);
+    };
+  }
 
-function requestDiagnosticLevel(
-  type: SyncularWorkerRequest['type'],
-  error: unknown
-): SyncularDiagnosticEvent['level'] {
-  if (type === 'setAuthHeaders' || syncularErrorStatus(error)) return 'warn';
-  return 'error';
-}
+  /** Offline gate that preserves the §5.4 `fetchUrl` capability marker. */
+  function gateSegmentsOffline(inner: SegmentDownloader): SegmentDownloader {
+    const fetchUrl = inner.fetchUrl;
+    return Object.assign(gateOffline(inner), {
+      ...(fetchUrl !== undefined
+        ? {
+            fetchUrl: (url: string) => {
+              assertOnline();
+              return fetchUrl(url);
+            },
+          }
+        : {}),
+    });
+  }
 
-function requestSuccessDetails(
-  request: SyncularWorkerRequest,
-  value: unknown
-): Record<string, unknown> {
-  switch (request.type) {
-    case 'open':
-      return {
-        storage: openedConfig?.storage,
-        clientId: openedConfig?.clientId,
-      };
-    case 'setAuthHeaders':
-      return { headerCount: Object.keys(request.headers).length };
-    case 'setFieldEncryption':
-      return {
-        enabled: request.config != null,
-        ruleCount: request.config?.rules.length ?? 0,
-      };
-    case 'setEncryptedCrdt':
-      return {
-        enabled: request.config != null,
-        keyCount: request.config ? Object.keys(request.config.keys).length : 0,
-      };
-    case 'setBlobEncryption':
-      return {
-        enabled: request.config != null,
-        keyCount: request.config ? Object.keys(request.config.keys).length : 0,
-      };
-    case 'syncPull':
-    case 'syncPush':
-    case 'syncOnce':
-      return syncResultDetails(value);
-    case 'storeBlob':
-      return { immediate: request.options?.immediate === true };
-    case 'pruneBlobCache':
-      return { maxBytes: request.maxBytes ?? null, prunedBytes: value };
-    case 'compactStorage':
-      return objectRecord(value);
-    case 'localHealthCheck': {
-      const report = objectRecord(value);
-      const findings = Array.isArray(report.findings) ? report.findings : [];
-      return {
-        ok: report.ok === true,
-        findingCount: findings.length,
-      };
-    }
-    case 'exportLocalSupportBundle': {
-      const bundle = objectRecord(value);
-      const health = objectRecord(bundle.health);
-      const findings = Array.isArray(health.findings) ? health.findings : [];
-      return {
-        redacted: bundle.redacted === true,
-        source: bundle.source,
-        findingCount: findings.length,
-      };
+  async function init(config: WorkerInitConfig): Promise<WorkerInitResult> {
+    if (client !== undefined) {
+      throw new ClientSyncError(
+        WORKER_FAILED_CODE,
+        'the worker is already initialized',
+      );
     }
-    case 'importLocalSupportBundle':
-      return objectRecord(value);
-    case 'repairLocalHealth':
-      return objectRecord(value);
-    case 'resetLocalSyncState':
-      return objectRecord(value);
-    case 'processBlobUploadQueue':
-      return objectRecord(value);
-    default:
-      return {};
+    autoSync = config.autoSync ?? true;
+    wakeJitterMs = config.wakeJitterMs ?? 200;
+
+    database =
+      overrides.openDatabase !== undefined
+        ? await overrides.openDatabase(config)
+        : await defaultOpenDatabase(config);
+    const transport = gateOffline(
+      overrides.createTransport !== undefined
+        ? overrides.createTransport(config)
+        : httpSyncTransport(config.endpoints.syncUrl),
+    );
+    const segments =
+      overrides.createSegments !== undefined
+        ? overrides.createSegments(config)
+        : config.endpoints.segmentsUrl !== undefined
+          ? httpSegmentDownloader(config.endpoints.segmentsUrl)
+          : undefined;
+    // §5.9 blob transport: only when a blobs URL is configured.
+    const blobs =
+      config.endpoints.blobsUrl !== undefined
+        ? httpBlobTransport(config.endpoints.blobsUrl)
+        : undefined;
+
+    // Realtime needs the (possibly persisted) clientId for the
+    // `{clientId}` URL placeholder — start the client first, then attach
+    // the connector through a mutable slot read at connect time.
+    let realtimeConnector: RealtimeConnector | undefined;
+    const started = new SyncClient({
+      database,
+      schema: config.schema,
+      transport,
+      ...(segments !== undefined
+        ? { segments: gateSegmentsOffline(segments) }
+        : {}),
+      ...(blobs !== undefined ? { blobs } : {}),
+      realtime: (handlers) => {
+        if (offline) {
+          throw new ClientSyncError(
+            'sync.transport_failed',
+            'the worker realtime channel is offline (setOffline(true))',
+            true,
+          );
+        }
+        if (realtimeConnector === undefined) {
+          throw new ClientSyncError(
+            'sync.invalid_request',
+            'no realtime connector configured',
+          );
+        }
+        return realtimeConnector(handlers);
+      },
+      ...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
+      ...(config.limits !== undefined ? { limits: config.limits } : {}),
+      onSyncNeeded: (reason) => {
+        post({ t: 'event', event: { kind: 'sync-needed', reason } });
+        scheduleAutoSync();
+      },
+      onConflict: (conflict) => {
+        post({ t: 'event', event: { kind: 'conflict', conflict } });
+      },
+      onUpgrading: (upgrading) => {
+        // §7.4.5: surface the schema-bump reset + completion to the UI thread.
+        post({ t: 'event', event: { kind: 'upgrading', upgrading } });
+      },
+      onPresence: (scopeKey) => {
+        // §8.6: surface a presence change to the UI thread.
+        post({ t: 'event', event: { kind: 'presence', scopeKey } });
+      },
+    });
+    // TODO 3.1 / I1: forward every coalesced apply-batch invalidation to the
+    // UI thread so `SyncClientHandle.onInvalidate` fires with worker parity.
+    started.onInvalidate((event) => {
+      if (!closed) post({ t: 'event', event: { kind: 'invalidate', event } });
+    });
+    await started.start();
+    realtimeConnector =
+      overrides.createRealtime !== undefined
+        ? overrides.createRealtime(config, started.clientId)
+        : config.endpoints.realtimeUrl !== undefined
+          ? webSocketRealtimeConnector(
+              config.endpoints.realtimeUrl.replace(
+                '{clientId}',
+                encodeURIComponent(started.clientId),
+              ),
+            )
+          : undefined;
+    client = started;
+    return { clientId: started.clientId };
   }
-}
 
-function syncResultDetails(value: unknown): Record<string, unknown> {
-  const result = objectRecord(value);
-  const changedTables = Array.isArray(result.changedTables)
-    ? result.changedTables
-    : [];
-  const changedRows = Array.isArray(result.changedRows)
-    ? result.changedRows
-    : [];
-  return {
-    changedTables,
-    changedRows,
-    changedRowsTruncated: result.changedRowsTruncated === true,
-    changedTableCount: changedTables.length,
-    changedRowCount: changedRows.length,
-    bootstrap: objectRecord(result.bootstrap),
-    pushedCommits:
-      typeof result.pushedCommits === 'number' ? result.pushedCommits : 0,
+  const api: WorkerApi = {
+    subscribe: (input) => requireClient().subscribe(input),
+    unsubscribe: (id) => requireClient().unsubscribe(id),
+    setWindow: async (base, units) => {
+      await requireClient().setWindow(base, units);
+      // A window change adds/removes value-sharded subscriptions; a widened
+      // unit needs a bootstrap pull to become visible. In autoSync mode the
+      // host loop owns rounds, so schedule one now — otherwise the new unit
+      // waits for an unrelated server wake-up (§8.4). A no-op change still
+      // schedules a harmless idempotent round.
+      scheduleAutoSync();
+    },
+    windowState: (base) => requireClient().windowState(base),
+    mutate: (mutations) => {
+      const id = requireClient().mutate(mutations);
+      // In autoSync mode the host loop owns rounds (§8.4): a local write must
+      // push without the app orchestrating sync, so schedule a jittered round
+      // to drain the outbox promptly. `mutate` is synchronous — its outbox
+      // write has committed before this line — and the round itself serializes
+      // on SyncClient's operation chain, so no ordering hack is needed here;
+      // the §8.4 jitter in `scheduleAutoSync` is the only deferral, and it
+      // coalesces bursts. (Historically this used setTimeout to dodge a
+      // nested-transaction flake; that race is fixed at the source now — the
+      // real cause was cross-operation interleaving, serialized in the core.)
+      scheduleAutoSync();
+      return id;
+    },
+    sync: () => {
+      const running = requireClient();
+      return serializedSync(() => running.sync());
+    },
+    syncUntilIdle: (maxRounds) => {
+      const running = requireClient();
+      return serializedSync(() => running.syncUntilIdle(maxRounds));
+    },
+    query: (sql, params) => requireClient().query(sql, params),
+    conflicts: () => requireClient().conflicts,
+    rejections: () => requireClient().rejections,
+    schemaFloor: () => requireClient().schemaFloor,
+    leaseState: () => requireClient().leaseState,
+    upgrading: () => requireClient().upgrading,
+    syncNeeded: () => requireClient().syncNeeded,
+    pendingCommits: () => requireClient().pendingCommits(),
+    subscriptions: () => requireClient().subscriptions(),
+    subscription: (id) => requireClient().subscription(id),
+    connectRealtime: () => requireClient().connectRealtime(),
+    disconnectRealtime: () => requireClient().disconnectRealtime(),
+    setPresence: (scopeKey, doc) => requireClient().setPresence(scopeKey, doc),
+    presence: (scopeKey) => requireClient().presence(scopeKey),
+    uploadBlob: (bytes, options) => requireClient().uploadBlob(bytes, options),
+    fetchBlob: (blobIdOrRef) => requireClient().fetchBlob(blobIdOrRef),
+    setOffline: (value) => {
+      offline = value;
+      if (offline) client?.disconnectRealtime();
+    },
+    close: async () => {
+      closed = true;
+      await client?.close();
+      database?.close();
+      client = undefined;
+      database = undefined;
+    },
   };
-}
 
-function syncScopeRevocationDetails(value: unknown): {
-  revokedSubscriptionIds: string[];
-  revokedSubscriptionCount: number;
-} | null {
-  const result = objectRecord(value);
-  const subscriptions = Array.isArray(result.subscriptions)
-    ? result.subscriptions
-    : [];
-  const revokedSubscriptionIds = subscriptions
-    .filter((subscription): subscription is { id: string; status: string } => {
-      return (
-        subscription !== null &&
-        typeof subscription === 'object' &&
-        (subscription as { status?: unknown }).status === 'revoked' &&
-        typeof (subscription as { id?: unknown }).id === 'string'
-      );
-    })
-    .map((subscription) => subscription.id);
+  async function dispatch(message: WorkerCallMessage): Promise<unknown> {
+    const method = api[message.method] as (...args: unknown[]) => unknown;
+    return await method.apply(api, message.args as unknown[]);
+  }
 
-  return revokedSubscriptionIds.length > 0
-    ? {
-        revokedSubscriptionIds,
-        revokedSubscriptionCount: revokedSubscriptionIds.length,
+  function run(
+    id: number,
+    fn: () => Promise<unknown>,
+    transfer?: (value: unknown) => Transferable[],
+  ): void {
+    void (async () => {
+      try {
+        const value = await fn();
+        post(
+          { t: 'result', id, value },
+          transfer !== undefined ? transfer(value) : undefined,
+        );
+      } catch (error) {
+        post({ t: 'error', id, error: toErrorShape(error) });
       }
-    : null;
-}
-
-function diagnosticStatus(error: unknown): Record<string, unknown> {
-  const status = syncularErrorStatus(error);
-  return status ? { status } : {};
-}
-
-function objectRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === 'object'
-    ? (value as Record<string, unknown>)
-    : {};
-}
+    })();
+  }
 
-function errorMessage(error: unknown): string {
-  return syncularErrorMessage(error);
-}
+  scope.addEventListener('message', (event) => {
+    const message = event.data as MainToWorkerMessage;
+    if (message.t === 'init') {
+      run(message.id, () => init(message.config));
+      return;
+    }
+    if (message.t === 'call') {
+      run(
+        message.id,
+        () => dispatch(message),
+        message.method === 'query'
+          ? (value) => queryTransferables(value as readonly unknown[])
+          : undefined,
+      );
+    }
+  });
 
-function errorRequiresFullRefresh(error: unknown): boolean {
-  return errorMessage(error).includes('full snapshot resync required');
+  post({ t: 'ready' });
 }
 
-function encodeWorkerError(error: unknown): SyncularWorkerErrorPayload {
-  if (isWorkerErrorPayload(error) && !(error instanceof Error)) return error;
-  if (error instanceof SyncularClientError) {
-    return {
-      code: error.code,
-      message: error.message,
-      category: error.category,
-      retryable: error.retryable,
-      recommendedAction: error.recommendedAction,
-      name: error.name,
-      stack: error.stack,
-      details: error.details,
-    };
-  }
-  if (error instanceof Error) {
-    const details = syncularErrorDetails(error);
-    const classification = classifySyncularError(error, error.message, details);
-    if (!classification) {
-      return createSyncularWorkerErrorPayload('worker.failed', error.message, {
-        name: error.name,
-        stack: error.stack,
-        details,
-      });
-    }
-    return {
-      code: classification.code,
-      message: error.message,
-      category: classification.category,
-      retryable: classification.retryable,
-      recommendedAction: classification.recommendedAction,
-      name: error.name,
-      stack: error.stack,
-      details,
-    };
-  }
-  const message = String(error);
-  const classification = classifySyncularError(error, message);
-  if (!classification) {
-    return createSyncularWorkerErrorPayload('worker.failed', message);
+async function defaultOpenDatabase(
+  config: WorkerInitConfig,
+): Promise<ClientDatabase> {
+  if (config.database.mode !== 'persistent') {
+    throw new ClientSyncError(
+      WORKER_FAILED_CODE,
+      "database mode 'custom' requires an openDatabase override in the " +
+        'worker bootstrap (startSyncWorker({ openDatabase }))',
+    );
   }
-  return {
-    code: classification.code,
-    message,
-    category: classification.category,
-    retryable: classification.retryable,
-    recommendedAction: classification.recommendedAction,
-  };
-}
-
-function isWorkerErrorPayload(
-  value: unknown
-): value is SyncularWorkerErrorPayload {
-  return Boolean(
-    value && typeof value === 'object' && 'code' in value && 'message' in value
-  );
+  return openPersistentWasmDatabase(config.database.name, {
+    ...(config.database.directory !== undefined
+      ? { directory: config.database.directory }
+      : {}),
+  });
 }