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

package/AGENTS.md

@@ -23,7 +23,7 @@ Local mutations are applied optimistically, ingested into a DBSP layer that driv
 
 ## Key exports (`src/index.ts`)
 
-- `Sp00kyClient<S>` — main class. Methods: `init()`, `create(id, payload)`, `update(table, id, payload, options?)`, `delete(table, idOrSelector)`, `query(table, opts?)`, `run(backend, route, payload)`, `bucket(name)`, `remoteQuery(sql, vars?)`, `useRemote(fn)`, `authenticate(token)`, `signOut()`. Plus `pendingMutationCount` and `subscribeToPendingMutations(cb)`.
+- `Sp00kyClient<S>` — main class. Methods: `init()`, `create(id, payload)`, `update(table, id, payload, options?)`, `delete(table, idOrSelector)`, `query(table, opts?)`, `run(backend, route, payload)`, `bucket(name)`, `remoteQuery(sql, vars?)`, `useRemote(fn)`, `authenticate(token)`, `signOut()`. Plus `pendingMutationCount` / `subscribeToPendingMutations(cb)` (outbox depth) and `fetchingQueryCount` / `subscribeToFetchActivity(cb)` (queries mid-fetch, aggregate) for traffic indicators.
 - `BucketHandle` — file storage handle (`put`, `get`, `delete`, `exists`), plus the cache-aware `read`, `url`, `pin`/`unpin`, `evict`, `prefetch`. `get` is always remote; `read`/`url` go through the blob cache.
 - `services/blobs/` — durable cache for bucket bytes: OPFS holds the files, `_00_blob` holds a manifest that reconcile rebuilds from disk (so a wiped local store costs metadata, not the offline cache). Nothing expires on a timer; eviction is LRU under a byte budget only, skipping pinned and on-screen entries. Config: `blobCache` in `types.ts`.
 - `AuthService` — token management, sign-in/sign-out events.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as Sp00kyQueryResultPromise, B as LocalStore, C as ReconnectConfig, D as RunOptions, E as RegistrationTimings, F as SyncHealthConfig, G as SyncEventSystem, H as DatabaseEventSystem, I as SyncHealthStatus, K as EventDefinition, L as TimingPhase, M as StorageHealthStatus, N as StoreType, O as Sp00kyConfig, P as SyncHealth, R as UpdateOptions, S as QueryUpdateCallback, T as RecordVersionDiff, U as DatabaseEventTypes, V as SealedQuery, W as Logger$1, _ as QueryState, a as MATERIALIZATION_SAMPLE_WINDOW, b as QueryTimeToLive, c as MutationEventType, d as PinoTransmit, f as PreloadOptions, g as QueryHash, h as QueryConfigRecord, i as Level, j as StorageHealth, k as Sp00kyQueryResult, l as PersistenceClient, m as QueryConfig, n as DebounceOptions, o as MutationCallback, p as PreloadRefresh, q as EventSystem, r as EventSubscriptionOptions, s as MutationEvent, t as ConnectionState, u as PhaseStat, v as QueryStatus, w as RecordVersionArray, x as QueryTimings, y as QueryStatusCallback, z as UpEvent } from "./types.js";
+import { A as ServerViewMeta, B as TimingPhase, C as QueryTimings, D as RecordVersionDiff, E as RecordVersionArray, F as StorageHealthStatus, G as DatabaseEventSystem, H as UpEvent, I as StoreType, J as SyncEventSystem, K as DatabaseEventTypes, L as SyncHealth, M as Sp00kyQueryResult, N as Sp00kyQueryResultPromise, O as RegistrationTimings, P as StorageHealth, R as SyncHealthConfig, S as QueryTimeToLive, T as ReconnectConfig, U as LocalStore, V as UpdateOptions, W as SealedQuery, X as EventSystem, Y as EventDefinition, _ as QueryConfigRecord, a as MATERIALIZATION_SAMPLE_WINDOW, b as QueryStatus, c as MutationEvent, d as PhaseStat, f as PinoTransmit, g as QueryConfig, h as QueryAuthorityCallback, i as Level, j as Sp00kyConfig, k as RunOptions, l as MutationEventType, m as PreloadRefresh, n as DebounceOptions, o as MembershipOutcome, p as PreloadOptions, q as Logger$1, r as EventSubscriptionOptions, s as MutationCallback, t as ConnectionState, u as PersistenceClient, v as QueryHash, w as QueryUpdateCallback, x as QueryStatusCallback, y as QueryState, z as SyncHealthStatus } from "./types.js";
 import * as surrealdb0 from "surrealdb";
 import { Duration, RecordId, Surreal as Surreal$1, SurrealEvents, SurrealTransaction } from "surrealdb";
 import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, FinalQuery, GetTable, QueryBuilder, QueryOptions, QueryPlan, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
@@ -733,10 +733,18 @@ declare class DataModule<S extends SchemaStructure> {
   private pendingQueries;
   private subscriptions;
   private statusSubscriptions;
+  /** Observers of a query's authority (`membershipKnown`) flips, keyed like `statusSubscriptions`. */
+  private authoritySubscriptions;
   private mutationCallbacks;
   private debounceTimers;
   private pendingStreamUpdates;
   private fetchDepth;
+  /**
+   * Observers of the AGGREGATE fetch activity: how many queries are mid-fetch
+   * right now. What a "downloading" indicator in the app chrome hangs off,
+   * instead of subscribing to every query's status one by one.
+   */
+  private activitySubscriptions;
   private logger;
   /**
    * Optional observer notified whenever a query's fetch status changes.
@@ -754,6 +762,15 @@ declare class DataModule<S extends SchemaStructure> {
    * DataModule is constructed — mirrors `onQueryStatusChange`.
    */
   onHeartbeat?: (hash: QueryHash) => void;
+  /**
+   * Fired once per episode when the server's `_00_query` row for a query we
+   * hold membership for is found missing (see `updateQueryRemoteArray`). Wired
+   * by Sp00kyClient to enqueue a `register` down-event so the SSP rebuilds the
+   * view; the client keeps rendering what it has meanwhile.
+   */
+  onViewLost?: (hash: QueryHash) => void;
+  /** DevTools observer for authority flips; mirrors `onQueryStatusChange`. */
+  onQueryAuthorityChange?: (hash: QueryHash, known: boolean) => void;
   /**
    * Optional hook fired by {@link deregisterQuery} when an opt-in query (e.g. a
    * viewport-windowed list cancelling an off-screen window) loses its last
@@ -806,6 +823,22 @@ declare class DataModule<S extends SchemaStructure> {
   subscribeStatus(queryHash: string, callback: QueryStatusCallback, options?: {
     immediate?: boolean;
   }): () => void;
+  /**
+   * Subscribe to a query's authority flips: whether server membership is known
+   * for it. With `{ immediate: true }` the callback fires synchronously with
+   * the current value (`false` for an unknown query).
+   */
+  subscribeAuthority(queryHash: string, callback: QueryAuthorityCallback, options?: {
+    immediate?: boolean;
+  }): () => void;
+  /** Whether server membership is known for `queryHash` (see `QueryConfig.membershipKnown`). */
+  isAuthoritative(queryHash: string): boolean;
+  /**
+   * The single writer of `config.membershipKnown` for a live query. Fans out
+   * to `subscribeAuthority` listeners and DevTools on a change; no-op when
+   * unchanged or the query is unknown.
+   */
+  private setMembershipKnown;
   /**
    * Set a query's fetch status and notify status observers (DevTools +
    * `subscribeStatus` listeners). No-op when the status is unchanged or the
@@ -821,6 +854,18 @@ declare class DataModule<S extends SchemaStructure> {
   beginFetching(queryHash: string): void;
   /** Leave a fetch cycle started with {@link beginFetching}; emits `idle` on the last exit. */
   endFetching(queryHash: string): void;
+  /** How many queries are mid-fetch right now (see {@link subscribeActivity}). */
+  get fetchingQueryCount(): number;
+  /**
+   * Observe the number of queries currently fetching. Fires on every change of
+   * that number (a query entering or leaving its outermost fetch cycle), and
+   * synchronously with the current value when `immediate` is set. One
+   * subscription per indicator, however many queries the page holds.
+   */
+  subscribeActivity(callback: (fetching: number) => void, options?: {
+    immediate?: boolean;
+  }): () => void;
+  private notifyActivity;
   /**
    * Subscribe to mutations (for sync)
    */
@@ -1117,9 +1162,15 @@ declare class DataModule<S extends SchemaStructure> {
   getActiveQueryHashes(): QueryHash[];
   updateQueryLocalArray(id: string, localArray: RecordVersionArray): Promise<void>;
   updateQueryRemoteArray(hash: string, remoteArray: RecordVersionArray, opts?: {
-    /** `_00_query.rowCount` read in the same round trip; `null` = unknown. */
-    serverRowCount?: number | null;
-  }): Promise<void>;
+    /** The `_00_query` row as read in the same round trip as the edges. */
+    meta?: ServerViewMeta;
+    /**
+     * The caller verified upstream that the ids missing from `remoteArray`
+     * no longer exist (see `Sp00kySync` LIVE removal handling); an empty set
+     * is then a real answer even without a readable row.
+     */
+    verifiedRemoval?: boolean;
+  }): Promise<MembershipOutcome>;
   /**
    * Cancel every armed timer ahead of a local-bucket switch: stream-update
    * debounce timers (their pending updates carry the OLD bucket's id-sets) and
@@ -1205,6 +1256,26 @@ declare class DataModule<S extends SchemaStructure> {
   private calculateMembershipKey;
   private sha256;
   private startTTLHeartbeat;
+  /**
+   * Heartbeat every watched query NOW and re-anchor its timer.
+   *
+   * The TTL timer is the only thing keeping a view alive on the server, and
+   * browsers throttle timers in hidden tabs (Chrome aligns them to one-minute
+   * ticks after five minutes hidden, and suspends them outright on some
+   * mobile platforms). A tab that comes back after a long stretch may have
+   * missed its beat by more than the server's slack, and the sweep will have
+   * taken the row and its edges. The client does not blank on that any more
+   * (`updateQueryRemoteArray` treats a missing row as "view lost"), but the
+   * sooner it finds out, the sooner the view is rebuilt: `heartbeatQuery`
+   * re-registers a query whose row is gone. Called on `visibilitychange` (to
+   * visible) and `online`.
+   *
+   * Queries beaten within the last `minGapMs` are skipped, so a flurry of
+   * wake events costs one beat per query. There is deliberately no local
+   * expiry anywhere in this module: the TTL is the server's, and the client's
+   * only duty is to keep asserting liveness while something is watching.
+   */
+  heartbeatOnWake(minGapMs?: number): number;
   private replaceRecordInQueries;
 }
 /**
@@ -1653,6 +1724,25 @@ declare class Sp00kySync<S extends SchemaStructure> {
    * changed.
    */
   private applyListRefSnapshot;
+  /**
+   * Re-read ONE query's server state now (edges + `_00_query` row) and land
+   * it through {@link applyListRefSnapshot}. The targeted form of the poll,
+   * for the moments that cannot wait for the next tick: a registration that
+   * answered `materializing`, and a LIVE removal that has to be checked
+   * against the row before it may empty a painted list.
+   */
+  private refetchListRefForQuery;
+  /** Per-query pending targeted re-reads: one timer and the ladder still to walk. */
+  private listRefRefetches;
+  /**
+   * Schedule a targeted re-read of `queryHash` after `delays[0]` ms. If the
+   * read still says the server is publishing (`materializing`), the next rung
+   * of the ladder is armed; any other outcome ends it. Re-scheduling a hash
+   * that already has a timer replaces it (latest wins), so bursts coalesce.
+   */
+  private scheduleListRefRefetch;
+  private clearListRefRefetch;
+  private clearListRefRefetches;
   /**
    * Resolve the current `_00_list_ref` table name for the active auth
    * context. Public so the `createRemoteQuery` initial-fetch path can
@@ -1708,6 +1798,26 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private refetchAfterReconnect;
   private startRefLiveQueries;
   private handleRemoteListRefChange;
+  /** LIVE removals awaiting verification, per query, with their coalescing timer. */
+  private pendingLiveRemovals;
+  /**
+   * Hold a LIVE `_00_list_ref` DELETE for {@link LIVE_REMOVAL_COALESCE_MS},
+   * then verify the batch (see {@link flushLiveRemovals}). A sweep or a
+   * republish delivers a view's whole set as one burst, so one verification
+   * round covers it.
+   */
+  private queueLiveRemoval;
+  /**
+   * Verify a coalesced batch of LIVE removals against the upstream records.
+   * Ids that no longer exist upstream are dropped from membership (the body
+   * delete already happened inside `syncRecords`) and the query re-renders.
+   * Anything still present upstream - or a verification that could not run -
+   * is settled by a targeted re-read of the server's set for this query,
+   * where the `_00_query` row decides: gone = view lost (keep rows,
+   * re-register), `materializing` = wait, `ready` = adopt the smaller set.
+   */
+  private flushLiveRemovals;
+  private clearLiveRemovals;
   /**
    * Handle a LIVE change to a SUBQUERY child edge (a `_00_list_ref` row with
    * `parent` set) for a `.related()` query. Unlike primary rows, child rows
@@ -2623,6 +2733,15 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    *  suite can guard the pre-emptive path against regression. */
   get liveRetryCount(): number;
   subscribeToPendingMutations(cb: (count: number) => void): () => void;
+  /** Number of queries mid-fetch right now. See {@link subscribeToFetchActivity}. */
+  get fetchingQueryCount(): number;
+  /**
+   * 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;
   /** Current sync-health snapshot. See {@link Sp00kyConfig.syncHealth}. */
   get syncHealth(): SyncHealth;
   /**
@@ -2821,6 +2940,16 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   subscribeQueryStatus(queryHash: string, callback: QueryStatusCallback, options?: {
     immediate?: boolean;
   }): () => void;
+  /**
+   * 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;
   /**
    * 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
@@ -2936,4 +3065,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, Level, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, isBlurhashValid, isImagePath, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, Level, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, MembershipOutcome, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryAuthorityCallback, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, ServerViewMeta, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, isBlurhashValid, isImagePath, semverGt, textToHtml };