@syncular/client 0.49.1 → 0.50.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -252,7 +252,24 @@ worker still holds the OPFS database and may be mid-commit, so a transfer
252
252
  needs a cooperative close-and-release handshake, and every focus change
253
253
  between tabs would restart the worker, reopen the database, and reconnect the
254
254
  realtime socket. A hidden leader answers its followers from its message
255
- handler, so leadership moves only when the leader tab closes.
255
+ handler, so leadership moves only when the leader tab closes, or when the
256
+ user takes over from an unresponsive one.
257
+
258
+ **Taking over from an unresponsive leader.** A leader whose main thread runs
259
+ no task (a frozen background tab, a hung window) blocks its followers with
260
+ `leader-unreachable`. Once that has lasted `takeOverAfterMs` (default twice
261
+ `followerCallTimeoutMs`), `handle.takeOver()`, called from a user action, steals
262
+ the leader's Web Lock, starts the worker in this tab on a higher epoch, and
263
+ steals the old worker's OPFS storage lock. OPFS sync access handles are
264
+ exclusive, so the new worker opens the database only after the old one closed
265
+ it. The old worker's database refuses every statement once its storage lock is
266
+ gone (`client.storage_fenced`) and closes its handles, and the old tab becomes
267
+ `blocked` with reason `leadership-taken` when it runs again. `takeOver()`
268
+ rejects with `client.takeover_refused` (`details.reason`: `not-unreachable`,
269
+ `too-early`, `in-progress`, `unsupported`) and with `client.storage_busy` while a
270
+ frozen worker still holds the files. `onLeaderUnreachable` reports the start of
271
+ each unreachable period with `takeOverAt`, and its end with `durationMs` and
272
+ the outcome.
256
273
 
257
274
  **Presence semantics — one device, one peer.** All tabs share the leader's
258
275
  single connection, so a device is exactly ONE presence peer collectively:
@@ -7,7 +7,7 @@ export type SyncAvailability = {
7
7
  readonly currentSchemaVersion: number;
8
8
  } | {
9
9
  readonly state: 'blocked';
10
- readonly reason: 'client-upgrade-required' | 'server-behind' | 'incompatible-schema' | 'leader-unreachable' | 'leader-incompatible';
10
+ readonly reason: 'client-upgrade-required' | 'server-behind' | 'incompatible-schema' | 'leader-unreachable' | 'leader-incompatible' | 'leadership-taken';
11
11
  readonly currentSchemaVersion: number;
12
12
  /** `leader-incompatible`: whether the tab holding the database runs an
13
13
  * older or a newer build than this one. */
@@ -10,7 +10,7 @@ export function blockedLeadershipAvailability(leadership, currentSchemaVersion)
10
10
  }
11
11
  : {
12
12
  state: 'blocked',
13
- reason: 'leader-unreachable',
13
+ reason: leadership.reason,
14
14
  currentSchemaVersion,
15
15
  retryable: true,
16
16
  };
package/dist/errors.d.ts CHANGED
@@ -1,6 +1,11 @@
1
1
  import type { RealtimeState } from './diagnostics.js';
2
2
  /** A persistent local store is temporarily owned by another live engine. */
3
3
  export declare const STORAGE_BUSY_CODE = "client.storage_busy";
4
+ /**
5
+ * Another tab took this engine's persistent store with `takeOver()`; the
6
+ * engine closed the store and refuses every further statement.
7
+ */
8
+ export declare const STORAGE_FENCED_CODE = "client.storage_fenced";
4
9
  /** The browser cannot provide the persistent storage APIs Syncular requires. */
5
10
  export declare const STORAGE_UNAVAILABLE_CODE = "client.storage_unavailable";
6
11
  /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
package/dist/errors.js CHANGED
@@ -1,5 +1,10 @@
1
1
  /** A persistent local store is temporarily owned by another live engine. */
2
2
  export const STORAGE_BUSY_CODE = 'client.storage_busy';
3
+ /**
4
+ * Another tab took this engine's persistent store with `takeOver()`; the
5
+ * engine closed the store and refuses every further statement.
6
+ */
7
+ export const STORAGE_FENCED_CODE = 'client.storage_fenced';
3
8
  /** The browser cannot provide the persistent storage APIs Syncular requires. */
4
9
  export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
5
10
  /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
@@ -1,11 +1,16 @@
1
1
  /**
2
2
  * Multi-tab ownership seam: exactly one core instance owns the
3
- * local database. The interface is the whole B3 deliverable — cross-tab
4
- * follower fanout is post-gate. Browsers use Web Locks; tests use the
5
- * no-op single-owner lock.
3
+ * local database. Browsers use Web Locks; tests use the no-op single-owner
4
+ * lock or an injected exclusive lock.
6
5
  */
7
6
  export interface LeaderLease {
8
7
  release(): void | Promise<void>;
8
+ /**
9
+ * Resolves when another context took this lease with
10
+ * {@link LeaderLock.steal}. The holder no longer owns the lock and must stop
11
+ * writing. Absent for locks that cannot be stolen.
12
+ */
13
+ readonly lost?: Promise<void>;
9
14
  }
10
15
  export interface LeaderLock {
11
16
  /** Resolves when this instance holds leadership for `name`. */
@@ -13,16 +18,22 @@ export interface LeaderLock {
13
18
  /**
14
19
  * Resolves immediately: the lease when leadership was free, `undefined`
15
20
  * when another owner holds it. The worker handle uses this so a second
16
- * tab gets a clear not-leader state instead of blocking forever
17
- * (followers are post-gate).
21
+ * tab gets a clear not-leader state instead of blocking forever.
18
22
  */
19
23
  tryAcquire?(name: string): Promise<LeaderLease | undefined>;
24
+ /**
25
+ * Takes `name` from its current holder at once; the holder's lease reports
26
+ * `lost`. Waiting requests stay queued behind the new holder.
27
+ */
28
+ steal?(name: string): Promise<LeaderLease>;
20
29
  }
21
30
  /** Single-owner environments (tests, dedicated workers): always leader. */
22
31
  export declare function singleOwnerLock(): LeaderLock;
23
32
  /**
24
33
  * Web Locks leader election: resolves once the exclusive lock is granted
25
34
  * and holds it until the lease is released (tab close releases it
26
- * implicitly, letting the next tab take over).
35
+ * implicitly, letting the next tab take over). A `steal` from another
36
+ * context rejects the holder's request with `AbortError`, which resolves the
37
+ * holder's `lost`.
27
38
  */
28
- export declare function webLocksLeaderLock(locks?: LockManager): LeaderLock;
39
+ export declare function webLocksLeaderLock(locks?: LockManager): Required<LeaderLock>;
@@ -8,31 +8,49 @@ export function singleOwnerLock() {
8
8
  /**
9
9
  * Web Locks leader election: resolves once the exclusive lock is granted
10
10
  * and holds it until the lease is released (tab close releases it
11
- * implicitly, letting the next tab take over).
11
+ * implicitly, letting the next tab take over). A `steal` from another
12
+ * context rejects the holder's request with `AbortError`, which resolves the
13
+ * holder's `lost`.
12
14
  */
13
15
  export function webLocksLeaderLock(locks) {
14
16
  const manager = locks ?? navigator.locks;
17
+ const request = (name, options) => new Promise((resolveRequest, rejectRequest) => {
18
+ let granted = false;
19
+ let markLost = () => { };
20
+ const lost = new Promise((resolve) => {
21
+ markLost = resolve;
22
+ });
23
+ manager
24
+ .request(name, options, (lock) => {
25
+ // `ifAvailable` grants `null` instead of waiting (Web Locks).
26
+ if (lock === null) {
27
+ resolveRequest(undefined);
28
+ return undefined;
29
+ }
30
+ granted = true;
31
+ return new Promise((resolveHold) => {
32
+ resolveRequest({ release: () => resolveHold(), lost });
33
+ });
34
+ })
35
+ .catch((error) => {
36
+ if (granted &&
37
+ error instanceof DOMException &&
38
+ error.name === 'AbortError') {
39
+ markLost();
40
+ return;
41
+ }
42
+ rejectRequest(error);
43
+ });
44
+ });
45
+ const held = async (name, options) => {
46
+ const lease = await request(name, options);
47
+ if (lease === undefined)
48
+ throw new Error('a waiting lock request returned no lock');
49
+ return lease;
50
+ };
15
51
  return {
16
- acquire: (name) => new Promise((resolveAcquire, rejectAcquire) => {
17
- manager
18
- .request(name, { mode: 'exclusive' }, () => new Promise((resolveHold) => {
19
- resolveAcquire({ release: () => resolveHold() });
20
- }))
21
- .catch((error) => rejectAcquire(error));
22
- }),
23
- tryAcquire: (name) => new Promise((resolveTry, rejectTry) => {
24
- manager
25
- .request(name, { mode: 'exclusive', ifAvailable: true }, (lock) => {
26
- // `ifAvailable` grants `null` instead of waiting (Web Locks).
27
- if (lock === null) {
28
- resolveTry(undefined);
29
- return undefined;
30
- }
31
- return new Promise((resolveHold) => {
32
- resolveTry({ release: () => resolveHold() });
33
- });
34
- })
35
- .catch((error) => rejectTry(error));
36
- }),
52
+ acquire: (name) => held(name, { mode: 'exclusive' }),
53
+ tryAcquire: (name) => request(name, { mode: 'exclusive', ifAvailable: true }),
54
+ steal: (name) => held(name, { mode: 'exclusive', steal: true }),
37
55
  };
38
56
  }
@@ -6,6 +6,10 @@ export declare const FOLLOWER_TIMEOUT_CODE = "client.follower_timeout";
6
6
  export declare const LEADER_INCOMPATIBLE_CODE = "client.leader_incompatible";
7
7
  /** Client-local: the leader that received a call stopped leading before it answered. */
8
8
  export declare const LEADER_HANDOVER_CODE = "client.leader_handover";
9
+ /** Client-local: another tab took this tab's leadership with `takeOver()`. */
10
+ export declare const LEADERSHIP_TAKEN_CODE = "client.leadership_taken";
11
+ /** Client-local: `takeOver()` was called while its conditions do not hold. */
12
+ export declare const TAKEOVER_REFUSED_CODE = "client.takeover_refused";
9
13
  /**
10
14
  * Version of the leader/follower wire and the forwarded handle API. Bump it
11
15
  * with every change to a message shape or to a forwarded method's arguments
@@ -51,6 +55,11 @@ export type LeadershipState = {
51
55
  /** Whether the tab holding the database runs an older or a newer build. */
52
56
  readonly leader: 'older' | 'newer';
53
57
  readonly retryable: true;
58
+ } | {
59
+ readonly state: 'blocked';
60
+ readonly reason: 'leadership-taken';
61
+ readonly code: typeof LEADERSHIP_TAKEN_CODE;
62
+ readonly retryable: true;
54
63
  };
55
64
  /** Identity fields; absent in messages from tabs before protocol 1. */
56
65
  interface IdentityFields {
@@ -212,6 +221,13 @@ export interface TabLeaderContext<E> {
212
221
  readonly epoch: number;
213
222
  /** This tab's id. The leader's own calls arrive under it. */
214
223
  readonly tabId: string;
224
+ /**
225
+ * True when this tab took the lock from an unreachable leader with
226
+ * `takeOver()`. That leader's worker can still hold the database files;
227
+ * the core must take over its storage lock and retry opening until the
228
+ * old worker releases them.
229
+ */
230
+ readonly takeover: boolean;
215
231
  /**
216
232
  * The leader lock. The coordinator releases it after {@link TabLeader.close}
217
233
  * resolves. Release it earlier only when the core is already gone, such as a
@@ -235,9 +251,38 @@ export interface TabLeader {
235
251
  * lock.
236
252
  */
237
253
  tabClosed?(tabId: string): void;
238
- /** Stop the core. The coordinator releases the leader lock afterwards. */
254
+ /**
255
+ * Stop the core. The coordinator releases the leader lock afterwards. It
256
+ * also runs when another tab took the lock: the core must not write again.
257
+ */
239
258
  close(): Promise<void>;
240
259
  }
260
+ /**
261
+ * A follower's link to its leader went `leader-unreachable`, or left that
262
+ * state. Times are `clock.now()` milliseconds (wall-clock by default).
263
+ */
264
+ export type LeaderUnreachableEvent = {
265
+ readonly phase: 'started';
266
+ readonly at: number;
267
+ /** The earliest time `takeOver()` is allowed. */
268
+ readonly takeOverAt: number;
269
+ } | {
270
+ readonly phase: 'ended';
271
+ readonly at: number;
272
+ readonly durationMs: number;
273
+ /**
274
+ * `rebound`: the leader answered again. `promoted`: its lock passed to
275
+ * this tab. `taken-over`: this tab's `takeOver()` succeeded.
276
+ * `incompatible`: a leader of another build answered. `closed`: this
277
+ * tab closed first.
278
+ */
279
+ readonly outcome: 'rebound' | 'promoted' | 'taken-over' | 'incompatible' | 'closed';
280
+ };
281
+ /** Time source and timer seam; tests inject a manual clock. */
282
+ export interface TabClock {
283
+ now(): number;
284
+ schedule(callback: () => void, delayMs: number): () => void;
285
+ }
241
286
  export interface TabCoordinatorConfig<E> {
242
287
  /** Web Lock name of the leadership; the channel and tab locks derive from it. */
243
288
  readonly name: string;
@@ -252,11 +297,19 @@ export interface TabCoordinatorConfig<E> {
252
297
  /** Events the leader broadcast, or sent to this tab. */
253
298
  onEvent?(event: E): void;
254
299
  onStateChange?(state: LeadershipState): void;
300
+ /** Start and end of every `leader-unreachable` period, for host telemetry. */
301
+ onLeaderUnreachable?(event: LeaderUnreachableEvent): void;
255
302
  /** Defaults to Web Locks; tests inject a name-keyed exclusive lock. */
256
303
  readonly lock?: LeaderLock;
257
304
  readonly channelFactory?: (name: string) => CrossTabChannel<E>;
258
305
  /** Liveness and handover-queue deadline; defaults to 10 s. */
259
306
  readonly callTimeoutMs?: number;
307
+ /**
308
+ * How long a follower must have been `leader-unreachable` before
309
+ * `takeOver()` is allowed; defaults to twice `callTimeoutMs`.
310
+ */
311
+ readonly takeOverAfterMs?: number;
312
+ readonly clock?: TabClock;
260
313
  }
261
314
  /** One tab's end of the coordinator, the same in leader and follower tabs. */
262
315
  export interface TabCoordinator {
@@ -264,6 +317,15 @@ export interface TabCoordinator {
264
317
  readonly state: LeadershipState;
265
318
  /** Run a call on the leader's core, in this tab or over the channel. */
266
319
  call(method: string, args: readonly unknown[]): Promise<unknown>;
320
+ /**
321
+ * Take the lock from a leader that has been `leader-unreachable` for
322
+ * `takeOverAfterMs`, and start the core in this tab. The old leader reports
323
+ * `leadership-taken` and closes its core once it runs again. Rejects with
324
+ * `client.takeover_refused` (`details.reason`: `not-unreachable`,
325
+ * `too-early`, `in-progress` or `unsupported`) when the conditions do not
326
+ * hold, and with the core's start error when the core cannot start.
327
+ */
328
+ takeOver(): Promise<void>;
267
329
  /** Stop the core (leader) or the link (follower), and release this tab's locks. */
268
330
  close(): Promise<void>;
269
331
  }
package/dist/multi-tab.js CHANGED
@@ -73,6 +73,10 @@ export const FOLLOWER_TIMEOUT_CODE = 'client.follower_timeout';
73
73
  export const LEADER_INCOMPATIBLE_CODE = 'client.leader_incompatible';
74
74
  /** Client-local: the leader that received a call stopped leading before it answered. */
75
75
  export const LEADER_HANDOVER_CODE = 'client.leader_handover';
76
+ /** Client-local: another tab took this tab's leadership with `takeOver()`. */
77
+ export const LEADERSHIP_TAKEN_CODE = 'client.leadership_taken';
78
+ /** Client-local: `takeOver()` was called while its conditions do not hold. */
79
+ export const TAKEOVER_REFUSED_CODE = 'client.takeover_refused';
76
80
  /**
77
81
  * Version of the leader/follower wire and the forwarded handle API. Bump it
78
82
  * with every change to a message shape or to a forwarded method's arguments
@@ -678,6 +682,9 @@ export class FollowerLink {
678
682
  function tabLockName(name, tabId) {
679
683
  return `${name}:tab:${tabId}`;
680
684
  }
685
+ function takeOverRefused(reason, takeOverAt) {
686
+ return new ClientSyncError(TAKEOVER_REFUSED_CODE, 'takeOver() requires a leader that has been unreachable for takeOverAfterMs', reason === 'too-early' || reason === 'in-progress', { reason, ...(takeOverAt !== undefined ? { takeOverAt } : {}) });
687
+ }
681
688
  /**
682
689
  * Elect one leader tab per `name` and run `lead` there; every other tab
683
690
  * forwards its calls to that core and receives its events. When the leader
@@ -686,6 +693,15 @@ function tabLockName(name, tabId) {
686
693
  */
687
694
  export async function createTabCoordinator(config) {
688
695
  const lock = config.lock ?? webLocksLeaderLock();
696
+ const clock = config.clock ?? {
697
+ now: () => Date.now(),
698
+ schedule: (callback, delayMs) => {
699
+ const timer = setTimeout(callback, delayMs);
700
+ return () => clearTimeout(timer);
701
+ },
702
+ };
703
+ const callTimeoutMs = config.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
704
+ const takeOverAfterMs = config.takeOverAfterMs ?? 2 * callTimeoutMs;
689
705
  const openChannel = config.channelFactory ?? broadcastChannelFactory();
690
706
  const channelName = multiTabChannelName(config.name);
691
707
  const identity = {
@@ -700,8 +716,45 @@ export async function createTabCoordinator(config) {
700
716
  let leading;
701
717
  let follower;
702
718
  let closed = false;
719
+ let takingOver = false;
720
+ /** Start of the current `leader-unreachable` period. */
721
+ let unreachableSince;
722
+ const report = (event) => {
723
+ try {
724
+ config.onLeaderUnreachable?.(event);
725
+ }
726
+ catch {
727
+ // A telemetry listener must never break cross-tab coordination.
728
+ }
729
+ };
730
+ const endUnreachable = (outcome) => {
731
+ if (unreachableSince === undefined)
732
+ return;
733
+ const at = clock.now();
734
+ report({ phase: 'ended', at, durationMs: at - unreachableSince, outcome });
735
+ unreachableSince = undefined;
736
+ };
703
737
  const setState = (next) => {
704
738
  state = next;
739
+ if (next.state === 'blocked' && next.reason === 'leader-unreachable') {
740
+ if (unreachableSince === undefined) {
741
+ unreachableSince = clock.now();
742
+ report({
743
+ phase: 'started',
744
+ at: unreachableSince,
745
+ takeOverAt: unreachableSince + takeOverAfterMs,
746
+ });
747
+ }
748
+ }
749
+ else if (next.state === 'follower') {
750
+ endUnreachable('rebound');
751
+ }
752
+ else if (next.state === 'leader') {
753
+ endUnreachable(takingOver ? 'taken-over' : 'promoted');
754
+ }
755
+ else if (next.state === 'blocked') {
756
+ endUnreachable('incompatible');
757
+ }
705
758
  try {
706
759
  config.onStateChange?.(next);
707
760
  }
@@ -711,12 +764,27 @@ export async function createTabCoordinator(config) {
711
764
  };
712
765
  // Held until close: a leader waits on it to learn this tab is gone.
713
766
  const tabLease = await lock.acquire(tabLockName(config.name, tabId));
714
- const lead = async (lease, epoch) => {
767
+ const lead = async (lease, epoch, takeover) => {
715
768
  let bridge;
716
769
  let current = true;
770
+ let stepDown;
771
+ let lostWhileStarting = false;
772
+ const taken = {
773
+ state: 'blocked',
774
+ reason: 'leadership-taken',
775
+ code: LEADERSHIP_TAKEN_CODE,
776
+ retryable: true,
777
+ };
778
+ void lease.lost?.then(() => {
779
+ if (stepDown !== undefined)
780
+ stepDown(taken);
781
+ else
782
+ lostWhileStarting = true;
783
+ });
717
784
  const leader = await config.lead({
718
785
  epoch,
719
786
  tabId,
787
+ takeover,
720
788
  lease,
721
789
  broadcast: (event) => {
722
790
  if (!current)
@@ -733,8 +801,9 @@ export async function createTabCoordinator(config) {
733
801
  bridge?.sendEvent(to, event);
734
802
  },
735
803
  });
736
- if (closed) {
737
- // Closed while the core was starting: nobody holds this tab any more.
804
+ if (closed || lostWhileStarting) {
805
+ // Closed while the core was starting, or another tab took the lock: a
806
+ // follower link, if any, binds to that tab's announcement.
738
807
  current = false;
739
808
  await leader.close();
740
809
  await lease.release();
@@ -749,6 +818,16 @@ export async function createTabCoordinator(config) {
749
818
  },
750
819
  };
751
820
  leading = ending;
821
+ stepDown = (next) => {
822
+ // Stop the core and release the lock; this tab stays blocked until it
823
+ // reloads.
824
+ if (leading !== ending)
825
+ return;
826
+ leading = undefined;
827
+ ending.end();
828
+ setState(next);
829
+ void leader.close().finally(() => lease.release());
830
+ };
752
831
  bridge = new LeaderBridge({
753
832
  channel: openChannel(channelName),
754
833
  epoch,
@@ -768,22 +847,14 @@ export async function createTabCoordinator(config) {
768
847
  },
769
848
  }
770
849
  : {}),
771
- onNewerTab: () => {
772
- // A newer build asked for the core: stop it and release the lock so
773
- // that tab promotes. This tab stays blocked until it reloads.
774
- if (leading !== ending)
775
- return;
776
- leading = undefined;
777
- ending.end();
778
- setState({
779
- state: 'blocked',
780
- reason: 'leader-incompatible',
781
- code: LEADER_INCOMPATIBLE_CODE,
782
- leader: 'newer',
783
- retryable: true,
784
- });
785
- void leader.close().finally(() => lease.release());
786
- },
850
+ // A newer build asked for the core.
851
+ onNewerTab: () => stepDown?.({
852
+ state: 'blocked',
853
+ reason: 'leader-incompatible',
854
+ code: LEADER_INCOMPATIBLE_CODE,
855
+ leader: 'newer',
856
+ retryable: true,
857
+ }),
787
858
  });
788
859
  // Calls queued for the next leader run on this tab's own core.
789
860
  follower?.handOver((method, args) => leader.call(tabId, method, args));
@@ -801,17 +872,64 @@ export async function createTabCoordinator(config) {
801
872
  }
802
873
  if (leading !== undefined)
803
874
  return leading.leader.call(tabId, method, args);
875
+ if (follower !== undefined)
876
+ return follower.call(method, args);
877
+ if (state.state === 'blocked' && state.reason === 'leadership-taken') {
878
+ return Promise.reject(new ClientSyncError(LEADERSHIP_TAKEN_CODE, 'another tab took over the core this tab ran', true));
879
+ }
804
880
  if (state.state === 'blocked' && state.reason === 'leader-incompatible') {
805
881
  return Promise.reject(new ClientSyncError(LEADER_INCOMPATIBLE_CODE, 'the tab that owns the database runs a different protocol or schema version', true));
806
882
  }
807
- if (follower !== undefined)
808
- return follower.call(method, args);
809
883
  return Promise.reject(new ClientSyncError(WORKER_FAILED_CODE, 'no core serves this tab'));
810
884
  },
885
+ takeOver: async () => {
886
+ if (closed) {
887
+ throw new ClientSyncError(WORKER_FAILED_CODE, 'the tab coordinator is closed');
888
+ }
889
+ const link = follower;
890
+ if (link === undefined ||
891
+ unreachableSince === undefined ||
892
+ state.state !== 'blocked' ||
893
+ state.reason !== 'leader-unreachable') {
894
+ throw takeOverRefused('not-unreachable');
895
+ }
896
+ if (takingOver)
897
+ throw takeOverRefused('in-progress');
898
+ const takeOverAt = unreachableSince + takeOverAfterMs;
899
+ if (clock.now() < takeOverAt)
900
+ throw takeOverRefused('too-early', takeOverAt);
901
+ if (lock.steal === undefined)
902
+ throw takeOverRefused('unsupported');
903
+ takingOver = true;
904
+ try {
905
+ const lease = await lock.steal(config.name);
906
+ if (closed) {
907
+ await lease.release();
908
+ return;
909
+ }
910
+ try {
911
+ // Exceed every epoch this tab saw, so the old leader's late replies
912
+ // and events are discarded everywhere.
913
+ await lead(lease, link.maxEpochSeen + 1, true);
914
+ }
915
+ catch (error) {
916
+ await lease.release();
917
+ throw error;
918
+ }
919
+ if (!closed && leading === undefined) {
920
+ // A third tab took the lock while this tab's core was starting.
921
+ throw new ClientSyncError(LEADERSHIP_TAKEN_CODE, 'another tab took over the core this tab ran', true);
922
+ }
923
+ }
924
+ finally {
925
+ takingOver = false;
926
+ }
927
+ },
811
928
  close: async () => {
812
929
  if (closed)
813
930
  return;
814
931
  closed = true;
932
+ endUnreachable('closed');
815
933
  follower?.close();
816
934
  follower = undefined;
817
935
  const ending = leading;
@@ -830,7 +948,7 @@ export async function createTabCoordinator(config) {
830
948
  : await lock.acquire(config.name);
831
949
  if (lease !== undefined) {
832
950
  try {
833
- await lead(lease, 0);
951
+ await lead(lease, 0, false);
834
952
  }
835
953
  catch (error) {
836
954
  await lease.release();
@@ -846,15 +964,16 @@ export async function createTabCoordinator(config) {
846
964
  onEvent: (event) => config.onEvent?.(event),
847
965
  onLeaderChange: () => { },
848
966
  onStateChange: setState,
849
- ...(config.callTimeoutMs !== undefined
850
- ? { callTimeoutMs: config.callTimeoutMs }
851
- : {}),
967
+ callTimeoutMs,
968
+ schedule: clock.schedule,
852
969
  });
853
970
  follower = link;
854
- // Granted only when the leader releases the lock (its tab closed).
971
+ // Granted only when the lock is released: the leader's tab closed, or this
972
+ // tab's own failed takeover let go of it.
855
973
  void lock.acquire(config.name).then(async (promoted) => {
856
- if (closed) {
857
- // Promoting a closed coordinator would hold the lock forever.
974
+ if (closed || follower !== link) {
975
+ // Closed, or this tab already leads through takeOver(): promoting would
976
+ // hold the lock forever.
858
977
  await promoted.release();
859
978
  return;
860
979
  }
@@ -863,7 +982,7 @@ export async function createTabCoordinator(config) {
863
982
  const epoch = link.maxEpochSeen + 1;
864
983
  link.unbind();
865
984
  try {
866
- await lead(promoted, epoch);
985
+ await lead(promoted, epoch, false);
867
986
  }
868
987
  catch {
869
988
  // The core failed to start: release so the next tab tries.
@@ -251,7 +251,8 @@ const unreadQuerySnapshots = new Map();
251
251
  function localReadsBlocked(availability) {
252
252
  return (availability.state === 'blocked' &&
253
253
  (availability.reason === 'leader-unreachable' ||
254
- availability.reason === 'leader-incompatible'));
254
+ availability.reason === 'leader-incompatible' ||
255
+ availability.reason === 'leadership-taken'));
255
256
  }
256
257
  /** One frozen snapshot per phase and availability for entries that have no
257
258
  * successful read, so switching between unread entries keeps the snapshot and
@@ -16,6 +16,12 @@ export interface PersistentWasmDatabaseOptions {
16
16
  readonly directory?: string;
17
17
  /** Initial SAH pool capacity (sqlite-wasm default: 6). */
18
18
  readonly initialCapacity?: number;
19
+ /**
20
+ * Take the storage lock from the worker that holds it, which fences that
21
+ * worker's database. Its SAHs stay held until it runs again, so the open
22
+ * fails with a retryable `client.storage_busy` until then.
23
+ */
24
+ readonly takeOver?: boolean;
19
25
  }
20
26
  /**
21
27
  * THE reload-persistent browser mode: a named database on OPFS via the