@spooky-sync/core 0.0.1-canary.235 → 0.0.1-canary.237

package/src/services/database/database.query-timeout.test.ts

@@ -23,13 +23,20 @@ const silentLogger: any = (() => {
 
 class TestService extends AbstractDatabaseService {
   protected eventType = DatabaseEventTypes.RemoteQuery;
-  constructor(client: any, timeoutMs: number) {
+  constructor(client: any, timeoutMs: number, maxConcurrent = 1) {
     super(client, silentLogger, createDatabaseEventSystem());
     this.queryTimeoutMs = timeoutMs;
+    this.maxConcurrentQueries = maxConcurrent;
   }
   async connect(): Promise<void> {}
 }
 
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  const promise = new Promise<T>((r) => (resolve = r));
+  return { promise, resolve };
+}
+
 describe('AbstractDatabaseService query timeout', () => {
   beforeEach(() => vi.useFakeTimers());
   afterEach(() => vi.useRealTimers());
@@ -80,4 +87,54 @@ describe('AbstractDatabaseService query timeout', () => {
     // No timer was armed, so a slow-but-alive query is never cut off.
     expect(vi.getTimerCount()).toBe(0);
   });
+
+  it('keeps statements strictly ordered at the default limit of 1', async () => {
+    const first = deferred<unknown[]>();
+    const client = { query: vi.fn().mockImplementationOnce(() => first.promise).mockResolvedValue([['second']]) };
+    const svc = new TestService(client, 0);
+
+    const a = svc.query('SELECT 1');
+    const b = svc.query('SELECT 2');
+    await vi.advanceTimersByTimeAsync(0);
+    // The second statement has not been handed to the SDK while the first is in flight.
+    expect(client.query).toHaveBeenCalledTimes(1);
+    first.resolve([['first']]);
+    await expect(a).resolves.toEqual([['first']]);
+    await expect(b).resolves.toEqual([['second']]);
+    expect(client.query).toHaveBeenCalledTimes(2);
+  });
+
+  it('runs statements concurrently up to maxConcurrentQueries and queues the rest', async () => {
+    const d1 = deferred<unknown[]>();
+    const d2 = deferred<unknown[]>();
+    const client = {
+      query: vi
+        .fn()
+        .mockImplementationOnce(() => d1.promise)
+        .mockImplementationOnce(() => d2.promise)
+        .mockResolvedValue([['third']]),
+    };
+    const svc = new TestService(client, 0, 2);
+
+    const a = svc.query('SELECT 1');
+    const b = svc.query('SELECT 2');
+    const c = svc.query('SELECT 3');
+    await vi.advanceTimersByTimeAsync(0);
+    // Two in flight at once; the third waits for a slot.
+    expect(client.query).toHaveBeenCalledTimes(2);
+    d2.resolve([['second']]);
+    await expect(b).resolves.toEqual([['second']]);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(client.query).toHaveBeenCalledTimes(3);
+    d1.resolve([['first']]);
+    await expect(a).resolves.toEqual([['first']]);
+    await expect(c).resolves.toEqual([['third']]);
+  });
+
+  it('releases the slot when a statement fails', async () => {
+    const client = { query: vi.fn().mockRejectedValueOnce(new Error('boom')).mockResolvedValue([['ok']]) };
+    const svc = new TestService(client, 0);
+    await expect(svc.query('SELECT 1')).rejects.toThrow('boom');
+    await expect(svc.query('SELECT 2')).resolves.toEqual([['ok']]);
+  });
 });

package/src/services/database/database.ts

@@ -50,88 +50,118 @@ export abstract class AbstractDatabaseService {
     return this.client.beginTransaction();
   }
 
-  private queryQueue: Promise<void> = Promise.resolve();
-
   /**
-   * Execute a query with serialized execution to prevent WASM transaction issues.
+   * How many statements may be in flight at once.
    *
-   * Serialization means every query waits on the previous one, so a call that
-   * never settles blocks the whole chain forever. {@link queryTimeoutMs} bounds
-   * each link: on expiry this promise rejects and the chain moves on, even
-   * though the underlying RPC is still parked in the SDK's pending map.
+   * `1` serializes every statement behind the previous one. The local engines
+   * need that: overlapping ops trip the WASM / SQLite transaction layer. The
+   * remote service raises it (`RemoteDatabaseService`): a SurrealDB socket
+   * multiplexes requests by id, and serializing them capped the client at one
+   * statement per round trip (~5/s at 170ms RTT), so the `_00_list_ref` poll
+   * alone could hold every registration behind it and one slow one-shot read
+   * stalled the whole client. The scheduler's `MAX_CONCURRENT_DOWN` only means
+   * something when this is above 1.
    */
+  protected maxConcurrentQueries = 1;
+  private inFlightQueries = 0;
+  private queryWaiters: Array<() => void> = [];
+
+  /** FIFO slot acquisition, so `maxConcurrentQueries = 1` keeps strict order. */
+  private acquireQuerySlot(): Promise<void> {
+    if (this.inFlightQueries < this.maxConcurrentQueries) {
+      this.inFlightQueries++;
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      this.queryWaiters.push(() => {
+        this.inFlightQueries++;
+        resolve();
+      });
+    });
+  }
+
+  private releaseQuerySlot(): void {
+    this.inFlightQueries--;
+    const next = this.queryWaiters.shift();
+    if (next) next();
+  }
+
   /**
-   * Hook run inside the query queue, right before a statement is sent. The
-   * remote service uses it to hold statements while a connect is in flight,
-   * so a query never runs on a socket that is open but has not had its
-   * namespace and token applied yet. The default does nothing.
+   * Hook run right before a statement is sent, inside its slot. The remote
+   * service uses it to hold statements while a connect is in flight, so a
+   * query never runs on a socket that is open but has not had its namespace
+   * and token applied yet. The default does nothing.
    */
   protected async beforeQuery(): Promise<void> {}
 
+  /**
+   * Execute a statement under {@link maxConcurrentQueries}.
+   *
+   * A statement that never settles would hold its slot forever, and with a
+   * limit of 1 that blocks every later statement behind it. {@link
+   * queryTimeoutMs} bounds each one: on expiry this promise rejects and the
+   * slot is released, even though the underlying RPC is still parked in the
+   * SDK's pending map.
+   */
   async query<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T> {
-    return new Promise((resolve, reject) => {
-      this.queryQueue = this.queryQueue
-        // oxlint-disable-next-line promise/always-return
-        .then(async () => {
-          await this.beforeQuery();
-          const startTime = performance.now();
-          try {
-            this.logger.debug(
-              { query, vars, Category: 'sp00ky-client::Database::query' },
-              'Executing query'
-            );
-            const pending = this.client.query(query, vars);
-            // In SurrealDB 2.0, .query() collects results by default.
-            // We cast to T directly as proper typing depends on the caller knowing the return structure.
-            // "timed out" in the message is load-bearing: `classifySyncError`
-            // keys off it to classify this as `network` so the sync queues
-            // retry rather than rolling the mutation back.
-            const result = (await withTimeout(
-              pending as unknown as Promise<T>,
-              this.queryTimeoutMs,
-              () => this.timeoutError(query)
-            )) as T;
-            const duration = performance.now() - startTime;
-
-            // Emit query event
-            this.events.emit(this.eventType, {
-              query,
-              vars,
-              duration,
-              success: true,
-              timestamp: Date.now(),
-            });
-
-            resolve(result);
-            this.logger.trace(
-              { query, result, Category: 'sp00ky-client::Database::query' },
-              'Query executed successfully'
-            );
-          } catch (err) {
-            const duration = performance.now() - startTime;
-
-            // Emit query event with error
-            this.events.emit(this.eventType, {
-              query,
-              vars,
-              duration,
-              success: false,
-              error: err instanceof Error ? err.message : String(err),
-              timestamp: Date.now(),
-            });
-
-            this.logger.error(
-              { query, vars, err, Category: 'sp00ky-client::Database::query' },
-              'Query execution failed'
-            );
-            // oxlint-disable-next-line no-multiple-resolved -- resolve/reject are in try/catch, mutually exclusive
-            reject(err);
-          }
-        })
-        .catch(() => {
-          // Ignore queue errors to keep the chain alive; the specific promise was rejected above.
+    await this.acquireQuerySlot();
+    try {
+      await this.beforeQuery();
+      const startTime = performance.now();
+      try {
+        this.logger.debug(
+          { query, vars, Category: 'sp00ky-client::Database::query' },
+          'Executing query'
+        );
+        const pending = this.client.query(query, vars);
+        // In SurrealDB 2.0, .query() collects results by default.
+        // We cast to T directly as proper typing depends on the caller knowing the return structure.
+        // "timed out" in the message is load-bearing: `classifySyncError`
+        // keys off it to classify this as `network` so the sync queues
+        // retry rather than rolling the mutation back.
+        const result = (await withTimeout(
+          pending as unknown as Promise<T>,
+          this.queryTimeoutMs,
+          () => this.timeoutError(query)
+        )) as T;
+        const duration = performance.now() - startTime;
+
+        // Emit query event
+        this.events.emit(this.eventType, {
+          query,
+          vars,
+          duration,
+          success: true,
+          timestamp: Date.now(),
         });
-    });
+
+        this.logger.trace(
+          { query, result, Category: 'sp00ky-client::Database::query' },
+          'Query executed successfully'
+        );
+        return result;
+      } catch (err) {
+        const duration = performance.now() - startTime;
+
+        // Emit query event with error
+        this.events.emit(this.eventType, {
+          query,
+          vars,
+          duration,
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+          timestamp: Date.now(),
+        });
+
+        this.logger.error(
+          { query, vars, err, Category: 'sp00ky-client::Database::query' },
+          'Query execution failed'
+        );
+        throw err;
+      }
+    } finally {
+      this.releaseQuerySlot();
+    }
   }
 
   async execute<T>(query: SealedQuery<T>, vars?: Record<string, unknown>): Promise<T> {

package/src/services/database/remote.ts

@@ -30,6 +30,13 @@ export function resolveReconnectConfig(
 /** Transport events the SDK publishes, mapped 1:1 to {@link ConnectionState}. */
 export type RemoteConnectionEvent = ConnectionState | 'error';
 
+/**
+ * Statements the remote service keeps in flight at once. Enough for the sync
+ * scheduler's `MAX_CONCURRENT_DOWN` registrations plus the list_ref poll and
+ * an app's own one-shot reads, small enough to stay polite to the server.
+ */
+const REMOTE_MAX_CONCURRENT_QUERIES = 6;
+
 export class RemoteDatabaseService extends AbstractDatabaseService {
   private config: Sp00kyConfig<any>['database'];
   protected eventType = DatabaseEventTypes.RemoteQuery;
@@ -90,6 +97,7 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
     this.config = config;
     this.reconnectConfig = resolveReconnectConfig(config.reconnect);
     this.queryTimeoutMs = Math.max(0, config.queryTimeoutMs ?? 60_000);
+    this.maxConcurrentQueries = REMOTE_MAX_CONCURRENT_QUERIES;
   }
 
   getConfig(): Sp00kyConfig<any>['database'] {

package/src/sp00ky.init-query.test.ts

@@ -43,16 +43,16 @@ describe('Sp00kyClient.initQuery structural invariants', () => {
     );
   });
 
-  it('finishQueryInit hydrates strictly before enqueuing register', () => {
+  it('finishQueryInit enqueues register before the hydrate fetch', () => {
     const body = methodBody('finishQueryInit');
     const fetchIdx = body.indexOf('this.remote.query');
     const enqueueIdx = body.indexOf('this.sync.enqueueDownEvent');
     expect(fetchIdx).toBeGreaterThanOrEqual(0);
     expect(enqueueIdx).toBeGreaterThanOrEqual(0);
     expect(
-      fetchIdx,
-      'hydrate must settle before the register enqueue so a stale one-shot snapshot can never land after the authoritative _00_list_ref overwrite'
-    ).toBeLessThan(enqueueIdx);
+      enqueueIdx,
+      'the authoritative register must never wait on the one-shot hydrate read (a windowed list paid a full-table scan per window before its own registration could start); applyHydration drops a hydrate that lands after the registration'
+    ).toBeLessThan(fetchIdx);
   });
 
   it('finishQueryInit captures the bucket epoch before the remote fetch', () => {
@@ -119,16 +119,16 @@ describe('Sp00kyClient.finishQueryInit behavior', () => {
     });
   });
 
-  it('cold path with hydrate enabled: fetch → hydrate → enqueue, in order', async () => {
+  it('cold path with hydrate enabled: enqueue → fetch → hydrate, in order', async () => {
     await client.finishQueryInit(hash, q, {});
-    expect(calls).toEqual(['fetch', 'hydrate', 'enqueue']);
+    expect(calls).toEqual(['enqueue', 'fetch', 'hydrate']);
     expect(enqueued).toEqual([{ type: 'register', payload: { hash } }]);
   });
 
   it('a preloaded query still hydrates when enabled — cache-first never depends on WHY rows are cached', async () => {
     client.preloadedHashes.add(q.hash);
     await client.finishQueryInit(hash, q, {});
-    expect(calls).toEqual(['fetch', 'hydrate', 'enqueue']);
+    expect(calls).toEqual(['enqueue', 'fetch', 'hydrate']);
   });
 
   it('warm query (not cold) goes straight to enqueue', async () => {
@@ -143,7 +143,7 @@ describe('Sp00kyClient.finishQueryInit behavior', () => {
       throw new Error('offline');
     };
     await expect(client.finishQueryInit(hash, q, {})).resolves.toBeUndefined();
-    expect(calls).toEqual(['fetch', 'enqueue']);
+    expect(calls).toEqual(['enqueue', 'fetch']);
   });
 
   it('a bucket switch during the fetch skips applyHydration', async () => {
@@ -153,7 +153,7 @@ describe('Sp00kyClient.finishQueryInit behavior', () => {
       return [[{ id: 'user:a' }]];
     };
     await client.finishQueryInit(hash, q, {});
-    expect(calls).toEqual(['fetch', 'enqueue']);
+    expect(calls).toEqual(['enqueue', 'fetch']);
   });
 
   it('default (instantHydrate unset) does not hydrate — register lifecycle is the only freshness path', async () => {
@@ -177,7 +177,7 @@ describe('Sp00kyClient.finishQueryInit behavior', () => {
     expect(h2).toBe(hash);
     // Let the shared chain drain.
     await Promise.all([...client.pendingQueryInits.values()]);
-    expect(calls).toEqual(['fetch', 'hydrate', 'enqueue']);
+    expect(calls).toEqual(['enqueue', 'fetch', 'hydrate']);
     expect(client.pendingQueryInits.size).toBe(0);
   });
 });

package/src/sp00ky.ts

@@ -1449,12 +1449,13 @@ export class Sp00kyClient<S extends SchemaStructure> {
     // Local-first paint: the hash is returned as soon as the LOCAL registration
     // above completes — `queryState.records` is already seeded from the local
     // cache/SSP snapshot, so `useQuery` subscribes and paints from memory with
-    // zero network on the paint path. Instant-hydrate and the `register`
-    // down-event continue in a background chain (hydrate strictly before
-    // enqueue, so a stale one-shot snapshot can never land after the sync's
-    // authoritative `_00_list_ref` overwrite). Concurrent mounts of the same
-    // query share one chain; a sequential re-mount starts a fresh one so its
-    // `register` re-enqueue keeps freshening warm data on use.
+    // zero network on the paint path. The `register` down-event and the
+    // instant-hydrate continue in a background chain: register is enqueued
+    // first (the authoritative path never waits on a one-shot read), and a
+    // hydrate that lands after the registration is dropped by
+    // `applyHydration`. Concurrent mounts of the same query share one chain; a
+    // sequential re-mount starts a fresh one so its `register` re-enqueue
+    // keeps freshening warm data on use.
     if (!this.pendingQueryInits.has(hash)) {
       const chain = this.finishQueryInit(hash, q, params).finally(() => {
         this.pendingQueryInits.delete(hash);
@@ -1466,20 +1467,40 @@ export class Sp00kyClient<S extends SchemaStructure> {
   }
 
   /**
-   * Background tail of {@link initQuery}: instant-hydrate (opt-in via
-   * `config.instantHydrate`, and only when the query is cold) followed by
-   * enqueuing the `register` down-event. Never rejects — both halves catch and
-   * log, so `void`-ing the returned promise can't produce an unhandled
-   * rejection. By default (hydrate off) the register lifecycle is the single
-   * freshness path; the one-shot fetch is an optimization apps enable
-   * explicitly, and it runs regardless of preload state — cache-first delivery
-   * never depends on WHY rows are cached.
+   * Background tail of {@link initQuery}: enqueue the `register` down-event,
+   * then instant-hydrate (opt-in via `config.instantHydrate`, and only when
+   * the query is cold). Never rejects — both halves catch and log, so
+   * `void`-ing the returned promise can't produce an unhandled rejection. By
+   * default (hydrate off) the register lifecycle is the single freshness path;
+   * the one-shot fetch is an optimization apps enable explicitly, and it runs
+   * regardless of preload state — cache-first delivery never depends on WHY
+   * rows are cached.
+   *
+   * Register goes first on purpose. The hydrate used to run strictly before
+   * the enqueue, so a windowed list's one-shot read (a full-table scan when
+   * the app has no matching index) held its own registration back by seconds
+   * per window. Now whichever answer lands first paints; a hydrate that
+   * arrives after the registration is dropped (`applyHydration`).
    */
   private async finishQueryInit(
     hash: string,
     q: InnerQuery<any, any, any>,
     params: Record<string, any>
   ): Promise<void> {
+    try {
+      await this.sync.enqueueDownEvent({
+        type: 'register',
+        payload: {
+          hash,
+        },
+      });
+    } catch (err) {
+      this.logger.error(
+        { err, hash, Category: 'sp00ky-client::Sp00kyClient::initQuery' },
+        'Failed to enqueue register down-event'
+      );
+    }
+
     if (this.config.instantHydrate === true && this.dataModule.isCold(hash)) {
       try {
         // Fence against bucket switches: rows fetched under the previous
@@ -1504,20 +1525,6 @@ export class Sp00kyClient<S extends SchemaStructure> {
         }
       }
     }
-
-    try {
-      await this.sync.enqueueDownEvent({
-        type: 'register',
-        payload: {
-          hash,
-        },
-      });
-    } catch (err) {
-      this.logger.error(
-        { err, hash, Category: 'sp00ky-client::Sp00kyClient::initQuery' },
-        'Failed to enqueue register down-event'
-      );
-    }
   }
 
   /**
@@ -1704,6 +1711,18 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return fn(this.remote.getClient());
   }
 
+  /**
+   * Run one raw SurrealQL statement on the remote through the client's own
+   * query path: the connect gate (it never runs on a socket whose namespace
+   * and token are not applied yet), the per-statement timeout and the
+   * concurrency limit. Prefer this over {@link useRemote} for one-shot reads
+   * such as counts; `useRemote` hands out the bare SDK client and raced a
+   * reconnect with "Specify a namespace to use".
+   */
+  async remoteQuery<T extends unknown[]>(sql: string, vars?: Record<string, unknown>): Promise<T> {
+    return this.remote.query<T>(sql, vars);
+  }
+
   /**
    * Mint the salt used for query-id hashing, so two sessions registering the
    * same logical query get distinct `_00_query` rows.

package/src/types.ts

@@ -596,6 +596,11 @@ export interface QueryState {
   /** Set once `applyHydration` has run for this query, so the cold instant-hydrate
    * path fires at most once per query (see DataModule.isCold/applyHydration). */
   hydrated?: boolean;
+  /** Set once a server-side membership set has been accepted this session
+   * (`updateQueryRemoteArray`). The `register` down-event is enqueued before
+   * the instant-hydrate, so a hydrate that finishes later must not prime
+   * membership over the authoritative set. Ephemeral. */
+  serverMembership?: boolean;
   /** Set once `notifyQuerySynced` has emitted for this registration lifetime.
    * Ephemeral (unlike the persisted `updateCount`), so a re-registered query
    * always emits at least once even when its records are unchanged — otherwise