@pylonsync/sync 0.3.198 → 0.3.201

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.198",
+  "version": "0.3.201",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -165,6 +165,23 @@ export class SyncEngine {
   private reconnectAttempts = 0;
   private persistence: import("./persistence").IndexedDBPersistence | null = null;
 
+  /**
+   * Flips true once `start()` has either:
+   *   - drained IndexedDB into the in-memory store (data path), OR
+   *   - decided the engine has no persistence layer (test / SSR / explicit opt-out).
+   *
+   * `useQuery`'s `loading` flag consumes this so apps don't render a
+   * "Loading…" flash on every page refresh when the disk replica
+   * already has the data. Without it, even returning visits show the
+   * spinner for the 50–200ms gap between component mount and IndexedDB
+   * `loadAllEntities()` resolving — visually identical to a true
+   * cold-start fetch.
+   */
+  private _hydrated = false;
+  isHydrated(): boolean {
+    return this._hydrated;
+  }
+
   readonly store: LocalStore;
   readonly mutations: MutationQueue;
 
@@ -395,7 +412,10 @@ export class SyncEngine {
         // subscribers re-read. Without this, if the subsequent pull returns
         // no changes (replica already at cursor), subscribers stay stuck on
         // their initial empty snapshot until the first WS event arrives.
+        this._hydrated = true;
         if (hydrated) this.store.notify();
+        else this.store.notify(); // notify even on empty cache so useQuery
+        // sees `isHydrated()` flip and can drop its initial loading state.
 
         // Load cursor.
         const savedCursor = await this.persistence.loadCursor();
@@ -439,6 +459,11 @@ export class SyncEngine {
         // IndexedDB not available — continue without persistence.
       }
     }
+    // Always flip `_hydrated` true by this point — even when persist
+    // was off or IndexedDB threw. useQuery's loading semantics depend
+    // on it; leaving false would pin every app with persist:false
+    // into a permanent "Loading…" state.
+    this._hydrated = true;
 
     // Seed the server-resolved session before the first pull so
     // `useSession` subscribers see the right tenant from frame one, and
@@ -458,10 +483,21 @@ export class SyncEngine {
     // the local IndexedDB has rows the server doesn't (deletes made by
     // another surface while this tab was closed, or events that fell
     // off the in-memory ChangeLog before this tab's cursor caught up).
-    // Fires after pull so we don't reconcile against rows that pull
-    // would have applied anyway. Errors are swallowed inside
-    // reconcileInner so a failed reconcile doesn't take down startup.
-    void this.reconcile();
+    //
+    // Deliberately NOT fired here anymore. Apps that select-org from
+    // a bootstrap effect race against this reconcile pass: the engine
+    // resolves /api/auth/me before selectOrg lands, tenant=null, the
+    // entity fetch returns 0 rows, every cached row gets tombstoned,
+    // and the user sees a "rows render then flash away" gap until
+    // selectOrg fires the session-changed envelope and the engine
+    // re-pulls. The visibility-change + WS-reconnect reconcile triggers
+    // below STILL run, so deletes made while the tab was closed
+    // converge on the next focus / reconnect — just not in the narrow
+    // window where the session might still be unresolved. Net effect:
+    // identical safety, no flash.
+    //
+    // The session-flip guard in reconcileInner is the second line of
+    // defense; this is the first. Belt + braces.
 
     // Wire the visibility-change reconcile so a tab that returns from
     // the background (laptop wakes, tab unhidden) catches up against
@@ -1217,13 +1253,29 @@ export class SyncEngine {
     // bypass the tombstone — re-creation server-side still propagates.
     const tombstoneSeq = this.cursor.last_seq;
     for (const entity of names) {
-      // Capture cursor BEFORE the fetch so we can detect drift mid-
-      // reconcile. If a WS event lands while this entity is being
-      // pulled, our snapshot is already stale — applying it would
-      // overwrite a newer authoritative row. Skip apply in that case
-      // and rely on the WS event plus the next reconcile trigger to
-      // converge.
+      // Capture cursor + resolved session BEFORE the fetch so we can
+      // detect drift mid-reconcile. Two distinct races:
+      //
+      //   1. Cursor moves: a WS event for this (or another) entity
+      //      landed while the page-paginated fetch was in flight. Our
+      //      snapshot is stale; applying it would clobber the fresher
+      //      WS-delivered row.
+      //
+      //   2. Session flips: the resolved tenant/user changed while
+      //      the fetch was in flight (e.g., the app called
+      //      /api/auth/select-org just after we issued the fetch).
+      //      The server filtered the response under the OLD tenant
+      //      context, so applying the result would tombstone rows
+      //      that ARE visible under the NEW tenant. This is the
+      //      "dashboard flashes data away on first load" bug — the
+      //      engine starts before the app calls selectOrg, fetches
+      //      under tenant=null, returns 0 rows, then the apply pass
+      //      nukes every locally-cached row. Skip the apply when
+      //      the session signature changed; the next reconcile
+      //      (triggered by session-changed envelope) will re-fetch
+      //      under the new context.
       const cursorBeforeFetch = this.cursor.last_seq;
+      const sessionBeforeFetch = sessionSignature(this._resolvedSession);
       let serverRows: Row[];
       try {
         serverRows = await this.fetchEntityRows(entity);
@@ -1248,6 +1300,14 @@ export class SyncEngine {
         // state for the affected row.
         continue;
       }
+      if (sessionSignature(this._resolvedSession) !== sessionBeforeFetch) {
+        // Session changed (token flipped, tenant switched, user
+        // signed out → in, etc.). The rows we fetched reflect the
+        // OLD session's policy view; applying them now would
+        // tombstone rows visible under the NEW session. Bail and let
+        // the session-changed envelope drive the next reconcile.
+        continue;
+      }
       await this.applyEntityReconcile(entity, serverRows, tombstoneSeq);
     }
   }
@@ -2132,6 +2192,19 @@ function rowsDiffer(a: Row, b: Row): boolean {
   return stableStringify(a) !== stableStringify(b);
 }
 
+/**
+ * Compact, comparable fingerprint of a resolved session. Used by
+ * reconcile() to detect mid-fetch identity flips — if the signature
+ * differs, the rows we just fetched were policy-filtered under a
+ * stale auth context and applying them would tombstone rows visible
+ * under the new context. Roles array is sorted+joined so insertion
+ * order doesn't trip the equality check.
+ */
+function sessionSignature(s: ResolvedSession): string {
+  const roles = (s.roles ?? []).slice().sort().join(",");
+  return `${s.userId ?? ""}|${s.tenantId ?? ""}|${s.isAdmin ? "1" : "0"}|${roles}`;
+}
+
 function stableStringify(value: unknown): string {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) {

package/src/reconcile.test.ts

@@ -284,6 +284,77 @@ describe("LocalStore.reconcileRemove", () => {
   });
 });
 
+describe("SyncEngine.reconcile session guard", () => {
+  // Regression for the "dashboard flashes data away on first load" bug.
+  // The engine starts before the app calls /api/auth/select-org, runs
+  // its initial pull + reconcile under tenant=null, and the
+  // policy-filtered entity fetch returns 0 rows — which then tombstones
+  // every IndexedDB-hydrated row from the previous session. Once the
+  // app calls selectOrg the rows reappear, but the user has already
+  // seen them flash.
+  //
+  // The guard: if the resolved session changes mid-fetch (token, tenant,
+  // user, isAdmin, or roles), reconcile MUST discard the result. The
+  // session-changed envelope queues another reconcile under the new
+  // identity.
+  test("skips apply when tenant flips during entity fetch", async () => {
+    let restore: (() => void) | null = null;
+    try {
+      restore = installFetch(async (url) => {
+        if (url.includes("/api/entities/Recording/cursor")) {
+          // Server filtered under stale tenant — returns empty. Without
+          // the guard, applyEntityReconcile would tombstone r1.
+          return {
+            status: 200,
+            body: { data: [], next_cursor: null, has_more: false },
+          };
+        }
+        return { status: 404, body: {} };
+      });
+
+      const engine = makeEngine();
+      seedStore(engine, "Recording", [{ id: "r1", title: "alive" }]);
+      expect(engine.store.list("Recording").length).toBe(1);
+
+      // Simulate the app calling select-org WHILE reconcile is mid-flight.
+      // The implementation reads `_resolvedSession` directly; we override
+      // via the engine's internal store mutation surface to match how the
+      // session-changed handler would update it during a real flip.
+      const engineWithSession = engine as unknown as {
+        _resolvedSession: {
+          userId: string | null;
+          tenantId: string | null;
+          isAdmin: boolean;
+          roles: string[];
+        };
+      };
+      engineWithSession._resolvedSession = {
+        userId: "u1",
+        tenantId: null,
+        isAdmin: false,
+        roles: [],
+      };
+      const reconcilePromise = engine.reconcile(["Recording"]);
+      // Flip the tenant before the fetch resolves. The microtask queue
+      // already has the in-flight fetch; this just changes the field
+      // they'll compare against.
+      engineWithSession._resolvedSession = {
+        userId: "u1",
+        tenantId: "org-42",
+        isAdmin: false,
+        roles: [],
+      };
+      await reconcilePromise;
+
+      // Row must survive — the stale fetch result was discarded.
+      expect(engine.store.list("Recording").length).toBe(1);
+      expect(engine.store.get("Recording", "r1")).not.toBeNull();
+    } finally {
+      restore?.();
+    }
+  });
+});
+
 describe("LocalStore.entityNames", () => {
   test("returns only entities with at least one row", () => {
     const engine = makeEngine();