@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.210

package/src/services/tabs/broker.test.ts

@@ -0,0 +1,327 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { handleConnect, __resetBrokerForTests } from './tabs-broker-worker';
+import { fakeChannel, flush, FakePort } from './fake-ports.fixture';
+import type { BrokerToTabMessage, TabToBrokerMessage } from './protocol';
+
+/** A connected fake tab: records broker messages, exposes a send helper. */
+interface TestTab {
+  tabId: string;
+  received: { msg: BrokerToTabMessage; ports: FakePort[] }[];
+  send: (msg: TabToBrokerMessage) => void;
+  port: FakePort;
+  /** Messages of one type, newest last. */
+  ofType: <T extends BrokerToTabMessage['type']>(
+    t: T
+  ) => Extract<BrokerToTabMessage, { type: T }>[];
+}
+
+function connectTab(tabId: string, opts: { bucket?: string; fingerprint?: string } = {}): TestTab {
+  const { port1, port2 } = fakeChannel();
+  handleConnect(port1 as unknown as MessagePort);
+  const received: TestTab['received'] = [];
+  port2.onmessage = (ev) => received.push({ msg: ev.data, ports: ev.ports });
+  const tab: TestTab = {
+    tabId,
+    received,
+    port: port2,
+    send: (msg) => port2.postMessage(msg),
+    ofType: (t) => received.filter((r) => r.msg.type === t).map((r) => r.msg) as any,
+  };
+  tab.send({
+    type: 'hello',
+    tabId,
+    fingerprint: opts.fingerprint ?? 'fp-test',
+    bucketId: opts.bucket ?? 'anon',
+    visibility: 'visible',
+    heldLeadership: null,
+  });
+  return tab;
+}
+
+/** Complete the promotion handshake for whichever tab got become-leader. */
+async function ackLeadership(tab: TestTab, bucket = 'anon'): Promise<number> {
+  await flush();
+  const grants = tab.ofType('become-leader');
+  expect(grants.length).toBeGreaterThan(0);
+  const leadershipId = grants[grants.length - 1].leadershipId;
+  tab.send({ type: 'leader-ready', tabId: tab.tabId, bucketId: bucket, leadershipId });
+  await flush();
+  return leadershipId;
+}
+
+beforeEach(() => {
+  __resetBrokerForTests();
+  vi.useFakeTimers();
+});
+afterEach(() => {
+  __resetBrokerForTests();
+  vi.useRealTimers();
+});
+
+// The broker is the single arbiter of who owns the OPFS pool. These tests
+// drive it with fake ports exactly like real tabs would.
+describe('tabs broker: election', () => {
+  it('elects exactly one leader for the first tab and announces readiness', async () => {
+    const a = connectTab('tab-a');
+    await flush();
+    expect(a.ofType('broker-hello')).toHaveLength(1);
+    const id = await ackLeadership(a);
+    expect(a.ofType('leader-ready').map((m) => m.leaderTabId)).toContain('tab-a');
+    expect(id).toBeGreaterThan(0);
+  });
+
+  it('attaches a second tab as follower with a db+sync port pair', async () => {
+    const a = connectTab('tab-a');
+    await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+
+    // No second become-leader; instead ports flow both ways.
+    expect(b.ofType('become-leader')).toHaveLength(0);
+    const attach = a.received.filter((r) => r.msg.type === 'attach-follower-ports');
+    const use = b.received.filter((r) => r.msg.type === 'use-follower-ports');
+    expect(attach).toHaveLength(1);
+    expect(use).toHaveLength(1);
+    expect(attach[0].ports).toHaveLength(2);
+    expect(use[0].ports).toHaveLength(2);
+    // The two db ports are entangled ends of ONE channel: a message posted on
+    // the leader's end arrives on the follower's end. (The broker mints REAL
+    // node MessageChannels here; only the control-plane ports are fakes.)
+    const leaderDb = attach[0].ports[0] as unknown as MessagePort;
+    const followerDb = use[0].ports[0] as unknown as MessagePort;
+    const got = new Promise<unknown>((resolve) => {
+      followerDb.onmessage = (ev: MessageEvent) => resolve(ev.data);
+    });
+    leaderDb.postMessage('entangled?');
+    vi.useRealTimers();
+    await expect(got).resolves.toBe('entangled?');
+    leaderDb.close();
+    followerDb.close();
+    vi.useFakeTimers();
+  });
+
+  it('stops re-minting follower ports once the leader confirms attachment', async () => {
+    const a = connectTab('tab-a');
+    const leadershipId = await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    a.send({
+      type: 'follower-port-attached',
+      tabId: 'tab-a',
+      bucketId: 'anon',
+      leadershipId,
+      followerTabId: 'tab-b',
+    });
+    await flush();
+    const before = b.ofType('use-follower-ports').length;
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(b.ofType('use-follower-ports').length).toBe(before);
+  });
+
+  it('re-mints follower ports with backoff while unconfirmed', async () => {
+    const a = connectTab('tab-a');
+    await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    expect(b.ofType('use-follower-ports')).toHaveLength(1);
+    await vi.advanceTimersByTimeAsync(1000);
+    await flush();
+    expect(b.ofType('use-follower-ports')).toHaveLength(2);
+    await vi.advanceTimersByTimeAsync(2000);
+    await flush();
+    expect(b.ofType('use-follower-ports')).toHaveLength(3);
+  });
+
+  it('rejects a tab whose fingerprint differs from the first hello', async () => {
+    connectTab('tab-a', { fingerprint: 'fp-1' });
+    const b = connectTab('tab-b', { fingerprint: 'fp-2' });
+    await flush();
+    expect(b.ofType('unsupported').map((m) => m.reason)).toEqual(['fingerprint-mismatch']);
+  });
+
+  it('keeps leadership ids monotonic across handoffs', async () => {
+    const a = connectTab('tab-a');
+    const id1 = await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    a.send({ type: 'shutdown', tabId: 'tab-a', bucketId: 'anon' });
+    await flush();
+    const id2 = await ackLeadership(b);
+    expect(id2).toBeGreaterThan(id1);
+  });
+});
+
+describe('tabs broker: failover', () => {
+  it('promotes the follower when the leader shuts down gracefully', async () => {
+    const a = connectTab('tab-a');
+    await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    a.send({ type: 'shutdown', tabId: 'tab-a', bucketId: 'anon' });
+    await flush();
+    expect(b.ofType('become-leader').length).toBeGreaterThan(0);
+  });
+
+  it('evicts a leader that misses pongs and re-elects', async () => {
+    const a = connectTab('tab-a');
+    await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    // b keeps answering pings, a goes silent.
+    b.port.onmessage = (ev) => {
+      b.received.push({ msg: ev.data, ports: ev.ports });
+      if (ev.data.type === 'ping') b.send({ type: 'pong', tabId: 'tab-b' });
+    };
+    await vi.advanceTimersByTimeAsync(21_000);
+    await flush();
+    expect(b.ofType('become-leader').length).toBeGreaterThan(0);
+  });
+
+  it('applies a failure backoff and grants allowMemoryFallback after 3 opfs cycles', async () => {
+    const a = connectTab('tab-a');
+    await flush();
+    for (let cycle = 0; cycle < 3; cycle++) {
+      const grants = a.ofType('become-leader');
+      const last = grants[grants.length - 1];
+      expect(last.allowMemoryFallback).toBe(false);
+      a.send({
+        type: 'leader-failed',
+        tabId: 'tab-a',
+        bucketId: 'anon',
+        leadershipId: last.leadershipId,
+        reason: 'opfs-unavailable: locked',
+      });
+      await flush();
+      // The 1s candidate backoff must pass before the next nomination.
+      await vi.advanceTimersByTimeAsync(1100);
+      await flush();
+    }
+    const grants = a.ofType('become-leader');
+    expect(grants[grants.length - 1].allowMemoryFallback).toBe(true);
+  });
+
+  it('re-elects when a promoted tab never answers become-leader', async () => {
+    // The wedge this guards: a tab that hangs mid-promotion sends neither
+    // leader-ready nor leader-failed, and keeps answering pings, so without a
+    // deadline the namespace keeps a leader that is never `ready` - no follower
+    // ports are minted and no re-election ever runs.
+    const a = connectTab('tab-a');
+    const b = connectTab('tab-b');
+    await flush();
+    const grantedTo = a.ofType('become-leader').length > 0 ? a : b;
+    const other = grantedTo === a ? b : a;
+    expect(grantedTo.ofType('become-leader').length).toBe(1);
+    // Both tabs keep answering pings; the promoted one just never reports.
+    for (const t of [a, b]) {
+      t.port.onmessage = (ev) => {
+        t.received.push({ msg: ev.data, ports: ev.ports });
+        if (ev.data.type === 'ping') t.send({ type: 'pong', tabId: t.tabId });
+      };
+    }
+    await vi.advanceTimersByTimeAsync(21_000);
+    await flush();
+    // The other tab gets a shot, under a NEW leadership id.
+    const handover = other.ofType('become-leader');
+    expect(handover.length).toBeGreaterThan(0);
+    expect(handover[handover.length - 1].leadershipId).toBeGreaterThan(
+      grantedTo.ofType('become-leader')[0].leadershipId
+    );
+  });
+
+  it('stops the promotion deadline once leader-ready lands', async () => {
+    const a = connectTab('tab-a');
+    const id = await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    a.port.onmessage = (ev) => {
+      a.received.push({ msg: ev.data, ports: ev.ports });
+      if (ev.data.type === 'ping') a.send({ type: 'pong', tabId: 'tab-a' });
+    };
+    b.port.onmessage = (ev) => {
+      b.received.push({ msg: ev.data, ports: ev.ports });
+      if (ev.data.type === 'ping') b.send({ type: 'pong', tabId: 'tab-b' });
+    };
+    await vi.advanceTimersByTimeAsync(30_000);
+    await flush();
+    // A confirmed leader is never torn down by the promotion deadline.
+    expect(a.ofType('demote')).toHaveLength(0);
+    expect(b.ofType('become-leader')).toHaveLength(0);
+    expect(a.ofType('become-leader')[0].leadershipId).toBe(id);
+  });
+
+  it('demotes a stale leader-ready from a superseded promotion', async () => {
+    const a = connectTab('tab-a');
+    const staleId = await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    a.send({ type: 'shutdown', tabId: 'tab-a', bucketId: 'anon' });
+    await flush();
+    await ackLeadership(b);
+    // The departed tab reconnects and replays its OLD leader-ready.
+    const a2 = connectTab('tab-a');
+    await flush();
+    a2.send({ type: 'leader-ready', tabId: 'tab-a', bucketId: 'anon', leadershipId: staleId });
+    await flush();
+    expect(a2.ofType('demote').map((m) => m.leadershipId)).toContain(staleId);
+  });
+
+  it('prefers a candidate that still holds a live worker (broker restart path)', async () => {
+    // Fresh broker instance, two tabs hello simultaneously; one held leadership
+    // from before the restart.
+    const a = connectTab('tab-a');
+    await flush();
+    const idA = await ackLeadership(a);
+    void idA;
+    __resetBrokerForTests();
+    const b2 = connectTab('tab-b');
+    void b2;
+    const { port1, port2 } = fakeChannel();
+    handleConnect(port1 as unknown as MessagePort);
+    const received: TestTab['received'] = [];
+    port2.onmessage = (ev) => received.push({ msg: ev.data, ports: ev.ports });
+    port2.postMessage({
+      type: 'hello',
+      tabId: 'tab-a',
+      fingerprint: 'fp-test',
+      bucketId: 'anon',
+      visibility: 'hidden',
+      heldLeadership: { leadershipId: 7, workerLockName: 'sp00ky-tabs:fp-test:anon:worker:7' },
+    });
+    await flush();
+    // Despite being hidden (b is visible), the holder wins with resumeHeld.
+    const grant = received.find((r) => r.msg.type === 'become-leader');
+    expect(grant).toBeDefined();
+    expect((grant!.msg as { resumeHeld: boolean }).resumeHeld).toBe(true);
+  });
+});
+
+describe('tabs broker: namespaces', () => {
+  it('separates tabs by bucket: one leader per bucket', async () => {
+    const a = connectTab('tab-a', { bucket: 'user1' });
+    await ackLeadership(a, 'user1');
+    const b = connectTab('tab-b', { bucket: 'user2' });
+    await flush();
+    expect(b.ofType('become-leader').length).toBeGreaterThan(0);
+  });
+
+  it('re-elects the old namespace immediately when a leader re-hellos into a new bucket', async () => {
+    const a = connectTab('tab-a');
+    await ackLeadership(a);
+    const b = connectTab('tab-b');
+    await flush();
+    // a switches buckets: same tabId, new bucket. b must be promoted in anon
+    // without waiting for a pong eviction.
+    a.send({
+      type: 'hello',
+      tabId: 'tab-a',
+      fingerprint: 'fp-test',
+      bucketId: 'user1',
+      visibility: 'visible',
+      heldLeadership: null,
+    });
+    await flush();
+    expect(b.ofType('become-leader').length).toBeGreaterThan(0);
+    // and a is offered leadership of the new bucket.
+    expect(a.ofType('become-leader').length).toBeGreaterThan(1);
+  });
+});

package/src/services/tabs/coordinator.test.ts

@@ -0,0 +1,365 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { handleConnect, __resetBrokerForTests } from './tabs-broker-worker';
+import { fakeChannel, flush, installBrokerGlobals, installFakeLocks } from './fake-ports.fixture';
+import {
+  TabsCoordinator,
+  SyncForwarder,
+  type CoordinatorHooks,
+  type LeaderSyncHub,
+} from './coordinator';
+import type { StorageHealth } from '../../types';
+import type { LeaderToFollowerMessage } from './protocol';
+
+function makeLogger(): any {
+  const noop = () => {};
+  const l: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  l.child = () => l;
+  return l;
+}
+
+interface HookLog {
+  adoptOwner: { bucketId: string; workerLockName: string; resumeHeld: boolean }[];
+  adoptAttached: { bucketId: string; storageHealth: StorageHealth }[];
+  released: number;
+  leaderLost: string[];
+  exposedPorts: string[];
+  hub: LeaderSyncHub | null;
+  forwarder: SyncForwarder | null;
+  leaderDuties: number;
+}
+
+function makeHooks(): { hooks: CoordinatorHooks; log: HookLog } {
+  const log: HookLog = {
+    adoptOwner: [],
+    adoptAttached: [],
+    released: 0,
+    leaderLost: [],
+    exposedPorts: [],
+    hub: null,
+    forwarder: null,
+    leaderDuties: 0,
+  };
+  const hooks: CoordinatorHooks = {
+    async adoptOwner(bucketId, opts) {
+      log.adoptOwner.push({ bucketId, workerLockName: opts.workerLockName, resumeHeld: opts.resumeHeld });
+      return { status: 'persistent', fallback: false, role: 'leader' };
+    },
+    async adoptAttached(_dbPort, snapshot) {
+      log.adoptAttached.push({ bucketId: snapshot.bucketId, storageHealth: snapshot.storageHealth });
+    },
+    async releaseOwnership() {
+      log.released++;
+    },
+    onLeaderLost(reason) {
+      log.leaderLost.push(reason);
+    },
+    async exposeClientPort(clientId) {
+      log.exposedPorts.push(clientId);
+    },
+    async removeClientPort() {},
+    becomeSyncLeader(hub) {
+      log.hub = hub;
+    },
+    async resumeSyncLeaderDuties() {
+      log.leaderDuties++;
+    },
+    becomeSyncFollower(forwarder) {
+      log.forwarder = forwarder;
+    },
+    becomeSyncSolo() {},
+    currentStorageHealth: () => ({ status: 'persistent', fallback: false, role: 'leader' }),
+  };
+  return { hooks, log };
+}
+
+function makeCoordinator(tabId: string, overrides: Partial<CoordinatorHooks> = {}) {
+  const { hooks, log } = makeHooks();
+  const coordinator = new TabsCoordinator({
+    tabId,
+    fingerprint: 'fp-coord-test',
+    hooks: { ...hooks, ...overrides },
+    logger: makeLogger(),
+  });
+  return { coordinator, log };
+}
+
+let restoreGlobals: () => void;
+beforeEach(() => {
+  __resetBrokerForTests();
+  restoreGlobals = installBrokerGlobals(handleConnect);
+});
+afterEach(() => {
+  restoreGlobals();
+  __resetBrokerForTests();
+});
+
+// End-to-end role assignment: two real coordinators, the real broker module,
+// fake SharedWorker/MessageChannel plumbing (node has no SharedWorker).
+describe('TabsCoordinator integration', () => {
+  it('boots the first tab as leader with a per-leadership worker lock name', async () => {
+    const { coordinator, log } = makeCoordinator('tab-1');
+    const role = await coordinator.start('anon');
+    expect(role).toBe('leader');
+    expect(log.adoptOwner).toHaveLength(1);
+    expect(log.adoptOwner[0].bucketId).toBe('anon');
+    expect(log.adoptOwner[0].workerLockName).toMatch(/^sp00ky-tabs:fp-coord-test:anon:worker:\d+$/);
+    expect(log.hub).not.toBeNull();
+    await coordinator.stop();
+  });
+
+  it('attaches the second tab as follower with the leader-reported snapshot', async () => {
+    const a = makeCoordinator('tab-1');
+    await a.coordinator.start('anon');
+    const b = makeCoordinator('tab-2');
+    const role = await b.coordinator.start('anon');
+
+    expect(role).toBe('follower');
+    // Leader forwarded the follower's db port into its worker...
+    expect(a.log.exposedPorts).toEqual(['tab-2']);
+    // ...and the follower adopted the leader's store snapshot.
+    expect(b.log.adoptAttached).toHaveLength(1);
+    expect(b.log.adoptAttached[0].bucketId).toBe('anon');
+    expect(b.log.adoptAttached[0].storageHealth.status).toBe('persistent');
+    expect(b.log.forwarder).not.toBeNull();
+    await b.coordinator.stop();
+    await a.coordinator.stop();
+  });
+
+  it('relays hub messages to the follower forwarder (ingest fan-out)', async () => {
+    const a = makeCoordinator('tab-1');
+    await a.coordinator.start('anon');
+    const b = makeCoordinator('tab-2');
+    await b.coordinator.start('anon');
+
+    const seen: LeaderToFollowerMessage[] = [];
+    b.log.forwarder!.onLeaderMessage = (msg) => seen.push(msg);
+    a.log.hub!.relayIngest([{ table: 'game', op: 'CREATE', id: 'game:1', record: { id: 'game:1' } }]);
+    await new Promise((r) => setTimeout(r, 20));
+
+    const relay = seen.filter((m) => m.type === 'ingest-relay');
+    expect(relay).toHaveLength(1);
+    expect((relay[0] as { seq: number }).seq).toBe(1);
+    await b.coordinator.stop();
+    await a.coordinator.stop();
+  });
+
+  it('forwards follower messages to the leader hub (mutation notify)', async () => {
+    const a = makeCoordinator('tab-1');
+    await a.coordinator.start('anon');
+    const b = makeCoordinator('tab-2');
+    await b.coordinator.start('anon');
+
+    const seen: { tabId: string; msg: unknown }[] = [];
+    a.log.hub!.onFollowerMessage = (tabId, msg) => seen.push({ tabId, msg });
+    b.log.forwarder!.mutationEnqueued('_00_pending_mutations:0000000000123_0001_tab2');
+    await new Promise((r) => setTimeout(r, 20));
+
+    const notify = seen.filter((s) => (s.msg as { type: string }).type === 'mutation-enqueued');
+    expect(notify).toHaveLength(1);
+    expect(notify[0].tabId).toBe('tab-2');
+    await b.coordinator.stop();
+    await a.coordinator.stop();
+  });
+
+  // A follower's optimistic write must reach the leader (which ingests it and
+  // fans it out) in one hop. Before this, only the mutation id was forwarded
+  // and every other tab waited on the server round-trip + LIVE delivery.
+  it('forwards a follower ingest to the leader hub tagged with the origin tab', async () => {
+    const a = makeCoordinator('tab-1');
+    await a.coordinator.start('anon');
+    const b = makeCoordinator('tab-2');
+    await b.coordinator.start('anon');
+
+    const seen: { tabId: string; msg: unknown }[] = [];
+    a.log.hub!.onFollowerMessage = (tabId, msg) => seen.push({ tabId, msg });
+    const tuples = [{ table: 'game', op: 'CREATE' as const, id: 'game:9', record: { id: 'game:9' } }];
+    b.log.forwarder!.ingest(tuples);
+    await new Promise((r) => setTimeout(r, 20));
+
+    const ingest = seen.filter((s) => (s.msg as { type: string }).type === 'ingest');
+    expect(ingest).toHaveLength(1);
+    expect(ingest[0].tabId).toBe('tab-2');
+    expect((ingest[0].msg as { tuples: unknown }).tuples).toEqual(tuples);
+    await b.coordinator.stop();
+    await a.coordinator.stop();
+  });
+
+  it('fan-out with exceptTabId skips the origin follower and reaches the others', async () => {
+    const a = makeCoordinator('tab-1');
+    await a.coordinator.start('anon');
+    const b = makeCoordinator('tab-2');
+    await b.coordinator.start('anon');
+    const c = makeCoordinator('tab-3');
+    await c.coordinator.start('anon');
+
+    const seenB: LeaderToFollowerMessage[] = [];
+    const seenC: LeaderToFollowerMessage[] = [];
+    b.log.forwarder!.onLeaderMessage = (msg) => seenB.push(msg);
+    c.log.forwarder!.onLeaderMessage = (msg) => seenC.push(msg);
+    a.log.hub!.relayIngest(
+      [{ table: 'game', op: 'CREATE', id: 'game:9', record: { id: 'game:9' } }],
+      'tab-2'
+    );
+    await new Promise((r) => setTimeout(r, 20));
+
+    expect(seenB.filter((m) => m.type === 'ingest-relay')).toHaveLength(0);
+    expect(seenC.filter((m) => m.type === 'ingest-relay')).toHaveLength(1);
+    await c.coordinator.stop();
+    await b.coordinator.stop();
+    await a.coordinator.stop();
+  });
+
+  // Unlike a mutation notify, an ingest is NOT queued across a leaderless
+  // window: the next leader primes its circuit from the shared store, which
+  // already holds the row, and a stale replay would put an older `_00_rv` in
+  // its version memo.
+  it('drops an ingest while detached instead of queueing it', async () => {
+    const forwarder = new SyncForwarder('tab-x');
+    forwarder.ingest([{ table: 'game', op: 'CREATE', id: 'game:1', record: { id: 'game:1' } }]);
+
+    const { port1, port2 } = fakeChannel();
+    const seen: { type: string }[] = [];
+    port2.onmessage = (ev) => {
+      seen.push(ev.data as { type: string });
+    };
+    forwarder.rebind(port1 as unknown as MessagePort);
+    await flush();
+
+    expect(seen.map((m) => m.type)).toEqual(['sync-hello']);
+    forwarder.unbind();
+  });
+
+  // Relay traffic that lands between `db-ready` and the sync hooks being
+  // installed (the store adopt is async) used to hit a null handler on a
+  // first attach and vanish.
+  it('buffers leader messages that land before the follower hooks are installed', async () => {
+    const a = makeCoordinator('tab-1');
+    await a.coordinator.start('anon');
+
+    let adoptStartedResolve!: () => void;
+    const adoptStartedP = new Promise<void>((r) => {
+      adoptStartedResolve = r;
+    });
+    let releaseAdopt!: () => void;
+    const adoptGate = new Promise<void>((r) => {
+      releaseAdopt = r;
+    });
+    const seen: LeaderToFollowerMessage[] = [];
+    const b = makeCoordinator('tab-2', {
+      async adoptAttached() {
+        adoptStartedResolve();
+        await adoptGate;
+      },
+      becomeSyncFollower(forwarder) {
+        forwarder.onLeaderMessage = (msg) => seen.push(msg);
+      },
+    });
+    const started = b.coordinator.start('anon');
+    await adoptStartedP;
+    a.log.hub!.broadcast({
+      type: 'mutation-settled',
+      mutationId: '_00_pending_mutations:1_0001_tab-1',
+      recordId: 'game:1',
+      eventType: 'create',
+    });
+    await new Promise((r) => setTimeout(r, 20));
+    expect(seen).toHaveLength(0);
+
+    releaseAdopt();
+    await started;
+    expect(seen.map((m) => m.type)).toEqual(['mutation-settled']);
+    await b.coordinator.stop();
+    await a.coordinator.stop();
+  });
+
+  it('promotes the follower when the leader stops (failover)', async () => {
+    const a = makeCoordinator('tab-1');
+    await a.coordinator.start('anon');
+    const b = makeCoordinator('tab-2');
+    await b.coordinator.start('anon');
+
+    const roles: string[] = [];
+    b.coordinator.onRoleChange((r) => roles.push(r));
+    await a.coordinator.stop();
+    // Election + promotion are async hops across the fake ports.
+    await new Promise((r) => setTimeout(r, 100));
+
+    expect(roles).toContain('leader');
+    expect(b.log.adoptOwner).toHaveLength(1);
+    // The new leadership got a HIGHER id, so a fresh worker lock name.
+    expect(b.log.adoptOwner[0].workerLockName).not.toBe(a.log.adoptOwner[0].workerLockName);
+    expect(b.log.hub).not.toBeNull();
+    await b.coordinator.stop();
+  });
+
+  // A failed promotion must give the leader TAB lock back. The name is shared
+  // per namespace, so a leaked one makes every later election fail with
+  // 'leader tab lock unavailable': all tabs time out in start(), boot solo, and
+  // then contend for the OPFS pool individually — one busy pool wedging the
+  // whole app into the pre-shared-tabs behavior it exists to replace.
+  describe('with Web Locks', () => {
+    let locks: ReturnType<typeof installFakeLocks>;
+    beforeEach(() => {
+      locks = installFakeLocks();
+    });
+    afterEach(() => locks.restore());
+
+    /** A tab whose store can never open. Resolves once it has failed a
+     *  promotion, so tests don't wait out start()'s 15s timeout. */
+    function makeDoomedTab(tabId: string) {
+      let failed!: () => void;
+      const hasFailed = new Promise<void>((r) => {
+        failed = r;
+      });
+      const tab = makeCoordinator(tabId, {
+        async adoptOwner() {
+          queueMicrotask(failed);
+          throw new Error('opfs-unavailable: NoModificationAllowedError (after 10 attempts)');
+        },
+      });
+      // start() only settles on a role or the timeout; neither is the point.
+      void tab.coordinator.start('anon').catch(() => {});
+      return { ...tab, hasFailed };
+    }
+
+    it('releases the leader tab lock when adoptOwner throws', async () => {
+      const a = makeDoomedTab('tab-1');
+      await a.hasFailed;
+      // Well inside the 1s re-nomination backoff, so a held lock here is a leak
+      // and not the next attempt's legitimate acquisition.
+      await new Promise((r) => setTimeout(r, 50));
+      expect(locks.heldNames()).not.toContain('sp00ky-tabs:fp-coord-test:anon:tab');
+      await a.coordinator.stop();
+    });
+
+    it('lets a later tab lead after another tab failed to open the store', async () => {
+      const a = makeDoomedTab('tab-1');
+      await a.hasFailed;
+
+      const b = makeCoordinator('tab-2');
+      await expect(b.coordinator.start('anon')).resolves.toBe('leader');
+      expect(b.log.adoptOwner).toHaveLength(1);
+      await b.coordinator.stop();
+      await a.coordinator.stop();
+    });
+  });
+
+  it('moves buckets by leaving and rejoining: old namespace re-elects', async () => {
+    const a = makeCoordinator('tab-1');
+    await a.coordinator.start('anon');
+    const b = makeCoordinator('tab-2');
+    await b.coordinator.start('anon');
+
+    const rolesB: string[] = [];
+    b.coordinator.onRoleChange((r) => rolesB.push(r));
+    const newRole = await a.coordinator.moveToBucket('user1');
+
+    expect(newRole).toBe('leader');
+    expect(a.log.adoptOwner.map((o) => o.bucketId)).toEqual(['anon', 'user1']);
+    expect(a.log.released).toBeGreaterThan(0);
+    await new Promise((r) => setTimeout(r, 100));
+    expect(rolesB).toContain('leader');
+    await b.coordinator.stop();
+    await a.coordinator.stop();
+  });
+});