@pylonsync/sync 0.3.366 → 0.3.368

package/dist/index.d.ts

@@ -56,6 +56,25 @@ export interface SyncEngineConfig {
      * becomes visible).
      */
     reconcileOnVisibility?: boolean;
+    /**
+     * Keep the local replica across ORG switches (same user). Default
+     * `true`: a tenant flip wipes the replica and re-bootstraps, because
+     * tenant-scoped read policies (`auth.tenantId == data.orgId`) mean
+     * the visible set genuinely changed.
+     *
+     * Set `false` ONLY when every synced entity's read policy is
+     * MEMBERSHIP-scoped (`exists(OrgMember where orgId == data.orgId and
+     * userId == auth.userId)`) — then the replica is valid across all the
+     * user's orgs at once, the wipe is pure waste, and an org switch
+     * becomes instant: components filter by the live `tenantId` while the
+     * engine runs a pull + reconcile in the background (which is what
+     * brings in rows of an org the user only just joined). With
+     * tenant-scoped policies this flag KEEPS STALE ROWS across switches —
+     * don't set it unless the policies match.
+     *
+     * USER flips (login/logout/account switch) always wipe regardless.
+     */
+    resetOnTenantFlip?: boolean;
     /**
      * Client → server keepalive interval (ms). The Pylon dev server's
      * dedicated :port+1 WS listener uses a dual-thread design where the

package/dist/test-harness/env.d.ts

@@ -19,6 +19,10 @@ export interface CreateTestEnvOptions {
      *  "poll" to disable the WS-onopen reconcile race in scenarios
      *  that only want to pin the in-start pipeline. */
     transport?: "websocket" | "poll" | "sse";
+    /** Passed through to the engine config — see SyncEngineConfig.
+     *  resetOnTenantFlip. Scenarios covering the member-scoped
+     *  no-wipe org switch set false. */
+    resetOnTenantFlip?: boolean;
     /** Base delay (ms) for WS reconnect backoff. The default value used
      *  inside the harness (`undefined` → 1000) introduces seconds of
      *  wall-clock waiting on every reconnect scenario; pass a small

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.366",
+  "version": "0.3.368",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -147,6 +147,25 @@ export interface SyncEngineConfig {
    * becomes visible).
    */
   reconcileOnVisibility?: boolean;
+  /**
+   * Keep the local replica across ORG switches (same user). Default
+   * `true`: a tenant flip wipes the replica and re-bootstraps, because
+   * tenant-scoped read policies (`auth.tenantId == data.orgId`) mean
+   * the visible set genuinely changed.
+   *
+   * Set `false` ONLY when every synced entity's read policy is
+   * MEMBERSHIP-scoped (`exists(OrgMember where orgId == data.orgId and
+   * userId == auth.userId)`) — then the replica is valid across all the
+   * user's orgs at once, the wipe is pure waste, and an org switch
+   * becomes instant: components filter by the live `tenantId` while the
+   * engine runs a pull + reconcile in the background (which is what
+   * brings in rows of an org the user only just joined). With
+   * tenant-scoped policies this flag KEEPS STALE ROWS across switches —
+   * don't set it unless the policies match.
+   *
+   * USER flips (login/logout/account switch) always wipe regardless.
+   */
+  resetOnTenantFlip?: boolean;
   /**
    * Client → server keepalive interval (ms). The Pylon dev server's
    * dedicated :port+1 WS listener uses a dual-thread design where the
@@ -2369,7 +2388,14 @@ export class SyncEngine {
       // new tenant while useQuery still has the old tenant's rows.
       const verdict = this.session.inspectSession(next);
       if (verdict.tenantChanged) {
-        if (verdict.replicaInvalidated) {
+        // `resetOnTenantFlip: false` — the app has declared its read
+        // policies MEMBERSHIP-scoped, so the replica is already valid
+        // for every org the user belongs to and the wipe would be pure
+        // waste (the "switch orgs → blank dashboard for seconds" cost).
+        // Only the TENANT verdict honors the flag; user flips (token
+        // change, guardReplicaIdentity) always wipe.
+        const skipReset = this.config.resetOnTenantFlip === false;
+        if (verdict.replicaInvalidated && !skipReset) {
           // Route reset through the public (queued) method so the
           // wipe serializes against in-flight pulls / WS-event
           // applies / pushes. sessionChain serializes session
@@ -2384,6 +2410,13 @@ export class SyncEngine {
           // Only the leader pulls — followers receive subsequent
           // applied broadcasts that close the catch-up window.
           await this.pull();
+          if (skipReset) {
+            // No wipe happened, so rows of an org the user only just
+            // JOINED aren't in the replica and no change event will
+            // re-deliver them (their events predate membership). The
+            // membership-scoped reconcile sweep upserts them.
+            void this.reconcile();
+          }
         }
       }
       this.session.commitObservation(next);

package/src/scenarios.test.ts

@@ -11,6 +11,7 @@
 
 import { afterEach, describe, expect, test } from "bun:test";
 
+import type { SyncEngine } from "./index";
 import { createTestEnv, type TestEnv } from "./test-harness";
 
 const tenantScopedVisibility = (
@@ -272,6 +273,39 @@ describe("sync scenarios", () => {
     expect(env.engine.store.get("Recording", "b1")).not.toBeNull();
   });
 
+  // MEMBER-SCOPED ORG SWITCH (pins resetOnTenantFlip: false). When every
+  // read policy is membership-scoped, the replica is valid across ALL the
+  // user's orgs at once — the tenant-flip wipe + from-zero re-bootstrap is
+  // pure waste (the "switch orgs → blank dashboard for seconds" cost). With
+  // the flag, a switch keeps every row and does NOT re-snapshot; the UI
+  // just filters by the live tenantId.
+  test("resetOnTenantFlip:false keeps the replica and skips the re-snapshot on org switch", async () => {
+    // Default visibility (no tenant filter) models membership-scoped reads:
+    // the caller sees every org's rows regardless of the active tenant.
+    env = createTestEnv({ transport: "poll", resetOnTenantFlip: false });
+    env.server.seed("Recording", [
+      { id: "a1", orgId: "org-a", title: "alice" },
+      { id: "b1", orgId: "org-b", title: "bob" },
+    ]);
+    env.signIn({ userId: "u1", tenantId: "org-a" });
+    await env.start();
+    await env.flush();
+    expect(env.engine.store.get("Recording", "a1")).not.toBeNull();
+    expect(env.engine.store.get("Recording", "b1")).not.toBeNull();
+
+    const snapshotsBefore = env.server.snapshotPullCount;
+    env.selectOrg("org-b");
+    await env.engine.notifySessionChanged();
+    await env.flush(100);
+
+    // No wipe: every org's rows survived the switch.
+    expect(env.engine.store.get("Recording", "a1")).not.toBeNull();
+    expect(env.engine.store.get("Recording", "b1")).not.toBeNull();
+    // No re-bootstrap: zero additional since=0 snapshot pulls. (The
+    // default-path test above proves the flag's absence still wipes.)
+    expect(env.server.snapshotPullCount - snapshotsBefore).toBe(0);
+  });
+
   // Reactive query subscription delivers a result over WS AND emits
   // the outbound `reactive-subscribe` envelope. Both directions of
   // the wire contract are pinned: the engine must SEND the

package/src/test-harness/env.ts

@@ -62,6 +62,10 @@ export interface CreateTestEnvOptions {
    *  "poll" to disable the WS-onopen reconcile race in scenarios
    *  that only want to pin the in-start pipeline. */
   transport?: "websocket" | "poll" | "sse";
+  /** Passed through to the engine config — see SyncEngineConfig.
+   *  resetOnTenantFlip. Scenarios covering the member-scoped
+   *  no-wipe org switch set false. */
+  resetOnTenantFlip?: boolean;
   /** Base delay (ms) for WS reconnect backoff. The default value used
    *  inside the harness (`undefined` → 1000) introduces seconds of
    *  wall-clock waiting on every reconnect scenario; pass a small
@@ -122,6 +126,7 @@ export function createTestEnv(opts: CreateTestEnvOptions = {}): TestEnv {
     storage,
     transport: opts.transport ?? "websocket",
     reconnectDelay: opts.reconnectDelay,
+    resetOnTenantFlip: opts.resetOnTenantFlip,
     // Tight timings so scenarios don't have to sleep seconds. The
     // engine's reconcile debounce is also relaxed so back-to-back
     // visibility-change triggers don't get coalesced away in tests.