fix(signals): hold optimistic store layers while their truth is in flight (#2951)

A bare (transaction-less) optimistic store write made in the same tick as
a refetch trigger died at plain flush end: the transition adopting the
write had no reason to stay open — transitionBlocked only recognizes
signal-form optimistic nodes, where the pending async and the override
share one node — so it settled in the flush that started the refetch and
its settle consumed the layer. The next click's draft then composed on
committed base, clobbering the still-rendered optimistic row.

createOptimisticStore now wraps the engine's transitionBlocked: a
transition holding an optimistic store whose firewall is still pending
stays open, so the layer rides until truth lands (projection landing) or
the transaction settles, and consecutive writes stack on the live
optimistic view. Plain-form stores have no firewall and keep their
flush-scoped flash semantics; #2899 disjoint-action independence is
untouched (owner stamps still scope each settle).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/fix-optimistic-store-refetch-hold.md

@@ -0,0 +1,5 @@
+---
+"@solidjs/signals": patch
+---
+
+Bare optimistic store writes made while the store's own refetch is in flight now hold until truth lands and compose across consecutive writes, instead of reverting at plain flush end and clobbering each other (#2951)

packages/solid-signals/src/core/scheduler.ts

@@ -875,9 +875,14 @@ function transitionComplete(transition: Transition): boolean {
     }
   }
   // Override blockage lives with the engine. Absent hook = "no optimistic
-  // blockage", which is exact: only _optimisticWrite (engine) pushes to
-  // _optimisticNodes, so without the engine the loop was vacuous anyway.
-  if (done && transition._optimisticNodes.length && GlobalQueue._transitionBlocked!(transition))
+  // blockage", which is exact: only the engine pushes to _optimisticNodes
+  // (via _optimisticWrite) or _optimisticStores (via _trackOptimisticStore),
+  // so without the engine the loop was vacuous anyway.
+  if (
+    done &&
+    (transition._optimisticNodes.length || transition._optimisticStores.size) &&
+    GlobalQueue._transitionBlocked!(transition)
+  )
     done = false;
   done && (transition._done = true);
   return done;

packages/solid-signals/src/store/optimistic.ts

@@ -1,3 +1,4 @@
+import { STATUS_PENDING } from "../core/constants.js";
 import {
   computed,
   CONFIG_AUTO_DISPOSE,
@@ -104,7 +105,28 @@ export function createOptimisticStore<T extends object = {}>(
   // STORE_OPTIMISTIC take the engine's write path, so install it before any
   // node can be created.
   installOptimisticEngine();
-  GlobalQueue._clearOptimisticStores ||= clearOptimisticStores;
+  if (!GlobalQueue._clearOptimisticStores) {
+    GlobalQueue._clearOptimisticStores = clearOptimisticStores;
+    // Store half of the engine's override blockage (#2951): signal-form
+    // createOptimistic carries the pending async and the override on ONE node,
+    // so transitionBlocked sees both; a derived optimistic STORE splits them —
+    // the layer sits on store targets while the in-flight truth lives on the
+    // firewall computed. Without this, the transition adopting a bare store
+    // write settled in the same flush that started the refetch and its settle
+    // consumed the layer mid-flight (follow-up writes then drafted from base,
+    // clobbering instead of composing). Optimistic state clears when truth
+    // lands or its transaction ends — never mid-refetch. Wrapped here (engine
+    // is already installed above) so store-free apps never carry the check.
+    const engineBlocked = GlobalQueue._transitionBlocked!;
+    GlobalQueue._transitionBlocked = transition => {
+      if (engineBlocked(transition)) return true;
+      for (const store of transition._optimisticStores) {
+        const firewall = (store[$TARGET] as StoreNode | undefined)?.[STORE_FIREWALL];
+        if (firewall && firewall._statusFlags & STATUS_PENDING) return true;
+      }
+      return false;
+    };
+  }
   const derived = typeof first === "function";
   // Plain form: the second slot carries options.
   if (!derived && options === undefined) options = second as ProjectionOptions | undefined;

packages/solid-signals/src/store/store.ts

@@ -918,8 +918,11 @@ function armOptimisticStoreWrite(target: StoreNode, store: any): void {
  * concurrent actions writing disjoint keys must revert independently, exactly
  * like optimistic signal nodes do via the transition's _optimisticNodes.
  * `activeTransition` is the write's transaction (action() opens it before the
- * body runs); null marks an ambient write that clears at plain flush end.
- * Same-key writes across actions keep last-write-wins layer semantics.
+ * body runs); null marks an ambient write, which clears at plain flush end —
+ * unless its flush's transition is blocked on the store's own in-flight truth
+ * (pending firewall, #2951), in which case it rides that transaction to
+ * settle. Same-key writes across actions keep last-write-wins layer
+ * semantics.
  */
 function stampOptimisticOwner(target: StoreNode, overrideKey: string, property: PropertyKey): void {
   if (overrideKey === STORE_OPTIMISTIC_OVERRIDE)

packages/solid-signals/tests/optimistic-store-refetch-hold.test.ts

@@ -0,0 +1,190 @@
+/**
+ * #2951 — bare (transaction-less) optimistic store writes made while the
+ * store's own truth is in flight must ride that refetch, not revert at plain
+ * flush end. Optimistic state clears when truth lands or its transaction
+ * settles — never on a timer.
+ *
+ * The broken shape: a click handler writes a plain dep (triggering a refetch
+ * of the derived optimistic store) and pushes an optimistic row in the same
+ * tick. The flush's transition adopted the write but nothing marked it
+ * blocked — signal-form createOptimistic carries the pending async and the
+ * override on ONE node (so transitionBlocked sees both), while the store form
+ * splits them between the firewall computed and the store targets' layer. The
+ * transition settled in the same flush that started the refetch, its settle
+ * consumed the layer, and the next click's draft composed on committed base —
+ * clobbering the still-rendered optimistic row instead of stacking on it.
+ */
+import { expect, test } from "vitest";
+import {
+  createEffect,
+  createOptimisticStore,
+  createRoot,
+  createSignal,
+  flush
+} from "../src/index.js";
+
+const tick = () => new Promise(r => setTimeout(r, 0));
+
+function setup() {
+  let setCount!: (v: number) => void;
+  let setS!: (fn: (s: { items: string[] }) => void) => void;
+  let dispose!: () => void;
+  const resolvers: ((items: string[]) => void)[] = [];
+  const views: string[][] = [];
+
+  createRoot(d => {
+    dispose = d;
+    const [count, _setCount] = createSignal(0);
+    setCount = _setCount;
+    const [store, _setS] = createOptimisticStore<{ items: string[] }>(
+      async () => {
+        count();
+        const items = await new Promise<string[]>(r => resolvers.push(r));
+        return { items };
+      },
+      { items: [] }
+    );
+    setS = _setS;
+    createEffect(
+      () => store.items.slice(),
+      v => {
+        views.push(v);
+      }
+    );
+  });
+  return { setCount, setS, resolvers, views, dispose };
+}
+
+test("#2951: consecutive bare writes stack on the same optimistic view until truth lands", async () => {
+  const { setCount, setS, resolvers, views, dispose } = setup();
+  flush();
+  await tick();
+  resolvers[0](["A"]);
+  await tick();
+  flush();
+  expect(views.at(-1)).toEqual(["A"]);
+
+  // Click 1: plain dep write starts a (slow) refetch; the bare optimistic
+  // push in the same tick must survive the flush that starts it.
+  setCount(1);
+  setS(d => {
+    d.items.push("U2*");
+  });
+  flush();
+  await tick();
+  expect(views.at(-1)).toEqual(["A", "U2*"]);
+
+  // Clicks 2 and 3 land while truth is still in flight: each draft composes
+  // ON TOP of the live optimistic view (same primitive -> same transaction).
+  setCount(2);
+  setS(d => {
+    expect(d.items.slice()).toEqual(["A", "U2*"]);
+    d.items.push("U3*");
+  });
+  flush();
+  await tick();
+  expect(views.at(-1)).toEqual(["A", "U2*", "U3*"]);
+
+  setCount(3);
+  setS(d => {
+    d.items.push("U4*");
+  });
+  flush();
+  await tick();
+  expect(views.at(-1)).toEqual(["A", "U2*", "U3*", "U4*"]);
+
+  // Truth supersedes every tentative layer: the projection landing consumes
+  // the overrides and the settled transaction sweeps the rest.
+  const all = ["A", "U2", "U3", "U4"];
+  for (let i = 1; i < resolvers.length; i++) resolvers[i](all);
+  await tick();
+  flush();
+  await tick();
+  flush();
+  expect(views.at(-1)).toEqual(all);
+  dispose();
+});
+
+test("#2951: write order within the tick does not matter (optimistic write first)", async () => {
+  const { setCount, setS, resolvers, views, dispose } = setup();
+  flush();
+  await tick();
+  resolvers[0](["A"]);
+  await tick();
+  flush();
+
+  setS(d => {
+    d.items.push("U2*");
+  });
+  setCount(1);
+  flush();
+  await tick();
+  expect(views.at(-1)).toEqual(["A", "U2*"]);
+
+  setS(d => {
+    d.items.push("U3*");
+  });
+  setCount(2);
+  flush();
+  await tick();
+  expect(views.at(-1)).toEqual(["A", "U2*", "U3*"]);
+
+  const all = ["A", "U2", "U3"];
+  for (let i = 1; i < resolvers.length; i++) resolvers[i](all);
+  await tick();
+  flush();
+  await tick();
+  flush();
+  expect(views.at(-1)).toEqual(all);
+  dispose();
+});
+
+test("#2951: a bare write during an already in-flight refetch (later tick) also holds", async () => {
+  const { setCount, setS, resolvers, views, dispose } = setup();
+  flush();
+  await tick();
+  resolvers[0](["A"]);
+  await tick();
+  flush();
+
+  // Start the refetch alone.
+  setCount(1);
+  flush();
+  await tick();
+  expect(views.at(-1)).toEqual(["A"]);
+
+  // A later tick's bare optimistic write must still ride the in-flight truth.
+  setS(d => {
+    d.items.push("U2*");
+  });
+  flush();
+  await tick();
+  expect(views.at(-1)).toEqual(["A", "U2*"]);
+
+  resolvers[1](["A", "U2"]);
+  await tick();
+  flush();
+  await tick();
+  flush();
+  expect(views.at(-1)).toEqual(["A", "U2"]);
+  dispose();
+});
+
+test("#2951: bare write on a derived store with settled truth keeps flash semantics", async () => {
+  const { setS, resolvers, views, dispose } = setup();
+  flush();
+  await tick();
+  resolvers[0](["A"]);
+  await tick();
+  flush();
+  expect(views.at(-1)).toEqual(["A"]);
+
+  // No refetch in flight: an ambient optimistic write with no transaction and
+  // no truth on the way reverts at plain flush end, as before.
+  setS(d => {
+    d.items.push("X*");
+  });
+  flush();
+  expect(views.at(-1)).toEqual(["A"]);
+  dispose();
+});