@spooky-sync/core 0.0.1-canary.202 → 0.0.1-canary.204

package/dist/index.d.ts

@@ -696,6 +696,13 @@ declare class DataModule<S extends SchemaStructure> {
   private resolveMembership;
   private readonly settledWrites;
   private readonly settledDeletes;
+  private pendingIds;
+  private pendingIdsAt;
+  private pendingIdsInflight;
+  private static readonly PENDING_IDS_TTL_MS;
+  /** Drop the cached outbox ids. Cheap; call it on anything that could change
+   *  `_00_pending_mutations`. */
+  private invalidatePendingIds;
   /**
    * Grace period for a settled write. Long enough to cover an SSP round trip
    * that is running slowly (seconds, not milliseconds, when the edge path is
@@ -841,6 +848,9 @@ declare class DataModule<S extends SchemaStructure> {
     writes: Set<string>;
     deletes: Set<string>;
   }>;
+  /** The uncached read. Also the reload path after an invalidation, so the ids
+   *  still survive a reload exactly as before. */
+  private readPendingRecordIds;
   /** True while ≥1 live subscriber is watching this query (refcount guard). */
   hasSubscribers(hash: string): boolean;
   /**
@@ -1079,6 +1089,15 @@ interface Sp00kySyncOptions {
    * up-queue for the session. Defaults to 30000; `0` disables the timeout.
    */
   pushTimeoutMs?: number;
+  /**
+   * Max time a single down event (`register`/`sync`/`cleanup`) may take before
+   * it is treated as a network failure and retried. The mirror of
+   * {@link pushTimeoutMs} for the read side, which had no such guard: a
+   * `fn::query::register` that never settled held its slot in the down drain,
+   * and every later registration behind it, for the rest of the session.
+   * Defaults to 30000; `0` disables the timeout.
+   */
+  downTimeoutMs?: number;
   /**
    * Transport supervisor. Sync reads its state to report `connection` in
    * {@link SyncHealth} so a UI can show "reconnecting…" the instant the socket
@@ -1148,6 +1167,7 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private readonly degradeAfterFailures;
   /** Per-push RPC deadline; see {@link withPushTimeout}. */
   private readonly pushTimeoutMs;
+  private readonly downTimeoutMs;
   private consecutiveSyncFailures;
   private syncHealthStatus;
   private lastSyncErrorKind;
@@ -1378,6 +1398,8 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private handleMutationSettled;
   private handleRollback;
   private processDownEvent;
+  private withDownTimeout;
+  private runDownEvent;
   /**
    * Synchronizes a specific query by hash.
    * Compares local and remote version arrays and fetches differences.
@@ -1471,6 +1493,24 @@ declare class AuthService<S extends SchemaStructure> {
    */
   subscribe(cb: (userId: string | null) => void): () => void;
   private notifyListeners;
+  /**
+   * Restore a session from the locally cached JWT, with NO network.
+   *
+   * This is what makes a warm boot paint instantly and what makes an offline
+   * boot possible at all: the token is in local storage, and it already carries
+   * both the access method and the `$auth.id` record id. Everything the client
+   * needs to route queries (`setCurrentUserId`) and to satisfy `$auth`-gated
+   * permission predicates in the in-browser SSP (`setSessionAuth`) is therefore
+   * available before a socket exists.
+   *
+   * The session is OPTIMISTIC: the token is unverified here. `check()` runs
+   * afterwards in the background and downgrades to a real sign-out if the
+   * server rejects it. Nothing is trusted that the server has not also seen -
+   * the local store only ever holds rows the server previously sent.
+   *
+   * Returns the restored user id, or null when there is no usable token.
+   */
+  restoreSessionFromToken(): Promise<string | null>;
   /**
    * Check for existing session and validate
    */
@@ -2166,6 +2206,15 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private sync;
   private devTools;
   private crdtManager;
+  /**
+   * True once the LOCAL half of boot is done and the client can serve reads
+   * from the local store. Distinct from being connected: `syncHealth` covers
+   * reaching the server and `storageHealth` covers whether the local store is
+   * durable, but neither says "usable". Consumers gate their first paint on
+   * this, which is what makes a warm boot instant and an offline boot possible.
+   */
+  private localReady;
+  private saltUserId;
   private featureFlags;
   private appReleases;
   private preloadedHashes;
@@ -2211,6 +2260,16 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    */
   private setupCallbacks;
   init(): Promise<void>;
+  /**
+   * The network half of boot: connect, verify the restored session, and let the
+   * sync engine catch up. Runs in the background after `init()` has already
+   * resolved, so nothing here is on the paint path.
+   *
+   * Every step is best-effort. A failure leaves the client in exactly the state
+   * a warm offline boot is in - local reads working, writes queued in the
+   * outbox - and the connection supervisor keeps retrying underneath.
+   */
+  private initRemote;
   private bucketSwitchChain;
   private pendingBucketTarget;
   /**
@@ -2363,14 +2422,38 @@ declare class Sp00kyClient<S extends SchemaStructure> {
     [x: string]: /*elided*/any;
   }>;
   delete(table: string, id: string): Promise<void>;
-  useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T>;
   /**
-   * Fetch SurrealDB's `session::id()` as a string. Used as a salt for
-   * query-id hashing so two sessions for the same user get distinct
-   * `_00_query` rows. Returns empty string if the query fails (we still
-   * boot, just without session scoping for IDs).
+   * Whether the local store is initialized and reads can be served. See the
+   * `localReady` field: this is deliberately independent of connectivity.
    */
-  private fetchSessionId;
+  isLocalReady(): boolean;
+  useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T>;
+  /**
+   * Mint the salt used for query-id hashing, so two sessions registering the
+   * same logical query get distinct `_00_query` rows.
+   *
+   * Generated LOCALLY, deliberately. This used to be `RETURN <string>session::id()`,
+   * which cost a serial round trip on the critical boot path and resolved to
+   * `''` offline. The value never needed to come from the server: the server
+   * derives its own `clientId` inside `fn::query::register` and *ignores*
+   * whatever the caller passed, and the permission rules that matter gate on
+   * `auth_id = $auth.id` rather than the session (`_00_list_ref`). Session
+   * scoping via `clientId = session::id()` was in fact removed upstream because
+   * it broke a user with two tabs open. All this value has to be is unique per
+   * browser session, which `randomUUID` gives us for free and offline.
+   */
+  /**
+   * The current principal as the `"table:id"` string the in-browser SSP wants
+   * for `$auth.id`, or null when signed out.
+   *
+   * Tolerates BOTH shapes `currentUser.id` can take, which is the point:
+   * a session restored from the cached token carries a plain string (the JWT's
+   * `ID` claim), while one verified by the server carries a RecordId. Passing
+   * the former to `encodeRecordId` reads `.table` off a string and throws
+   * during boot.
+   */
+  private sessionAuthId;
+  private mintSessionSalt;
 }
 //#endregion
 //#region src/utils/semver.d.ts