@syncular/client 0.29.1 → 0.30.1

package/dist/reactive-store.js

@@ -1,4 +1,4 @@
-import { classifySyncAvailability, } from './availability.js';
+import { blockedLeadershipAvailability, classifySyncAvailability, } from './availability.js';
 import { ClientSyncError, SyncRoundFailedError } from './errors.js';
 import { windowBaseKey } from './window.js';
 function errorOf(value) {
@@ -233,6 +233,10 @@ class ObservationCache {
         for (const entry of this.#active)
             entry.onChange(batch);
     }
+    onLeaderServing() {
+        for (const entry of this.#active)
+            entry.onLeaderServing?.();
+    }
     clear() {
         for (const entry of this.#entries.values())
             entry.dispose();
@@ -301,47 +305,7 @@ class QueryEntry {
             this.#offStatus = this.store.status.subscribe(() => this.#onAvailabilityChange());
             this.#offRound = this.store.roundFailure.subscribe(() => this.#onRoundFailureChange());
             this.#onAvailabilityChange();
-            if (this.spec.claimCoverage !== false) {
-                const claims = [];
-                // A composed spec carries one coverage entry per query branch, and
-                // several branches can target the same base. One claim per distinct
-                // base covers the union of their units; a later entry for the same
-                // base does not replace the earlier one.
-                const unitsByBase = new Map();
-                for (const coverage of this.spec.coverage ?? []) {
-                    const baseKey = windowBaseKey(coverage.base);
-                    const existing = unitsByBase.get(baseKey);
-                    if (existing === undefined) {
-                        unitsByBase.set(baseKey, {
-                            base: coverage.base,
-                            units: new Set(coverage.units),
-                        });
-                    }
-                    else {
-                        for (const unit of coverage.units)
-                            existing.units.add(unit);
-                    }
-                }
-                for (const { base, units } of unitsByBase.values()) {
-                    claims.push(this.store.setWindowClaim(this.#owner, base, [...units]));
-                }
-                const generation = this.#generation;
-                this.#claimPending = claims.length > 0;
-                if (claims.length > 0)
-                    void Promise.all(claims).then(() => {
-                        if (generation !== this.#generation || this.#listeners.size === 0)
-                            return;
-                        this.#claimPending = false;
-                        if (!this.#running && this.#state.phase !== 'ready')
-                            this.#requestRead();
-                    }, (error) => {
-                        if (generation !== this.#generation || this.#listeners.size === 0)
-                            return;
-                        this.#claimPending = false;
-                        this.#claimError = errorOf(error);
-                        this.#requestRead();
-                    });
-            }
+            this.#claimCoverage();
             this.#requestRead();
         }
         return () => {
@@ -357,6 +321,50 @@ class QueryEntry {
             }
         };
     };
+    /** Claim this query's window coverage; a failure surfaces on the next read. */
+    #claimCoverage() {
+        if (this.spec.claimCoverage === false)
+            return;
+        const claims = [];
+        // A composed spec carries one coverage entry per query branch, and
+        // several branches can target the same base. One claim per distinct
+        // base covers the union of their units; a later entry for the same
+        // base does not replace the earlier one.
+        const unitsByBase = new Map();
+        for (const coverage of this.spec.coverage ?? []) {
+            const baseKey = windowBaseKey(coverage.base);
+            const existing = unitsByBase.get(baseKey);
+            if (existing === undefined) {
+                unitsByBase.set(baseKey, {
+                    base: coverage.base,
+                    units: new Set(coverage.units),
+                });
+            }
+            else {
+                for (const unit of coverage.units)
+                    existing.units.add(unit);
+            }
+        }
+        for (const { base, units } of unitsByBase.values()) {
+            claims.push(this.store.setWindowClaim(this.#owner, base, [...units]));
+        }
+        const generation = this.#generation;
+        this.#claimPending = claims.length > 0;
+        if (claims.length > 0)
+            void Promise.all(claims).then(() => {
+                if (generation !== this.#generation || this.#listeners.size === 0)
+                    return;
+                this.#claimPending = false;
+                if (!this.#running && this.#state.phase !== 'ready')
+                    this.#requestRead();
+            }, (error) => {
+                if (generation !== this.#generation || this.#listeners.size === 0)
+                    return;
+                this.#claimPending = false;
+                this.#claimError = errorOf(error);
+                this.#requestRead();
+            });
+    }
     refresh = () => {
         if (this.#delegate !== undefined)
             this.#delegate.refresh();
@@ -382,6 +390,15 @@ class QueryEntry {
         this.store.releaseWindowClaims(this.#owner);
         this.reset();
     }
+    /** A claim rejected while no leader served this tab (blocked, handover,
+     * another build) is claimed again; its stored error would fail every read. */
+    onLeaderServing() {
+        if (this.#delegate !== undefined || this.#claimError === undefined)
+            return;
+        this.#claimError = undefined;
+        this.#claimCoverage();
+        this.#requestRead();
+    }
     onChange(batch) {
         if (!batchMatches(batch, this.spec))
             return;
@@ -811,12 +828,7 @@ export class ReactiveClientStore {
         const snapshot = this.status.getSnapshot();
         if (snapshot.status === undefined) {
             return snapshot.leadership?.state === 'blocked'
-                ? {
-                    state: 'blocked',
-                    reason: 'leader-unreachable',
-                    currentSchemaVersion: this.client.currentSchemaVersion ?? 0,
-                    retryable: true,
-                }
+                ? blockedLeadershipAvailability(snapshot.leadership, this.client.currentSchemaVersion ?? 0)
                 : { state: 'ready' };
         }
         return classifySyncAvailability(snapshot.status, snapshot.leadership);
@@ -990,6 +1002,15 @@ export class ReactiveClientStore {
             });
             if (previous.isLoading)
                 this.status.refresh();
+            // Window edits that failed while no leader served this tab apply now;
+            // an applied group compares equal and makes no call.
+            if (leadership.state === 'leader' || leadership.state === 'follower') {
+                for (const group of this.#windowClaims.values()) {
+                    if (group.claims.size > 0)
+                        this.#scheduleWindow(group);
+                }
+                this.#queries.onLeaderServing();
+            }
         });
         this.status.refresh();
         this.conflicts.refresh();

package/dist/worker-host.d.ts

@@ -190,6 +190,12 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
     get __isClosed(): boolean;
     /** @internal — swap this handle from follower to leader (promotion). */
     __becomeLeader(core: LeaderCore): void;
+    /**
+     * @internal — a newer tab asked for the database: close the core and
+     * release the lock so that tab promotes. This tab stays blocked until it
+     * reloads with the newer build.
+     */
+    __yieldToNewerTab(): void;
     /** @internal — apply a follower reachability snapshot in place. */
     __setLeadership(state: LeadershipState): void;
     /** @internal — dispatch a worker/relayed event to handle-local listeners. */

package/dist/worker-host.js

@@ -5,7 +5,7 @@ import { ClientSyncError } from './errors.js';
 import { ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
 import { singleOwnerLock, webLocksLeaderLock, } from './leader-lock.js';
 import { decodeLocalDataRebootstrapResult, } from './local-rebootstrap.js';
-import { broadcastChannelFactory, FollowerLink, LeaderBridge, multiTabChannelName, newTabId, } from './multi-tab.js';
+import { broadcastChannelFactory, FollowerLink, LEADER_INCOMPATIBLE_CODE, LeaderBridge, MULTI_TAB_PROTOCOL_VERSION, multiTabChannelName, newTabId, } from './multi-tab.js';
 import { decodePreviousVersionAuditResult, decodePreviousVersionDiscardResult, decodePreviousVersionSnapshot, } from './previous-version.js';
 import { NOT_LEADER_CODE, WORKER_FAILED_CODE, WORKER_RESTART_REQUIRED_CODE, } from './worker-protocol.js';
 const WORKER_BUNDLE_LOAD_FAILURE = /(?:failed to fetch dynamically imported module|error loading dynamically imported module|importing a module script failed|failed to load module script)/iu;
@@ -128,7 +128,8 @@ export class SyncClientHandle {
     }
     /** @internal — swap this handle from follower to leader (promotion). */
     __becomeLeader(core) {
-        this.#follower?.close();
+        // Calls queued for the next leader run on this tab's own core.
+        this.#follower?.handOver(core.invoke);
         this.#follower = undefined;
         this.#core = core;
         this.#clientId = core.clientId;
@@ -143,6 +144,34 @@ export class SyncClientHandle {
             }
         }
     }
+    /**
+     * @internal — a newer tab asked for the database: close the core and
+     * release the lock so that tab promotes. This tab stays blocked until it
+     * reloads with the newer build.
+     */
+    __yieldToNewerTab() {
+        const core = this.#core;
+        if (core === undefined)
+            return;
+        this.#core = undefined;
+        this.#role = 'follower';
+        this.__setLeadership({
+            state: 'blocked',
+            reason: 'leader-incompatible',
+            code: LEADER_INCOMPATIBLE_CODE,
+            leader: 'newer',
+            retryable: true,
+        });
+        for (const listener of this.#roleListeners) {
+            try {
+                listener('follower');
+            }
+            catch {
+                /* a UI listener must never break the handover */
+            }
+        }
+        void core.close(true);
+    }
     /** @internal — apply a follower reachability snapshot in place. */
     __setLeadership(state) {
         this.#leadership = state;
@@ -234,6 +263,10 @@ export class SyncClientHandle {
         if (this.#closed) {
             return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'the handle is closed'));
         }
+        if (this.#leadership.state === 'blocked' &&
+            this.#leadership.reason === 'leader-incompatible') {
+            return Promise.reject(new ClientSyncError(LEADER_INCOMPATIBLE_CODE, 'the tab that owns the database runs a different protocol or schema version', true));
+        }
         if (this.#role === 'follower') {
             if (this.#follower === undefined) {
                 return Promise.reject(new ClientSyncError(NOT_LEADER_CODE, 'this tab is not the leader — another tab owns the syncular ' +
@@ -621,6 +654,8 @@ async function bootLeader(config, lockName, lease, parts) {
         fireConfigCallbacks(config, event);
         handleRef.handle?.__dispatchEvent(event);
     };
+    // A newer tab may say hello before the handle exists; yield once it does.
+    let newerTab = false;
     const makeBridge = config.multiTab !== false
         ? (clientId, invoke) => {
             const factory = config.channelFactory ?? broadcastChannelFactory();
@@ -629,7 +664,12 @@ async function bootLeader(config, lockName, lease, parts) {
                 channel,
                 epoch: parts.epoch ?? 0,
                 clientId,
+                identity: tabIdentity(config),
                 invoke,
+                onNewerTab: () => {
+                    newerTab = true;
+                    handleRef.handle?.__yieldToNewerTab();
+                },
             });
         }
         : undefined;
@@ -653,8 +693,16 @@ async function bootLeader(config, lockName, lease, parts) {
         leadershipListeners: parts.leadershipListeners,
     });
     handleRef.handle = handle;
+    if (newerTab)
+        handle.__yieldToNewerTab();
     return handle;
 }
+function tabIdentity(config) {
+    return {
+        protocol: MULTI_TAB_PROTOCOL_VERSION,
+        schemaVersion: config.schema.version,
+    };
+}
 /**
  * Boot a follower: open the channel, bind to the leader, and race the lock in
  * the background so this tab promotes itself the instant the leader closes.
@@ -668,6 +716,7 @@ async function bootFollower(config, lockName, lock, parts) {
     const follower = new FollowerLink({
         channel,
         fromId: newTabId(),
+        identity: tabIdentity(config),
         onEvent: (event) => handleRef.handle?.__dispatchEvent(event),
         onLeaderChange: (clientId) => {
             // Learn the leader's shared client id (best-effort; the handle exposes
@@ -702,6 +751,8 @@ async function bootFollower(config, lockName, lock, parts) {
         const nextEpoch = follower.maxEpochSeen + 1;
         // Unbind the link so any late leader traffic is ignored, then promote.
         follower.unbind();
+        // A newer tab may say hello before this core is installed.
+        let newerTab = false;
         try {
             const core = await startWorkerCore({
                 config,
@@ -719,7 +770,12 @@ async function bootFollower(config, lockName, lock, parts) {
                                 channel: promoteChannel,
                                 epoch: nextEpoch,
                                 clientId,
+                                identity: tabIdentity(config),
                                 invoke,
+                                onNewerTab: () => {
+                                    newerTab = true;
+                                    handle.__yieldToNewerTab();
+                                },
                             });
                         },
                     }
@@ -733,6 +789,8 @@ async function bootFollower(config, lockName, lock, parts) {
                 return;
             }
             handle.__becomeLeader(core);
+            if (newerTab)
+                handle.__yieldToNewerTab();
         }
         catch {
             // Promotion failed to spawn a worker — release so the next tab tries.
@@ -775,7 +833,15 @@ async function bootFollower(config, lockName, lock, parts) {
     // the shared origin replica behind the same barrier before it is returned;
     // otherwise an already-running leader would silently ignore the request.
     if (config.securityPreflight === true) {
-        await handle.beginSecurityPreflight();
+        try {
+            await handle.beginSecurityPreflight();
+        }
+        catch (error) {
+            // The caller never receives this handle, so it must not stay queued for
+            // the lock and promote into a database nobody holds.
+            await handle.close();
+            throw error;
+        }
     }
     return handle;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.29.1",
+  "version": "0.30.1",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.29.1"
+    "@syncular/core": "0.30.1"
   },
   "devDependencies": {
-    "@syncular/server": "0.29.1",
+    "@syncular/server": "0.30.1",
     "playwright": "1.63.0"
   }
 }

package/src/availability.ts

@@ -10,13 +10,38 @@ export type SyncAvailability =
         | 'client-upgrade-required'
         | 'server-behind'
         | 'incompatible-schema'
-        | 'leader-unreachable';
+        | 'leader-unreachable'
+        | 'leader-incompatible';
       readonly currentSchemaVersion: number;
+      /** `leader-incompatible`: whether the tab holding the database runs an
+       * older or a newer build than this one. */
+      readonly leader?: 'older' | 'newer';
       readonly requiredSchemaVersion?: number;
       readonly latestServerSchemaVersion?: number;
       readonly retryable: boolean;
     };
 
+/** The availability of a tab whose leader link is blocked. */
+export function blockedLeadershipAvailability(
+  leadership: Extract<LeadershipState, { state: 'blocked' }>,
+  currentSchemaVersion: number,
+): SyncAvailability {
+  return leadership.reason === 'leader-incompatible'
+    ? {
+        state: 'blocked',
+        reason: 'leader-incompatible',
+        currentSchemaVersion,
+        leader: leadership.leader,
+        retryable: true,
+      }
+    : {
+        state: 'blocked',
+        reason: 'leader-unreachable',
+        currentSchemaVersion,
+        retryable: true,
+      };
+}
+
 /** Classify schema and browser-ownership state without parsing diagnostics. */
 export function classifySyncAvailability(
   status: SyncStatusSnapshot,
@@ -24,12 +49,7 @@ export function classifySyncAvailability(
 ): SyncAvailability {
   const currentSchemaVersion = status.currentSchemaVersion;
   if (leadership?.state === 'blocked') {
-    return {
-      state: 'blocked',
-      reason: 'leader-unreachable',
-      currentSchemaVersion,
-      retryable: true,
-    };
+    return blockedLeadershipAvailability(leadership, currentSchemaVersion);
   }
   const required = status.schemaFloor?.requiredSchemaVersion;
   const latest = status.schemaFloor?.latestSchemaVersion;