@pylonsync/sync 0.3.202 → 0.3.205

package/src/server-subscriptions.test.ts

@@ -0,0 +1,99 @@
+// Unit tests for ServerSubscriptions. Pins the replay-on-reconnect
+// contract so both consumers (CRDT + reactive) get identical
+// semantics from one registry.
+
+import { describe, expect, test } from "bun:test";
+
+import { ServerSubscriptions } from "./server-subscriptions";
+
+describe("ServerSubscriptions", () => {
+  test("register sends the subscribe message", () => {
+    const sent: unknown[] = [];
+    const subs = new ServerSubscriptions((m) => sent.push(m));
+    subs.register("k1", { type: "sub", k: "k1" });
+    expect(sent).toEqual([{ type: "sub", k: "k1" }]);
+  });
+
+  test("re-registering the same key with identical payload does NOT re-send", () => {
+    const sent: unknown[] = [];
+    const subs = new ServerSubscriptions((m) => sent.push(m));
+    subs.register("k1", { type: "sub", k: "k1", v: 1 });
+    subs.register("k1", { type: "sub", k: "k1", v: 1 });
+    expect(sent.length).toBe(1);
+  });
+
+  test("re-registering with a CHANGED payload re-sends", () => {
+    // The intended path for useReactiveQuery(name, args) when args
+    // change: same sub_id, different args; the server has to learn.
+    const sent: unknown[] = [];
+    const subs = new ServerSubscriptions((m) => sent.push(m));
+    subs.register("k1", { type: "sub", k: "k1", v: 1 });
+    subs.register("k1", { type: "sub", k: "k1", v: 2 });
+    expect(sent).toEqual([
+      { type: "sub", k: "k1", v: 1 },
+      { type: "sub", k: "k1", v: 2 },
+    ]);
+    // Most recent payload wins on replay.
+    sent.length = 0;
+    subs.replay();
+    expect(sent).toEqual([{ type: "sub", k: "k1", v: 2 }]);
+  });
+
+  test("payload equality is structural (key order, nested)", () => {
+    const sent: unknown[] = [];
+    const subs = new ServerSubscriptions((m) => sent.push(m));
+    subs.register("k1", { type: "sub", args: { a: 1, b: 2 } });
+    // Same logical payload, different key insertion order.
+    subs.register("k1", { type: "sub", args: { b: 2, a: 1 } });
+    expect(sent.length).toBe(1);
+  });
+
+  test("unregister sends the unsubscribe and forgets the spec", () => {
+    const sent: unknown[] = [];
+    const subs = new ServerSubscriptions((m) => sent.push(m));
+    subs.register("k1", { type: "sub", k: "k1" });
+    subs.unregister("k1", { type: "unsub", k: "k1" });
+    expect(sent).toEqual([
+      { type: "sub", k: "k1" },
+      { type: "unsub", k: "k1" },
+    ]);
+    expect(subs.has("k1")).toBe(false);
+    // Replay after unregister sends nothing.
+    sent.length = 0;
+    subs.replay();
+    expect(sent).toEqual([]);
+  });
+
+  test("unregister of an unknown key is a no-op", () => {
+    const sent: unknown[] = [];
+    const subs = new ServerSubscriptions((m) => sent.push(m));
+    subs.unregister("ghost", { type: "unsub", k: "ghost" });
+    expect(sent).toEqual([]);
+  });
+
+  test("replay re-sends every active subscribe message in order", () => {
+    const sent: unknown[] = [];
+    const subs = new ServerSubscriptions((m) => sent.push(m));
+    subs.register("a", { type: "sub", k: "a" });
+    subs.register("b", { type: "sub", k: "b" });
+    subs.register("c", { type: "sub", k: "c" });
+    sent.length = 0;
+    subs.replay();
+    expect(sent).toEqual([
+      { type: "sub", k: "a" },
+      { type: "sub", k: "b" },
+      { type: "sub", k: "c" },
+    ]);
+  });
+
+  test("replay skips unregistered keys", () => {
+    const sent: unknown[] = [];
+    const subs = new ServerSubscriptions((m) => sent.push(m));
+    subs.register("a", { type: "sub", k: "a" });
+    subs.register("b", { type: "sub", k: "b" });
+    subs.unregister("a", { type: "unsub", k: "a" });
+    sent.length = 0;
+    subs.replay();
+    expect(sent).toEqual([{ type: "sub", k: "b" }]);
+  });
+});

package/src/server-subscriptions.ts

@@ -0,0 +1,78 @@
+// ServerSubscriptions — replay-on-reconnect registry shared by every
+// server-side ephemeral subscription type.
+//
+// The server clears per-client subscription state on disconnect: CRDT
+// row subscriptions, reactive query subscriptions, and any future kind
+// (file streams, presence, etc.) all evaporate when the WS socket
+// closes. Each kind used to track its own re-registration in a
+// separate field on the engine, with its own loop in `ws.onopen`. This
+// generalizes: every subscription kind records the exact WS message
+// the server needs to re-create its server-side state; reconnect
+// replays the bundle.
+//
+// Kind-specific concerns (CRDT refcount, reactive handler routing)
+// stay in the engine. This module only owns the replay bookkeeping.
+
+export class ServerSubscriptions {
+  private specs = new Map<string, unknown>(); // key → subscribeMessage
+
+  constructor(private readonly sendWs: (msg: unknown) => void) {}
+
+  /** Register a subscription. Sends `subscribeMessage` over WS and
+   *  remembers it so the next reconnect re-sends it.
+   *
+   *  Re-registering the same key with the SAME payload is a no-op
+   *  (the prior subscribe is still live on the server). But a
+   *  re-register with a DIFFERENT payload re-sends — that's the
+   *  intended behavior of `useReactiveQuery(name, args)` when args
+   *  change: same sub_id, new args, server must observe the change
+   *  or the handler keeps running against stale arguments. */
+  register(key: string, subscribeMessage: unknown): void {
+    const prev = this.specs.get(key);
+    const changed =
+      prev === undefined || !sameJson(prev, subscribeMessage);
+    this.specs.set(key, subscribeMessage);
+    if (changed) this.sendWs(subscribeMessage);
+  }
+
+  /** Unregister. Sends `unsubscribeMessage` over WS and forgets the
+   *  replay entry. No-op for unknown keys (matches React's
+   *  StrictMode-friendly double-unmount semantics). */
+  unregister(key: string, unsubscribeMessage: unknown): void {
+    if (!this.specs.has(key)) return;
+    this.specs.delete(key);
+    this.sendWs(unsubscribeMessage);
+  }
+
+  /** Whether `key` is currently registered. */
+  has(key: string): boolean {
+    return this.specs.has(key);
+  }
+
+  /** Re-send every registered subscribe message. Called from
+   *  `ws.onopen` after the socket reconnects — the server purges
+   *  per-client subscription state on disconnect, so without this
+   *  resync the subscriber's first event would never arrive. */
+  replay(): void {
+    for (const msg of this.specs.values()) {
+      this.sendWs(msg);
+    }
+  }
+}
+
+/** Stable structural equality. Used to skip the WS round-trip when a
+ *  re-register has the same payload — and to trigger one when it
+ *  doesn't. Cheap enough on the small JSON shapes these messages use. */
+function sameJson(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+}
+
+function canonical(v: unknown): unknown {
+  if (v === null || typeof v !== "object") return v;
+  if (Array.isArray(v)) return v.map(canonical);
+  const obj = v as Record<string, unknown>;
+  const sorted: Record<string, unknown> = {};
+  for (const k of Object.keys(obj).sort()) sorted[k] = canonical(obj[k]);
+  return sorted;
+}

package/src/session-chain.test.ts

@@ -0,0 +1,133 @@
+// Regression tests for the sessionChain FIFO + reactiveSubOwners
+// set introduced in the codex round-3 fixes. These exercise the
+// engine end-to-end so the chain semantics + refcount semantics
+// are pinned at the engine layer, not just at the unit-test layer
+// for SessionResolver / ServerSubscriptions.
+
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { createTestEnv, type TestEnv } from "./test-harness";
+
+const u1OrgA = { userId: "u1", tenantId: "org-a", isAdmin: false, roles: [] };
+const u1OrgB = { userId: "u1", tenantId: "org-b", isAdmin: false, roles: [] };
+const u1OrgC = { userId: "u1", tenantId: "org-c", isAdmin: false, roles: [] };
+
+describe("sessionChain ordering", () => {
+  let env: TestEnv | null = null;
+  afterEach(async () => {
+    if (env) await env.dispose();
+    env = null;
+  });
+
+  test("rapid back-to-back applySessionTransition commits in arrival order", async () => {
+    env = createTestEnv();
+    env.signIn({ userId: "u1", tenantId: "org-a" });
+    await env.start();
+
+    // applySessionTransition is private — reach via the engine. The
+    // public path on a leader-only test env is `notifySessionChanged`
+    // which fetches /api/auth/me. To test direct chain ordering we
+    // poke the session through inspectSession + commitObservation
+    // is too low-level; instead we fire three notifySessionChanged
+    // calls and rely on the chain to serialize them.
+    //
+    // The harness flips server-side tenant between calls so each
+    // refresh observes a different value. The chain must commit
+    // in (A, B, C) arrival order regardless of network race timing.
+    const engine = env.engine as unknown as {
+      session: {
+        observeSession(s: typeof u1OrgA): unknown;
+        resolved(): typeof u1OrgA;
+      };
+      applySessionTransition(s: typeof u1OrgA, b: boolean): Promise<void>;
+    };
+    const p1 = engine.applySessionTransition(u1OrgA, false);
+    const p2 = engine.applySessionTransition(u1OrgB, false);
+    const p3 = engine.applySessionTransition(u1OrgC, false);
+    await Promise.all([p1, p2, p3]);
+
+    // Final committed tenant must be the LAST one enqueued.
+    expect(engine.session.resolved().tenantId).toBe("org-c");
+  });
+});
+
+describe("reactive subscription refcount under remount", () => {
+  let env: TestEnv | null = null;
+  afterEach(async () => {
+    if (env) await env.dispose();
+    env = null;
+  });
+
+  test("double subscribeReactive + single unsubscribeReactive keeps the sub alive", async () => {
+    // Mimics React StrictMode: mount calls subscribeReactive twice
+    // with the same sub_id, unmount calls unsubscribeReactive twice.
+    // The second unsubscribe early-returns (handler already removed)
+    // so we only count ONE effective unsubscribe per mount cycle.
+    // After ONE unsubscribe, the sub should still be alive because
+    // the owner set hasn't dropped to empty.
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+    await env.start();
+
+    let calls = 0;
+    env.engine.subscribeReactive("sub-1", "q", { a: 1 }, () => {
+      calls++;
+    });
+    env.engine.subscribeReactive("sub-1", "q", { a: 1 }, () => {
+      calls++;
+    });
+
+    // Internal owner set should have size 1 (self only, idempotent
+    // because Set.add). Reach into the SubscriptionCoordinator that
+    // the engine delegates to.
+    const engine = env.engine as unknown as {
+      serverSubs: { has(k: string): boolean };
+      subscriptions: {
+        reactiveSubOwners: Map<string, Set<string>>;
+      };
+    };
+    expect(engine.subscriptions.reactiveSubOwners.get("sub-1")?.size).toBe(1);
+    expect(engine.serverSubs.has("sub-1")).toBe(true);
+
+    // First unsubscribe: handler removed, owner count → 0 → unsub.
+    env.engine.unsubscribeReactive("sub-1");
+    expect(engine.subscriptions.reactiveSubOwners.has("sub-1")).toBe(false);
+    expect(engine.serverSubs.has("sub-1")).toBe(false);
+
+    // Second unsubscribe (the StrictMode double-unmount) is a no-op
+    // because the handler is already gone — must NOT throw, must
+    // not decrement anything further.
+    const e = env!;
+    expect(() => e.engine.unsubscribeReactive("sub-1")).not.toThrow();
+    void calls;
+  });
+
+  test("subscribe with new args re-sends the WS frame", async () => {
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+    await env.start();
+
+    const wsMessages = env.server.receivedWsMessages;
+    const before = wsMessages.length;
+
+    env.engine.subscribeReactive("sub-1", "q", { v: 1 }, () => {});
+    await env.flush();
+    env.engine.subscribeReactive("sub-1", "q", { v: 2 }, () => {});
+    await env.flush();
+
+    const subs = wsMessages
+      .slice(before)
+      .filter(
+        (m) =>
+          typeof m.msg === "object" &&
+          m.msg !== null &&
+          (m.msg as { type?: string }).type === "reactive-subscribe" &&
+          (m.msg as { sub_id?: string }).sub_id === "sub-1",
+      );
+    // Two subscribe frames — one per arg change. The first was the
+    // initial subscribe; the second is the args-update re-send.
+    expect(subs.length).toBe(2);
+    expect((subs[0].msg as { args: { v: number } }).args.v).toBe(1);
+    expect((subs[1].msg as { args: { v: number } }).args.v).toBe(2);
+  });
+});

package/src/session-resolver.test.ts

@@ -0,0 +1,94 @@
+// SessionResolver — unit tests for the verdicts the engine consumes.
+// Pins the null→X / X→Y / token-flip rules in one place so the engine
+// doesn't have to re-test them through its full pull/reconcile loop.
+
+import { describe, expect, test } from "bun:test";
+
+import { SessionResolver, sessionSignature } from "./session-resolver";
+
+const anon = { userId: null, tenantId: null, isAdmin: false, roles: [] };
+const u1OrgA = { userId: "u1", tenantId: "org-a", isAdmin: false, roles: [] };
+const u1OrgB = { userId: "u1", tenantId: "org-b", isAdmin: false, roles: [] };
+const u1NoTenant = {
+  userId: "u1",
+  tenantId: null,
+  isAdmin: false,
+  roles: [],
+};
+
+describe("SessionResolver", () => {
+  test("first observation seeds state without invalidating the replica", () => {
+    const r = new SessionResolver();
+    const v = r.observeSession(u1OrgA);
+    expect(v.tenantChanged).toBe(false);
+    expect(v.replicaInvalidated).toBe(false);
+    expect(v.isFirstResolution).toBe(false);
+    expect(v.identityChanged).toBe(true); // null → u1
+    expect(r.resolved()).toEqual(u1OrgA);
+  });
+
+  test("null → X flip is first-resolution (pull but NO reset)", () => {
+    const r = new SessionResolver();
+    r.observeSession(u1NoTenant); // seed lastSeenTenant=null
+    const v = r.observeSession(u1OrgA);
+    expect(v.tenantChanged).toBe(true);
+    expect(v.isFirstResolution).toBe(true);
+    expect(v.replicaInvalidated).toBe(false);
+  });
+
+  test("X → Y flip invalidates replica AND requires pull", () => {
+    const r = new SessionResolver();
+    r.observeSession(u1OrgA);
+    const v = r.observeSession(u1OrgB);
+    expect(v.tenantChanged).toBe(true);
+    expect(v.isFirstResolution).toBe(false);
+    expect(v.replicaInvalidated).toBe(true);
+  });
+
+  test("X → null (sign out) invalidates replica", () => {
+    const r = new SessionResolver();
+    r.observeSession(u1OrgA);
+    const v = r.observeSession(anon);
+    expect(v.tenantChanged).toBe(true);
+    expect(v.isFirstResolution).toBe(false);
+    expect(v.replicaInvalidated).toBe(true);
+  });
+
+  test("identical session is a no-op", () => {
+    const r = new SessionResolver();
+    r.observeSession(u1OrgA);
+    const v = r.observeSession({ ...u1OrgA });
+    expect(v.identityChanged).toBe(false);
+    expect(v.tenantChanged).toBe(false);
+    expect(v.replicaInvalidated).toBe(false);
+  });
+
+  test("role change is identity-only (no tenant flip, no reset)", () => {
+    const r = new SessionResolver();
+    r.observeSession(u1OrgA);
+    const v = r.observeSession({ ...u1OrgA, roles: ["editor"] });
+    expect(v.identityChanged).toBe(true);
+    expect(v.tenantChanged).toBe(false);
+    expect(v.replicaInvalidated).toBe(false);
+  });
+
+  test("token flip detection", () => {
+    const r = new SessionResolver();
+    expect(r.observeToken("tok-a").tokenChanged).toBe(false); // first observation
+    expect(r.observeToken("tok-a").tokenChanged).toBe(false);
+    expect(r.observeToken("tok-b").tokenChanged).toBe(true);
+    expect(r.observeToken("tok-b").tokenChanged).toBe(false);
+    expect(r.observeToken(null).tokenChanged).toBe(true); // sign-out
+  });
+
+  test("signature changes when any field changes", () => {
+    expect(sessionSignature(u1OrgA)).not.toBe(sessionSignature(u1OrgB));
+    expect(sessionSignature(u1OrgA)).not.toBe(
+      sessionSignature({ ...u1OrgA, roles: ["editor"] }),
+    );
+    // Role order doesn't affect the signature (sorted before joining).
+    expect(
+      sessionSignature({ ...u1OrgA, roles: ["a", "b"] }),
+    ).toBe(sessionSignature({ ...u1OrgA, roles: ["b", "a"] }));
+  });
+});

package/src/session-resolver.ts

@@ -0,0 +1,133 @@
+// SessionResolver — the engine's identity state machine.
+//
+// Before extraction, four pieces of state (`_resolvedSession`,
+// `lastSeenToken`, `lastSeenTenant`, `sessionSignature`) and three
+// branching rules (null→X first-resolution skip, X→Y reset, token-flip
+// reset) were sprinkled across four methods in index.ts. Each call site
+// re-implemented the comparison. This module collects the rules into
+// one place so the engine just feeds observations in and reads back
+// verdicts.
+//
+// No engine dependencies — pure state. Unit-tested in isolation.
+
+import type { ResolvedSession } from "./types";
+
+/** Verdict returned from `observeSession`. The engine acts on these
+ *  three booleans; the resolver makes no decisions about side effects
+ *  (replica reset, store notify, pull) — those belong upstream. */
+export interface SessionTransition {
+  /** Resolved session differs in any field (userId / tenantId / isAdmin /
+   *  roles). When true, the engine should notify subscribers. */
+  identityChanged: boolean;
+  /** The tenant moved AND it isn't the null→X first-resolution case —
+   *  cached rows belong to a different tenant and the replica should
+   *  be wiped before the next pull. */
+  replicaInvalidated: boolean;
+  /** First time tenant flipped from null to a real value (the engine
+   *  started before /api/auth/select-org landed). The cached rows in
+   *  this case ARE for the new tenant; reset would tombstone valid
+   *  state. Engine should pull but NOT reset. */
+  isFirstResolution: boolean;
+  /** Tenant value moved at all (covers both null→X and X→Y). When
+   *  true, the engine should pull regardless of reset semantics —
+   *  cached rows under the old tenant won't include rows added under
+   *  the new one. */
+  tenantChanged: boolean;
+}
+
+export interface TokenTransition {
+  /** Token flipped since the last observation. Engine should reset
+   *  the replica because the visible set changed under a new identity. */
+  tokenChanged: boolean;
+}
+
+const EMPTY_SESSION: ResolvedSession = {
+  userId: null,
+  tenantId: null,
+  isAdmin: false,
+  roles: [],
+};
+
+export class SessionResolver {
+  private _resolved: ResolvedSession = EMPTY_SESSION;
+  /** `undefined` until the first observation — distinguishes "we've
+   *  never seen a token" from "the token is null." Same for tenant. */
+  private lastSeenToken: string | null | undefined = undefined;
+  private lastSeenTenant: string | null | undefined = undefined;
+
+  /** Current resolved session — what `useSession` consumers should see. */
+  resolved(): ResolvedSession {
+    return this._resolved;
+  }
+
+  /** Stable string signature of the current session. Captured before
+   *  long-running ops (reconcile, in particular) so the op can detect
+   *  if anything changed during its in-flight period and bail. */
+  signature(): string {
+    return sessionSignature(this._resolved);
+  }
+
+  /** Compute the verdict for a freshly resolved session WITHOUT
+   *  mutating internal state. The engine inspects the verdict to
+   *  decide whether to reset the replica + pull, then calls
+   *  `commitObservation(next)` once it's safe for `useSession`
+   *  subscribers to see the new tenant.
+   *
+   *  Splitting compute from commit prevents the "useSession reports
+   *  new tenant + useQuery shows old tenant's rows" inconsistency
+   *  window that existed when the resolved session was mutated
+   *  before `resetReplica()` finished. */
+  inspectSession(next: ResolvedSession): SessionTransition {
+    const prev = this._resolved;
+    const tenantNow = next.tenantId;
+
+    const identityChanged = sessionSignature(prev) !== sessionSignature(next);
+    const tenantChanged =
+      this.lastSeenTenant !== undefined && this.lastSeenTenant !== tenantNow;
+    const isFirstResolution =
+      this.lastSeenTenant === null && tenantNow !== null;
+    const replicaInvalidated = tenantChanged && !isFirstResolution;
+
+    return {
+      identityChanged,
+      replicaInvalidated,
+      isFirstResolution,
+      tenantChanged,
+    };
+  }
+
+  /** Commit a previously-inspected session as the current truth.
+   *  Engine calls this AFTER acting on the verdict (replica reset,
+   *  pull) so subscribers never observe a half-applied transition. */
+  commitObservation(next: ResolvedSession): void {
+    this.lastSeenTenant = next.tenantId;
+    this._resolved = next;
+  }
+
+  /** Convenience for tests / migration: inspect + commit in one call.
+   *  Production callers should use `inspectSession` + `commitObservation`
+   *  to control the timing of state mutation. */
+  observeSession(next: ResolvedSession): SessionTransition {
+    const verdict = this.inspectSession(next);
+    this.commitObservation(next);
+    return verdict;
+  }
+
+  /** Feed in the current bearer token. Returns whether it flipped
+   *  since the previous observation. The engine uses this in pull()
+   *  to decide whether to reset before reading the cursor. */
+  observeToken(token: string | null): TokenTransition {
+    const tokenChanged =
+      this.lastSeenToken !== undefined && this.lastSeenToken !== token;
+    this.lastSeenToken = token;
+    return { tokenChanged };
+  }
+}
+
+/** Stable signature of a resolved session. Used by reconcile to detect
+ *  mid-fetch session flips. Roles array is sorted+joined so insertion
+ *  order doesn't trip the equality check. */
+export function sessionSignature(s: ResolvedSession): string {
+  const roles = (s.roles ?? []).slice().sort().join(",");
+  return `${s.userId ?? ""}|${s.tenantId ?? ""}|${s.isAdmin ? "1" : "0"}|${roles}`;
+}