@syncular/client 0.15.42 → 0.15.44

package/dist/worker-host.d.ts

@@ -157,6 +157,14 @@ export declare class SyncClientHandle {
         leadershipListeners?: Set<(state: LeadershipState) => void>;
         leadership?: LeadershipState;
     });
+    /**
+     * @internal — whether `close()` has run.
+     *
+     * A follower keeps a blocking `acquire` outstanding for the whole time it is a
+     * follower, so its promotion can fire long after the application has discarded
+     * the handle. The promotion path consults this before opening anything.
+     */
+    get __isClosed(): boolean;
     /** @internal — swap this handle from follower to leader (promotion). */
     __becomeLeader(core: LeaderCore): void;
     /** @internal — apply a follower reachability snapshot in place. */

package/dist/worker-host.js

@@ -113,6 +113,16 @@ export class SyncClientHandle {
             onInvalidate: (listener) => this.onInvalidate(listener),
         });
     }
+    /**
+     * @internal — whether `close()` has run.
+     *
+     * A follower keeps a blocking `acquire` outstanding for the whole time it is a
+     * follower, so its promotion can fire long after the application has discarded
+     * the handle. The promotion path consults this before opening anything.
+     */
+    get __isClosed() {
+        return this.#closed;
+    }
     /** @internal — swap this handle from follower to leader (promotion). */
     __becomeLeader(core) {
         this.#follower?.close();
@@ -652,6 +662,14 @@ async function bootFollower(config, lockName, lock, parts) {
             await lease.release();
             return;
         }
+        if (handle.__isClosed) {
+            // The application discarded this handle while it was queued for
+            // leadership. Promoting now would open a database nobody is holding and
+            // then keep the lock forever, so no other tab could ever take over.
+            // Release instead, and let the next waiter have it.
+            await lease.release();
+            return;
+        }
         // The follower saw the departing leader's epoch; the new leader must
         // strictly exceed it so stale replies/events are discarded everywhere.
         const nextEpoch = follower.maxEpochSeen + 1;
@@ -681,6 +699,13 @@ async function bootFollower(config, lockName, lock, parts) {
                     }
                     : {}),
             });
+            if (handle.__isClosed) {
+                // Closed while the worker was starting. `close()` already ran and found
+                // no core to shut down, so this one would leak: tear it down here rather
+                // than hand it to a discarded handle. `close(true)` releases the lease.
+                await core.close(true);
+                return;
+            }
             handle.__becomeLeader(core);
         }
         catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.42",
+  "version": "0.15.44",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,7 +89,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.42"
+    "@syncular/core": "0.15.44"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -100,7 +100,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.42",
+    "@syncular/server": "0.15.44",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -558,6 +558,16 @@ export class SyncClient {
    * (the fast-bail the delta path reads).
    */
   #syncOutstanding = false;
+  /**
+   * Bumped by every local projection reset (`rebootstrapLocalData`). A sync
+   * round captures this epoch together with its subscription state; a
+   * mismatch at SUB_END means a reset landed while the round was in flight,
+   * so the captured cursors predate the rewind and persisting them would
+   * overwrite it and silently skip the fresh bootstrap. The Rust core is
+   * synchronous over `&mut self` and gets this fencing for free; the epoch
+   * restores the equivalent semantics across the round's await points.
+   */
+  #localResetEpoch = 0;
   /** Retry policy belongs to the operation that classified the failure. */
   #retryDelayMs = 250;
   readonly #hasBlobs: boolean;
@@ -2124,53 +2134,62 @@ export class SyncClient {
     const rejectionCount = this.#rejections.length;
     try {
       return this.#applyBatch((batch) => {
-        const initialRowIds = this.#localPurgeRowIds(purge);
         const targetsByTable = this.#localPurgeTargetsByTable(purge);
-        const doomed = listOutbox(this.#db)
-          .filter((commit) => {
-            const images = new Map(
-              listOutboxBeforeImages(this.#db, commit.clientCommitId).map(
-                (image) => [image.opIndex, image],
-              ),
-            );
-            return commit.operations.some((operation, opIndex) => {
-              const targets = targetsByTable.get(operation.table);
-              if (targets === undefined) return false;
-              if (
-                initialRowIds.get(operation.table)?.has(operation.rowId) ===
-                true
-              ) {
-                return true;
-              }
-              if (
-                operation.values !== undefined &&
-                targets.some((target) =>
-                  localDataPurgeTargetMatches(target, operation.values ?? {}),
-                )
-              ) {
-                return true;
-              }
-              const beforeValues = images.get(opIndex)?.values;
-              return (
-                beforeValues !== undefined &&
-                targets.some((target) =>
-                  localDataPurgeTargetMatches(target, beforeValues),
-                )
+        // Doomed detection runs to fixpoint, matching the Rust core's rule:
+        // a commit is doomed when any of its ops touches a base-matching
+        // row. Base values only become visible here as rollbacks restore
+        // before-images and rebase later commits' images onto them (a
+        // stacked edit over a moved row initially shows the moved values),
+        // so each pass rolls back what it caught — newest-first, so an
+        // older doomed write never reappears — and re-scans until the
+        // outbox is stable.
+        const doomed: OutboxCommit[] = [];
+        let rowIds = this.#localPurgeRowIds(purge);
+        for (;;) {
+          const caught = listOutbox(this.#db)
+            .filter((commit) => {
+              const images = new Map(
+                listOutboxBeforeImages(this.#db, commit.clientCommitId).map(
+                  (image) => [image.opIndex, image],
+                ),
               );
-            });
-          })
-          // Reverse order is essential: each rollback restores its before-image;
-          // removing newest-first prevents an older doomed write reappearing.
-          .sort((a, b) => b.seq - a.seq);
-
-        for (const commit of doomed) {
-          this.#rollbackFailedCommit(commit, batch);
+              return commit.operations.some((operation, opIndex) => {
+                const targets = targetsByTable.get(operation.table);
+                if (targets === undefined) return false;
+                if (
+                  rowIds.get(operation.table)?.has(operation.rowId) === true
+                ) {
+                  return true;
+                }
+                if (
+                  operation.values !== undefined &&
+                  targets.some((target) =>
+                    localDataPurgeTargetMatches(target, operation.values ?? {}),
+                  )
+                ) {
+                  return true;
+                }
+                const beforeValues = images.get(opIndex)?.values;
+                return (
+                  beforeValues !== undefined &&
+                  targets.some((target) =>
+                    localDataPurgeTargetMatches(target, beforeValues),
+                  )
+                );
+              });
+            })
+            .sort((a, b) => b.seq - a.seq);
+          if (caught.length === 0) break;
+          for (const commit of caught) {
+            this.#rollbackFailedCommit(commit, batch);
+          }
+          doomed.push(...caught);
+          // Rollback may reveal a target row hidden by an optimistic delete
+          // or move; the re-selected set drives both the next scan and the
+          // final row deletion below.
+          rowIds = this.#localPurgeRowIds(purge);
         }
 
-        // Rollback may reveal a target row hidden by an optimistic delete or
-        // move, so select the final base/visible set only after doomed commits
-        // have been removed.
-        const rowIds = this.#localPurgeRowIds(purge);
         let purgedRows = 0;
         for (const [tableName, ids] of rowIds) {
           if (ids.size === 0) continue;
@@ -2296,6 +2315,9 @@ export class SyncClient {
       this.#needsPull = priorNeedsPull;
       throw error;
     }
+    // Fence any in-flight sync round: its captured subscription state now
+    // predates the rewind, so its SUB_END cursors must stay unpersisted.
+    this.#localResetEpoch += 1;
 
     if (!priorUpgrading) this.#config.onUpgrading?.(true);
     this.#config.onSyncNeeded?.('startup');
@@ -2575,6 +2597,9 @@ export class SyncClient {
       // mapping.
       const { pushFrames, outbox, deferred } =
         await this.#encodeOutboxForPush();
+      // Captured together with the subscription state below: the response
+      // apply persists SUB_END cursors only while this epoch is current.
+      const resetEpoch = this.#localResetEpoch;
       const subs = loadSubscriptions(this.#db).filter(
         (sub) => sub.status === 'active',
       );
@@ -2625,6 +2650,7 @@ export class SyncClient {
         outbox,
         subs,
         'pull',
+        resetEpoch,
       );
       // §4.8 E1: the push half may have drained commits that pinned rows of
       // a shrunk window unit — retry any deferred evictions now.
@@ -2998,6 +3024,7 @@ export class SyncClient {
     sentCommits: readonly OutboxCommit[],
     sentSubs: readonly SubscriptionRecord[] | undefined,
     mode: 'pull' | 'delta',
+    resetEpoch: number = this.#localResetEpoch,
   ): Promise<SyncSummary> {
     const summary = emptySummary(sentCommits.length);
     const commitsById = new Map(
@@ -3258,7 +3285,12 @@ export class SyncClient {
             if (
               section !== undefined &&
               !section.skip &&
-              section.sub !== undefined
+              section.sub !== undefined &&
+              // Reset fence: a rebootstrap that landed mid-round already
+              // rewound this subscription's cursor; the captured SUB_END
+              // state predates the rewind and must stay unpersisted so the
+              // next round runs the fresh bootstrap.
+              this.#localResetEpoch === resetEpoch
             ) {
               const applied = this.#finishSection(
                 section.sub,
@@ -3315,7 +3347,14 @@ export class SyncClient {
       .map((sub) => sub.id);
     // §7.4.5: the reset is over once the first post-reset pull round leaves
     // no subscription mid-bootstrap — the tables are rebuilt and current.
-    if (this.#upgrading && mode === 'pull' && bootstrapping.length === 0) {
+    // The epoch check keeps a round that predates a mid-flight rebootstrap
+    // from declaring that reset finished before its bootstrap ran.
+    if (
+      this.#upgrading &&
+      mode === 'pull' &&
+      bootstrapping.length === 0 &&
+      this.#localResetEpoch === resetEpoch
+    ) {
       this.#setUpgrading(false);
     }
     return { ...summary, bootstrapping };
@@ -3331,6 +3370,12 @@ export class SyncClient {
   ): boolean {
     const commit = commitsById.get(frame.clientCommitId);
     if (commit === undefined) return false;
+    // `commitsById` is the round's send-time snapshot. The commit can leave
+    // the outbox before this frame is handled — a local purge doomed it while
+    // the round was in flight, or an earlier duplicate frame in this response
+    // already drained it. Its recorded outcome stands, and skipping keeps the
+    // cached outbox count exact (a drain may only be counted once).
+    if (!this.#outboxCommitExists(frame.clientCommitId)) return false;
     if (frame.status === 'applied' || frame.status === 'cached') {
       // §6.3: applied and cached both drain the outbox — cached means
       // "already applied, you may have missed the ack".
@@ -3427,6 +3472,15 @@ export class SyncClient {
     return true;
   }
 
+  #outboxCommitExists(clientCommitId: string): boolean {
+    return (
+      this.#db.query(
+        'SELECT 1 FROM _syncular_outbox WHERE client_commit_id = ? LIMIT 1',
+        [clientCommitId],
+      ).length > 0
+    );
+  }
+
   #decodeServerRow(
     tableName: string | undefined,
     payload: Uint8Array,

package/src/encryption.ts

@@ -13,11 +13,13 @@ import {
   DecryptError,
   decryptValue,
   encryptValue,
+  KEY_LENGTH,
   type NonceSource,
   type PlainValue,
   type RowColumn,
   type RowValue,
 } from '@syncular/core';
+import { ClientSyncError } from './errors';
 import type { CompiledClientTable } from './schema';
 
 /**
@@ -59,12 +61,29 @@ export interface EncryptionKeyringConfig {
   readonly keyIdColumns?: Readonly<Record<string, string>>;
 }
 
-/** Convert a portable keyring into the direct-client encryption contract. */
+/**
+ * Convert a portable keyring into the direct-client encryption contract.
+ * Key lengths are validated here, at install time: every side of the wire
+ * enforces {@link KEY_LENGTH}-byte keys, so a wrong-length key fails loud
+ * with a clear config error before any sync round runs.
+ */
 export function encryptionConfigFromKeyring(
   keyring: EncryptionKeyringConfig,
 ): EncryptionConfig {
+  for (const [keyId, key] of Object.entries(keyring.keys)) {
+    if (key.length !== KEY_LENGTH) {
+      throw new ClientSyncError(
+        'sync.invalid_request',
+        `encryption key ${JSON.stringify(keyId)} must be ${KEY_LENGTH} bytes (AES-256), got ${key.length}`,
+      );
+    }
+  }
   return {
-    keyProvider: (keyId) => keyring.keys[keyId],
+    // Own-property lookup only: the keyId arrives from the wire envelope, so
+    // a prototype-chain name like "constructor" must read as a missing key
+    // and take the clean DecryptError path.
+    keyProvider: (keyId) =>
+      Object.hasOwn(keyring.keys, keyId) ? keyring.keys[keyId] : undefined,
     ...(keyring.keyIdColumns !== undefined
       ? { keyIdColumns: keyring.keyIdColumns }
       : {}),

package/src/reactive-store.ts

@@ -850,10 +850,16 @@ export class ReactiveClientStore {
       // Releasing a window is best-effort teardown. A resource owner may have
       // already closed the underlying worker/native handle before React effect
       // cleanup runs (notably during schema-changing HMR). Do not let that
-      // harmless ordering race escape as an unhandled rejection.
-      void Promise.resolve(this.client.setWindow(group.base, [])).catch(
-        () => undefined,
-      );
+      // harmless ordering race escape as an unhandled rejection — and the
+      // interface permits a plain void return, so a closed handle may also
+      // throw synchronously; swallow that the same way.
+      try {
+        void Promise.resolve(this.client.setWindow(group.base, [])).catch(
+          () => undefined,
+        );
+      } catch {
+        // Same teardown race, surfaced synchronously.
+      }
     }
     this.#windowClaims.clear();
   }

package/src/realtime-supervisor.ts

@@ -53,8 +53,18 @@ export interface RealtimeSupervisorSnapshot {
 export interface RealtimeSupervisorOptions {
   /** Host online/offline evidence. Unknown remains connectable and observable. */
   readonly connectivity?: RealtimeSupervisorSignal<ClientDiagnosticsConnectivity>;
-  /** Browser/native foreground evidence. Background always suspends the socket. */
+  /** Browser/native foreground evidence. Background suspends a tab-owned
+   * socket; with `sharedTransport` it only serves as a resume nudge. */
   readonly lifecycle?: RealtimeSupervisorSignal<RealtimeSupervisorLifecycleState>;
+  /**
+   * The client's realtime transport is shared with sibling tabs or webviews
+   * (multi-tab handles proxying to one leader socket, native cores behind
+   * several views). Backgrounding THIS view then keeps the socket open,
+   * because a sibling may still be visible and a follower's disconnect would
+   * tear down realtime for everyone. Offline and protection evidence still
+   * suspend.
+   */
+  readonly sharedTransport?: boolean;
   /** Publish preflight before draining keys so reconnect stops in the same turn. */
   readonly protection?: RealtimeSupervisorSignal<RealtimeSupervisorProtectionState>;
   /** Deterministic test/host timer seam. */
@@ -215,6 +225,7 @@ export class RealtimeSupervisor {
   readonly #connectivity?: RealtimeSupervisorOptions['connectivity'];
   readonly #lifecycle?: RealtimeSupervisorOptions['lifecycle'];
   readonly #protection?: RealtimeSupervisorOptions['protection'];
+  readonly #sharedTransport: boolean;
   readonly #scheduleTimer: NonNullable<RealtimeSupervisorOptions['schedule']>;
   readonly #random: () => number;
   readonly #initialDelayMs: number;
@@ -247,6 +258,7 @@ export class RealtimeSupervisor {
     this.#connectivity = options.connectivity;
     this.#lifecycle = options.lifecycle;
     this.#protection = options.protection;
+    this.#sharedTransport = options.sharedTransport === true;
     this.#scheduleTimer = options.schedule ?? scheduleTimer;
     this.#random = options.random ?? Math.random;
     this.#initialDelayMs = boundedDelay(
@@ -304,6 +316,7 @@ export class RealtimeSupervisor {
     this.#unsubscribeLifecycle?.();
     this.#unsubscribeProtection?.();
     this.#publish({ phase: 'stopped', attempt: 0 });
+    this.#listeners.clear();
     if (disconnect) this.#disconnect();
   }
 
@@ -336,7 +349,9 @@ export class RealtimeSupervisor {
     ) {
       return 'offline';
     }
-    if (this.#lifecycle?.current() === 'background') return 'background';
+    if (!this.#sharedTransport && this.#lifecycle?.current() === 'background') {
+      return 'background';
+    }
     return undefined;
   }
 
@@ -410,43 +425,77 @@ export class RealtimeSupervisor {
       this.#reconcileHostState();
       return;
     }
+    // Count an attempt only when this call actually schedules one. Repeated
+    // 'disconnected' diagnostics beside a pending retry keep the backoff and
+    // the worker-mode reconnect nudge intact.
+    if (
+      this.#connected ||
+      this.#connecting ||
+      this.#cancelRetry !== undefined
+    ) {
+      return;
+    }
     const delay = this.#retryDelay();
     this.#attempt = Math.min(32, this.#attempt + 1);
     this.#schedule(delay);
   }
 
+  /**
+   * A superseded attempt observed a generation bump mid-flight. Whenever a
+   * newer generation is mid-connect or holds the transport, that generation
+   * owns the shared socket and the stale attempt leaves every field alone.
+   * With the supervisor otherwise quiescent (suspended or stopped), the
+   * socket this attempt opened is unwanted — release it.
+   */
+  #releaseSupersededSocket(): void {
+    if (this.#connecting || this.#connected || this.#transportConnected) {
+      return;
+    }
+    this.#disconnect();
+  }
+
   async #connect(): Promise<void> {
     if (!this.#canConnect() || this.#connected || this.#connecting) return;
+    const generation = this.#generation;
     this.#connecting = true;
     this.#publish({ phase: 'connecting', attempt: this.#attempt });
-    const generation = this.#generation;
     let failed = false;
     try {
       await this.#client.connectRealtime();
+      if (generation !== this.#generation) {
+        this.#releaseSupersededSocket();
+        return;
+      }
       this.#transportConnected = true;
-      if (generation !== this.#generation || !this.#canConnect()) {
+      if (!this.#canConnect()) {
+        this.#transportConnected = false;
         this.#disconnect();
         return;
       }
       await this.#catchUpConnectedTransport(generation);
     } catch {
+      if (generation !== this.#generation) {
+        this.#releaseSupersededSocket();
+        return;
+      }
       failed = true;
       this.#connected = false;
       this.#transportConnected = false;
       this.#disconnect();
     } finally {
-      this.#connecting = false;
+      // A superseded attempt leaves the successor's in-flight state alone.
+      if (generation === this.#generation) this.#connecting = false;
     }
     if (failed && generation === this.#generation) this.#scheduleRetry();
   }
 
   async #catchUpConnectedTransport(generation: number): Promise<void> {
     await this.#client.syncUntilIdle();
-    if (
-      generation !== this.#generation ||
-      !this.#canConnect() ||
-      !this.#transportConnected
-    ) {
+    if (generation !== this.#generation) {
+      this.#releaseSupersededSocket();
+      return;
+    }
+    if (!this.#canConnect() || !this.#transportConnected) {
       this.#disconnect();
       return;
     }
@@ -459,20 +508,25 @@ export class RealtimeSupervisor {
     if (!this.#canConnect() || this.#connecting || !this.#transportConnected) {
       return;
     }
+    const generation = this.#generation;
     this.#connecting = true;
     this.#clearRetry();
     this.#publish({ phase: 'connecting', attempt: this.#attempt });
-    const generation = this.#generation;
     let failed = false;
     try {
       await this.#catchUpConnectedTransport(generation);
     } catch {
+      if (generation !== this.#generation) {
+        this.#releaseSupersededSocket();
+        return;
+      }
       failed = true;
       this.#connected = false;
       this.#transportConnected = false;
       this.#disconnect();
     } finally {
-      this.#connecting = false;
+      // A superseded adoption leaves the successor's in-flight state alone.
+      if (generation === this.#generation) this.#connecting = false;
     }
     if (failed && generation === this.#generation) this.#scheduleRetry();
   }
@@ -497,8 +551,13 @@ export class RealtimeSupervisor {
       if (disconnect) this.#disconnect();
       return;
     }
-    if (!this.#realtimeSupported) return;
-    this.#realtimeSupported = true;
+    if (!this.#realtimeSupported) {
+      // A live socket is positive evidence the earlier 'unsupported' report
+      // was transient (a mid-restart or mis-detected capability probe), so it
+      // recovers the supervisor. Every other report keeps the latch closed.
+      if (snapshot.host.realtime !== 'connected') return;
+      this.#realtimeSupported = true;
+    }
     const block = this.#hostBlock();
     if (block) {
       this.#suspend(block);
@@ -506,8 +565,10 @@ export class RealtimeSupervisor {
     }
     if (snapshot.host.realtime === 'connected') {
       this.#transportConnected = true;
-      if (this.#connecting) return;
-      this.#connected = false;
+      // Steady state: diagnostics re-announce 'connected' on every sync
+      // round and subscription change. An already-adopted transport keeps
+      // its phase and skips the redundant catch-up.
+      if (this.#connecting || this.#connected) return;
       void this.#adoptConnectedTransport();
       return;
     }
@@ -566,12 +627,22 @@ export class RealtimeSupervisor {
   }
 }
 
-/** Install one supervisor and make client disposal cancel it before close. */
+/**
+ * Install one supervisor and make client disposal cancel it before close.
+ * A client accepts exactly one supervisor for its lifetime; installing a
+ * second throws, because silently keeping the first would discard the second
+ * call's options.
+ */
 export function installRealtimeSupervisor<T extends RealtimeSupervisorClient>(
   client: T,
   options?: RealtimeSupervisorOptions,
 ): T {
-  if (attachment(client)) return client;
+  if (attachment(client)) {
+    throw new Error(
+      'installRealtimeSupervisor: this client already has a supervisor; ' +
+        'install one supervisor per client lifetime',
+    );
+  }
   const supervisor = new RealtimeSupervisor(client, options);
   Object.defineProperty(client, REALTIME_SUPERVISOR_KEY, {
     configurable: false,