fix(signals): arm the optimistic store mask only on effective writes

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

Author: ryansolid

.changeset/optimistic-mask-effective-writes-only.md

@@ -0,0 +1,5 @@
+---
+"@solidjs/signals": patch
+---
+
+Ineffective optimistic store writes no longer arm the store-wide isPending mask or entangle the transition. Previously the mask armed on any write-trap fire before the equality short-circuit, so `setStore(s => ({ ...s }))` (which replays every key with equal values) and same-value property writes silently decreed the store settled while the semantically identical `setStore(s => s)` did not. The mask and reversion tracking now arm only when data actually changes, matching the signal path where an equal-value first optimistic write creates no override.

packages/solid-signals/SPEC-ASYNC-SEMANTICS.md

@@ -37,7 +37,7 @@ optimistic lanes.
 | A18 | (was B4; **refined by re-rule 2026-07-07b**) An override's lifetime is bound to **its own transition** — which, because lanes keep their transitions separate from unrelated work, contains exactly the override's own async cascade. Mechanically: authoritative values arriving under an active override hold in `_pendingValue` like any other transition write and **elevate to `_value` only at their transition's commit** (`_value` changes at commit points, period); the elevation is unobservable under the override mask (A17); reverting is a pure drop — there is no revert target and reverts commit nothing. Consequences: (1) in unmerged graphs, own-source resolution IS the lane-transition's completion, so the correction reveals on arrival — the original A18 pins hold unchanged; (2) matching confirmations collapse silently (revert sees value == override, nobody re-runs); (3) when the override's transition genuinely merges with unrelated async, the correction reveals atomically with that merged completion — reading `isPending === false` throughout (A20 mask: the override is decreed settled) — corrections still *propagate* internally on arrival (fresh readers/async drivers see the hold), so downstream refetches start immediately and no waterfalls form; only the reveal is gated. This supersedes the earlier "bound to its own async source, not its transition" formulation, which was implemented by escaping the transition commit (revert-target commit at revert) and allowed a mid-flight arrival to reveal before its own transition completed. | maintainer rulings, 2026-07-07 (original) and 2026-07-07b (re-rule: "the non-blocking aspect… only gates the reveal"; `_value` elevation at commit points) | `tests/spec-async-semantics.test.ts` (same pins — behavior coincides in unmerged graphs) |
 | A19 | (was C1 — **partially reverses an earlier decision**) **Definition: `isPending(x)` ≡ the value you can currently observe for `x` is not the final one.** Three causes of non-finality, each ending on its own terms: (i) a write held by a live transition — ends at commit; (ii) the node's own async in flight — ends at resolution; (iii) a fresh value that arrived but is held uncommitted by a transition it's entangled with — ends at that commit. A node is pending while *any* cause holds it and final the moment none does — cascading async falls out of the definition rather than needing a rule ("once it can show its landed value it is no longer pending"). **Two exceptions.** (1) The initial NotReady: an uninitialized source is *loading*, not pending (A16/A12) — no observable value exists to be non-final — and its thrown `NotReadyError` must propagate to loading boundaries (A16/B5a) because SSR streaming and hydration reveal are driven by boundaries. (2) Decree (amended 2026-07-07c): an active optimistic override is final *because its writer declared it so* — the A20 mask exempts the node (and, for derived stores, the whole store — A21) from every cause above for the override's lifetime. "Not the final one" is judged per channel read (A20 §2), and an override supersedes both channels. Everywhere else, boundaries and reporters never enter the definition: they decide what renders and what a transition waits for, not verdicts. The rejected earlier framing ("if it isn't read somewhere that reports to the transition, it isn't actually pending") was a proxy for cause (i) wrongly applied to causes (ii)/(iii), tying data verdicts to graph-topology accidents. Causes (ii)/(iii) were implemented by the #2838 shadow/companion redesign (2026-07-07) — see V3/V1 under Known violations (fixed). | maintainer ruling, 2026-07-07 | cause (i) + boundary interplay: `tests/spec-async-semantics.test.ts`; causes (ii)/(iii): same file, "V1–V5" describe |
 | A20 | (**re-ruled 2026-07-07c** — supersedes the 2026-07-07 "overrides are unsettled" ruling, which held for one day) **The mask: an optimistic override is certainty by decree; `isPending` follows the channel you read.** (1) An *active* override reads `isPending === false` — uniformly, on every node kind, in **both** forms, for the override's whole lifetime (until its own source confirms it, A18, or the transition reverts it). Writing optimistically *declares* the shown value the outcome; a decree cannot be superseded by work already in motion, because the writer just asserted it won't be. `isPending` is reserved for data being updated by machinery the reader did *not* decree — refetches, transition-held commits — never for the provisional nature of an override ("isPending is about the data being in the process of being updated, not about an action being in progress"). Action-scoped affordances ("Saving…", per-row spinners) therefore belong **in the data**: a co-written flag (`todo.pending = true` — the repo's todos example) or a separate `createOptimistic(false)`. You are already writing the optimistic update; the flag rides along. The old no-extra-boolean idiom (`isPending(() => books.length)` as the "Adding…" label) is rejected — it derived an action's progress from a data verdict. (2) Verdicts are per-channel: the plain form watches the *committed* channel — pending while its own fetch is in flight and while a resolved value is held uncommitted by a transition; the latest form watches the *fresh* channel — `latest` is an override the system writes for itself the moment a held value exists (A8), and that self-override masks holds like any user override, leaving only actually-in-flight async as its pending cause. Pairing falls out for both forms: neither ever pairs `true` with the value that made it false. (3) Scope: the mask covers the primitive that was written — node-scoped for signals and computeds; store-scoped for derived optimistic stores (A21). (4) Non-derived optimistic signals/stores are never pending *from themselves* — there is no source to confirm or refetch, the write is an instantly-visible decree — they pend only via a transition hold on the trigger like any plain signal. (5) No tension with A17/A18: the override is THE value (A17), its lifetime is transition-bound (A18), and the mask simply says the verdict agrees with the decree for exactly that lifetime — mask on at write, off at revert/confirm, in the same atomic settle. | GabbeV model adopted, maintainer re-rule 2026-07-07c (#2844/#2728 discussions) | A20 describe in `tests/spec-async-semantics.test.ts`; `tests/createOptimistic.test.ts` (mask + source-still-pends contrast); latest-channel: `tests/createMemo.test.ts`, solid-web `test/latest-async.spec.tsx`; INV-10 enforces the mask in dev |
-| A21 | **The store-wide mask: for a derived optimistic store, the store is the primitive — any active optimistic write masks `isPending` for the *entire* store.** Written leaves, untouched siblings, structural reads (`length`, iteration), and the firewall's own refetch all read `false` while any override on the store is live, in both forms; the mask lifts when the store's optimistic state fully clears (same lane lifetime as A20). Rationale: a refetch pends the whole store because the authority's change set is unbounded (A9) — the decree that silences it must speak for the same unbounded scope, or `isPending(() => store.items.length)` would flip on a refresh the writer already declared the outcome of ("If I do `setOptimisticFormOptions(x => x.cities.push("London"))` then I expect the select to consider it settled" — same for `x.cities[i] = "London"`). Once you write optimistically you own the store's pending affordances (A20 §1: flags in the data). Consequences: (1) optimistic writes to the same store entangle — not just writes to the same property; (2) plain (non-derived) optimistic stores get this for free — with no source they were never pending from themselves (A20 §4); (3) A9 is the unmasked rule: with **no** active override, every leaf reports the firewall's refetch in both forms — the store-wide mask is an override-lifetime exception, not a repeal. | GabbeV/maintainer, 2026-07-07c ("any optimistic write turns off isPending for the whole store"; "the store is the boundary") | "store-wide mask" pin in the A20 describe, `tests/spec-async-semantics.test.ts`; `tests/store/createOptimisticStore.test.ts` (refresh-pends → write-masks → lift contrasts); INV-10 store-mask arm |
+| A21 | **The store-wide mask: for a derived optimistic store, the store is the primitive — any active optimistic write masks `isPending` for the *entire* store.** Written leaves, untouched siblings, structural reads (`length`, iteration), and the firewall's own refetch all read `false` while any override on the store is live, in both forms; the mask lifts when the store's optimistic state fully clears (same lane lifetime as A20). Rationale: a refetch pends the whole store because the authority's change set is unbounded (A9) — the decree that silences it must speak for the same unbounded scope, or `isPending(() => store.items.length)` would flip on a refresh the writer already declared the outcome of ("If I do `setOptimisticFormOptions(x => x.cities.push("London"))` then I expect the select to consider it settled" — same for `x.cities[i] = "London"`). Once you write optimistically you own the store's pending affordances (A20 §1: flags in the data). Consequences: (1) optimistic writes to the same store entangle — not just writes to the same property; (2) plain (non-derived) optimistic stores get this for free — with no source they were never pending from themselves (A20 §4); (3) A9 is the unmasked rule: with **no** active override, every leaf reports the firewall's refetch in both forms — the store-wide mask is an override-lifetime exception, not a repeal; (4) (added 2026-07-08) only **effective** writes arm the mask and entangle — the decree is about data actually asserted, so trap fires that change nothing (`s => s`, `s => ({ ...s })` replaying equal values, same-value property writes, deletes of absent properties) are no-ops with no decree, matching the signal path where an equal-value first optimistic write short-circuits before any override exists. A deliberate "silence this refresh" affordance is future explicit API (#2844 family), not an emergent no-op write. | GabbeV/maintainer, 2026-07-07c ("any optimistic write turns off isPending for the whole store"; "the store is the boundary"); effective-write gate ruled 2026-07-08 (brenelz/GabbeV probing `setOptStore(s => s)`) | "store-wide mask" pin in the A20 describe, `tests/spec-async-semantics.test.ts`; `tests/store/createOptimisticStore.test.ts` (refresh-pends → write-masks → lift contrasts); INV-10 store-mask arm |
 
 ## Tier B (inferred — needs verdict)
 
@@ -170,6 +170,12 @@ rippled through:
 - **INV-10** added: dev-mode asserts a companion's observable verdict is
   `false` whenever its owner has an active override or its firewall's
   store-wide mask is up.
+- **A21 consequence (4)** added 2026-07-08: the mask/entanglement arm only on
+  *effective* writes. Previously arming ran in `prepareStoreWrite` before the
+  equality short-circuit, so `s => ({ ...s })` and same-value writes masked
+  while the semantically identical `s => s` did not — the boundary was "did a
+  trap fire", not "did data change". Arming now happens per-trap after the
+  effective-write determination (`armOptimisticStoreWrite`).
 
 What did *not* change: A17 (override is THE value), A18's lifetime/hold
 mechanics, A19's cause algebra for non-decreed data, A13/V1–V3/V5 (resting

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

@@ -422,11 +422,20 @@ function prepareStoreWrite(target: StoreNode, store: any, property: PropertyKey)
   }
   const useOptimistic = target[STORE_OPTIMISTIC] && !projectionWriteActive;
   const overrideKey = useOptimistic ? STORE_OPTIMISTIC_OVERRIDE : STORE_OVERRIDE;
-  if (useOptimistic) {
+  return { base, overrideKey, state };
+}
+
+/**
+ * Registers the store for transition reversion and arms the store-wide
+ * isPending mask (A21). Called only once a write is known to be effective —
+ * ineffective writes (same value, delete of an absent property) are no-ops
+ * and must not decree the store settled or entangle it.
+ */
+function armOptimisticStoreWrite(target: StoreNode, store: any): void {
+  if (target[STORE_OPTIMISTIC] && !projectionWriteActive) {
     trackOptimisticStore(store);
     maskStoreTarget(target, true);
   }
-  return { base, overrideKey, state };
 }
 
 function upsertStoreNode(
@@ -643,6 +652,7 @@ export const storeTraps: ProxyHandler<StoreNode> = {
         const nextLength = isArrayIndexWrite && nextIndex > len ? nextIndex : undefined;
 
         if (prev === value && nextLength === undefined) return true;
+        armOptimisticStoreWrite(target, store);
         if (value !== undefined && value === base && nextLength === undefined)
           delete target[overrideKey]?.[property];
         else {
@@ -698,6 +708,7 @@ export const storeTraps: ProxyHandler<StoreNode> = {
     if (writeOnly(store)) {
       untrack(() => {
         const { base, overrideKey } = prepareStoreWrite(target, store, property);
+        armOptimisticStoreWrite(target, store);
         const normalizedDescriptor =
           "value" in descriptor
             ? {
@@ -734,19 +745,16 @@ export const storeTraps: ProxyHandler<StoreNode> = {
       untrack(() => {
         const useOptimistic = target[STORE_OPTIMISTIC] && !projectionWriteActive;
         const overrideKey = useOptimistic ? STORE_OPTIMISTIC_OVERRIDE : STORE_OVERRIDE;
-        // Track store for reversion when writing optimistically
-        if (useOptimistic) {
-          trackOptimisticStore(target[$PROXY]);
-          maskStoreTarget(target, true);
-        }
         const prevLayer = getOverlayLayer(target, property);
         const prev = prevLayer ? prevLayer[property] : target[STORE_VALUE][property];
         if (
           property in target[STORE_VALUE] ||
           (target[STORE_OVERRIDE] && property in target[STORE_OVERRIDE])
         ) {
+          armOptimisticStoreWrite(target, target[$PROXY]);
           (target[overrideKey] || (target[overrideKey] = Object.create(null)))[property] = $DELETED;
         } else if (target[overrideKey] && property in target[overrideKey]) {
+          armOptimisticStoreWrite(target, target[$PROXY]);
           delete target[overrideKey][property];
         } else return true;
         notifyStoreProperty(target, property, "delete", undefined, prev, true);

packages/solid-signals/tests/store/createOptimisticStore.test.ts

@@ -1733,6 +1733,101 @@ describe("createOptimisticStore", () => {
       expect(isPending(() => state!.data)).toBe(false);
     });
 
+    // The mask is armed by effective writes (data actually changed), not by
+    // trap fires: `s => s`, `s => ({ ...s })` (replays every key with equal
+    // values), same-value property writes, and deletes of absent properties
+    // are all no-ops and must not decree the store settled or entangle it.
+    describe("ineffective optimistic writes do not arm the mask", () => {
+      async function setup() {
+        const [$id, setId] = createSignal(1);
+        let state!: { data: number };
+        let setState!: (fn: (s: { data: number }) => any) => void;
+
+        createRoot(() => {
+          [state, setState] = createOptimisticStore(
+            async (s: { data: number }) => {
+              const id = $id();
+              await Promise.resolve();
+              s.data = id * 10;
+            },
+            { data: 0 }
+          );
+          createRenderEffect(
+            () => state.data,
+            () => {}
+          );
+        });
+
+        flush();
+        await new Promise(r => setTimeout(r, 0));
+        expect(state.data).toBe(10);
+
+        // Refetch in flight: the leaf pends (live-probe baseline).
+        setId(2);
+        flush();
+        expect(isPending(() => state.data)).toBe(true);
+
+        return { state, setState };
+      }
+
+      async function finish(state: { data: number }) {
+        await new Promise(r => setTimeout(r, 0));
+        expect(state.data).toBe(20);
+        expect(isPending(() => state.data)).toBe(false);
+      }
+
+      it("pure no-op setter (s => s) leaves the refetch pending", async () => {
+        const { state, setState } = await setup();
+        setState(s => s);
+        expect(isPending(() => state.data)).toBe(true); // not masked pre-flush either
+        flush();
+        expect(isPending(() => state.data)).toBe(true);
+        await finish(state);
+      });
+
+      it("same-value property write leaves the refetch pending", async () => {
+        const { state, setState } = await setup();
+        setState(s => {
+          s.data = s.data;
+        });
+        expect(isPending(() => state.data)).toBe(true);
+        flush();
+        expect(isPending(() => state.data)).toBe(true);
+        await finish(state);
+      });
+
+      it("returned shallow copy leaves the refetch pending", async () => {
+        const { state, setState } = await setup();
+        setState(s => ({ ...s }));
+        expect(isPending(() => state.data)).toBe(true);
+        flush();
+        expect(isPending(() => state.data)).toBe(true);
+        await finish(state);
+      });
+
+      it("delete of an absent property leaves the refetch pending", async () => {
+        const { state, setState } = await setup();
+        setState(s => {
+          delete (s as any).missing;
+        });
+        expect(isPending(() => state.data)).toBe(true);
+        flush();
+        expect(isPending(() => state.data)).toBe(true);
+        await finish(state);
+      });
+
+      it("control: a real write mid-refetch masks", async () => {
+        const { state, setState } = await setup();
+        setState(s => {
+          s.data = 999;
+        });
+        flush();
+        expect(state.data).toBe(999);
+        expect(isPending(() => state.data)).toBe(false);
+        await finish(state);
+      });
+    });
+
     it("isPending preserves async optimistic store overrides", async () => {
       const [$id, setId] = createSignal(1);
       let state: { data: number };