Skip to content

Commit cb20ea2

Browse files
ryansolidClaude via Cursor
andcommitted
fix(signals): a projection draft is valid until superseded or disposed, not until no longer in flight (#3585)
The draft handed to a createProjection / createStore(fn) / createOptimisticStore(fn) run now stays writable after the derive returns until the next run of the derive starts or the owner is disposed (proj R37). A subscription set up inside a sync derive can push into the draft from its callback without the never-resolving- Promise workaround. The old gate (`!settled || owner._x?._inFlight === result`) was timing-dependent: a sync derive's `undefined` result equalled a never-installed `_x`'s `_inFlight`, so the "dead" draft was live exactly while nothing had read the projection, and a superseded run's leaked callback kept writing into the next run's state. The gate is now a per-run token on the family plus `isDisposed(owner)`. A late write with no flight up arms the flush itself: `schedule()` withholds its microtask under projectionWriteActive (a landing normally drains those writes and a drain before the landing tears the run), and the draft re-arms it through `scheduleWithheld` — before, such a write left `scheduled` set with no microtask and stranded the whole scheduler until an explicit flush(). Writes to a superseded or disposed draft are dropped silently (same as R26). seedLoadingValue's detached shadow is a documented carve-out. Co-authored-by: Claude via Cursor <[email protected]>
1 parent be83b01 commit cb20ea2

9 files changed

Lines changed: 778 additions & 72 deletions

File tree

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+
Behavior change: a `createProjection` / `createStore(fn, seed)` / `createOptimisticStore(fn)` draft now stays valid until it is superseded by the next run of the derive or its owner is disposed — no longer "until no longer in flight" (#3585). A subscription set up inside a sync derive can write through the draft from its callback without the never-resolving-Promise workaround; the write applies, notifies subscribers, and arms the flush itself when no async run is in flight to do so (the scheduler used to strand on such writes). Writes through a superseded or disposed draft are dropped silently, so a previous run's leaked callback can no longer write into the current run's state (it did before, whenever nothing had read the projection yet).

‎documentation/solid-2.0/04-stores.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,20 @@ const users = createProjection(async () => {
117117
}, [], { key: "id" });
118118
```
119119

120+
**The draft stays valid until the next run or disposal** (#3585). The draft a run receives is not closed when the derive returns: it remains writable — from a subscription callback, a timer, a post-`await` continuation — until the derive runs again (the next run's draft replaces it the moment that run starts, even if it is still awaiting) or the projection's owner is disposed. That makes external subscriptions a plain derive:
121+
122+
```js
123+
const data = createProjection((draft) => {
124+
draft.length = 0;
125+
const unsubscribe = subscribeToData(props.id, (item) => {
126+
draft.push(item);
127+
});
128+
onCleanup(unsubscribe);
129+
}, []);
130+
```
131+
132+
A late write is applied to the store and reaches subscribers at the next flush, which it schedules itself when no async run is in flight to do so. Writes through a superseded or disposed draft are dropped silently — a callback from a previous run cannot write into the state the current run owns, and a leaked callback after unmount is a no-op — but the cleanup is still yours (`onCleanup(unsubscribe)` above); the draft going dead does not stop the subscription. One carve-out: with `seedLoadingValue: true`, the first run works a detached copy of the seed rather than the live draft (the seed *is* the displayed value during the loading window), so a callback captured during that first run stops writing through once it lands — set up long-lived subscriptions on later runs, or without `seedLoadingValue`.
133+
120134
**A derive must never swallow `NotReadyError`** (#3073). Reading a not-yet-settled async source inside a derive throws; that propagation is load-bearing. It is how loading states coordinate on every build, and on the server build — which has no subscription graph — it is additionally the *only* re-derive channel: the projection machinery catches the escaping error, holds the projection pending, and retries the derive when the source settles. A derive that wraps its reads in a broad `try/catch` "completes" with partial state and severs that channel — the browser build masks the mistake (dependencies register before the throw, so reactivity re-runs the derive anyway), but the node build freezes at the first result. To branch on readiness instead of suspending, probe with `isPending()` rather than catching; not-ready handling (hold the previous state, retry at settlement) is already the machinery's job.
121135

122136
**`createStore(fn, seed, options?)`** — a writable derived store. Same derive semantics as `createProjection`, but returns `[store, setter]` so you can also write to it imperatively. Use this when you need both reactively derived state *and* local mutations.

‎packages/signals/docs/RULES-INDEX.md‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
3131
| R (CS) | 59 | 18 | 16 | 31 |
3232
| R (OL) | 37 | 0 | 0 | 37 |
3333
| R (OS) | 46 | 2 | 0 | 44 |
34-
| R (PJ) | 36 | 6 | 1 | 30 |
34+
| R (PJ) | 37 | 8 | 5 | 28 |
3535
| R (RS) | 38 | 9 | 2 | 27 |
3636
| § | 24 | 14 | 8 | 8 |
3737

@@ -66,7 +66,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
6666
| A19 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:101` | async.ts×1 core.ts×2 optimistic.ts×1 verdict.ts×2 | spec-async-semantics.test.ts×3 superseded-before-first-commit.test.ts×1 uninitialized-visibility.test.ts×1 visibility-oracle-store.states.ts×8 visibility-oracle-store.test.ts×1 visibility-oracle.states.ts×11 visibility-oracle.test.ts×1 write-proposals-3494.test.ts×1 | [ruled 2026-07-07 (promoted from C1)] `isPending(x)` ≡ the observable value is not final (three causes) — (was C1 — **partially reverses an earlier decision**) **Definition: `isPending(x)` ≡ the value… |
6767
| A20 | superseded | `docs/SPEC-ASYNC-SEMANTICS.md:350` | invariants.ts×1 | question-scoped-pending.test.ts×2 spec-async-semantics.test.ts×3 createOptimisticStore.test.ts×1 | [superseded 2026-07-13 by A24] (superseded) Optimistic writes announce a store-wide pending — (**SUPERSEDED 2026-07-13 by A24** — the mask is deleted; optimistic writes are verdict-inert. Kept for the… |
6868
| A21 | superseded | `docs/SPEC-ASYNC-SEMANTICS.md:357` | — | question-scoped-pending.test.ts×3 spec-async-semantics.test.ts×3 | [superseded 2026-07-13 by A24] (superseded) The store-wide mask — (**SUPERSEDED 2026-07-13 by A24** — the store-wide mask is deleted with the mask model; nothing silences a new question. The effective… |
69-
| A22 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:181` | — | spec-async-semantics.test.ts×1 visibility-oracle-store.states.ts×1 | [ruled 2026-07-08] Pending is per-node; store-wide only for the firewall's own work — **Pending is per-node: store-wide verdicts exist only as the firewall's own in-flight work (A9) and the decree tha… |
69+
| A22 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:181` | — | createProjection.draft-lifetime-3585.test.ts×1 spec-async-semantics.test.ts×1 visibility-oracle-store.states.ts×1 | [ruled 2026-07-08] Pending is per-node; store-wide only for the firewall's own work — **Pending is per-node: store-wide verdicts exist only as the firewall's own in-flight work (A9) and the decree tha… |
7070
| A23 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:189` | — | spec-async-semantics.test.ts×1 | [ruled 2026-07-08] The `isPending` probe is reads-only — **The `isPending` probe is reads-only — the thunk's return value is never inspected.** `isPending(() => store)` reads nothing and reports `fals… |
7171
| A24 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:109` | — | optimistic-undefined-override.test.ts×1 reveal-gating-contract.test.ts×1 spec-async-semantics.test.ts×2 visibility-oracle-store.states.ts×4 visibility-oracle.states.ts×3 visibility-oracle.test.ts×1 | [ruled 2026-07-13] Question-scoped pending: pending iff a value change is in flight or an `affects()` mark is live — (**ruled 2026-07-13** — supersedes A20/A21; the converged model from the #2844/#272… |
7272
| A25 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:251` | verdict.ts×1 | uninitialized-visibility.test.ts×3 visibility-oracle-store.states.ts×7 visibility-oracle-store.test.ts×1 | [ruled 2026-07-16] A derived store's seed is a draft, never an observable value — (**ruled 2026-07-16**, #2897) **A derived store's seed is a draft, never an observable value.** The seed exists for th… |
@@ -178,7 +178,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
178178
| CS-R34 | live | `docs/rules-mining/core-store.md:151` | store.ts×1 | visibility-oracle-store.states.ts×1 | ~~Optimistic writes visible immediately at write time (before flush)~~, never touch base raw; ambient (non-action) optimistic writes auto-revert at flush end.** _Visibility superseded 2026-09-10 by A2… |
179179
| CS-R35 | live | `docs/rules-mining/core-store.md:156` | — | — | Mid-refetch optimistic overlays are consumed when data lands — identical via direct reads, mapArray, wrapper views, Object.keys, snapshot.** |
180180
| CS-R36 | live | `docs/rules-mining/core-store.md:160` | — | — | An active optimistic hold on a wrapper view masks inner-store changes for the view's subscribers: mid-hold inner refresh landing causes ZERO re-runs of the view's structural subscribers; the reveal re… |
181-
| CS-R37 | live | `docs/rules-mining/core-store.md:165` | — | visibility-oracle-store.states.ts×3 | Setting store state from effect callbacks and promise resolutions works, applying next flush.** |
181+
| CS-R37 | live | `docs/rules-mining/core-store.md:165` | — | createProjection.draft-lifetime-3585.test.ts×1 visibility-oracle-store.states.ts×3 | Setting store state from effect callbacks and promise resolutions works, applying next flush.** |
182182
| CS-R38 | live | `docs/rules-mining/core-store.md:171` | — | — | Shallow stores: root keys reactive (per-key nodes, membership, length), values served raw by identity at every depth, arrays and objects.** |
183183
| CS-R39 | live | `docs/rules-mining/core-store.md:175` | — | visibility-oracle-store.states.ts×1 | Shallow setter-scope reads serve raws; in-place mutation of a served raw is reactively inert — records replaced, never edited.** |
184184
| CS-R40 | live | `docs/rules-mining/core-store.md:179` | — | — | Shallow reconcile is positional: per-index effects only where the reference changed; reference-identical rows skip entirely; length propagates; `key` option moot.** Aligned: unowned-reference skip rul… |
@@ -317,20 +317,21 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
317317
| PJ-R20 | live | `docs/rules-mining/projections.md:70` | — | — | Chained backing works for array roots** (structural + row-level edits flow). |
318318
| PJ-R21 | live | `docs/rules-mining/projections.md:72` | — | — | `createStore(fn, seed)` is the same projection mechanism and chains identically.** |
319319
| PJ-R22 | live | `docs/rules-mining/projections.md:74` | — | — | `snapshot()` of a chained projection returns plain data equal to the current view and detached from future source writes.** |
320-
| PJ-R23 | live | `docs/rules-mining/projections.md:80` | store.ts×2 | — | The seed is a draft for the derive, never observable (#2897)**: until first settle/yield, every read — tracked, untracked, enumeration/spread — throws NotReadyError. |
320+
| PJ-R23 | live | `docs/rules-mining/projections.md:80` | store.ts×2 | createProjection.draft-lifetime-3585.test.ts×1 | The seed is a draft for the derive, never observable (#2897)**: until first settle/yield, every read — tracked, untracked, enumeration/spread — throws NotReadyError. |
321321
| PJ-R24 | live | `docs/rules-mining/projections.md:83` | — | — | Draft writes during an in-flight async run are invisible until that run settles** (per-run atomic visibility). |
322-
| PJ-R25 | live | `docs/rules-mining/projections.md:85` | — | — | Async generators publish one snapshot per yield**: bare `yield` publishes accumulated draft mutations; `yield value` replaces the entire state (no merge); each yield transforms again. |
323-
| PJ-R26 | live | `docs/rules-mining/projections.md:87` | — | — | Latest-run-wins supersession**: superseded runs' later yields and pending draft writes are discarded entirely; if no run ever landed, stays NotReady. |
324-
| PJ-R27 | live | `docs/rules-mining/projections.md:89` | — | — | Async recompute does not coarsen granularity**: after settle, only changed-path subscribers rerun. |
325-
| PJ-R28 | live | `docs/rules-mining/projections.md:91` | — | — | `refresh(proj)` forces a new derive run; bare refresh is quiet** (no pending published; silent reveal). |
326-
| PJ-R29 | live | `docs/rules-mining/projections.md:93` | — | — | `affects(proj)` + `refresh(proj)` is a declared reload**: subscribed effects see isPending true + stale value for the window, then settle. |
327-
| PJ-R30 | live | `docs/rules-mining/projections.md:95` | — | — | With no effect subscribed, async work creates no transition** (isPending false throughout initial load). |
328-
| PJ-R31 | live | `docs/rules-mining/projections.md:97` | — | — | With a subscribed effect, source-triggered async reruns are transitions** (pending true + stale during window); initial no-stale-data load is never pending. |
329-
| PJ-R32 | live | `docs/rules-mining/projections.md:99` | — | — | Reading a pending async source inside the derive propagates NotReady to consumers** (Loading boundaries fall back); settle fires downstream effects exactly once with the settled value, never the seed … |
330-
| PJ-R33 | live | `docs/rules-mining/projections.md:101` | — | — | Settlement is a status change, not a value diff**: boundaries and blocked effects release even when the settled value equals the seed. |
331-
| PJ-R34 | live | `docs/rules-mining/projections.md:103` | — | — | Errored derives follow async memo rules**: after rejection ALL readers (settle-time, late tracked, untracked) throw the error (StatusError-wrapped; boundaries unwrap). Seed never served uninitialized;… |
332-
| PJ-R35 | live | `docs/rules-mining/projections.md:106` | — | — | A genuine tracked read on a later cycle retries an errored derive** (memo parity: never untracked, never inside isPending probe, at most once per cycle); successful retry serves fresh value. |
333-
| PJ-R36 | live | `docs/rules-mining/projections.md:110` | — | — | Disposing the owning root stops the projection** (no recomputes, no notifications afterward). |
322+
| PJ-R25 | live | `docs/rules-mining/projections.md:86` | — | — | Async generators publish one snapshot per yield**: bare `yield` publishes accumulated draft mutations; `yield value` replaces the entire state (no merge); each yield transforms again. |
323+
| PJ-R26 | live | `docs/rules-mining/projections.md:88` | projection.ts×1 | createProjection.draft-lifetime-3585.test.ts×1 | Latest-run-wins supersession**: superseded runs' later yields and pending draft writes are discarded entirely; if no run ever landed, stays NotReady. |
324+
| PJ-R27 | live | `docs/rules-mining/projections.md:90` | — | — | Async recompute does not coarsen granularity**: after settle, only changed-path subscribers rerun. |
325+
| PJ-R28 | live | `docs/rules-mining/projections.md:92` | — | — | `refresh(proj)` forces a new derive run; bare refresh is quiet** (no pending published; silent reveal). |
326+
| PJ-R29 | live | `docs/rules-mining/projections.md:94` | — | — | `affects(proj)` + `refresh(proj)` is a declared reload**: subscribed effects see isPending true + stale value for the window, then settle. |
327+
| PJ-R30 | live | `docs/rules-mining/projections.md:96` | — | — | With no effect subscribed, async work creates no transition** (isPending false throughout initial load). |
328+
| PJ-R31 | live | `docs/rules-mining/projections.md:98` | — | createProjection.draft-lifetime-3585.test.ts×1 | With a subscribed effect, source-triggered async reruns are transitions** (pending true + stale during window); initial no-stale-data load is never pending. |
329+
| PJ-R32 | live | `docs/rules-mining/projections.md:100` | — | — | Reading a pending async source inside the derive propagates NotReady to consumers** (Loading boundaries fall back); settle fires downstream effects exactly once with the settled value, never the seed … |
330+
| PJ-R33 | live | `docs/rules-mining/projections.md:102` | — | — | Settlement is a status change, not a value diff**: boundaries and blocked effects release even when the settled value equals the seed. |
331+
| PJ-R34 | live | `docs/rules-mining/projections.md:104` | — | — | Errored derives follow async memo rules**: after rejection ALL readers (settle-time, late tracked, untracked) throw the error (StatusError-wrapped; boundaries unwrap). Seed never served uninitialized;… |
332+
| PJ-R35 | live | `docs/rules-mining/projections.md:107` | — | — | A genuine tracked read on a later cycle retries an errored derive** (memo parity: never untracked, never inside isPending probe, at most once per cycle); successful retry serves fresh value. |
333+
| PJ-R36 | live | `docs/rules-mining/projections.md:111` | — | — | Disposing the owning root stops the projection** (no recomputes, no notifications afterward). |
334+
| PJ-R37 | ruled | `docs/rules-mining/projections.md:113` | scheduler.ts×2 projection.ts×3 target.ts×1 | createProjection.draft-lifetime-3585.test.ts×1 | A draft is valid from the start of its run until it is superseded or its owner is disposed — not "until no longer in flight" (#3585, ruled 2026-09-22).** The draft handed to a run stays writable after… |
334335
## R — reconcile-snapshot (`RS-R<n>`)
335336

336337
| id | status | defined | cited in src | cited in tests | statement (at definition) |

0 commit comments

Comments
 (0)