@spooky-sync/core 0.0.1-canary.102 → 0.0.1-canary.104

package/dist/index.d.ts

@@ -54,9 +54,62 @@ declare abstract class AbstractDatabaseService {
 declare class LocalDatabaseService extends AbstractDatabaseService {
   private config;
   protected eventType: "DATABASE_LOCAL_QUERY";
+  /** Bucket currently open. Set by `connect`/`switchStore`. */
+  private bucketId;
+  /**
+   * Monotonic store generation. Bumped on every `switchStore`. Async chains
+   * that read from the store, await something remote, and then write back
+   * (sync poll, SSP stream updates) capture this at chain start and drop
+   * their write when it no longer matches — a stale-epoch write would land
+   * another user's data in the new bucket.
+   */
+  private storeEpoch;
+  /** Gate that `query()`/`execute()` await; closed for the switch window. */
+  private gate;
+  /** The incoming client while a switch is in flight (for unload cleanup). */
+  private pendingSwitchClient;
   constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
   getConfig(): Sp00kyConfig<any>['database'];
-  connect(): Promise<void>;
+  get currentBucketId(): string;
+  get epoch(): number;
+  /**
+   * Close the query gate for a bucket switch. Every `query()`/`execute()`
+   * issued after this waits until the returned release fn runs — so work
+   * triggered mid-switch (sibling auth subscribers registering queries)
+   * lands on the NEW bucket instead of racing the swap. The migrator uses
+   * `queryUngated()` to provision the new bucket while the gate is closed.
+   */
+  beginSwitch(): () => void;
+  query<T extends unknown[]>(query: string, vars?: Record<string, unknown>, opts?: {
+    epoch?: number;
+  }): Promise<T>;
+  execute<T>(query: SealedQuery<T>, vars?: Record<string, unknown>, opts?: {
+    epoch?: number;
+  }): Promise<T>;
+  /** Gate-bypassing query — ONLY for the switch path itself (schema
+   *  provisioning must run while the gate is closed, or it deadlocks). */
+  queryUngated<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T>;
+  connect(bucketId?: string): Promise<void>;
+  /**
+   * Switch the local store to another user's bucket. Opens the NEW bucket on a
+   * second client first (with the same 3-tier recovery), then atomically swaps
+   * `this.client` and closes the old one — a failed open never leaves the
+   * service on a dead client. Bumps the store epoch so in-flight old-bucket
+   * async chains can detect they're stale.
+   *
+   * Callers own the drain/rebind choreography (close the gate, quiesce sync +
+   * timers BEFORE calling this; re-provision + rebind AFTER).
+   */
+  switchStore(bucketId: string): Promise<void>;
+  /**
+   * Open `storeUrl` on `client` with tiered recovery:
+   * tier 1 retries the same store (transient idb-handle races — preserves the
+   * cache), tier 2 drops THIS bucket's IndexedDB store and reconnects fresh,
+   * tier 3 falls back to `mem://` for the session. Only ever drops the bucket
+   * being opened — other users' buckets hold their own caches AND un-pushed
+   * mutation outboxes, which must survive another bucket's corruption.
+   */
+  private openWithRecovery;
   private unloadCloseRegistered;
   /**
    * Close the local DB on page unload so the SurrealDB-WASM worker releases its
@@ -67,6 +120,7 @@ declare class LocalDatabaseService extends AbstractDatabaseService {
    * reload, making warm loads as slow as cold ones. `pagehide` is the reliable
    * unload signal (fires on bfcache + normal navigation); `close()` is async but
    * the WASM worker initiates the IndexedDB connection teardown synchronously.
+   * Also closes a mid-switch incoming client so its fresh handle doesn't linger.
    */
   private registerUnloadClose;
   private openStore;
@@ -187,6 +241,8 @@ declare class StreamProcessorService {
   private batching;
   private batchBuffer;
   private sessionAuth;
+  private stateKeySuffix;
+  private stateGeneration;
   constructor(events: EventSystem<StreamProcessorEvents>, db: LocalDatabaseService, persistenceClient: PersistenceClient, logger: Logger);
   /**
    * Add a receiver for stream updates.
@@ -234,6 +290,19 @@ declare class StreamProcessorService {
    * This must be called before using other methods.
    */
   init(): Promise<void>;
+  /** Route the persisted circuit snapshot to a per-bucket key. */
+  setStateKeySuffix(bucketId: string): void;
+  private stateKey;
+  /**
+   * Drop the current WASM processor and start a fresh, empty circuit. Used on
+   * local-bucket switches: the old circuit holds the previous user's rows AND
+   * views registered with the previous `$auth` context, so neither may survive.
+   * Deliberately does NOT `loadState()` — a persisted snapshot references views
+   * under a dead sessionId salt; the DataModule rebind re-registers every live
+   * view against this fresh processor. Caller must re-seed `setPermissions`
+   * afterwards (a fresh circuit default-denies every table).
+   */
+  reset(): Promise<void>;
   loadState(): Promise<void>;
   /**
    * Seed per-table `select` permission predicates ({ [table]: whereText }).
@@ -309,6 +378,9 @@ declare class CacheModule implements StreamUpdateReceiver {
    */
   onStreamUpdate(update: StreamUpdate): void;
   lookup(recordId: string): number;
+  /** Drop the version cache on a bucket switch — a stale version would make
+   *  the sync diff skip fetching a body the new bucket legitimately needs. */
+  clearVersionLookups(): void;
   /**
    * Save a single record to local DB and ingest into DBSP
    * Used by mutations (create/update)
@@ -360,6 +432,8 @@ declare class DataModule<S extends SchemaStructure> {
   private statusSubscriptions;
   private mutationCallbacks;
   private debounceTimers;
+  private pendingStreamUpdates;
+  private fetchDepth;
   private logger;
   /**
    * Optional observer notified whenever a query's fetch status changes.
@@ -432,6 +506,15 @@ declare class DataModule<S extends SchemaStructure> {
    * query is unknown.
    */
   setQueryStatus(queryHash: string, status: QueryStatus): void;
+  /**
+   * Enter a fetch cycle for a query. Refcounted: registration and concurrent
+   * poll/LIVE sync rounds can overlap on the same hash, and only the OUTERMOST
+   * cycle may flip the status — 0→1 emits `fetching`, and `endFetching`'s 1→0
+   * emits `idle`. Always pair with `endFetching` in a `finally`.
+   */
+  beginFetching(queryHash: string): void;
+  /** Leave a fetch cycle started with {@link beginFetching}; emits `idle` on the last exit. */
+  endFetching(queryHash: string): void;
   /**
    * Subscribe to mutations (for sync)
    */
@@ -440,6 +523,14 @@ declare class DataModule<S extends SchemaStructure> {
    * Handle stream updates from DBSP (via CacheModule)
    */
   onStreamUpdate(update: StreamUpdate): Promise<void>;
+  /**
+   * Process a query's pending (debounced) stream update NOW instead of on the
+   * trailing edge. Called by the sync engine before it flips a query back to
+   * `idle`, so the status change never races ahead of the rows it fetched.
+   * No-op when nothing is pending. The pending entry is removed before the
+   * await so a concurrently-firing timer can't process it twice.
+   */
+  flushPendingStreamUpdate(queryHash: string): Promise<void>;
   private materializeRecords;
   private processStreamUpdate;
   /**
@@ -528,6 +619,28 @@ declare class DataModule<S extends SchemaStructure> {
   getActiveQueryHashes(): QueryHash[];
   updateQueryLocalArray(id: string, localArray: RecordVersionArray): Promise<void>;
   updateQueryRemoteArray(hash: string, remoteArray: RecordVersionArray): Promise<void>;
+  /**
+   * 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
+   * per-query TTL heartbeats (they'd refresh the previous user's remote
+   * `_00_query` rows under the new session). The rebind re-arms heartbeats.
+   */
+  quiesce(): void;
+  /**
+   * Re-home every active query in a freshly-opened bucket, KEEPING its hash —
+   * `useQuery` subscriptions are keyed by hash and don't re-register on auth
+   * changes, so the hooks must stay attached. Per query:
+   *   1. reset the sync arrays + hydration flag and drop the previous user's
+   *      records, notifying subscribers with the new-bucket materialization
+   *      (usually empty) so their rows leave the UI immediately;
+   *   2. recreate the `_00_query` row in the new bucket;
+   *   3. re-register the SSP view on the (fresh, post-reset) processor — this
+   *      also rebinds the view to the NEW `$auth` context;
+   *   4. restart the TTL heartbeat.
+   * Returns the hashes so the caller can enqueue remote re-registration, which
+   * refills records from the server via the normal register→sync→notify path.
+   */
+  rebindAfterBucketSwitch(): Promise<QueryHash[]>;
   /**
    * Called after a query's initial sync completes.
    * Ensures subscribers are notified even if no stream updates fired (e.g. empty result set).
@@ -624,6 +737,7 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private liveQueryUnsubscribe;
   private listRefPollTimer;
   private listRefPollRunning;
+  private listRefPollInFlight;
   readonly refSyncIntervalMs: number;
   private listRefIdleStreak;
   private stillRemoteStreaks;
@@ -674,6 +788,25 @@ declare class Sp00kySync<S extends SchemaStructure> {
    * @throws Error if already initialized.
    */
   init(): Promise<void>;
+  /**
+   * 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
+   * loop is stopped AND its in-flight tick awaited, LIVE is killed, debounce
+   * timers are cancelled (their outbox rows are already persisted), and the
+   * scheduler has drained its in-flight queue item — including that item's
+   * outbox-row delete, which must land in the OLD bucket. Queued down-events
+   * are dropped (they reference old-bucket query rows; the post-switch rebind
+   * re-enqueues registrations). The old user's un-pushed outbox is deliberately
+   * NOT drained: the remote session already belongs to the next user.
+   */
+  prepareBucketSwitch(): Promise<void>;
+  /**
+   * Resume syncing against the freshly-opened bucket: reload the mutation
+   * outbox from ITS `_00_pending_mutations` (the new user's own un-pushed
+   * offline work) and restart the scheduler. LIVE + the list_ref poll restart
+   * via the `setCurrentUserId` call that follows in the auth listener.
+   */
+  completeBucketSwitch(): Promise<void>;
   /**
    * Push the authenticated user's record id from the parent client's
    * auth subscription. Tears down the existing `_00_list_ref` LIVE (if
@@ -894,7 +1027,15 @@ declare class CrdtField {
   /** Whether the LoroDoc was loaded from saved CRDT state */
   hasContent(): boolean;
   startSync(local: LocalDatabaseService, remote: RemoteDatabaseService, recordId: string, sessionId: string, debounceMs: number): void;
-  stopSync(): void;
+  /**
+   * Stop syncing this field. Flushes one final remote push by default so the
+   * last keystrokes aren't lost. Pass `{ flush: false }` on a bucket switch —
+   * the remote session already belongs to the NEXT user, and pushing this
+   * (previous user's) snapshot under it would clobber the record remotely.
+   */
+  stopSync(options?: {
+    flush?: boolean;
+  }): void;
   importRemote(state: Uint8Array): void;
   exportSnapshot(): Uint8Array;
   /** Push this session's cursor blob into the parent row at
@@ -969,7 +1110,14 @@ declare class CrdtManager {
    */
   open(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
   close(table: string, recordId: string, field: string): void;
-  closeAll(): void;
+  /**
+   * Close every open field + table LIVE. Fields flush a final remote push by
+   * default; pass `{ flush: false }` on a bucket switch, where that flush
+   * would push the previous user's snapshot under the next user's session.
+   */
+  closeAll(options?: {
+    flush?: boolean;
+  }): void;
   /** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
    *  every open CrdtField on `table`. */
   private ensureTableSubscription;
@@ -1115,6 +1263,35 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    */
   private setupCallbacks;
   init(): Promise<void>;
+  private bucketSwitchChain;
+  private pendingBucketTarget;
+  /**
+   * Ensure the local store is this user's bucket, switching if needed. Called
+   * from the auth listener on every auth flip; concurrent calls are chained
+   * and superseded intermediates are skipped (latest target wins).
+   */
+  private ensureLocalBucket;
+  /**
+   * The bucket-switch choreography: drain → swap → rebind.
+   *
+   * Drain: sync quiesced (poll/LIVE stopped, in-flight round awaited so its
+   * outbox delete lands in the OLD bucket, debounce timers cancelled),
+   * DataModule timers cleared, CRDT fields closed WITHOUT their final flush
+   * (the remote session already belongs to the next user).
+   *
+   * Swap: gate closes so any local query issued mid-switch (sibling auth
+   * subscribers, FeatureFlagModule) waits and then runs against the NEW
+   * bucket; store swaps open-new-before-close-old; schema provisions
+   * (no-op for a returning bucket); stale `_00_query` rows are wiped (dead
+   * sessionId-salted hashes with stale arrays — record bodies stay warm);
+   * SSP resets to a fresh circuit with re-seeded permissions.
+   *
+   * Rebind: auth token re-persisted (the surrealdb persistence client wrote it
+   * into the OLD bucket's `_00_kv` before this listener ran), active queries
+   * re-homed keeping their hashes, sync resumed on the new bucket's own
+   * outbox, and every query re-registered remotely to refill from the server.
+   */
+  private doSwitchBucket;
   close(): Promise<void>;
   /**
    * Subscribe to a feature flag for the current user. Returns a