@pylonsync/sync 0.3.178 → 0.3.180

package/package.json

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

package/src/index.ts

@@ -114,6 +114,19 @@ export class LocalStore {
    * dominate anything a concurrent pull could replay.
    */
   private tombstones: Map<string, Map<string, number>> = new Map();
+  /**
+   * Pending optimistic deletes — `(entity, row_id)` pairs the local
+   * client has dropped but the server hasn't yet confirmed. Stored
+   * separately from `tombstones` because the optimistic "block any
+   * incoming insert/update for this row" guard runs at infinite
+   * seq, but the real server delete seq (typically 4–6 digits)
+   * would never max-merge past `Number.MAX_SAFE_INTEGER`. The old
+   * design left MAX_SAFE_INTEGER permanently in `tombstones` for
+   * any optimistically-deleted id, so a future server-issued insert
+   * with seq=N could never pass the `seq < tombstoneSeq` check —
+   * the row id was blocked for the lifetime of the replica.
+   */
+  private optimisticTombstones: Map<string, Set<string>> = new Map();
   private listeners: Set<() => void> = new Set();
 
   /** Get all rows for an entity. */
@@ -163,6 +176,9 @@ export class LocalStore {
 
   /** Check if `(entity, id)` has a tombstone. */
   private isTombstoned(entity: string, id: string, at_seq?: number): boolean {
+    // Pending optimistic delete — block everything until the server's
+    // real delete arrives and supersedes us.
+    if (this.optimisticTombstones.get(entity)?.has(id)) return true;
     const tombSeq = this.tombstones.get(entity)?.get(id);
     if (tombSeq === undefined) return false;
     // If the caller didn't tell us when their change happened, treat as
@@ -172,6 +188,11 @@ export class LocalStore {
   }
 
   private recordTombstone(entity: string, id: string, seq: number): void {
+    // A real (server-issued) tombstone supersedes any pending optimistic
+    // entry for this id. Without this drop, the optimistic
+    // MAX_SAFE_INTEGER entry would persist forever and block future
+    // re-creations of the same id (the case codex flagged P1).
+    this.optimisticTombstones.get(entity)?.delete(id);
     if (!this.tombstones.has(entity)) {
       this.tombstones.set(entity, new Map());
     }
@@ -264,8 +285,20 @@ export class LocalStore {
     }
     this.notify();
     if (this._persistFn) {
-      const results = changes.map((c) => this._persistFn!(this.hydrateFromMemory(c)));
-      await Promise.all(results.map((r) => (r instanceof Promise ? r : Promise.resolve())));
+      // Persist sequentially in arrival order — `Promise.all` would
+      // fire every IndexedDB write concurrently and the IDB scheduler
+      // can resolve them out of order. An `update → delete` pair on
+      // the same row would race the delete behind the update on disk,
+      // leaving a stale row in the persisted replica while the cursor
+      // advanced past the delete. Sequencing here matches the in-memory
+      // apply order, which itself is sequenced by the engine's
+      // `applyQueue`.
+      for (const change of changes) {
+        const result = this._persistFn(this.hydrateFromMemory(change));
+        if (result instanceof Promise) {
+          await result;
+        }
+      }
     }
   }
 
@@ -364,11 +397,17 @@ export class LocalStore {
   /** Apply an optimistic delete. */
   optimisticDelete(entity: string, id: string): void {
     this.tables.get(entity)?.delete(id);
-    // Client-side deletes dominate any concurrent server replay until the
-    // server confirms; use MAX_SAFE_INTEGER as the tombstone seq. When the
-    // server's real delete event arrives it will refresh the tombstone with
-    // the authoritative seq (via `recordTombstone`'s max-of).
-    this.recordTombstone(entity, id, Number.MAX_SAFE_INTEGER);
+    // Optimistic delete: block any incoming insert/update for this id
+    // until the server's authoritative delete arrives. Tracked in
+    // `optimisticTombstones` rather than `tombstones` so the real
+    // server seq can supersede it cleanly — the previous design wrote
+    // MAX_SAFE_INTEGER into `tombstones` and `recordTombstone`'s
+    // max-merge would never replace it with the smaller real seq,
+    // leaving the id permanently quarantined.
+    if (!this.optimisticTombstones.has(entity)) {
+      this.optimisticTombstones.set(entity, new Set());
+    }
+    this.optimisticTombstones.get(entity)!.add(id);
     this.notify();
   }
 
@@ -381,6 +420,7 @@ export class LocalStore {
   clearAll(): void {
     this.tables.clear();
     this.tombstones.clear();
+    this.optimisticTombstones.clear();
     this.notify();
   }
 }
@@ -716,6 +756,17 @@ export class SyncEngine {
   private wsStableTimer: ReturnType<typeof setTimeout> | null = null;
   private pingTimer: ReturnType<typeof setInterval> | null = null;
 
+  /**
+   * Serialized apply queue. Every change-event apply — from WS onmessage,
+   * pull(), or session-changed catchup — chains onto this promise so
+   * applies execute in arrival order. Without this, two WS messages or
+   * two concurrent pull()s race: seq 3's persistence can land before
+   * seq 2's, leaving the row at the older value AND the cursor briefly
+   * regressing if writes complete out of order. The queue also gates
+   * the cursor advance so `last_seq` only moves forward.
+   */
+  private applyQueue: Promise<void> = Promise.resolve();
+
   /**
    * Registered consumers for binary WebSocket frames. SyncEngine itself
    * doesn't decode binary — it just owns the WS connection and routes
@@ -965,6 +1016,77 @@ export class SyncEngine {
 
   private pollTimer: ReturnType<typeof setInterval> | null = null;
 
+  /**
+   * Serialize a batch of change applies behind any in-flight applies, and
+   * advance the cursor monotonically when the batch lands. Both the WS
+   * onmessage path and pull() funnel through here so seq 3's persistence
+   * can't race ahead of seq 2's. The returned promise resolves after
+   * THIS batch is applied (not after later batches), so a caller awaiting
+   * pull() still completes deterministically.
+   *
+   * Per-event monotonic filter: re-applies of an already-seen seq are
+   * skipped before touching the store. Without that, a retransmit
+   * (WS + pull window overlap) would have us run applyChange twice
+   * against the local store.
+   */
+  private enqueueApply(
+    changes: ChangeEvent[],
+    options:
+      | SyncCursor
+      | { targetCursor?: SyncCursor; skipSeqGuard?: boolean; advanceCursor?: boolean } = {},
+  ): Promise<void> {
+    // Back-compat: callers that pass a SyncCursor positional arg get
+    // the same semantics as before. New callers can pass an options
+    // object — `skipSeqGuard` lets reconcile bypass the seq filter
+    // (its synthetic events fabricate seqs that don't fit the natural
+    // monotonic order), and `advanceCursor: false` keeps the cursor
+    // pinned where it was so reconcile doesn't fake-advance past the
+    // server's real position.
+    const opts: { targetCursor?: SyncCursor; skipSeqGuard?: boolean; advanceCursor?: boolean } =
+      options && typeof options === "object" && "last_seq" in options
+        ? { targetCursor: options as SyncCursor }
+        : (options as {
+            targetCursor?: SyncCursor;
+            skipSeqGuard?: boolean;
+            advanceCursor?: boolean;
+          });
+    const skipSeqGuard = opts.skipSeqGuard ?? false;
+    const advanceCursor = opts.advanceCursor ?? true;
+    const targetCursor = opts.targetCursor;
+
+    const prev = this.applyQueue;
+    const next = prev.then(async () => {
+      const filtered = skipSeqGuard
+        ? changes
+        : changes.filter(
+            (c) => typeof c.seq === "number" && c.seq > this.cursor.last_seq,
+          );
+      if (filtered.length > 0) {
+        await this.store.applyChangesAsync(filtered);
+      }
+      if (!advanceCursor) return;
+      // Pick the cursor target. Explicit `targetCursor` (from pull) wins
+      // — pull's response carries the server's authoritative current_seq
+      // even when no changes landed in this window. Otherwise derive
+      // from the last applied seq.
+      const candidate =
+        targetCursor ??
+        (filtered.length > 0
+          ? { last_seq: filtered[filtered.length - 1].seq }
+          : null);
+      if (candidate && candidate.last_seq > this.cursor.last_seq) {
+        this.cursor = candidate;
+        if (this.persistence) {
+          await this.persistence.saveCursor(this.cursor);
+        }
+      }
+    });
+    // Errors stay scoped to this batch — don't poison the chain for
+    // future applies.
+    this.applyQueue = next.catch(() => {});
+    return next;
+  }
+
   private startPolling(): void {
     const interval = this.config.pollInterval ?? 1000;
     this.pollTimer = setInterval(() => {
@@ -1118,18 +1240,14 @@ export class SyncEngine {
       try {
         const msg = JSON.parse(event.data as string);
 
-        // Sync change event. Persist BEFORE advancing the cursor so a crash
-        // can't leave `last_seq` ahead of the replica on disk.
+        // Sync change event. Persist BEFORE advancing the cursor so a
+        // crash can't leave `last_seq` ahead of the replica on disk.
+        // The shared apply queue serializes WS messages with each other
+        // AND with concurrent pull() calls, so seq order is preserved
+        // and the cursor only advances monotonically.
         if (msg.seq && msg.entity && msg.kind) {
           const change = msg as ChangeEvent;
-          if (change.seq > this.cursor.last_seq) {
-            void this.store.applyChangesAsync([change]).then(async () => {
-              this.cursor = { last_seq: change.seq };
-              if (this.persistence) {
-                await this.persistence.saveCursor(this.cursor);
-              }
-            });
-          }
+          void this.enqueueApply([change]);
           return;
         }
 
@@ -1259,14 +1377,7 @@ export class SyncEngine {
           const msg = JSON.parse(event.data);
           if (msg.seq && msg.entity && msg.kind) {
             const change = msg as ChangeEvent;
-            if (change.seq > this.cursor.last_seq) {
-              void this.store.applyChangesAsync([change]).then(async () => {
-                this.cursor = { last_seq: change.seq };
-                if (this.persistence) {
-                  await this.persistence.saveCursor(this.cursor);
-                }
-              });
-            }
+            void this.enqueueApply([change]);
           }
         } catch {
           // Ignore malformed events.
@@ -1480,22 +1591,14 @@ export class SyncEngine {
       );
       // Successful response — clear the 410 circuit breaker.
       this.consecutive_410s = 0;
-      if (resp.changes.length > 0) {
-        // Await disk writes before touching the cursor so a crash here can't
-        // persist a cursor that's ahead of what actually landed in IndexedDB.
-        await this.store.applyChangesAsync(resp.changes);
-      }
-      // Always advance the cursor to whatever the server reports, not just
-      // when changes land. If a read policy filters out every event in a
-      // window the server still moves its last_seq forward; clamping to only
-      // "non-empty" responses pins the client at `since=0` forever and turns
-      // every reconnect into another pull for the same empty window.
-      if (resp.cursor && resp.cursor.last_seq > this.cursor.last_seq) {
-        this.cursor = resp.cursor;
-        if (this.persistence) {
-          await this.persistence.saveCursor(this.cursor);
-        }
-      }
+      // Route through the apply queue so concurrent WS messages and
+      // pull responses don't race. The queue's monotonic guard skips
+      // any seq we've already applied (e.g. WS already landed the
+      // events that pull is now redelivering) and only advances the
+      // cursor forward. We still advance even when no changes land,
+      // because the server's last_seq may have moved past us due to
+      // policy-filtered events.
+      await this.enqueueApply(resp.changes, resp.cursor);
       // If there are more, pull again immediately.
       if (resp.has_more) {
         await this.pull();
@@ -1695,30 +1798,47 @@ export class SyncEngine {
       }
     }
     if (changes.length > 0) {
-      await this.store.applyChangesAsync(changes);
+      // Reconcile applies route through the same serialized queue as
+      // WS/pull so a stale reconcile response can't interleave with a
+      // newer WS/pull update mid-batch. The synthetic seqs reconcile
+      // fabricates (tombstoneSeq + 1) collide with WS-issued seqs so
+      // we skip the monotonic guard and don't advance the cursor —
+      // the cursor still reflects the server's last_seq, not our
+      // fabricated reconcile seqs.
+      await this.enqueueApply(changes, {
+        skipSeqGuard: true,
+        advanceCursor: false,
+      });
     }
     // Removals: every local row whose id isn't in the server set is
     // stale. Tombstone with the current cursor so future legitimate
-    // re-creations still flow through.
+    // re-creations still flow through. Synthesize Delete events for
+    // each removal and route through the apply queue so the order
+    // relative to WS/pull updates is preserved — a removal here is
+    // really "server says this row is gone as of tombstoneSeq", which
+    // matters if a later WS update reinstates it on the same row id.
     const locals = this.store.list(entity);
-    let removed = false;
+    const removalChanges: ChangeEvent[] = [];
     for (const local of locals) {
       const id = (local as { id?: unknown }).id;
       if (typeof id !== "string") continue;
       if (!serverIds.has(id)) {
-        if (this.store.reconcileRemove(entity, id, tombstoneSeq)) {
-          removed = true;
-          if (this.persistence) {
-            try {
-              await this.persistence.deleteRow(entity, id);
-            } catch {
-              /* best-effort */
-            }
-          }
-        }
+        removalChanges.push({
+          seq: tombstoneSeq,
+          entity,
+          row_id: id,
+          kind: "delete",
+          data: undefined,
+          timestamp: "",
+        });
       }
     }
-    if (removed) this.store.notify();
+    if (removalChanges.length > 0) {
+      await this.enqueueApply(removalChanges, {
+        skipSeqGuard: true,
+        advanceCursor: false,
+      });
+    }
   }
 
   private async dropEntity(