@spooky-sync/core 0.0.1-canary.154 → 0.0.1-canary.155

package/src/modules/data/mutation-id.ts

@@ -0,0 +1,35 @@
+/**
+ * Outbox mutation ids. Previously `_00_pending_mutations:${Date.now()}`, which
+ * (a) collides when two mutations land in the same millisecond, a real case
+ * once multiple tabs share one store, and (b) never actually ordered the
+ * drain, because `loadFromDatabase` sorted by a `created_at` field that does
+ * not exist on the table. The new shape is sortable AND collision-free:
+ *
+ *   <13-digit zero-padded ms timestamp>_<4-digit base36 seq>_<tabId>
+ *
+ * Lexicographic order == chronological order (per tab; cross-tab within-ms
+ * ordering is arbitrary, which matches reality), so `ORDER BY id` in the
+ * drain is now meaningful. The tabId suffix also routes rollbacks back to the
+ * tab that owns the mutation in shared-tabs mode.
+ */
+
+let seq = 0;
+
+/** Tab identity for mutation ids in SOLO mode, minted once per session. In
+ *  shared-tabs mode the coordinator's tabId is passed in instead. */
+const FALLBACK_TAB_ID = Math.random().toString(36).slice(2, 8);
+
+export function mintMutationId(tabId?: string): string {
+  const ts = Date.now().toString().padStart(13, '0');
+  const n = (seq = (seq + 1) % 36 ** 4).toString(36).padStart(4, '0');
+  return `_00_pending_mutations:${ts}_${n}_${tabId ?? FALLBACK_TAB_ID}`;
+}
+
+/** The tab that created the mutation, or null for a legacy numeric id. */
+export function mutationOwnerTabId(mutationId: string): string | null {
+  const raw = mutationId.startsWith('_00_pending_mutations:')
+    ? mutationId.slice('_00_pending_mutations:'.length)
+    : mutationId;
+  const parts = raw.split('_');
+  return parts.length >= 3 ? parts[parts.length - 1] : null;
+}

package/src/modules/devtools/index.ts

@@ -51,6 +51,13 @@ export class DevToolsService implements StreamUpdateReceiver {
   // (the on-demand GET_STATE pull) still works before the push channel turns on.
   private enabled = false;
 
+  /** Shared-tabs snapshot for the panel, wired by Sp00kyClient when active. */
+  private tabsInfoProvider: (() => Record<string, unknown> | null) | null = null;
+
+  setTabsInfoProvider(provider: () => Record<string, unknown> | null): void {
+    this.tabsInfoProvider = provider;
+  }
+
   // Full local table list (incl. internal `_00_*`), enumerated from the local DB
   // via our own reliable `service.query` — the DevTools panel's page-eval query
   // bridge is unreliable under load, so the panel relies on this instead.
@@ -327,6 +334,8 @@ export class DevToolsService implements StreamUpdateReceiver {
         // Durability of the local store. `fallback: true` means persistence was
         // requested but the dataset is actually sitting in RAM.
         storage: this.databaseService.storageHealth ?? { status: 'unknown', fallback: false },
+        // Shared-tabs role state (null when the feature is off / fell back).
+        tabs: this.tabsInfoProvider?.() ?? null,
       },
     });
   }

package/src/modules/sync/queue/queue-up.forwarded.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, vi } from 'vitest';
+import { UpQueue } from './queue-up';
+
+function makeLogger(): any {
+  const noop = () => {};
+  const l: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  l.child = () => l;
+  return l;
+}
+
+const ROW = {
+  id: '_00_pending_mutations:0001753875000000_0001_tabB',
+  mutationType: 'create',
+  recordId: 'game:g1',
+  data: { title: 'x' },
+};
+
+// Shared-tabs: followers commit outbox rows into the shared store and notify
+// the leader by id. The notify may be REPLAYED (failover buffering), so the
+// enqueue must be idempotent, and only the leader ever drains.
+describe('UpQueue.enqueueFromDatabase', () => {
+  function makeQueue(rows: Record<string, unknown[]>) {
+    const query = vi.fn(async (_sql: string, vars?: Record<string, unknown>) => {
+      const id = String(vars?.mutation_id ?? '');
+      return [rows[id] ?? []];
+    });
+    const local: any = { query };
+    return { queue: new UpQueue(local, makeLogger()), query };
+  }
+
+  it('loads exactly the forwarded row and enqueues it once', async () => {
+    const { queue } = makeQueue({ [ROW.id]: [ROW] });
+    await queue.enqueueFromDatabase(ROW.id);
+    expect(queue.size).toBe(1);
+  });
+
+  it('is idempotent: a replayed notify does not double-enqueue', async () => {
+    const { queue, query } = makeQueue({ [ROW.id]: [ROW] });
+    await queue.enqueueFromDatabase(ROW.id);
+    await queue.enqueueFromDatabase(ROW.id);
+    expect(queue.size).toBe(1);
+    // The second call short-circuits before even touching the store.
+    expect(query).toHaveBeenCalledTimes(1);
+  });
+
+  it('a row that never committed is a silent no-op (the app promise already rejected)', async () => {
+    const { queue } = makeQueue({});
+    await queue.enqueueFromDatabase(ROW.id);
+    expect(queue.size).toBe(0);
+  });
+});

package/src/modules/sync/queue/queue-up.ts

@@ -6,7 +6,12 @@ import {
   createSyncQueueEventSystem,
   SyncQueueEventTypes,
 } from '../events/index';
-import { parseRecordIdString, extractTablePart, classifySyncError } from '../../../utils/index';
+import {
+  parseRecordIdString,
+  extractTablePart,
+  classifySyncError,
+  encodeRecordId,
+} from '../../../utils/index';
 import type { Logger } from '../../../services/logger/index';
 import type { PushEventOptions } from '../../../events/index';
 
@@ -184,49 +189,41 @@ export class UpQueue {
     return this.local.query(`DELETE $mutation_id`, { mutation_id });
   }
 
+  /**
+   * Shared-tabs: a follower committed an outbox row into the shared store and
+   * notified the leader; enqueue exactly that row. Idempotent: a replayed
+   * notify (failover) or a row already queued is a no-op, and a row that never
+   * committed simply is not found (the follower's own write promise already
+   * rejected in that case).
+   */
+  async enqueueFromDatabase(mutationId: string): Promise<void> {
+    if (this.queue.some((e) => encodeUpEventId(e) === mutationId)) return;
+    try {
+      const [records] = await this.local.query<any>(`SELECT * FROM $mutation_id`, {
+        mutation_id: parseRecordIdString(mutationId),
+      });
+      const event = Array.isArray(records) && records[0] ? rowToUpEvent(records[0], this.logger) : null;
+      if (event) this.addToQueue(event);
+    } catch (error) {
+      this.logger.error(
+        { error, mutationId, Category: 'sp00ky-client::UpQueue::enqueueFromDatabase' },
+        'Failed to load a forwarded mutation'
+      );
+    }
+  }
+
   async loadFromDatabase() {
     try {
+      // ORDER BY id: mutation ids are zero-padded-timestamp-prefixed (see
+      // modules/data/mutation-id.ts), so lexicographic id order IS chronological
+      // order. (The previous created_at was never a defined field on this
+      // table, so the old ordering was undefined.)
       const [records] = await this.local.query<any>(
-        `SELECT * FROM _00_pending_mutations ORDER BY created_at ASC`
+        `SELECT * FROM _00_pending_mutations ORDER BY id ASC`
       );
 
       this.queue = records
-        .map((r: any): UpEvent | null => {
-          switch (r.mutationType) {
-            case 'create':
-              return {
-                type: 'create',
-                mutation_id: parseRecordIdString(r.id),
-                record_id: parseRecordIdString(r.recordId),
-                data: r.data,
-                tableName: extractTablePart(r.recordId),
-              };
-            case 'update':
-              return {
-                type: 'update',
-                mutation_id: parseRecordIdString(r.id),
-                record_id: parseRecordIdString(r.recordId),
-                data: r.data,
-                beforeRecord: r.beforeRecord,
-              };
-            case 'delete':
-              return {
-                type: 'delete',
-                mutation_id: parseRecordIdString(r.id),
-                record_id: parseRecordIdString(r.recordId),
-              };
-            default:
-              this.logger.warn(
-                {
-                  mutationType: r.mutationType,
-                  record: r,
-                  Category: 'sp00ky-client::UpQueue::loadFromDatabase',
-                },
-                'Unknown mutation type'
-              );
-              return null;
-          }
-        })
+        .map((r: any): UpEvent | null => rowToUpEvent(r, this.logger))
         .filter((e: UpEvent | null): e is UpEvent => e !== null);
     } catch (error) {
       this.logger.error(
@@ -236,3 +233,42 @@ export class UpQueue {
     }
   }
 }
+
+/** The stable string id of an event's outbox row. */
+function encodeUpEventId(event: UpEvent): string {
+  return encodeRecordId(event.mutation_id);
+}
+
+/** Materialize one `_00_pending_mutations` row into an UpEvent. */
+function rowToUpEvent(r: any, logger: Logger): UpEvent | null {
+  switch (r.mutationType) {
+    case 'create':
+      return {
+        type: 'create',
+        mutation_id: parseRecordIdString(r.id),
+        record_id: parseRecordIdString(r.recordId),
+        data: r.data,
+        tableName: extractTablePart(r.recordId),
+      };
+    case 'update':
+      return {
+        type: 'update',
+        mutation_id: parseRecordIdString(r.id),
+        record_id: parseRecordIdString(r.recordId),
+        data: r.data,
+        beforeRecord: r.beforeRecord,
+      };
+    case 'delete':
+      return {
+        type: 'delete',
+        mutation_id: parseRecordIdString(r.id),
+        record_id: parseRecordIdString(r.recordId),
+      };
+    default:
+      logger.warn(
+        { mutationType: r.mutationType, record: r, Category: 'sp00ky-client::UpQueue::rowToUpEvent' },
+        'Unknown mutation type'
+      );
+      return null;
+  }
+}

package/src/modules/sync/scheduler.ts

@@ -26,8 +26,10 @@ export class SyncScheduler {
     private onSyncOutcome?: (ok: boolean, error?: unknown) => void
   ) {}
 
-  async init() {
-    await this.upQueue.loadFromDatabase();
+  async init(opts: { loadOutbox?: boolean } = {}) {
+    // Shared-tabs followers skip the outbox load: the shared store's
+    // `_00_pending_mutations` is drained by exactly one tab (the leader).
+    if (opts.loadOutbox !== false) await this.upQueue.loadFromDatabase();
     this.upQueue.events.subscribe(SyncQueueEventTypes.MutationEnqueued, this.syncUp.bind(this));
     this.downQueue.events.subscribe(
       SyncQueueEventTypes.QueryItemEnqueued,

package/src/modules/sync/sync.ts

@@ -22,6 +22,9 @@ import type { CacheModule } from '../cache/index';
 import type { DataModule } from '../data/index';
 import { classifySyncError, encodeRecordId, extractIdPart, extractTablePart, surql } from '../../utils/index';
 import { ANON_USER_ID, DEFAULT_REF_MODE, listRefTableFor, RefMode } from '../ref-tables';
+import { mutationOwnerTabId } from '../data/mutation-id';
+import type { LeaderSyncHub, SyncForwarder } from '../../services/tabs/coordinator';
+import { parseRecordIdString } from '../../utils/index';
 
 /**
  * Tunables for `Sp00kySync` construction.
@@ -75,6 +78,15 @@ export class Sp00kySync<S extends SchemaStructure> {
   // subscription in `Sp00kyClient`; null when unauthenticated.
   private currentUserId: string | null = null;
 
+  // ---- shared-tabs role state ----
+  // Followers keep their own remote WS (registration, per-query sync, poll)
+  // but must never drain the shared outbox or hold a second list_ref LIVE.
+  // The leader relays its LIVE events and routes rollbacks by mutation owner.
+  private tabRole: 'solo' | 'leader' | 'follower' = 'solo';
+  private tabId: string | null = null;
+  private hub: LeaderSyncHub | null = null;
+  private forwarder: SyncForwarder | null = null;
+
   private refMode: RefMode = DEFAULT_REF_MODE;
 
   // When true, an unauthenticated client still runs the `_00_list_ref` poll
@@ -366,7 +378,7 @@ export class Sp00kySync<S extends SchemaStructure> {
   public async init() {
     if (this.isInit) throw new Error('Sp00kySync is already initialized');
     this.isInit = true;
-    await this.scheduler.init();
+    await this.scheduler.init({ loadOutbox: this.tabRole !== 'follower' });
     this.subscribeToReconnect();
     void this.scheduler.syncUp();
     void this.scheduler.syncDown();
@@ -393,6 +405,116 @@ export class Sp00kySync<S extends SchemaStructure> {
     }
   }
 
+  // ---- shared-tabs roles ------------------------------------------------------
+
+  /** Set BEFORE init(): shapes what init boots (a follower loads no outbox and
+   *  never starts LIVE; its own registration/poll paths stay untouched). */
+  public setTabContext(role: 'solo' | 'leader' | 'follower', tabId: string | null): void {
+    this.tabRole = role;
+    this.tabId = tabId;
+  }
+
+  /** Leader duties: drain the shared outbox, own the single list_ref LIVE,
+   *  relay LIVE events and rollbacks to followers via `hub`. Idempotent for a
+   *  boot-time leader; a runtime promotion (failover) reloads the outbox,
+   *  which now holds EVERY tab's rows, and restarts LIVE under this session. */
+  public async promoteToLeader(hub: LeaderSyncHub): Promise<void> {
+    this.tabRole = 'leader';
+    this.hub = hub;
+    this.forwarder = null;
+    hub.onFollowerMessage = (tabId, msg) => {
+      void tabId;
+      switch (msg.type) {
+        case 'sync-hello':
+          break;
+        case 'mutation-enqueued':
+          void this.enqueueForwardedMutation(msg.mutationId);
+          break;
+        case 'request-poll':
+          this.listRefIdleStreak = 0;
+          break;
+      }
+    };
+    if (this.isInit) {
+      await this.upQueue.loadFromDatabase();
+      void this.scheduler.syncUp();
+      if (this.currentUserId || this.anonLiveEnabled) {
+        this.startListRefPoll();
+        await this.restartRefLiveQuery().catch((err) => {
+          this.logger.warn(
+            { err, Category: 'sp00ky-client::Sp00kySync::promoteToLeader' },
+            'LIVE restart failed on promotion; poll fallback covers it'
+          );
+        });
+      }
+    }
+  }
+
+  /** Follower duties: no outbox drain, no LIVE. Mutations forward to the
+   *  leader; everything else (registration, per-query sync, poll) runs
+   *  against this tab's own remote session as usual. */
+  public demoteToFollower(forwarder: SyncForwarder): void {
+    this.tabRole = 'follower';
+    this.hub = null;
+    this.forwarder = forwarder;
+    void this.killRefLiveQuery();
+    forwarder.onLeaderMessage = (msg) => {
+      switch (msg.type) {
+        case 'list-ref-change':
+          void this.applyRelayedListRefChange(msg).catch((err) => {
+            this.logger.error(
+              { err, Category: 'sp00ky-client::Sp00kySync::relay' },
+              'Relayed list_ref change failed'
+            );
+          });
+          break;
+        case 'mutation-rolled-back':
+          this.events.emit(SyncEventTypes.MutationRolledBack, {
+            eventType: msg.eventType,
+            recordId: msg.recordId,
+            error: msg.error,
+          });
+          break;
+        default:
+          // db-ready and ingest-relay are handled by the engine/cache wiring
+          // in Sp00kyClient before messages reach this handler.
+          break;
+      }
+    };
+  }
+
+  /** A forwarded outbox row from a follower: load + drain it. Idempotent. */
+  public async enqueueForwardedMutation(mutationId: string): Promise<void> {
+    if (this.tabRole !== 'leader') return;
+    await this.upQueue.enqueueFromDatabase(mutationId);
+  }
+
+  /** A relayed `_00_list_ref` LIVE event: resolve against THIS tab's queries
+   *  and run the exact same handling the LIVE subscription would have. */
+  private async applyRelayedListRefChange(msg: {
+    action: 'CREATE' | 'UPDATE' | 'DELETE';
+    queryId: string;
+    recordId: string;
+    version: number;
+    parent: boolean;
+  }): Promise<void> {
+    const queryId = parseRecordIdString(msg.queryId);
+    // Foreign query (another tab's session-salted hash): not ours, ignore.
+    if (!this.dataModule.getQueryById(queryId)) return;
+    const recordId = parseRecordIdString(msg.recordId);
+    if (msg.parent) {
+      await this.handleRemoteSubqueryChange(msg.action, queryId, recordId, msg.version);
+    } else {
+      await this.handleRemoteListRefChange(msg.action, queryId, recordId, msg.version);
+    }
+  }
+
+  /** One immediate poll cycle (failover convergence). */
+  public async forcePollRound(): Promise<void> {
+    this.listRefIdleStreak = 0;
+    await this.pollListRefForActiveQueries().catch(() => false);
+  }
+
   /**
    * Quiesce all sync activity ahead of a local-bucket switch. After this
    * resolves, nothing in the sync module writes to the local store: the poll
@@ -772,6 +894,9 @@ export class Sp00kySync<S extends SchemaStructure> {
   }
 
   private async startRefLiveQueries() {
+    // Shared-tabs follower: exactly one LIVE per user exists, on the leader;
+    // its events reach this tab through the relay.
+    if (this.tabRole === 'follower') return;
     const tableName = this.listRefTable();
     this.logger.debug(
       { tableName, Category: 'sp00ky-client::Sp00kySync::startRefLiveQueries' },
@@ -837,6 +962,20 @@ export class Sp00kySync<S extends SchemaStructure> {
     this.lastLiveEventAt = Date.now();
     this.listRefIdleStreak = 0;
 
+    // Shared-tabs leader: the list_ref table is USER-scoped, so this LIVE also
+    // carries events for FOLLOWER tabs' queries (their own session-salted
+    // hashes). Relay every primary event; each follower resolves the queryId
+    // against its own DataModule and ignores foreign ones. Then continue with
+    // this tab's own handling below.
+    this.hub?.broadcast({
+      type: 'list-ref-change',
+      action,
+      queryId: encodeRecordId(queryId),
+      recordId: encodeRecordId(recordId),
+      version,
+      parent: false,
+    });
+
     // NOTE: DELETE is handled like CREATE/UPDATE below. When another window (or
     // this one) deletes a record, the server's SSP removes it from `_00_list_ref`
     // and the LIVE subscription delivers a DELETE here — `createDiffFromDbOp`
@@ -846,13 +985,17 @@ export class Sp00kySync<S extends SchemaStructure> {
     const existing = this.dataModule.getQueryById(queryId);
 
     if (!existing) {
-      this.logger.warn(
-        {
-          queryId: queryId.toString(),
-          Category: 'sp00ky-client::Sp00kySync::handleRemoteListRefChange',
-        },
-        'Received remote update for unknown local query'
-      );
+      // With a hub attached, an unknown query is the NORMAL case (it belongs
+      // to a follower tab); without one it still warrants the warning.
+      if (!this.hub) {
+        this.logger.warn(
+          {
+            queryId: queryId.toString(),
+            Category: 'sp00ky-client::Sp00kySync::handleRemoteListRefChange',
+          },
+          'Received remote update for unknown local query'
+        );
+      }
       return;
     }
 
@@ -899,6 +1042,16 @@ export class Sp00kySync<S extends SchemaStructure> {
 
     if (action === 'DELETE') return;
 
+    // Relay child-edge events too (see handleRemoteListRefChange).
+    this.hub?.broadcast({
+      type: 'list-ref-change',
+      action,
+      queryId: encodeRecordId(queryId),
+      recordId: encodeRecordId(childId),
+      version,
+      parent: true,
+    });
+
     const existing = this.dataModule.getQueryById(queryId);
     if (!existing) return;
 
@@ -1013,6 +1166,21 @@ export class Sp00kySync<S extends SchemaStructure> {
       recordId,
       error: error.message,
     });
+
+    // Shared-tabs: the store rollback above already propagated to every tab
+    // via the ingest relay; additionally deliver the EVENT to the tab that
+    // owns the mutation so its UI (toasts, subscribeToRollbacks) fires there.
+    const mutationId = encodeRecordId(event.mutation_id);
+    const owner = mutationOwnerTabId(mutationId);
+    if (this.hub && owner && this.tabId && owner !== this.tabId) {
+      this.hub.sendTo(owner, {
+        type: 'mutation-rolled-back',
+        mutationId,
+        recordId,
+        eventType: event.type,
+        error: error.message,
+      });
+    }
   }
 
   private async processDownEvent(event: DownEvent) {
@@ -1171,6 +1339,16 @@ export class Sp00kySync<S extends SchemaStructure> {
    * @param mutations Array of UpEvents (create/update/delete) to enqueue.
    */
   public async enqueueMutation(mutations: UpEvent[]) {
+    // Follower: the outbox rows are already committed in the SHARED store (the
+    // mutation tx went through the leader's worker); only the leader drains,
+    // so hand over the ids instead of queueing locally. A notify lost in a
+    // failover window is covered by the new leader's loadFromDatabase.
+    if (this.tabRole === 'follower') {
+      for (const m of mutations) {
+        this.forwarder?.mutationEnqueued(encodeRecordId(m.mutation_id));
+      }
+      return;
+    }
     this.scheduler.enqueueMutation(mutations);
   }
 

package/src/services/database/engine-factory.ts

@@ -16,7 +16,8 @@ import { SqliteCacheEngine } from './sqlite-cache-engine';
 export function createLocalEngine(
   choice: LocalEngineChoice | undefined,
   config: Sp00kyConfig<any>['database'],
-  logger: Logger
+  logger: Logger,
+  opts: { shared?: boolean } = {}
 ): LocalStore {
   if (choice === undefined || choice === 'surrealdb') {
     return new SurrealCacheEngine(config, logger);
@@ -25,7 +26,7 @@ export function createLocalEngine(
     // Mirror the SurrealDB engine's `store` semantics: 'memory' → in-memory
     // SQLite (transient), 'indexeddb' → OPFS-backed (durable).
     const useOpfs = (config.store ?? 'memory') !== 'memory';
-    return new SqliteCacheEngine(config, logger, { useOpfs });
+    return new SqliteCacheEngine(config, logger, { useOpfs, shared: opts.shared });
   }
   // Custom engine instance — trust it to satisfy LocalStore.
   return choice as unknown as LocalStore;