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

package/src/sp00ky.ts

@@ -10,6 +10,7 @@ import type {
   RunOptions,
   SyncHealth,
   StorageHealth,
+  QueryAuthorityCallback,
 } from './types';
 import {
   ConnectionSupervisor,
@@ -400,6 +401,21 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.sync.subscribeToPendingMutations(cb);
   }
 
+  /** Number of queries mid-fetch right now. See {@link subscribeToFetchActivity}. */
+  get fetchingQueryCount(): number {
+    return this.dataModule.fetchingQueryCount;
+  }
+
+  /**
+   * Observe how many queries are fetching from the server. Fires immediately
+   * with the current count and again on every change, so one subscription can
+   * drive a "downloading" indicator for the whole app. Pair with
+   * {@link subscribeToPendingMutations} for the "uploading" half.
+   */
+  subscribeToFetchActivity(cb: (fetching: number) => void): () => void {
+    return this.dataModule.subscribeActivity(cb, { immediate: true });
+  }
+
   /** Current sync-health snapshot. See {@link Sp00kyConfig.syncHealth}. */
   get syncHealth(): SyncHealth {
     return this.sync.syncHealth;
@@ -737,6 +753,20 @@ export class Sp00kyClient<S extends SchemaStructure> {
       });
     };
 
+    // The server no longer has the `_00_query` row of a query we hold
+    // membership for (TTL sweep, SSP reset, scheduler wipe). Rebuild the view
+    // through the ordinary register path; `register` events coalesce in the
+    // down queue, so a lost view costs one registration however many reads
+    // noticed it. Local state is untouched until the new set lands.
+    this.dataModule.onViewLost = (queryHash) => {
+      this.devTools.logEvent('QUERY_VIEW_LOST', { queryHash });
+      this.sync.enqueueDownEvent({ type: 'register', payload: { hash: queryHash } });
+    };
+
+    this.dataModule.onQueryAuthorityChange = (queryHash, known) => {
+      this.devTools.logEvent('QUERY_AUTHORITY_CHANGED', { queryHash, known });
+    };
+
     // Eager teardown of an opt-in deregistered query: enqueue a `cleanup`
     // down-event so it's serialized after any in-flight register/sync for the
     // same query (avoids out-of-order delete-before-create).
@@ -1000,7 +1030,25 @@ export class Sp00kyClient<S extends SchemaStructure> {
           this.sync.releaseViewsOnUnload();
         };
         window.addEventListener('pagehide', onPageHide);
-        this.detachUnloadRelease = () => window.removeEventListener('pagehide', onPageHide);
+        // Re-assert liveness the moment a throttled tab is back in front, or
+        // the network is back: the sweep may have taken views while the TTL
+        // timers were frozen, and `heartbeatQuery` rebuilds a swept view. Only
+        // watched queries beat, and never twice within 30s.
+        const onWake = () => {
+          if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return;
+          this.dataModule.heartbeatOnWake();
+        };
+        if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+          document.addEventListener('visibilitychange', onWake);
+        }
+        window.addEventListener('online', onWake);
+        this.detachUnloadRelease = () => {
+          window.removeEventListener('pagehide', onPageHide);
+          window.removeEventListener('online', onWake);
+          if (typeof document !== 'undefined' && typeof document.removeEventListener === 'function') {
+            document.removeEventListener('visibilitychange', onWake);
+          }
+        };
       }
 
       this.featureFlags.init();
@@ -1648,6 +1696,21 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.dataModule.subscribeStatus(queryHash, callback, options);
   }
 
+  /**
+   * Subscribe to a query's authority flips: `true` once server membership is
+   * known for it (a registration or poll landed, or a durable `_00_window`
+   * seed was read on boot), `false` when it is reset (bucket switch). With
+   * `{ immediate: true }` the callback fires synchronously with the current
+   * value. Powers the bindings' `isAuthoritative()` / cold-only `isLoading()`.
+   */
+  subscribeQueryAuthority(
+    queryHash: string,
+    callback: QueryAuthorityCallback,
+    options?: { immediate?: boolean }
+  ): () => void {
+    return this.dataModule.subscribeAuthority(queryHash, callback, options);
+  }
+
   /**
    * Report the frontend processing time (ms) a client framework spent applying
    * an update for a query (e.g. `useQuery`'s `reconcile()`), so DevTools/MCP can

package/src/types.ts

@@ -530,32 +530,6 @@ export interface QueryConfig {
    * by an old client that mirrored unflushed reads still self-heals.
    */
   membershipKnown?: boolean;
-  /**
-   * Whether a NON-EMPTY id-set has arrived from the server for this query in
-   * this session. Gates whether an empty read may be believed.
-   *
-   * The server publishes `_00_list_ref` asynchronously — the SSP queues a
-   * view's initial edges to a coalescing flusher and returns from
-   * `fn::query::register` before they land — so an empty read right after
-   * registration says nothing about the query being empty. Believing it (and
-   * mirroring it to the durable `_00_window` row) blanked lists and kept them
-   * blank across reloads. Once a real set has been seen, a later empty one is a
-   * genuine transition and must be honoured, or removed rows resurrect.
-   *
-   * In-memory only: a fresh session must re-earn the right to believe empties.
-   * What does persist is the `confirmed` marker on the `_00_window` row, which
-   * an empty set earns when it arrives with a server row count of zero or after
-   * a non-empty set in the same session.
-   */
-  remoteSeen?: boolean;
-  /**
-   * Consecutive empty id-sets read from the server while `remoteSeen` is still
-   * false. Bounds how long an unconfirmed empty may be ignored, so a window
-   * that genuinely emptied while this device was away is believed on the second
-   * read instead of rendering stale rows forever. Reset by any non-empty set.
-   * In-memory only.
-   */
-  emptyReads?: number;
   /**
    * Key of this query's durable `_00_window` membership row: a hash of
    * `{surql, params}` WITHOUT the `session::id()` salt that `id` carries, so it
@@ -585,6 +559,30 @@ export type QueryConfigRecord = QueryConfig & { id: string };
  */
 export type QueryStatus = 'idle' | 'fetching';
 
+/**
+ * What the server's `_00_query` row says about a view, read alongside its
+ * `_00_list_ref` edges (registration, the poll, a targeted re-read).
+ *
+ * - `present: false`: the row is not there (or not readable). The SSP no
+ *   longer has this view: a TTL sweep, an SSP reset, a scheduler wipe. An
+ *   empty edge set read at the same time is NOT "no rows", it is "no view".
+ * - `state: 'materializing'`: the SSP has (re)computed the set and its edges
+ *   are in flight; an empty read is "not landed yet".
+ * - `state: 'ready'`: the edges are committed (flipped in the same
+ *   transaction), so `rowCount === 0` with no edges is a real empty result.
+ * - `state: null`: a server that predates the marker; only `rowCount` can be
+ *   used, with its `> 0` = flush window / `0` = empty ambiguity.
+ */
+export interface ServerViewMeta {
+  present: boolean;
+  /** `_00_query.rowCount`; `null` when unreadable. */
+  rowCount: number | null;
+  state: 'materializing' | 'ready' | null;
+}
+
+/** Outcome of handing a server id-set to `DataModule.updateQueryRemoteArray`. */
+export type MembershipOutcome = 'applied' | 'ignored' | 'view-lost';
+
 /**
  * Internal state of a live query.
  */
@@ -601,6 +599,15 @@ export interface QueryState {
    * the instant-hydrate, so a hydrate that finishes later must not prime
    * membership over the authoritative set. Ephemeral. */
   serverMembership?: boolean;
+  /**
+   * Set when the server's `_00_query` row for this query went missing while
+   * we held membership (TTL sweep, SSP reset, scheduler wipe). The view is
+   * being re-registered; until a readable row comes back, empty reads are
+   * NOT the server's answer and nothing is dropped. Ephemeral.
+   */
+  viewLost?: boolean;
+  /** Last `_00_query.state` read from the server, for DevTools. Ephemeral. */
+  serverState?: 'materializing' | 'ready' | null;
   /** 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
@@ -610,6 +617,8 @@ export interface QueryState {
   ttlTimer: NodeJS.Timeout | null;
   /** TTL duration in milliseconds. */
   ttlDurationMs: number;
+  /** When the last TTL heartbeat for this query was sent (ms epoch); `undefined` before the first. */
+  lastHeartbeatAt?: number;
   /** Number of times the query has been updated. */
   updateCount: number;
   /** Timestamp (ms) of the last user-visible update, or null before the first
@@ -695,6 +704,12 @@ export interface QueryTimings {
 // Callback types
 export type QueryUpdateCallback = (records: Record<string, any>[]) => void;
 export type QueryStatusCallback = (status: QueryStatus) => void;
+/**
+ * Observer for a query's authority flips: `true` once server membership is
+ * known for it (registration, poll, durable seed), `false` when it is reset
+ * (bucket switch). What the bindings' `isAuthoritative()` mirrors.
+ */
+export type QueryAuthorityCallback = (known: boolean) => void;
 export type MutationCallback = (mutations: UpEvent[]) => void;
 
 export type MutationEventType = 'create' | 'update' | 'delete';

package/src/utils/error-classification.test.ts

@@ -29,6 +29,16 @@ describe('classifySyncError', () => {
     expect(classifySyncError(new Error(message))).toBe('network');
   });
 
+  it.each([
+    // SurrealDB optimistic-concurrency conflict: retryable by definition.
+    'Transaction conflict: Resource busy: . This transaction can be retried',
+    // Session state not re-applied yet after the SDK's reconnect handshake.
+    'Specify a namespace to use',
+    'Specify a database to use',
+  ])('classifies transient server state %j as network (retry, never rollback)', (message) => {
+    expect(classifySyncError(new Error(message))).toBe('network');
+  });
+
   it.each([
     'Permission denied',
     'There was a problem with the database: record already exists',

package/src/utils/error-classification.ts

@@ -19,6 +19,24 @@ const NETWORK_ERROR_PATTERNS = [
   'enotfound',
   'epipe',
   'abort',
+  // Transient server-side states that are NOT the mutation's fault and clear
+  // on their own, so the outbox must retry them rather than roll the write
+  // back. Seen 2026-09-08 on whitepawn: a 1200-game import lost 752 games and
+  // ~1500 player_name rows because every queued CREATE that hit one of these
+  // during a DB stall + WebSocket reconnect was classified `application`,
+  // rolled back locally and discarded - silent data loss.
+  //
+  // - SurrealDB optimistic-concurrency conflicts: "Transaction conflict:
+  //   Resource busy: . This transaction can be retried".
+  // - A socket whose namespace/identity has not been re-applied yet after the
+  //   SDK's own reconnect handshake: "Specify a namespace to use" /
+  //   "Specify a database to use". The statement is fine; the session is not
+  //   ready.
+  'transaction conflict',
+  'resource busy',
+  'can be retried',
+  'specify a namespace',
+  'specify a database',
 ];
 
 export function classifySyncError(error: unknown): 'network' | 'application' {