Skip to content

Commit 500d484

Browse files
fix(signals): propagate affects() marks through derivation on the status rails
Rebuilds affects() as a sentinel pending-source that rides the same status rails as real in-flight async: derived memos/effects read pending during the mark's window while marked values stay readable, quiet refresh() re-asks can't silence a declared window, and marks never block their own transaction's settlement. Keyless store marks now cover captured child proxies (<For> rows) by identity scope, with birth inheritance for nodes created mid-window (#2882). Also narrows the API to affects(target, key?). Co-authored-by: Cursor <[email protected]>
1 parent 5f76b3d commit 500d484

17 files changed

Lines changed: 1002 additions & 176 deletions
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
"@solidjs/signals": patch
3+
---
4+
5+
Rebuild `affects()` on the status rails so marks propagate through derivation (#2882). A live mark now pushes `STATUS_PENDING` downstream from the marked node exactly like real in-flight async — memos and effects DERIVED from marked data read pending too, not just direct reads of the marked slot — under a dedicated sentinel pending-source per marked node, so the two channels can't clear each other: a landing on the marked node settles only its own source entry, a quiet `refresh()` re-ask can't silence the declared window (the sentinel is never a re-ask), and a mark never blocks its own transaction's settlement (release happens AT settle). Computeds that recompute mid-window re-acquire the mark through the read path.
6+
7+
This also fixes keyless marks not covering captured store proxies (`<For>` rows): a keyless declaration walks the marked record's subtree (through write overlays), registers on every live node in it, snapshots the reachable raw identities, and nodes created during the window inherit the mark at birth from that scope. Records added after the declaration are not covered (snapshot-at-declaration semantics).

‎.changeset/affects-single-key.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@solidjs/signals": patch
3+
"solid-js": patch
4+
---
5+
6+
Narrow `affects()` to a single optional key: `affects(target, key?)`. The variadic form read like a 1.x store path (`affects(state, "user", "name")` suggests `state.user.name` but marked two sibling slots) — mark multiple slots with multiple calls, or target the nested record directly. Passing more than one key now throws in dev.

‎documentation/solid-2.0/06-actions-optimistic.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -76,11 +76,11 @@ const addTodo = action(function* (todo) {
7676

7777
`refresh()` is also an action: call it from event handlers, effects, or other actions rather than from pure computations. It starts invalidation work; it does not carry user-visible optimistic state by itself. Because it re-asks the *same* question (no input changed), a bare `refresh()` is quiet: the fresh value reveals silently and `isPending` stays `false`. When the reload should read as pending, declare it with `affects()`.
7878

79-
### `affects(target, ...keys)` (declare what in-flight work will change)
79+
### `affects(target, key?)` (declare what in-flight work will change)
8080

81-
`affects` declares that the surrounding work will change the targeted data. The named slots read as pending (`isPending` → `true`) from the declaration until the transaction settles or reverts. It is additive only: a declaration can turn pending *on* for data the graph can't see changing yet; nothing turns pending *off* while a real change is in flight.
81+
`affects` declares that the surrounding work will change the targeted data. The marked data — and anything derived from it — reads as pending (`isPending` → `true`) from the declaration until the transaction settles or reverts, exactly as if a real fetch for it were in flight; the values themselves stay readable throughout. It is additive only: a declaration can turn pending *on* for data the graph can't see changing yet; nothing turns pending *off* while a real change is in flight — pairing `affects(x)` with `refresh(x)` keeps the whole window pending even though the bare refresh alone would be quiet.
8282

83-
Targets mirror how you read: `affects(store)` marks a store record (root or nested — siblings are untouched), `affects(record, "key")` marks exactly the named slots, and `affects(accessor)` marks a signal/memo source.
83+
Targets mirror how you read: `affects(store)` marks a store record (root or nested) and everything reachable from it at declaration time — including rows captured by `<For>` — while siblings stay untouched; `affects(record, "key")` marks exactly the named slot; and `affects(accessor)` marks a signal/memo source. One key per call — keys do **not** form a path (mark several slots with several calls, or target the nested record directly).
8484

8585
```js
8686
const reload = action(function* () {

‎documentation/solid-2.0/MIGRATION.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -673,7 +673,7 @@ These APIs are new additions (not renames of 1.x APIs):
673673
- **`isPending(fn)`** — expression-level "unrevealed change in flight" check.
674674
- **`latest(fn)`** — peek at in-flight values during transitions.
675675
- **`refresh(target)`** — explicit recomputation/invalidation of derived reads (a quiet re-ask — not pending).
676-
- **`affects(target, ...keys)`** — declare that in-flight work will change the targeted data; the named slots read pending until the transaction settles.
676+
- **`affects(target, key?)`** — declare that in-flight work will change the targeted data; the marked record (or the single named slot) reads pending until the transaction settles.
677677
- **`resolve(fn)`** — returns a Promise that resolves when a reactive expression settles.
678678
- **`Loading` `on` prop** — controls when a Loading boundary re-shows fallback during revalidation.
679679
- **`deep(store)`** — deep observation of a store (tracks all nested changes).

‎packages/solid-signals/INTERNALS-ASYNC-STATE.md‎

Lines changed: 71 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@ A `Signal`/`Computed` participating in async/transitions carries:
1818
| `_value` | Committed, visible value | `recompute` (create/effect paths), `commitPendingNode`, `resolveOptimisticNodes`, `asyncWrite` (lane branch) |
1919
| `_pendingValue` | Transition-held next value; `NOT_PENDING` sentinel when absent (one meaning — a pending commit; revert targets were eliminated 2026-07-07b, §5e) | `setSignal` (non-optimistic), `recompute` (held branch), `asyncWrite` (override-active branch) |
2020
| `_overrideValue` | Optimistic override; `undefined` = not an optimistic node, `NOT_PENDING` = resting optimistic node, else = active override | `setSignal` (optimistic branch), `recompute` (lane-corrected), `resolveOptimisticNodes` (clears to `NOT_PENDING`) |
21-
| `_affectsCount` | Live `affects()` mark refcount: non-zero forces the node's verdict to `true` (declared motion, §5g). Carried by source nodes, store leaf nodes, and per-record `$AFFECTS` nodes | `registerAffectsMark` (+1, staged with the current transaction), `releaseAffectsMarks` (−1 at settle / flush end) |
21+
| `_affectsCount` | Live `affects()` mark refcount: non-zero forces the node's verdict to `true` and propagates pending downstream via the node's sentinel (declared motion, §5g). Carried by source nodes, store leaf/track/has nodes, and per-record `$AFFECTS` carriers | `registerAffectsMark`/`markAffects` (+1, staged with the current transaction or a scope entry), `releaseAffectsMark` (−1 at settle / flush end; settles the sentinel when the count zeroes) |
22+
| `_affectsSentinel` | The mark's identity on the pending-source rails (lazy): held in downstream `_pendingSources` like a real in-flight source, never a re-ask, never self-pending, branded with `_affectsFor` so settlement checks skip it | `getAffectsSentinel` (async.ts) |
2223
| `_reask` | Question-scoped classification of the CURRENT pending window: `true` = the in-flight recompute is a re-ask of the same question (refresh with no input value change) — quiet, not pending (§5g). Meaningless while not `STATUS_PENDING` | `recompute` (from the `REACTIVE_REASK` flag), cleared by `clearStatus` and by value-change notifications (`insertSubs` clears the flag pre-recompute) |
2324
| `_statusFlags` | `STATUS_PENDING` / `STATUS_ERROR` / `STATUS_UNINITIALIZED` | `notifyStatus`, `clearStatus`, commit paths |
2425
| `_error` | Current error (`NotReadyError` for pending, `StatusError`-wrapped for real) | compute catch, `notifyStatus` |
@@ -388,13 +389,19 @@ the question being asked. Three consequences replace the mask's one rule:
388389
state — `{ value: guess, pending: true }`. To downstream async, an
389390
optimistic write is a real input change (it launches real fetches that
390391
pend their own slots).
391-
3. **`affects(target, ...keys)` is the sole declaration verb.** A mark is
392-
additive pending on exactly the named slots (store record → every read
393-
through it; leaf keys → those slots; accessor → that source), live from
394-
declaration to its transaction's settle/revert (ambient marks release at
395-
flush end). The declared reload idiom — `affects(x); refresh(x)` — is how
396-
process intent ("this work will change x") enters the verdict when the
397-
graph can't see it yet.
392+
3. **`affects(target, key?)` is the sole declaration verb.** A mark is
393+
additive pending on exactly the marked data (store record → every record
394+
reachable from it at declaration time, by identity — captured child
395+
proxies included, #2882; leaf key → that slot; accessor → that source)
396+
**and on everything derived from it**: marks ride the same status rails
397+
as real in-flight async (§ affects-on-rails below), so memos/effects over
398+
marked data read pending like they would over a real pending source,
399+
while the marked values themselves stay readable. Live from declaration
400+
to its transaction's settle/revert (ambient marks release at flush end).
401+
The declared reload idiom — `affects(x); refresh(x)` — is how process
402+
intent ("this work will change x") enters the verdict when the graph
403+
can't see it yet; the mark's own channel is never a re-ask, so the
404+
refresh's quiet classification cannot silence the declared window.
398405

399406
Verdict ladder (`computePendingState`): disposal guard → live
400407
`_affectsCount` → latest-shadow branch (owner's `_affectsCount`, then owner
@@ -414,25 +421,58 @@ Supporting machinery:
414421
node already pending on an unanswered new question stays non-quiet);
415422
`clearStatus` resets it on landing. When a reask classification changes
416423
while pending, `repollDownstreamVerdicts` re-derives companions downstream.
417-
- **Affects lifecycle** (scheduler.ts): `registerAffectsMark` bumps
418-
`_affectsCount`, stages the registration with the current transaction
419-
(ambient registrations are adopted by `initTransition`, merged by
420-
`mergeTransitionState`, mirroring `_optimisticNodes`), and pokes the
421-
node's companions; `releaseAffectsMarks` decrements at the transaction's
422-
settle (or plain flush end for ambient marks) and snaps companions
423-
through the settlement checkpoint (committed, not transition-scoped).
424-
- **Store addressing** (store.ts): `affects(record)` marks a per-record
425-
`$AFFECTS` node; `affects(record, ...keys)` marks the leaf nodes.
426-
Witnessing: the `get`/`has`/`ownKeys` traps and the `snapshot`/`deep`
427-
walk (utils.ts — it bypasses traps) upsert-and-witness the record's
428-
`$AFFECTS` node into the active probe, so probes subscribe to the channel
429-
*before* any mark exists — a later `affects()` wakes materialized `false`
430-
verdicts through the node's companion. The upsert is skipped for untracked
431-
probes (`tracking` off): they can't be woken by a later mark, so they only
432-
need marks that already exist — no node, no allocation. The per-node
433-
companion channel (not a shared version signal) is load-bearing here:
434-
companions carry their own optimistic lane, which is what lets the wake-up
435-
escape an incomplete transition's effect stash.
424+
- **Affects on rails** (async.ts/scheduler.ts): a mark is a synthetic
425+
in-flight change on the normal status rails, under its own **sentinel**
426+
pending-source (`getAffectsSentinel`, one per marked node, branded with
427+
`_affectsFor`). `registerAffectsMark` bumps `_affectsCount`, stages the
428+
registration with the current transaction (ambient registrations are
429+
adopted by `initTransition`, merged by `mergeTransitionState`, mirroring
430+
`_optimisticNodes`), pokes the node's companions, and **propagates
431+
`STATUS_PENDING` downstream** from the marked node via `notifyStatus` with
432+
a `NotReadyError(sentinel)` — so downstream verdicts derive from the
433+
ordinary `newQuestionInFlight` clause. The separate identity is what keeps
434+
the channels from clearing each other: a landing on the marked node
435+
settles only the node's OWN source entry (`settlePendingSource` is
436+
source-parameterized); `quietPending` never reports quiet while a sentinel
437+
is among the sources (its `_reask` is permanently false), so a declared
438+
reload survives its refresh's quiet classification; and neither
439+
`transitionComplete` check counts a sentinel-sourced pending as a blocker
440+
(`_affectsFor` brand) — a mark releases AT settle, so self-blocking would
441+
deadlock. The marked node itself never carries `STATUS_PENDING` (marks
442+
are value-transparent at the source; its own verdict is the
443+
`_affectsCount` clause). Computeds that recompute mid-window shed the
444+
sentinel via `clearStatus` and re-acquire it through the read path:
445+
`read()` records marked sources into the recompute's `affectsReads`
446+
accumulator (gated by the global `activeAffectsMarks` counter; probe
447+
reads excluded so an `isPending` wrapper memo doesn't mark itself), and
448+
`recompute` applies them after its commit (`applyAffectsReads` — earlier
449+
would route the fresh value into the error-skip branch).
450+
`releaseAffectsMark` decrements at the transaction's settle (or plain
451+
flush end for ambient marks), settles the sentinel out of every
452+
downstream `_pendingSources` (waking `_blocked` nodes), and snaps
453+
companions through the settlement checkpoint (committed, not
454+
transition-scoped — the settle walk snaps too, for the same reason).
455+
- **Store addressing** (store.ts): `affects(record)` upserts a per-record
456+
`$AFFECTS` node (the mark's carrier — registry key and liveness anchor),
457+
walks the record's subtree — reading through write overlays — registering
458+
the mark on **every live node** in it (property leaves, `$TRACK`,
459+
has-nodes: the edges existing readers subscribed through), and snapshots
460+
the reachable raw identities into the mark's scope (`affectsScopes`,
461+
released with the carrier's last registration). Nodes created during the
462+
window inherit the mark at birth (`getNode` → `inheritAffectsMarks`, keyed
463+
by the owning record's raw identity; inherited marks are released with the
464+
carrier's entry), which is how captured child proxies (`<For>` rows,
465+
#2882) and late tracked reads observe a mark their read path never
466+
traverses. `affects(record, key)` marks the named leaf node (single key —
467+
keys are not a path). Witnessing (`witnessAffectsMark`, pendingCheckActive
468+
traps + the `snapshot`/`deep` walk in utils.ts) now only covers untracked
469+
probes over records whose nodes never materialized: it adds the record's
470+
own `$AFFECTS` carrier and any scope carrier containing the record's raw
471+
to the probe. Tracked probes need none of this — they read real nodes,
472+
which carry marks directly. The per-node companion channel (not a shared
473+
version signal) is load-bearing for wake-ups: companions carry their own
474+
optimistic lane, which is what lets a late registration's wake escape an
475+
incomplete transition's effect stash.
436476
- **Probe rethrow scope** (core.ts `isPending`): only a truly UNINITIALIZED
437477
source's NotReady rethrows out of the probe (loading participates in
438478
readiness); an initialized source throwing NotReady during a quiet re-ask
@@ -484,9 +524,10 @@ sibling rows because the confirm refresh is a quiet re-ask).
484524
live `affects()` mark": same-question re-asks (refresh/poll/confirm) are
485525
silent; a new question pends monotonically and nothing silences it;
486526
optimistic writes are verdict-inert (display without decree — honest mixed
487-
state over an in-flight question); `affects(target, ...keys)` is the sole,
488-
additive declaration verb. Vouching, `UNCHANGED`, and the store-wide mask
489-
are deleted concepts. `isPending` keeps its name (isStale was weighed —
527+
state over an in-flight question); `affects(target, key?)` is the sole,
528+
additive declaration verb (single optional key since 2026-07-14 — the
529+
variadic form read as a 1.x path and was dropped). Vouching, `UNCHANGED`,
530+
and the store-wide mask are deleted concepts. `isPending` keeps its name (isStale was weighed —
490531
semantics now match "stale" but the argument-taking form already reads as
491532
data-scoped; revisit only with docs-team pressure). Implementation in §5g;
492533
scenario matrix pinned in `tests/question-scoped-pending.test.ts`.

‎packages/solid-signals/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,7 @@ createRoot(dispose => {
226226
| `isPending(accessor)` | Check if an unrevealed value change is in flight for a read |
227227
| `latest(accessor)` | Get the last resolved value, or follow not-ready if none exists |
228228
| `refresh(accessor)` | Re-trigger an async computation (a quiet re-ask — not pending) |
229-
| `affects(target, ...keys)` | Declare that in-flight work will change the targeted data (reads pending until settle) |
229+
| `affects(target, key?)` | Declare that in-flight work will change the targeted data (reads pending until settle) |
230230
| `resolve(fn)` | Returns a promise that resolves when a reactive expression settles |
231231
| `mapArray(list, mapFn)` | Reactive array mapping with keyed reconciliation |
232232
| `repeat(count, mapFn)` | Reactive repeat based on a reactive count |

0 commit comments

Comments
 (0)