@strata-sync/client 0.1.0

package/src/sync-orchestrator.ts

@@ -0,0 +1,1041 @@
+import type {
+  ConnectionState,
+  DeltaPacket,
+  RebaseOptions,
+  SyncAction,
+  SyncClientState,
+  Transaction,
+} from "@strata-sync/core";
+import {
+  applyDeltas,
+  getOrCreateClientId,
+  ModelRegistry,
+  rebaseTransactions,
+} from "@strata-sync/core";
+import type { IdentityMapRegistry } from "./identity-map";
+import type { OutboxManager } from "./outbox-manager";
+import type {
+  StorageAdapter,
+  StorageMeta,
+  SyncClientEvent,
+  SyncClientOptions,
+  TransportAdapter,
+} from "./types";
+
+/**
+ * Orchestrates the sync state machine
+ */
+export class SyncOrchestrator {
+  private readonly storage: StorageAdapter;
+  private readonly transport: TransportAdapter;
+  private readonly identityMaps: IdentityMapRegistry;
+  private outboxManager: OutboxManager | null = null;
+  private readonly options: SyncClientOptions;
+  private readonly registry: ModelRegistry;
+
+  private _state: SyncClientState = "disconnected";
+  private _connectionState: ConnectionState = "disconnected";
+  private readonly stateListeners: Set<(state: SyncClientState) => void> =
+    new Set();
+  private readonly connectionListeners: Set<(state: ConnectionState) => void> =
+    new Set();
+
+  private readonly schemaHash: string;
+  private clientId = "";
+  private lastSyncId = 0;
+  private lastError: Error | null = null;
+  private firstSyncId = 0;
+  private groups: string[] = [];
+
+  private deltaSubscription: AsyncIterator<DeltaPacket> | null = null;
+  private running = false;
+  private readonly emitEvent?: (event: SyncClientEvent) => void;
+  private onTransactionConflict?: (tx: Transaction) => void;
+
+  constructor(
+    options: SyncClientOptions,
+    identityMaps: IdentityMapRegistry,
+    emitEvent?: (event: SyncClientEvent) => void
+  ) {
+    this.options = options;
+    this.storage = options.storage;
+    this.transport = options.transport;
+    this.identityMaps = identityMaps;
+    this.registry = new ModelRegistry(
+      options.schema ?? ModelRegistry.snapshot()
+    );
+    this.schemaHash = this.registry.getSchemaHash();
+    this.groups = options.groups ?? [];
+    this.emitEvent = emitEvent;
+
+    // Listen for transport connection changes
+    this.transport.onConnectionStateChange((state) => {
+      this.setConnectionState(state);
+      this.handleConnectionChange(state);
+    });
+  }
+
+  setOutboxManager(outboxManager: OutboxManager): void {
+    this.outboxManager = outboxManager;
+  }
+
+  setConflictHandler(handler: (tx: Transaction) => void): void {
+    this.onTransactionConflict = handler;
+  }
+
+  /**
+   * Gets the current sync state
+   */
+  get state(): SyncClientState {
+    return this._state;
+  }
+
+  /**
+   * Gets the current connection state
+   */
+  get connectionState(): ConnectionState {
+    return this._connectionState;
+  }
+
+  /**
+   * Gets the client ID
+   */
+  getClientId(): string {
+    return this.clientId;
+  }
+
+  /**
+   * Gets the last sync ID
+   */
+  getLastSyncId(): number {
+    return this.lastSyncId;
+  }
+
+  /**
+   * Gets the first sync ID from the last full bootstrap
+   */
+  getFirstSyncId(): number {
+    return this.firstSyncId;
+  }
+
+  /**
+   * Gets the last error
+   */
+  getLastError(): Error | null {
+    return this.lastError;
+  }
+
+  /**
+   * Starts the sync orchestrator
+   */
+  async start(): Promise<void> {
+    if (this.running) {
+      return;
+    }
+    this.running = true;
+
+    this.emitEvent?.({ type: "syncStart" });
+    this.setState("connecting");
+
+    try {
+      await this.openStorage();
+      const meta = await this.loadMetadata();
+      await this.configureGroups(meta);
+      await this.bootstrapIfNeeded(meta);
+      await this.applyPendingOutboxTransactions();
+      this.startDeltaSubscription();
+      await this.processOutboxTransactions();
+      this.setState("syncing");
+    } catch (error) {
+      this.lastError =
+        error instanceof Error ? error : new Error(String(error));
+      this.emitEvent?.({ type: "syncError", error: this.lastError });
+      this.setState("error");
+      throw error;
+    }
+  }
+
+  private async openStorage(): Promise<void> {
+    await this.storage.open({
+      name: this.options.dbName,
+      userId: this.options.userId,
+      version: this.options.version,
+      userVersion: this.options.userVersion,
+      schema: this.options.schema ?? this.registry.snapshot(),
+    });
+  }
+
+  private async loadMetadata(): Promise<StorageMeta> {
+    const meta = await this.storage.getMeta();
+    this.clientId =
+      meta.clientId ??
+      getOrCreateClientId(`${this.options.dbName ?? "sync-db"}_client_id`);
+    this.lastSyncId = meta.lastSyncId ?? 0;
+    this.firstSyncId = meta.firstSyncId ?? this.lastSyncId;
+    return meta;
+  }
+
+  private async configureGroups(meta: StorageMeta): Promise<void> {
+    const storedGroups = meta.subscribedSyncGroups ?? [];
+    const configuredGroups = this.options.groups ?? storedGroups;
+    this.groups = configuredGroups.length > 0 ? configuredGroups : storedGroups;
+
+    if (this.areGroupsEqual(storedGroups, this.groups)) {
+      return;
+    }
+
+    this.firstSyncId = this.lastSyncId;
+    await this.storage.setMeta({
+      subscribedSyncGroups: this.groups,
+      firstSyncId: this.firstSyncId,
+      updatedAt: Date.now(),
+    });
+  }
+
+  private async bootstrapIfNeeded(meta: StorageMeta): Promise<void> {
+    const needsBootstrap = await this.shouldBootstrap(meta);
+    if (!needsBootstrap) {
+      await this.hydrateIdentityMaps();
+      return;
+    }
+
+    await this.runBootstrapStrategy();
+  }
+
+  private async shouldBootstrap(meta: StorageMeta): Promise<boolean> {
+    const bootstrapModels = this.registry.getBootstrapModelNames();
+    const arePersisted = await this.areModelsPersisted(bootstrapModels);
+    const hasSchemaMismatch = meta.schemaHash
+      ? meta.schemaHash !== this.schemaHash
+      : false;
+
+    return (
+      meta.bootstrapComplete === false ||
+      hasSchemaMismatch ||
+      this.lastSyncId === 0 ||
+      !arePersisted
+    );
+  }
+
+  private async runBootstrapStrategy(): Promise<void> {
+    const bootstrapMode = this.options.bootstrapMode ?? "auto";
+    if (bootstrapMode === "local") {
+      await this.localBootstrap();
+      return;
+    }
+
+    try {
+      await this.bootstrap();
+    } catch (error) {
+      const canFallback =
+        bootstrapMode === "auto" && (await this.hasLocalData());
+      if (canFallback) {
+        await this.localBootstrap();
+        return;
+      }
+      throw error;
+    }
+  }
+
+  private async applyPendingOutboxTransactions(): Promise<void> {
+    const pending = await this.getActiveOutboxTransactions();
+    await this.applyPendingTransactionsToIdentityMaps(pending);
+  }
+
+  private async processOutboxTransactions(): Promise<void> {
+    if (!this.outboxManager) {
+      return;
+    }
+    await this.outboxManager.processPendingTransactions();
+  }
+
+  /**
+   * Stops the sync orchestrator
+   */
+  async stop(): Promise<void> {
+    this.running = false;
+
+    if (this.deltaSubscription) {
+      await this.deltaSubscription.return?.();
+      this.deltaSubscription = null;
+    }
+
+    await this.transport.close();
+    await this.storage.close();
+
+    this.setState("disconnected");
+  }
+
+  /**
+   * Forces an immediate sync
+   */
+  async syncNow(): Promise<void> {
+    // Fetch any missed deltas
+    const packet = await this.transport.fetchDeltas(this.lastSyncId);
+    await this.applyDeltaPacket(packet);
+
+    // Process pending outbox
+    if (this.outboxManager) {
+      await this.outboxManager.processPendingTransactions();
+    }
+  }
+
+  /**
+   * Subscribes to state changes
+   */
+  onStateChange(callback: (state: SyncClientState) => void): () => void {
+    this.stateListeners.add(callback);
+    return () => {
+      this.stateListeners.delete(callback);
+    };
+  }
+
+  /**
+   * Subscribes to connection state changes
+   */
+  onConnectionStateChange(
+    callback: (state: ConnectionState) => void
+  ): () => void {
+    this.connectionListeners.add(callback);
+    return () => {
+      this.connectionListeners.delete(callback);
+    };
+  }
+
+  /**
+   * Performs initial bootstrap
+   */
+  private async bootstrap(): Promise<void> {
+    this.setState("bootstrapping");
+
+    // Clear existing data
+    await this.storage.clear();
+    this.identityMaps.clearAll();
+
+    // Stream bootstrap data
+    const iterator = this.transport.bootstrap({
+      type: "full",
+      schemaHash: this.schemaHash,
+      onlyModels: this.registry.getBootstrapModelNames(),
+      syncGroups: this.groups,
+    });
+
+    let databaseVersion: number | undefined;
+
+    while (true) {
+      const { value, done } = await iterator.next();
+      if (done) {
+        if (!value) {
+          throw new Error("Bootstrap completed without metadata");
+        }
+        const metadata = value;
+        if (metadata.lastSyncId === undefined) {
+          throw new Error("Bootstrap metadata is missing lastSyncId");
+        }
+        this.lastSyncId = metadata.lastSyncId;
+        this.firstSyncId = metadata.lastSyncId;
+        this.groups =
+          (metadata.subscribedSyncGroups?.length ?? 0) > 0
+            ? metadata.subscribedSyncGroups
+            : this.groups;
+        databaseVersion = metadata.databaseVersion;
+        break;
+      }
+
+      const row = value;
+      const primaryKey = this.registry.getPrimaryKey(row.modelName);
+      const id = row.data[primaryKey] as string;
+      if (typeof id !== "string") {
+        continue;
+      }
+      // Store in IndexedDB
+      await this.storage.put(row.modelName, row.data);
+
+      // Add to identity map
+      const map = this.identityMaps.getMap(row.modelName);
+      map.set(id, row.data);
+    }
+
+    // Update metadata + persistence flags
+    const bootstrapModels = this.registry.getBootstrapModelNames();
+
+    for (const modelName of bootstrapModels) {
+      await this.storage.setModelPersistence(modelName, true);
+    }
+
+    await this.storage.setMeta({
+      lastSyncId: this.lastSyncId,
+      firstSyncId: this.firstSyncId,
+      subscribedSyncGroups: this.groups,
+      bootstrapComplete: true,
+      lastSyncAt: Date.now(),
+      schemaHash: this.schemaHash,
+      databaseVersion,
+      updatedAt: Date.now(),
+    });
+    this.emitEvent?.({ type: "syncComplete", lastSyncId: this.lastSyncId });
+  }
+
+  /**
+   * Performs a local-only bootstrap using existing storage data.
+   */
+  private async localBootstrap(): Promise<void> {
+    this.setState("bootstrapping");
+    await this.hydrateIdentityMaps();
+  }
+
+  /**
+   * Checks whether any hydrated models exist in storage.
+   */
+  private async hasLocalData(): Promise<boolean> {
+    for (const modelName of this.registry.getHydratedModelNames()) {
+      const count = await this.storage.count(modelName);
+      if (count > 0) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Loads existing data from storage into identity maps
+   */
+  private async hydrateIdentityMaps(): Promise<void> {
+    for (const modelName of this.registry.getHydratedModelNames()) {
+      const rows =
+        await this.storage.getAll<Record<string, unknown>>(modelName);
+      const map = this.identityMaps.getMap(modelName);
+      const primaryKey = this.registry.getPrimaryKey(modelName);
+
+      for (const row of rows) {
+        const id = row[primaryKey] as string;
+        if (typeof id !== "string") {
+          continue;
+        }
+        map.set(id, row);
+      }
+    }
+  }
+
+  private async areModelsPersisted(modelNames: string[]): Promise<boolean> {
+    for (const modelName of modelNames) {
+      const persistence = await this.storage.getModelPersistence(modelName);
+      if (!persistence.persisted) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  private areGroupsEqual(a: string[], b: string[]): boolean {
+    if (a.length !== b.length) {
+      return false;
+    }
+    const setA = new Set(a);
+    if (setA.size !== b.length) {
+      return false;
+    }
+    for (const value of b) {
+      if (!setA.has(value)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Starts the delta subscription
+   */
+  private startDeltaSubscription(): void {
+    const subscription = this.transport.subscribe({
+      afterSyncId: this.lastSyncId,
+      groups: this.groups,
+    });
+
+    this.deltaSubscription = subscription[Symbol.asyncIterator]();
+
+    // Process deltas in background
+    this.processDeltaStream().catch(() => undefined);
+  }
+
+  /**
+   * Processes the delta stream
+   */
+  private async processDeltaStream(): Promise<void> {
+    if (!this.deltaSubscription) {
+      return;
+    }
+
+    try {
+      while (this.running) {
+        const { value, done } = await this.deltaSubscription.next();
+        if (done) {
+          break;
+        }
+
+        await this.applyDeltaPacket(value);
+      }
+    } catch (error) {
+      if (this.running) {
+        this.lastError =
+          error instanceof Error ? error : new Error(String(error));
+        this.emitEvent?.({ type: "syncError", error: this.lastError });
+        // Try to reconnect
+        this.setState("error");
+        setTimeout(() => {
+          if (this.running) {
+            this.startDeltaSubscription();
+          }
+        }, 5000);
+      }
+    }
+  }
+
+  /**
+   * Applies a delta packet to local state
+   */
+  private async applyDeltaPacket(packet: DeltaPacket): Promise<void> {
+    if (packet.actions.length === 0) {
+      await this.handleEmptyPacket(packet);
+      return;
+    }
+
+    await this.storage.addSyncActions(packet.actions);
+
+    const activeTransactions = await this.getActiveOutboxTransactions();
+    await this.rebasePendingTransactions(activeTransactions, packet.actions);
+    await this.handleCoverageActions(packet.actions);
+    await this.handleSyncGroupActions(packet.actions, packet.lastSyncId);
+
+    await this.applyPacketToStorage(packet);
+    await this.updateSyncMetadata(packet.lastSyncId);
+    await this.finishOutboxProcessing(packet.actions);
+    await this.applyPendingOutboxToIdentityMaps();
+    this.emitModelChangeEvents(packet.actions);
+    await this.emitOutboxCount();
+  }
+
+  private async handleEmptyPacket(packet: DeltaPacket): Promise<void> {
+    if (packet.lastSyncId > this.lastSyncId) {
+      await this.updateSyncMetadata(packet.lastSyncId);
+    }
+  }
+
+  private async getActiveOutboxTransactions(): Promise<Transaction[]> {
+    const outbox = await this.storage.getOutbox();
+    return outbox.filter(
+      (tx) =>
+        tx.state === "queued" ||
+        tx.state === "sent" ||
+        tx.state === "awaitingSync"
+    );
+  }
+
+  private createDeltaTarget() {
+    return {
+      put: async (
+        modelName: string,
+        id: string,
+        data: Record<string, unknown>
+      ) => {
+        await this.storage.put(modelName, data);
+        const map = this.identityMaps.getMap(modelName);
+        map.merge(id, data);
+      },
+      delete: async (modelName: string, id: string) => {
+        await this.storage.delete(modelName, id);
+        const map = this.identityMaps.getMap(modelName);
+        map.delete(id);
+      },
+      patch: async (
+        modelName: string,
+        id: string,
+        changes: Record<string, unknown>
+      ) => {
+        const existing = await this.storage.get<Record<string, unknown>>(
+          modelName,
+          id
+        );
+        if (!existing) {
+          return;
+        }
+        const updated = { ...existing, ...changes };
+        await this.storage.put(modelName, updated);
+        const map = this.identityMaps.getMap(modelName);
+        map.merge(id, updated);
+      },
+      get: (modelName: string, id: string) => {
+        return this.storage.get<Record<string, unknown>>(modelName, id);
+      },
+    };
+  }
+
+  private async applyPacketToStorage(packet: DeltaPacket): Promise<void> {
+    const deltaTarget = this.createDeltaTarget();
+    await applyDeltas(packet, deltaTarget, this.registry);
+  }
+
+  private async updateSyncMetadata(lastSyncId: number): Promise<void> {
+    this.lastSyncId = lastSyncId;
+    await this.storage.setMeta({
+      lastSyncId: this.lastSyncId,
+      lastSyncAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+    this.emitEvent?.({ type: "syncComplete", lastSyncId: this.lastSyncId });
+  }
+
+  private async finishOutboxProcessing(actions: SyncAction[]): Promise<void> {
+    await this.removeConfirmedTransactions(actions);
+    await this.removeRedundantCreateTransactions(actions);
+    if (this.outboxManager) {
+      await this.outboxManager.completeUpToSyncId(this.lastSyncId);
+    }
+  }
+
+  private async applyPendingOutboxToIdentityMaps(): Promise<void> {
+    const pending = await this.getActiveOutboxTransactions();
+    this.applyPendingTransactionsToIdentityMaps(pending);
+  }
+
+  private resolveModelChangeAction(
+    action: SyncAction["action"]
+  ): "insert" | "update" | "delete" | "archive" | "unarchive" | null {
+    switch (action) {
+      case "I":
+        return "insert";
+      case "U":
+        return "update";
+      case "D":
+        return "delete";
+      case "A":
+        return "archive";
+      case "V":
+        return "unarchive";
+      default:
+        return null;
+    }
+  }
+
+  private emitModelChangeEvents(actions: SyncAction[]): void {
+    for (const action of actions) {
+      const eventAction = this.resolveModelChangeAction(action.action);
+      if (!eventAction) {
+        continue;
+      }
+      this.emitEvent?.({
+        type: "modelChange",
+        modelName: action.modelName,
+        modelId: action.modelId,
+        action: eventAction,
+      });
+    }
+  }
+
+  private async emitOutboxCount(): Promise<void> {
+    if (!this.emitEvent) {
+      return;
+    }
+    const pendingCount = (await this.getActiveOutboxTransactions()).length;
+    this.emitEvent({ type: "outboxChange", pendingCount });
+  }
+
+  private async rebasePendingTransactions(
+    pending: Transaction[],
+    actions: SyncAction[]
+  ): Promise<void> {
+    if (pending.length === 0) {
+      return;
+    }
+
+    const rebaseOptions: RebaseOptions = {
+      clientId: this.clientId,
+      defaultResolution: this.options.rebaseStrategy ?? "server-wins",
+      fieldLevelConflicts: this.options.fieldLevelConflicts ?? true,
+    };
+
+    const result = rebaseTransactions(pending, actions, rebaseOptions);
+
+    for (const conflict of result.conflicts) {
+      await this.handleConflict(conflict);
+    }
+
+    await this.updatePendingOriginals(result.pending, actions);
+  }
+
+  private async handleConflict(
+    conflict: import("@strata-sync/core").RebaseConflict
+  ): Promise<void> {
+    const { localTransaction: tx } = conflict;
+    const resolution =
+      conflict.resolution === "manual" ? "server-wins" : conflict.resolution;
+
+    if (resolution === "server-wins") {
+      await this.storage.removeFromOutbox(tx.clientTxId);
+      this.onTransactionConflict?.(tx);
+    } else if (
+      (resolution === "client-wins" || resolution === "merge") &&
+      (tx.action === "U" || tx.action === "A" || tx.action === "V")
+    ) {
+      const updatedOriginal = {
+        ...(tx.original ?? {}),
+        ...conflict.serverAction.data,
+      };
+      tx.original = updatedOriginal;
+      await this.storage.updateOutboxTransaction(tx.clientTxId, {
+        original: updatedOriginal,
+      });
+    }
+
+    this.emitEvent?.({
+      type: "rebaseConflict",
+      modelName: tx.modelName,
+      modelId: tx.modelId,
+      conflictType: conflict.conflictType,
+      resolution,
+    });
+  }
+
+  private async updatePendingOriginals(
+    pending: Transaction[],
+    actions: SyncAction[]
+  ): Promise<void> {
+    const actionsByKey = this.buildActionsByKey(actions);
+
+    for (const tx of pending) {
+      if (tx.action !== "U" && tx.action !== "A" && tx.action !== "V") {
+        continue;
+      }
+      const key = `${tx.modelName}:${tx.modelId}`;
+      const related = actionsByKey.get(key);
+      if (!related) {
+        continue;
+      }
+      const updatedOriginal = this.getUpdatedOriginal(tx, related);
+      if (!updatedOriginal) {
+        continue;
+      }
+      tx.original = updatedOriginal;
+      await this.storage.updateOutboxTransaction(tx.clientTxId, {
+        original: updatedOriginal,
+      });
+    }
+  }
+
+  private buildActionsByKey(actions: SyncAction[]): Map<string, SyncAction[]> {
+    const actionsByKey = new Map<string, SyncAction[]>();
+    for (const action of actions) {
+      const key = `${action.modelName}:${action.modelId}`;
+      const existing = actionsByKey.get(key) ?? [];
+      existing.push(action);
+      actionsByKey.set(key, existing);
+    }
+    return actionsByKey;
+  }
+
+  private shouldRebaseAction(action: SyncAction["action"]): boolean {
+    return action === "U" || action === "I" || action === "V" || action === "C";
+  }
+
+  private getUpdatedOriginal(
+    tx: Transaction,
+    related: SyncAction[]
+  ): Record<string, unknown> | null {
+    const original = { ...(tx.original ?? {}) };
+    let updated = false;
+
+    for (const action of related) {
+      if (!this.shouldRebaseAction(action.action)) {
+        continue;
+      }
+      for (const field of Object.keys(tx.payload)) {
+        if (field in action.data) {
+          original[field] = action.data[field];
+          updated = true;
+        }
+      }
+    }
+
+    return updated ? original : null;
+  }
+
+  private applyPendingTransactionsToIdentityMaps(pending: Transaction[]): void {
+    if (pending.length === 0) {
+      return;
+    }
+
+    for (const tx of pending) {
+      const map = this.identityMaps.getMap<Record<string, unknown>>(
+        tx.modelName
+      );
+
+      switch (tx.action) {
+        case "I":
+        case "U":
+          map.merge(tx.modelId, tx.payload);
+          break;
+        case "D":
+          map.delete(tx.modelId);
+          break;
+        case "A": {
+          const archivedAt =
+            (tx.payload as Record<string, unknown>).archivedAt ??
+            new Date().toISOString();
+          map.merge(tx.modelId, { archivedAt });
+          break;
+        }
+        case "V": {
+          const existing = map.get(tx.modelId);
+          if (existing) {
+            const updated = { ...existing };
+            (updated as Record<string, unknown>).archivedAt = undefined;
+            map.set(tx.modelId, updated);
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    }
+  }
+
+  private async removeConfirmedTransactions(
+    actions: SyncAction[]
+  ): Promise<void> {
+    const clientTxIds = actions
+      .map((action) => action.clientTxId)
+      .filter((value): value is string => typeof value === "string");
+
+    if (clientTxIds.length === 0) {
+      return;
+    }
+
+    const outbox = await this.storage.getOutbox();
+    const known = new Set(outbox.map((tx) => tx.clientTxId));
+    for (const clientTxId of clientTxIds) {
+      if (known.has(clientTxId)) {
+        await this.storage.removeFromOutbox(clientTxId);
+      }
+    }
+  }
+
+  private async removeRedundantCreateTransactions(
+    actions: SyncAction[]
+  ): Promise<void> {
+    const createdIds = actions
+      .filter((action) => action.action === "I")
+      .map((action) => action.modelId);
+
+    if (createdIds.length === 0) {
+      return;
+    }
+
+    const createdSet = new Set(createdIds);
+    const outbox = await this.storage.getOutbox();
+
+    for (const tx of outbox) {
+      if (tx.action === "I" && createdSet.has(tx.modelId)) {
+        await this.storage.removeFromOutbox(tx.clientTxId);
+      }
+    }
+  }
+
+  private async handleCoverageActions(actions: SyncAction[]): Promise<void> {
+    for (const action of actions) {
+      if (action.action !== "C") {
+        continue;
+      }
+      const indexedKey = (action.data as Record<string, unknown>).indexedKey;
+      const keyValue = (action.data as Record<string, unknown>).keyValue;
+      if (typeof indexedKey === "string" && typeof keyValue === "string") {
+        await this.storage.setPartialIndex(
+          action.modelName,
+          indexedKey,
+          keyValue
+        );
+      }
+    }
+  }
+
+  private async handleSyncGroupActions(
+    actions: SyncAction[],
+    nextSyncId: number
+  ): Promise<void> {
+    const groupUpdates: string[][] = [];
+    for (const action of actions) {
+      if (action.action !== "G" && action.action !== "S") {
+        continue;
+      }
+      const data = action.data as Record<string, unknown>;
+      const groups = data.subscribedSyncGroups;
+      if (Array.isArray(groups)) {
+        const filtered = groups.filter(
+          (group): group is string => typeof group === "string"
+        );
+        if (filtered.length > 0) {
+          groupUpdates.push(filtered);
+        }
+      }
+    }
+
+    if (groupUpdates.length === 0) {
+      return;
+    }
+
+    const nextGroups = groupUpdates.at(-1);
+    if (!nextGroups || this.areGroupsEqual(this.groups, nextGroups)) {
+      return;
+    }
+
+    const currentSet = new Set(this.groups);
+    const nextSet = new Set(nextGroups);
+    const addedGroups = nextGroups.filter((group) => !currentSet.has(group));
+    const removedGroups = this.groups.filter((group) => !nextSet.has(group));
+
+    if (addedGroups.length > 0) {
+      await this.bootstrapSyncGroups(addedGroups, nextSyncId);
+    }
+
+    if (removedGroups.length > 0) {
+      await this.removeSyncGroupData(removedGroups);
+    }
+
+    this.groups = nextGroups;
+    this.firstSyncId = nextSyncId;
+    await this.storage.setMeta({
+      subscribedSyncGroups: this.groups,
+      firstSyncId: this.firstSyncId,
+      updatedAt: Date.now(),
+    });
+  }
+
+  private async bootstrapSyncGroups(
+    groups: string[],
+    firstSyncId: number
+  ): Promise<void> {
+    const iterator = this.transport.bootstrap({
+      type: "partial",
+      schemaHash: this.schemaHash,
+      firstSyncId,
+      syncGroups: groups,
+      noSyncPackets: true,
+    });
+
+    const hydrated = new Set(this.registry.getHydratedModelNames());
+
+    while (true) {
+      const { value, done } = await iterator.next();
+      if (done) {
+        break;
+      }
+
+      const row = value;
+      const primaryKey = this.registry.getPrimaryKey(row.modelName);
+      const id = row.data[primaryKey] as string;
+      if (typeof id !== "string") {
+        continue;
+      }
+      await this.storage.put(row.modelName, row.data);
+
+      if (hydrated.has(row.modelName)) {
+        const map = this.identityMaps.getMap(row.modelName);
+        map.merge(id, row.data);
+      }
+    }
+  }
+
+  private async removeSyncGroupData(groups: string[]): Promise<void> {
+    if (groups.length === 0) {
+      return;
+    }
+
+    for (const model of this.registry.getAllModels()) {
+      const modelName = model.name ?? "";
+      const groupKey = model.groupKey;
+      if (!(modelName && groupKey)) {
+        continue;
+      }
+
+      const primaryKey = model.primaryKey ?? "id";
+      const map = this.identityMaps.getMap<Record<string, unknown>>(modelName);
+
+      for (const group of groups) {
+        const rows = await this.storage.getByIndex<Record<string, unknown>>(
+          modelName,
+          groupKey,
+          group
+        );
+
+        for (const row of rows) {
+          const id = row[primaryKey] as string;
+          if (typeof id !== "string") {
+            continue;
+          }
+          await this.storage.delete(modelName, id);
+          map.delete(id);
+          this.emitEvent?.({
+            type: "modelChange",
+            modelName,
+            modelId: id,
+            action: "delete",
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Handles connection state changes
+   */
+  private handleConnectionChange(state: ConnectionState): void {
+    if (state === "connected" && this._state === "error") {
+      // Reconnected - catch up on missed deltas
+      this.syncNow().catch(() => {
+        // Ignore errors, will retry
+      });
+    }
+  }
+
+  /**
+   * Sets the sync state
+   */
+  private setState(state: SyncClientState): void {
+    if (this._state !== state) {
+      this._state = state;
+      if (state !== "error") {
+        this.lastError = null;
+      }
+      this.emitEvent?.({ type: "stateChange", state });
+      for (const listener of this.stateListeners) {
+        listener(state);
+      }
+    }
+  }
+
+  /**
+   * Sets the connection state
+   */
+  private setConnectionState(state: ConnectionState): void {
+    if (this._connectionState !== state) {
+      this._connectionState = state;
+      this.emitEvent?.({ type: "connectionChange", state });
+      for (const listener of this.connectionListeners) {
+        listener(state);
+      }
+    }
+  }
+
+  /**
+   * Gets the model registry
+   */
+  getRegistry(): ModelRegistry {
+    return this.registry;
+  }
+
+  /**
+   * Gets the storage adapter
+   */
+  getStorage(): StorageAdapter {
+    return this.storage;
+  }
+}