Skip to content

Commit 50225d0

Browse files
ryansolidClaude via Cursorcursoragent
committed
fix(signals): optimistic writes become visible at flush (A28 for overrides)
An optimistic write is a write: setOptimistic / an optimistic store setter parks the value in `_x._pendingOverride` and marks the node unflushed; the flush's promotion installs it as the active override (promoteOverride: install, sync companions, walk the lane). Until then plain reads, snapshot(), isPending() and the affects() declaration walk answer the flushed value — the same rule every other write follows, and the visibility React's useOptimistic gives. An ambient write (no action in flight) is shown by its flush to effects and reverted at the flush's end. Writer channels still compose on the tick's own writes: the functional updater reads the parked value, and store drafts read through `draftOverride` (parked write ahead of the flushed override) at seeding, in-draft reads, the draft length view and notifyOptimisticWrites' diff base — so two `count++` are +2, a push after a push lands in the next slot, and a toggle toggled back emits the cancelling write. Engine companions (the latest() shadow, the isPending() verdict signal — `_parentSource` set) are the system's own overrides written inside the flush and install eagerly. A record born in the same tick's optimistic write is declared on the draft (`affects(s.rows[i], key)` inside the setter) or after a yield; a same-tick `affects(state)` snapshots the pre-write view. Three affects tests and ~30 pre-flush reads re-expected; A28(5) in the spec, MIGRATION note, mined rules R2/R1/R34 marked superseded. Size: floor +52 B (22,279 -> 22,331); brotli caps ratcheted per scenario. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent 244efce commit 50225d0

23 files changed

Lines changed: 667 additions & 158 deletions
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@solidjs/signals": patch
3+
---
4+
5+
Optimistic writes become visible at flush (A28 for overrides). `setOptimistic(x)` / an optimistic store setter no longer installs the override synchronously: the write parks on the node and becomes the active override when the flush carries it, so plain reads, `snapshot()`, `isPending()` and `affects()` all answer the flushed value until then — the same rule every other write follows, and the same visibility React's `useOptimistic` gives. An ambient optimistic write (no action in flight) is shown by its flush to effects and reverted at the flush's end. The setter's functional updater and a store setter's draft still compose on the tick's own earlier writes (two `count++` are +2; a toggle toggled back cancels). To mark a row you are adding as pending, call `affects` on the draft row inside the setter.

‎documentation/solid-2.0/MIGRATION.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -390,6 +390,15 @@ const addTodo = action(function* (todo) {
390390
});
391391
```
392392

393+
Optimistic writes follow the same rule as every other write: they become visible at the flush that carries them, not synchronously. Reading `optimisticTodos.list` on the line after `setOptimisticTodos(...)` still answers the previous value (the same as React's `useOptimistic`, which shows the optimistic value on the next render). The setter's draft does see the writes earlier setters made in the same tick, so two `s.count++` in a row are +2. When you need to declare a row you are adding as pending, declare it on the draft, where it already exists:
394+
395+
```js
396+
setOptimisticMessages(s => {
397+
s.list.push({ text, status: "sending" });
398+
affects(s.list[s.list.length - 1], "status"); // not `messages.list[...]` — that row is not visible yet
399+
});
400+
```
401+
393402
## Stores
394403

395404
### Draft-first setters (and `storePath` as an opt-in helper)

‎packages/signals/docs/SPEC-ASYNC-SEMANTICS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ optimistic lanes.
4545

4646
| A26 | (**ruled 2026-07-17**, #2913; **enforcement hardened 2026-08-31**, #3141 — parking is flush-driven, and a transaction opened with no writes before its first suspension scheduled no flush, so `activeTransition` stayed ambient across the await window and captured exactly the unrelated work this ruling rejects: an optimistic store's authoritative landing on a still-live lane was adopted and held until the stranger action settled. `initTransition` now guarantees a flush, so the ambient window closes one flush later regardless of whether the transaction wrote anything) **`yield` is an action's only transaction-safe suspension point; internal `await` continuations run outside the transaction by platform necessity.** The driver regains control exclusively at yield boundaries (`it.next()` resumes the body synchronously, so `restoreTransition` wraps the segment); a post-`await` continuation is a bare promise job the runtime cannot hook — JavaScript has no ambient async context (TC39 AsyncContext, unshipped), and holding `activeTransition` open across the await window was rejected as strictly worse: unrelated ambient writes interleaving during `await fetch()` (a user click, a timer) would be captured into the action's transaction and held until it settles. Consequences, all accepted: (1) a write to a **fresh** signal between an `await` and the next `yield` escapes and commits ambiently; (2) a signal **already written under the transaction** rejoins it even after an `await` (its `_transition` stamp routes the write back) — containment is write-history-dependent by design, not by accident; (3) the supported idiom is `await` for typed results, then a **bare `yield` before any writes** — re-entry is what `yield` is for, and TypeScript ergonomics are exactly why `await` stays welcome (yield results are untyped; awaited results are typed); (4) calling public `flush()` inside an action body is out of contract — it drains and stashes the transaction mid-step, stranding later same-segment writes; follow the idiom and there is nothing to flush for. The doc block on `action()` teaches the idiom. | maintainer ruling 2026-07-17 ("2913 is not addressable… it is a known thing and it isn't detectable, otherwise we'd have a different solution"; "one reason to not yield the promise is TypeScript — we are set up so you can await typed results and then yield nothing the next line"; flush-in-body ruled out of contract: "if they follow that they shouldn't be flushing there") | `tests/action-await-contract.test.ts` (documented escape, the await-then-bare-yield idiom, yield-the-promise alternative, pre-await stamp rejoin); `tests/store/optimistic-ambient-capture.test.ts` (#3141 — the ambient window closes in one flush even for a writeless transaction) |
4747
| A27 | (**ruled 2026-08-10**) **The commit-#0 loading window is loading-class and verdict-quiet.** A node born committed via `loadingValue` (memos: `createMemo` / `createSignal(fn)` / `createOptimistic(fn)`) or `seedLoadingValue` (projections: `createProjection` / `createStore(fn)` / `createOptimisticStore(fn)`) starts with the loading value as commit #0 of its lineage instead of `STATUS_UNINITIALIZED`. While its first real answer is in flight, the window is loading-class on every axis: (1) **reads** — every consumer path serves commit #0 (no `NotReadyError`, no Loading-boundary suspension; `latest()` and `resolve()` return it; it is the compute's first `prev`); (2) **transitions** — the window never initiates or extends one (matching boundary-fallback semantics): ambient writes concurrent with the window commit immediately rather than being held, and a loading node mounted inside a live transition does not add to what that transition waits for; (3) **verdict** — `isPending` reads false at the source, upstream, and downstream, in both forms. The quiet ruling is not an exception to A19 but its question scoping applied: commit #0 answers the question **by declaration**, so the first flight is re-ask-shaped — the shown answer still answers the question (A24 family). The alternative was rejected as structurally unavailable: genuine pending is chain-shaped (the shadow of a held commit — held write upstream, in-flight async at the node, propagated non-finality downstream), and the window has no held commit to shadow, so a true verdict could only exist as a point anomaly at the probed node while upstream and downstream read false — and making it propagate would reintroduce exactly the status machinery the window exists to silence (and re-open the server/client split: `isPending` is always false on the server). First-load affordances are therefore the **value channel**'s job — the author encodes provenance (`null`, a `skeleton` flag) into the loading value itself — and `data.skeleton || isPending(data)` covers the two disjoint states. The window closes at the first real landing on any path (sync return, sync-resolved thenable, first iterator yield, async settle); a real error answers reads but does not close it — a retry serves commit #0 again. After close, A19 applies unchanged: refetches are pending-class forever. A25 is unchanged for plain seeds: without `seedLoadingValue` a derived store's seed remains an unobservable draft; `seedLoadingValue` is precisely the author promoting the seed to commit #0 — observable by declaration. | maintainer ruling 2026-08-10 ("the reason I had skeleton or isPending is because isPending would be false in my mind"; "it was false both upstream and downstream") | `tests/loading-value.test.ts` |
48-
| A28 | (**ruled 2026-09-08**; supersedes the #2922 mid-tick pull) **A write becomes visible at flush — to every channel.** Between `set(x)` and the next `flush()` the write is _unflushed_: it is not the committed value, not the staged value `latest()`/`isPending()` serve, and not an input to any recompute. `latest(x)` reads the **flushed staged world** — the newest value a flush has processed, held or not (a transaction's hold governs what _effects_ publish, not what `latest` answers; `latest` opts into that tearing, but only once a flush has carried the write) — so `setCount(30); latest(count)` is the pre-write answer until the flush that carries the write, after which `latest(count)` is 30 and `latest(doubled)` is 60 in the same instant (the derivation flushed with it). Nothing is ever 30 while its derivations are still 20-shaped: there is no "read your own write" channel that bypasses the flush, because no channel can show downstream of an unflushed write, and a channel that shows the write alone tears against every derivation. Consequences: (1) `latest` is one rule regardless of reader — event handler, memo, prop getter — so wrapping a `latest` read in a memo does not change what it answers (the visibility mismatch that motivated a separate `readStaged` does not arise); (2) `isPending(x)` is false for an unflushed write (nothing is observable yet to be pending _from_); (3) a companion created lazily after several flushes needs no retained history — the flushed staged value is the only answer it could ever have given — and it answers **as if it had always existed** (#3336): its backfill is the write of the transaction _holding_ that value, not of the ambient window the reader happens to run in, so it lives and reverts with the hold instead of reverting at the reader's flush end; the same one level down for a store key first read under a hold — the node is born with the committed value and the held write staged as the holding transaction's, so plain reads and `latest()` answer for an unobserved key exactly as they do for one some other reader had materialized before the hold; (4) `flush()` is the boundary, so the imperative idiom is `set(x); flush(); latest(x)`, and within a recompute or a flush every write issued is promoted at the end of that recompute/round so the graph never runs a round against a value it wrote but cannot see. Mechanically, writes take one path: stage + mark unflushed + schedule; consumers (`flush`, `recompute`) promote — clear the mark, restore the last-flushed staged view, sync companions, walk subscribers. There is no eager path. | maintainer ruling 2026-09-08 ("since we can't derive downstream before flush happens I do like latest being invisible until flush"; "nothing should be 30 pre flush… because double count can't be 60"; "latest opts into the tearing but really only after a flush") | `tests/latest-held-till-flush.test.ts`; `tests/latest-repeated-writes.test.ts` (#2922 re-pinned); `tests/latest-unobserved-memo.test.ts`; `tests/latest-probe-order-independence.test.ts`; `tests/isPending-memo-consistency.test.ts`; `tests/store/projection-transition-isolation.test.ts` |
48+
| A28 | (**ruled 2026-09-08**; supersedes the #2922 mid-tick pull) **A write becomes visible at flush — to every channel.** Between `set(x)` and the next `flush()` the write is _unflushed_: it is not the committed value, not the staged value `latest()`/`isPending()` serve, and not an input to any recompute. `latest(x)` reads the **flushed staged world** — the newest value a flush has processed, held or not (a transaction's hold governs what _effects_ publish, not what `latest` answers; `latest` opts into that tearing, but only once a flush has carried the write) — so `setCount(30); latest(count)` is the pre-write answer until the flush that carries the write, after which `latest(count)` is 30 and `latest(doubled)` is 60 in the same instant (the derivation flushed with it). Nothing is ever 30 while its derivations are still 20-shaped: there is no "read your own write" channel that bypasses the flush, because no channel can show downstream of an unflushed write, and a channel that shows the write alone tears against every derivation. Consequences: (1) `latest` is one rule regardless of reader — event handler, memo, prop getter — so wrapping a `latest` read in a memo does not change what it answers (the visibility mismatch that motivated a separate `readStaged` does not arise); (2) `isPending(x)` is false for an unflushed write (nothing is observable yet to be pending _from_); (3) a companion created lazily after several flushes needs no retained history — the flushed staged value is the only answer it could ever have given — and it answers **as if it had always existed** (#3336): its backfill is the write of the transaction _holding_ that value, not of the ambient window the reader happens to run in, so it lives and reverts with the hold instead of reverting at the reader's flush end; the same one level down for a store key first read under a hold — the node is born with the committed value and the held write staged as the holding transaction's, so plain reads and `latest()` answer for an unobserved key exactly as they do for one some other reader had materialized before the hold; (4) `flush()` is the boundary, so the imperative idiom is `set(x); flush(); latest(x)`, and within a recompute or a flush every write issued is promoted at the end of that recompute/round so the graph never runs a round against a value it wrote but cannot see; (5) (**extended 2026-09-10**, "let's match" — React's `useOptimistic` shows the optimistic value on the next render, never synchronously) **an optimistic write is a write**: `setOptimistic(x)` becomes the _active_ override (A17) at the flush that carries it, and until then no reader — plain, `snapshot()`, `isPending()`, the `affects()` declaration walk — sees it. An ambient one (no action in flight) is installed at the flush's start and reverted at its end, so effects are the channel that shows it (`[1, 2, 1]`); one an action holds stays readable after the flush for the action's lifetime. The writer's own composition channels see the parked write exactly as they see a plain write's staged value: a functional updater, and a store draft (`setState(s => …)` composes on the tick's earlier setters — two `count++` are +2, a push after a push lands in the next slot, a toggle toggled back diffs against the first and emits the write that cancels it). A record born in the same tick's optimistic write is therefore declared on the draft (`affects(s.rows[2], key)` inside the setter — the same target the flush will serve) or after a yield, not by a same-tick `affects(state)`, which snapshots the pre-write view. Engine companions (the `latest()` shadow, the `isPending()` verdict signal — `_parentSource` set) are the system's own overrides, written inside the flush after its promotions to mirror flushed state (A8), and install eagerly. Mechanically, writes take one path: stage + mark unflushed + schedule (an optimistic write parks its value in `_pendingOverride` instead of staging); consumers (`flush`, `recompute`) promote — clear the mark, restore the last-flushed staged view, sync companions, walk subscribers (for a parked override: install it, sync companions, walk the lane — `promoteOverride`). There is no eager path. | maintainer ruling 2026-09-08 ("since we can't derive downstream before flush happens I do like latest being invisible until flush"; "nothing should be 30 pre flush… because double count can't be 60"; "latest opts into the tearing but really only after a flush"); optimistic writes 2026-09-10 ("My gut is to match. I'm gathering React does."; "yeah lets match") | `tests/latest-held-till-flush.test.ts`; `tests/latest-repeated-writes.test.ts` (#2922 re-pinned); `tests/latest-unobserved-memo.test.ts`; `tests/latest-probe-order-independence.test.ts`; `tests/isPending-memo-consistency.test.ts`; `tests/store/projection-transition-isolation.test.ts`; optimistic: `tests/createOptimistic.test.ts` ("basic behavior"), `tests/store/createOptimisticStore.test.ts` ("basic behavior", "rapid successive actions"), `tests/question-scoped-pending.test.ts` (affects on the draft), `tests/optimistic-store-layer-scope.test.ts` (#2899) |
4949

5050
## Tier B (inferred — needs verdict)
5151

‎packages/signals/docs/rules-mining/core-store.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,9 +113,9 @@ Files: **CS** = `tests/store/createStore.test.ts`, **SP** = `tests/store/storePa
113113
**R33. Action/async lane semantics on store properties: a write held by an action makes isPending true for that property (per-property, not whole-store) while showing the committed value; applies on settle.** Aligned: the node-lane model's purpose.
114114
- CS "isPending sees a derived store property update held by an action", "…held by async work".
115115

116-
**R34. Optimistic writes visible immediately at write time (before flush), never touch base raw; ambient (non-action) optimistic writes auto-revert at flush end.**
116+
**R34. ~~Optimistic writes visible immediately at write time (before flush)~~, never touch base raw; ambient (non-action) optimistic writes auto-revert at flush end.**
117117
- SH "optimistic shallow store: replacement stages, base rows untouched, children raw".
118-
- **CONFLICT (asymmetry to define):** ordinary writes invisible pre-flush (R24) but optimistic writes visible pre-flush. Read-path table needs a "pre-flush" column.
118+
- ~~**CONFLICT (asymmetry to define):** ordinary writes invisible pre-flush (R24) but optimistic writes visible pre-flush. Read-path table needs a "pre-flush" column.~~ **Resolved 2026-09-10 by A28(5):** the asymmetry is gone — optimistic writes, like ordinary ones, become visible at the flush that carries them. The SH test was re-expected in place (the replacement is shown by the flush, to effects, then reverted).
119119

120120
**R35. Mid-refetch optimistic overlays are consumed when data lands — identical via direct reads, mapArray, wrapper views, Object.keys, snapshot.**
121121
- SIS 5 tests.

‎packages/signals/docs/rules-mining/optimistic-lanes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Scope note: CO contains **no store-form tests** — it is entirely the signal/co
99
**R1.** `createOptimistic(value | fn)` returns `[accessor, setter]`; the accessor returns the initial or computed value; the setter accepts a value or an updater function.
1010
- Evidence: CO — "should store and return value on read", "should update signal via update function and revert on flush"
1111

12-
**R2.** An optimistic write is synchronously visible to direct reads before any flush — inside the action body, outside it, and outside any reactive context.
12+
**R2.** ~~An optimistic write is synchronously visible to direct reads before any flush — inside the action body, outside it, and outside any reactive context.~~ **Superseded 2026-09-10 by A28(5)** (SPEC-ASYNC-SEMANTICS.md): an optimistic write becomes the active override at the flush that carries it; before that, only the setter's own updater (and a store draft) sees it. The cited tests were re-expected in place.
1313
- Evidence: CO — "should update signal via setter and revert on flush", "reading outside reactive context…", "rapid user actions: multiple selections before first resolves"
1414

1515
**R3.** The setter's updater receives the current *visible* (optimistic-if-overridden) value, never the committed value; a plain setter on the underlying source during a transition composes on the transition's *pending* value. The two compose independently.

‎packages/signals/docs/rules-mining/optimistic-store.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Source suites: `tests/store/createOptimisticStore.test.ts`, `tests/optimistic-st
44

55
## A. Visibility
66

7-
**R1 — Synchronous universal visibility.** An optimistic write is visible to every reader immediately at write time, before any flush: tracked, untracked, inside the action body, outside any reactive context, and subsequent setter drafts.
7+
**R1 — ~~Synchronous universal visibility.~~** ~~An optimistic write is visible to every reader immediately at write time, before any flush: tracked, untracked, inside the action body, outside any reactive context, and subsequent setter drafts.~~ **Superseded 2026-09-10 by A28(5)** (SPEC-ASYNC-SEMANTICS.md): visible to every reader at the flush that carries it. The one surviving clause is "subsequent setter drafts" — the draft is the writer's channel and composes on the tick's parked writes (`draftOverride`). The cited tests were re-expected in place.
88
- createOptimisticStore — "should update store via setter and revert on flush", "should show optimistic value when read outside reactive context"; refetch-hold draft assertion.
99

1010
**R2 — Drafts compose on the live optimistic view.** Each setter draft reads through all prior optimistic state (same tick, across ticks, across separate actions/refetches).

0 commit comments

Comments
 (0)