@pylonsync/sync 0.3.202 → 0.3.203

package/src/op-queue.ts

@@ -0,0 +1,73 @@
+// OpQueue — single serialized channel for the engine's outbound
+// network operations (pull, push, reconcile, refresh, resetReplica).
+//
+// Why this exists: before unification, each op had its own ad-hoc
+// dedupe primitive (inFlightPush, inFlightReconcile, "void refresh()"
+// fire-and-forget). The combinations leaked races — pull mid-refresh,
+// reconcile mid-pull, session-changed-mid-reconcile — that each
+// required their own inline guard. Putting every op on one FIFO
+// reduces the race surface to "did a prior op execute between when I
+// scheduled and when I ran" — which is just a counter check, not a
+// snapshot comparison.
+//
+// Ops are keyed; concurrent enqueues with the same key share the
+// running promise. That preserves the old "callers always get the
+// same promise while X is running" coalescing semantics without
+// needing a separate inFlightX field per op.
+//
+// Apply queue (change-event applies) stays SEPARATE. WS events that
+// arrive while a pull is in flight should land in the local replica
+// without waiting for the pull's HTTP round-trip. That separation is
+// the only reason we don't put `applyChanges` on this queue too.
+
+export class OpQueue {
+  private chain: Promise<void> = Promise.resolve();
+  private pending = new Map<string, Promise<unknown>>();
+  /** Monotonic op counter — incremented as each op begins running.
+   *  Lets a caller stash a snapshot ("epoch when I scheduled") and
+   *  detect after `await` whether another op ran in between. */
+  private epoch = 0;
+
+  /** Schedule an op behind any currently running/queued ops.
+   *
+   *  Coalescing: if `key` matches a pending op, the existing promise
+   *  is returned — the new caller does NOT re-enqueue. This preserves
+   *  the "many concurrent callers share one in-flight op" semantics
+   *  that pull/push/reconcile had via their respective mutexes. */
+  enqueue<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    const existing = this.pending.get(key);
+    if (existing) return existing as Promise<T>;
+
+    let resolveOuter!: (v: T) => void;
+    let rejectOuter!: (e: unknown) => void;
+    const outer = new Promise<T>((res, rej) => {
+      resolveOuter = res;
+      rejectOuter = rej;
+    });
+    this.pending.set(key, outer);
+
+    const prev = this.chain;
+    this.chain = prev.then(async () => {
+      this.epoch += 1;
+      try {
+        const v = await fn();
+        resolveOuter(v);
+      } catch (e) {
+        rejectOuter(e);
+      } finally {
+        // Clear key BEFORE outer settles so a downstream `.then()` on
+        // the returned promise can re-enqueue without colliding with
+        // our own pending entry.
+        this.pending.delete(key);
+      }
+    });
+
+    return outer;
+  }
+
+  /** Current epoch — read before scheduling, compare after `await` to
+   *  detect "another op ran while I was waiting." */
+  currentEpoch(): number {
+    return this.epoch;
+  }
+}

package/src/reconcile.test.ts

@@ -34,10 +34,16 @@ function makeEngine(): SyncEngine {
   // run on the Bun runtime which has no `indexedDB` global. Reconcile
   // itself only touches `this.persistence` defensively, so disabling
   // the layer is harmless here.
+  //
+  // `multiTab: false` opts out of the broker entirely so the engine
+  // acts as the sole leader from construction. Without this the tests
+  // would skip the leader-gated reconcile path because start() (which
+  // is what flips the leader bit in normal use) is never called here.
   return new SyncEngine({
     baseUrl: "http://stub.invalid",
     persist: false,
     reconcileMinIntervalMs: 0,
+    multiTab: false,
   });
 }
 
@@ -224,6 +230,7 @@ describe("SyncEngine.reconcile", () => {
       baseUrl: "http://stub.invalid",
       persist: false,
       reconcileMinIntervalMs: 5_000,
+      multiTab: false,
     });
     seedStore(engine, "Recording", [{ id: "r1", title: "alive" }]);
 
@@ -300,10 +307,29 @@ describe("SyncEngine.reconcile session guard", () => {
   test("skips apply when tenant flips during entity fetch", async () => {
     let restore: (() => void) | null = null;
     try {
+      const engine = makeEngine();
+      // Seed the resolver with a tenant=null session — every call to
+      // session.signature() through the rest of this test reflects
+      // this value until the fetch handler flips it below.
+      engine.session.observeSession({
+        userId: "u1",
+        tenantId: null,
+        isAdmin: false,
+        roles: [],
+      });
+
       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.
+          // Flip the session signature WHILE the fetch is "in flight"
+          // — between the engine's `sessionBeforeFetch` capture and
+          // the apply pass. Models a WS session-changed envelope
+          // landing in the gap.
+          engine.session.observeSession({
+            userId: "u1",
+            tenantId: "org-42",
+            isAdmin: false,
+            roles: [],
+          });
           return {
             status: 200,
             body: { data: [], next_cursor: null, has_more: false },
@@ -312,41 +338,13 @@ describe("SyncEngine.reconcile session guard", () => {
         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;
+      await engine.reconcile(["Recording"]);
 
-      // Row must survive — the stale fetch result was discarded.
+      // Row must survive — the stale fetch result was discarded by
+      // the session-signature guard.
       expect(engine.store.list("Recording").length).toBe(1);
       expect(engine.store.get("Recording", "r1")).not.toBeNull();
     } finally {

package/src/round6-codex.test.ts

@@ -0,0 +1,328 @@
+// Regression tests for codex review round-6 findings on the
+// multi-tab leader/follower integration glue in SyncEngine.
+//
+// Each test pins one finding so a future revert surfaces immediately:
+//   1. `isMultiTabLeader` defaults to false (P1)
+//   2. mutations-acked broadcast filters to actually-applied op_ids,
+//      and mutations-failed carries the rest (P1)
+//   3. A peer leaving (`bye` → onLeave) scrubs forwarded subs and
+//      unregisters the WS subscription when no owner remains (P2)
+
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { SyncEngine } from "./index";
+import { createTestEnv, type TestEnv } from "./test-harness";
+
+describe("codex round-6: isMultiTabLeader default", () => {
+  test("a fresh engine WITHOUT multiTab:false is NOT leader", () => {
+    // Pre-fix the default was `true`, so a tab that joined an
+    // established election would never receive onPromote (it wasn't
+    // promoted) or onDemote (it was never leader), and the engine's
+    // leader-gated paths (WS, pull, push, poll) all ran on every tab.
+    const engine = new SyncEngine({
+      baseUrl: "http://stub.invalid",
+      persist: false,
+    });
+    const internal = engine as unknown as { isMultiTabLeader: boolean };
+    expect(internal.isMultiTabLeader).toBe(false);
+  });
+
+  test("multiTab:false in config promotes to leader from construction", () => {
+    // Sanity for the constructor escape hatch: tests + apps that
+    // explicitly disable multi-tab need to act as their own leader
+    // immediately, before start().
+    const engine = new SyncEngine({
+      baseUrl: "http://stub.invalid",
+      persist: false,
+      multiTab: false,
+    });
+    const internal = engine as unknown as { isMultiTabLeader: boolean };
+    expect(internal.isMultiTabLeader).toBe(true);
+  });
+});
+
+describe("codex round-6: mutations-acked broadcast filters by status", () => {
+  let env: TestEnv | null = null;
+  afterEach(async () => {
+    if (env) await env.dispose();
+    env = null;
+  });
+
+  test("only applied op_ids broadcast as acks; failed ones broadcast separately", async () => {
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+    await env.start();
+
+    const broadcasts: { type: string; payload: unknown }[] = [];
+    const engine = env.engine as unknown as {
+      broadcastToTabs(payload: unknown): void;
+      request<T>(method: string, path: string, body?: unknown): Promise<T>;
+      mutations: {
+        add(change: unknown): string;
+      };
+      push(): Promise<void>;
+    };
+
+    // Spy on broadcastToTabs by replacing it. Save the original so
+    // the engine's internal calls still hit the recorder.
+    const originalBroadcast = engine.broadcastToTabs.bind(engine);
+    engine.broadcastToTabs = (payload: unknown) => {
+      const p = payload as { type: string };
+      if (p.type === "mutations-acked" || p.type === "mutations-failed") {
+        broadcasts.push({ type: p.type, payload });
+      }
+      originalBroadcast(payload);
+    };
+
+    // Stub the engine's HTTP request so /api/sync/push returns a
+    // mixed-status response: op-good applied, op-bad error. Other
+    // request paths fall through to the real harness fetch.
+    const originalRequest = engine.request.bind(engine);
+    engine.request = (async <T,>(
+      method: string,
+      path: string,
+      body?: unknown,
+    ): Promise<T> => {
+      if (path === "/api/sync/push") {
+        return {
+          applied: 1,
+          deduped: 0,
+          errors: ["rejected by validation"],
+          results: [
+            { op_id: "op-good", status: "applied", seq: 1 },
+            {
+              op_id: "op-bad",
+              status: "error",
+              error: { code: "VALIDATION_ERROR", message: "rejected by validation" },
+            },
+          ],
+          cursor: { last_seq: 1 },
+        } as unknown as T;
+      }
+      return originalRequest(method, path, body);
+    }) as typeof engine.request;
+
+    // Two mutations, one good one bad. add() preserves op_id from
+    // the change envelope (this is the multi-tab leader's behavior
+    // when it forwards a follower's batch).
+    engine.mutations.add({
+      op_id: "op-good",
+      entity: "Todo",
+      row_id: "good",
+      kind: "insert",
+      data: { id: "good", text: "ok" },
+    });
+    engine.mutations.add({
+      op_id: "op-bad",
+      entity: "Todo",
+      row_id: "bad",
+      kind: "insert",
+      data: { id: "bad", text: "boom" },
+    });
+
+    await engine.push();
+    await env.flush();
+
+    const acks = broadcasts.filter((b) => b.type === "mutations-acked");
+    const fails = broadcasts.filter((b) => b.type === "mutations-failed");
+
+    expect(acks.length).toBe(1);
+    expect(fails.length).toBe(1);
+
+    const ackedIds = (acks[0].payload as { opIds: string[] }).opIds;
+    expect(ackedIds).toEqual(["op-good"]);
+
+    const failedOps = (fails[0].payload as {
+      ops: { opId: string; error: string }[];
+    }).ops;
+    expect(failedOps.length).toBe(1);
+    expect(failedOps[0].opId).toBe("op-bad");
+    expect(failedOps[0].error.length).toBeGreaterThan(0);
+  });
+
+  test("follower receiving mutations-failed marks the op failed (not applied)", async () => {
+    // Receiving side: confirms the new follower handler doesn't lose
+    // the failure. Pre-fix the leader sent every op_id as acked and
+    // the follower silently clear()ed them; now the follower stays
+    // failed so UI / retry can act.
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+    await env.start();
+
+    const engine = env.engine as unknown as {
+      handleMultiTabMessage(msg: unknown, from: string): void;
+      mutations: {
+        add(change: unknown): string;
+        pending(): { id: string; status: string; error?: string }[];
+      };
+    };
+
+    // Seed a pending mutation locally — simulates the follower's
+    // optimistic queue.
+    engine.mutations.add({
+      op_id: "op-x",
+      entity: "Todo",
+      row_id: "x",
+      kind: "insert",
+      data: { id: "x", text: "y" },
+    });
+
+    // Leader → follower envelope. Drive through the orchestrator's
+    // public message dispatch — same path the BroadcastChannel
+    // onmessage hits in production.
+    (engine as unknown as {
+      orchestrator: {
+        handleMessage(msg: unknown, from: string): void;
+      };
+    }).orchestrator.handleMessage(
+      {
+        type: "mutations-failed",
+        ops: [{ opId: "op-x", error: "server rejected" }],
+      },
+      "leader-tab-id",
+    );
+
+    // The mutation stays in the queue, status=failed, with the error
+    // string preserved.
+    const all = (engine.mutations as unknown as {
+      queue: { id: string; status: string; error?: string }[];
+    }).queue;
+    const found = all.find((m) => m.id === "op-x");
+    expect(found).toBeDefined();
+    expect(found?.status).toBe("failed");
+    expect(found?.error).toBe("server rejected");
+  });
+});
+
+describe("codex round-6: peer leaving scrubs forwarded subs", () => {
+  let env: TestEnv | null = null;
+  afterEach(async () => {
+    if (env) await env.dispose();
+    env = null;
+  });
+
+  // Helper: reach into the SubscriptionCoordinator that the engine
+  // delegates to. The state these tests pin lives on the coordinator
+  // now, not the engine itself. The orchestrator's inbound dispatch
+  // is bypassed by calling subscriptions.handleForwardedRegister /
+  // scrubPeer directly — that's the same path the orchestrator takes
+  // when a real broker message arrives, just driven by the test.
+  function internals(env: TestEnv) {
+    return env.engine as unknown as {
+      serverSubs: { has(k: string): boolean };
+      subscriptions: {
+        crdtForwarders: Map<string, Set<string>>;
+        reactiveSubOwners: Map<string, Set<string>>;
+        handleForwardedRegister(msg: unknown, fromTabId: string): void;
+        scrubPeer(tabId: string): void;
+      };
+    };
+  }
+
+  test("onMultiTabPeerLeft removes the tab from crdtForwarders + unregisters WS sub", async () => {
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+    await env.start();
+
+    const engine = internals(env);
+
+    // Simulate a follower forwarding a CRDT sub via the broker
+    // app-message path. The leader's handler creates an entry in
+    // crdtForwarders and registers with serverSubs.
+    engine.subscriptions.handleForwardedRegister(
+      {
+        type: "sub-register",
+        kind: "crdt",
+        key: "Todo\x00row-1",
+        entity: "Todo",
+        rowId: "row-1",
+      },
+      "follower-1",
+    );
+
+    expect(
+      engine.subscriptions.crdtForwarders.get("Todo\x00row-1")?.has("follower-1"),
+    ).toBe(true);
+    expect(engine.serverSubs.has("Todo\x00row-1")).toBe(true);
+
+    // Now the follower disappears (broker fires onLeave).
+    engine.subscriptions.scrubPeer("follower-1");
+
+    expect(engine.subscriptions.crdtForwarders.has("Todo\x00row-1")).toBe(false);
+    expect(engine.serverSubs.has("Todo\x00row-1")).toBe(false);
+  });
+
+  test("onMultiTabPeerLeft keeps the sub alive if another tab still owns it", async () => {
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+    await env.start();
+
+    const engine = internals(env);
+
+    // Two followers forward the SAME crdt key. The leader keeps a
+    // single server sub with two entries in the forwarder set.
+    engine.subscriptions.handleForwardedRegister(
+      {
+        type: "sub-register",
+        kind: "crdt",
+        key: "Todo\x00row-1",
+        entity: "Todo",
+        rowId: "row-1",
+      },
+      "follower-a",
+    );
+    engine.subscriptions.handleForwardedRegister(
+      {
+        type: "sub-register",
+        kind: "crdt",
+        key: "Todo\x00row-1",
+        entity: "Todo",
+        rowId: "row-1",
+      },
+      "follower-b",
+    );
+
+    expect(engine.subscriptions.crdtForwarders.get("Todo\x00row-1")?.size).toBe(2);
+    expect(engine.serverSubs.has("Todo\x00row-1")).toBe(true);
+
+    // Only follower-a leaves. The sub stays alive because follower-b
+    // still owns it.
+    engine.subscriptions.scrubPeer("follower-a");
+
+    expect(engine.subscriptions.crdtForwarders.get("Todo\x00row-1")?.size).toBe(1);
+    expect(
+      engine.subscriptions.crdtForwarders.get("Todo\x00row-1")?.has("follower-b"),
+    ).toBe(true);
+    expect(engine.serverSubs.has("Todo\x00row-1")).toBe(true);
+  });
+
+  test("onMultiTabPeerLeft scrubs reactive owner sets and unregisters when empty", async () => {
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+    await env.start();
+
+    const engine = internals(env);
+
+    engine.subscriptions.handleForwardedRegister(
+      {
+        type: "sub-register",
+        kind: "reactive",
+        key: "sub-1",
+        sub_id: "sub-1",
+        fn_name: "q",
+        args: { v: 1 },
+      },
+      "follower-x",
+    );
+
+    expect(engine.subscriptions.reactiveSubOwners.get("sub-1")?.has("follower-x")).toBe(
+      true,
+    );
+    expect(engine.serverSubs.has("sub-1")).toBe(true);
+
+    engine.subscriptions.scrubPeer("follower-x");
+
+    expect(engine.subscriptions.reactiveSubOwners.has("sub-1")).toBe(false);
+    expect(engine.serverSubs.has("sub-1")).toBe(false);
+  });
+});