You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 46ab2dd
Browse filesBrowse the repository at this point in the historyBrowse files
authored
feat(signals): dev diagnostic CAUGHT_REACTIVE_READ — a reactive read's throw caught and the pass completed (D-42) (#4481)
* feat(signals): dev diagnostic CAUGHT_REACTIVE_READ — a reactive read's throw caught and the pass completed (D-42)
A reactive read's throw (NotReadyError or the source's error) is addressed
to the graph: try/catch around it is not a channel (D-42 / S-47). This
detects the detectable half — a computation's pass completed normally after
a reactive read threw into it — and warns once per computation, dev only.
Mechanism: read()/serve()/verdict throw sites record the throw against the
running pass in a module-level WeakMap; recompute clears the record at the
pass head and judges it when _fn returns. A body that returned a flight
(thenable / async iterable) is judged when the flight settles: a rejection
is the throw continuing (an async function converts a pre-await throw into
its rejection), a landed value is the catch. The runtime's own catches —
boundary output and `on`, isPending's probe, watch's error arm, comparator,
cleanup and effect-callback routing, solid-js's hydration trace and
Dynamic's warm-up — forget the record. Zero production bytes (size harness
byte-identical across all 22 scenarios).
Co-authored-by: Cursor <[email protected]>
* docs(signals): CAUGHT_REACTIVE_READ error arm — errored regardless by the rules (F-12/#4410); today's runtime may complete with the caught value until the source is retried (#4486)
Co-authored-by: Cursor <[email protected]>
* test(signals): treeshake suite gets a 30 s hang guard — each case runs a Vite build; CI's first bundle went past vitest's 5 s
Co-authored-by: Cursor <[email protected]>
* test: pin the #4342 query-cache shape as a CAUGHT_REACTIVE_READ true positive; note it at the web spec's catch
Co-authored-by: Cursor <[email protected]>
---------
Co-authored-by: Cursor <[email protected]>
Co-authored-by: Claude <[email protected]>
Dev diagnostic `CAUGHT_REACTIVE_READ` (D-42 / S-47): warns once per computation when a reactive read's throw — `NotReadyError` or the source's error — was caught inside the computation's body and the pass completed with a value. An `async` computation is judged when its flight settles (a rejection is the throw continuing; a landed value is the catch). The runtime's own catches (boundaries, `isPending`, `watch`, comparator/cleanup/effect-callback routing, solid-js's hydration trace) never warn. Dev-only; no production bytes.
Copy file name to clipboardExpand all lines: documentation/solid-2.0/08-dev-diagnostics.md
+35Lines changed: 35 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -392,6 +392,40 @@ It covers native Promise computations. Not covered: `async function*` bodies (as
392
392
393
393
Warns that an async value read inside `createTrackedEffect` or `onSettled` will throw if it's ever pending, because these scopes can't route not-ready reads through `Loading`. Use `createEffect` (which supports async-aware reactivity) instead.
394
394
395
+
#### `CAUGHT_REACTIVE_READ`
396
+
397
+
**Message (not ready):** "[owner] caught the not-ready throw of [source] and completed with a value. A reactive read is not an await: the throw is how the read suspends to a `<Loading>` boundary or holds the change, and when the source changes later this computation is marked pending and not re-run, so the catch will not fire again. Branch on readiness with isPending(), show ahead with latest(), or let the read suspend."
398
+
399
+
**Message (error):** "[owner] caught the error of [source] and completed with a value. An error is the source's status, not a throw this computation owns: the computation is errored with it regardless, and today's runtime may complete with the caught value until the source is retried, when the error reaches `<Errored>` (or halts) and the catch does not fire again. Handle errors with `<Errored>` or createEffect's error option."
400
+
401
+
A computation — a memo, a render effect's compute, a component body, a store derive — wrapped a reactive read in `try/catch` as it would an `await`, the read threw (`NotReadyError` because the source is loading, or the source's error), the catch swallowed it, and the computation completed with a substitute value. The throw was addressed to the graph, not to the code around the read: `NotReadyError` is how the read suspends to the nearest `<Loading>` boundary or holds the change; an error is how it reaches `<Errored>` or `createEffect`'s error arm. Swallowing it severs that channel — the first load is masked (no fallback, no hold), the error never reaches a boundary, and on the server, where there is no subscription graph to re-run the computation when the source lands, the substitute is the answer.
402
+
403
+
It is also unreliable by construction: when a source goes pending or errored, its dependents are _marked_ with that status and do not run, so the catch never sees the change. It fires only on a pass that happens to run while the source is already in that state — its creation, another input of its own changing. The same code catches on one pass and is bypassed on the next. For an error the catch is inert by the rules: a reader of an errored source is errored with it whether or not it catches (F-12, #4410); today's runtime may complete with the caught value until the source is retried (#4486).
404
+
405
+
```js
406
+
// Warns: the catch masks the first load; the re-ask is held through this memo as if the catch were not there
407
+
constlabel=createMemo(() => {
408
+
try {
409
+
returnuser().name;
410
+
} catch {
411
+
return"…";
412
+
}
413
+
});
414
+
415
+
// Fix: branch on readiness, or show the last value ahead of the landing
Interop layers that catch `NotReadyError` and re-throw it (`catch (e) { if (e instanceof NotReadyError) throw e; … }`) do not warn: the pass did not complete. An `async` computation is judged when its promise settles, not when the function returns: a read before the first `await` that throws turns into the promise's rejection, which is the throw continuing (no warning); a value landing after such a throw is the catch (warns). Warns once per computation. **Under-reports by design:** a catch the status propagation bypasses is not detected — the warning fires on the pass where the catch actually ran, so a computation created over an already-loaded source and never re-run while it is pending or errored stays silent. The runtime's own catches (`isPending`, `latest`, `resolve`/`until`, the boundaries) are the mechanism and never warn. Dev-only; adds nothing to production builds.
428
+
395
429
#### `NO_OWNER_EFFECT`
396
430
397
431
**Message:** "Effects created outside a reactive context will never be disposed"
@@ -974,6 +1008,7 @@ The runtime derives a request's trace itself in every tier — the W3C `tracepar
974
1008
|`STRICT_READ_UNTRACKED`| warn | strict-read | Untracked reactive read in component/effect body |
975
1009
|`UNTRACKED_READ_AFTER_AWAIT`| warn | async | Async computation first read a signal/memo/store key after an `await`; never a dependency (dev; V8 engines only) |
|`CAUGHT_REACTIVE_READ`| warn | async | A computation caught a reactive read's throw (not ready, or the source's error) and completed with a value: the load is masked or the error hidden; once per node |
977
1012
|`LOADING_ON_OUTSIDE_HOLD`| warn | async |`<Loading on>` changed but its data is also read outside the boundary and holds the frame: the fallback can never be seen |
978
1013
|`LOADING_ON_ACCESSOR`| warn | async |`<Loading on>` received a function (an accessor) instead of the dependency's value; it is never called, so the boundary never re-arms |
979
1014
|`NO_OWNER_EFFECT`| warn | lifecycle | Effect created without reactive owner |
Copy file name to clipboardExpand all lines: packages/signals/docs/RULES-DERIVED.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -370,7 +370,7 @@ And when the catch does run it severs the channel: the computation completes wit
370
370
371
371
What the author has instead: `isPending(x)` to branch on readiness; `latest(x)` to show ahead or to see a staged error early (D-22, D-41); `<Loading>`, `<Errored>` and `createEffect`'s error arm as the catchers (F-4, F-12, D-38). `try/catch` belongs where something is actually awaited — an action body (`yield refresh(x)` throws back at the yield), an event handler, `resolve()`/`until()`/`refresh()` (D-31). `NotReadyError` is exported for interop layers that re-throw it, not as an app-code catch; the runtime's own catches (`isPending`/`latest` unowned, A16) are the mechanism, not a license.
372
372
373
-
**What it does not say.** It does not say catching is detected: nothing warns today — a computation that completes after a `NotReadyError` or a source's error was thrown into it is indistinguishable from one that never read the source (a dev diagnostic is a runtime change, open). It does not say a derivation can never observe an error: `latest(x)` throws a staged error (D-41), and a `createEffect` error arm sees compute-phase errors (D-38). It does not say a dependent never re-runs on a status change: a verdict reader, a boundary output and a kept-tail link re-derive (`propagateStatus`), and a catch in one of those sees the change — that it does is the mechanism's business, not a contract.
373
+
**What it does not say.** It does not say catching is detected: nothing warns today — a computation that completes after a `NotReadyError` or a source's error was thrown into it is indistinguishable from one that never read the source (dev: `CAUGHT_REACTIVE_READ` warns when the catch ran and the pass completed; the bypass is not detectable). It does not say a derivation can never observe an error: `latest(x)` throws a staged error (D-41), and a `createEffect` error arm sees compute-phase errors (D-38). It does not say a dependent never re-runs on a status change: a verdict reader, a boundary output and a kept-tail link re-derive (`propagateStatus`), and a catch in one of those sees the change — that it does is the mechanism's business, not a contract.
374
374
375
375
**Collapses:** `05-async-data.md` "Error handling" (one path; the 1.x split), `04-stores.md` "A derive must never swallow `NotReadyError`" (#3073 — the derive form of this rule), the `NotReadyError` JSDoc, [A16](./SPEC-ASYNC-SEMANTICS.md#a16-ispending-never-throws-in-untracked-contexts)'s swallow scope (B5a, #2928), #4486. **Status:** standing; the not-ready bypass is pinned as it is in `tests/try-catch-reactive-read.test.ts`. Deviation today (#4486): a reader created over, or re-run onto, an already-errored sync memo completes with its caught value until the clock-gated retry (`read()`'s errored-memo path) re-runs the source inside its pass, which halts (no boundary) or errors the boundary while the memo still reads the caught value. Ruled 2026-10-30: errored from the first pass. Fix built on `fix/errored-reader-4486` (+83 B min / +41 B brotli core floor), not shipped: the deviation is reachable only through a catch `CAUGHT_REACTIVE_READ` warns on in dev (#4481), and without a catch the path is coherent; accepted 2026-10-30, #4486 closed. Pinned `tests/errored-reader-4486.test.ts` (`it.fails` at the ruled screens, so a core change that fixes it is noticed).
Copy file name to clipboardExpand all lines: packages/signals/docs/RULES-INDEX.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -60,7 +60,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
60
60
| A13 | ruled |`docs/SPEC-ASYNC-SEMANTICS.md:207`| — | spec-async-semantics.test.ts×7 |[ruled 2026-07-06 (promoted from B1)] Resting optimistic ≡ plain async memo at every checkpoint — (was B1) A resting optimistic node (no active override) is observationally identical to a plain async … |
61
61
| A14 | amended |`docs/SPEC-ASYNC-SEMANTICS.md:215`| — | spec-async-semantics.test.ts×1 |[ruled, amended in place 2026-07-06 (promoted from B2)] Companion nodes get child lanes that do not merge with the owner — (was B2) `isPending`/`latest` companion nodes get child lanes that do not mer… |
| A16 | amended |`docs/SPEC-ASYNC-SEMANTICS.md:223`| scheduler.ts×1 | latest-uninitialized-over-latest-4362.test.ts×2 spec-async-semantics.test.ts×1 strict-read-pending-store.test.ts×2 uninitialized-visibility.test.ts×1 visibility-oracle-store.states.ts×2 visibility-oracle.states.ts×2 visibility-oracle.test.ts×1 |[ruled, amended in place 2026-07-06 (promoted from B5)]`isPending` never throws in untracked contexts — (was B5) `isPending` never throws in untracked contexts — thunks that throw real errors or read… |
63
+
| A16 | amended |`docs/SPEC-ASYNC-SEMANTICS.md:223`| scheduler.ts×1 |caught-reactive-read-diagnostic.test.ts×1 latest-uninitialized-over-latest-4362.test.ts×2 spec-async-semantics.test.ts×1 strict-read-pending-store.test.ts×2 uninitialized-visibility.test.ts×1 visibility-oracle-store.states.ts×2 visibility-oracle.states.ts×2 visibility-oracle.test.ts×1 |[ruled, amended in place 2026-07-06 (promoted from B5)]`isPending` never throws in untracked contexts — (was B5) `isPending` never throws in untracked contexts — thunks that throw real errors or read… |
64
64
| A17 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:71` | async.ts×3 constants.ts×1 lanes.ts×7 scheduler.ts×2 seat.ts×1 verdict.ts×1 map.ts×1 optimistic.ts×1 store.ts×3 | create-deferred-3710.test.ts×1 fuzz-findings-l2.test.ts×6 lane-uninitialized-landing-3648.test.ts×5 optimistic-over-held-row-3796.test.ts×1 optimistic-read-lane-not-transaction-3698.test.ts×2 optimistic-undefined-override.test.ts×1 posture-store-parity.test.ts×1 refresh-await.test.ts×1 reveal-gating-contract.test.ts×3 spec-async-semantics.test.ts×10 createOptimisticStore.test.ts×2 kanban-a17-fixture.test.ts×3 optimistic-list-mutation-matrix.test.ts×1 optimistic-maparray-index-frame-f1.test.ts×1 optimistic-untracked-reads-f3-f5.test.ts×1 signal-store-twins-qd.test.ts×1 treeshake.test.ts×1 until.test.ts×1 visibility-oracle-store.states.ts×24 visibility-oracle-store.test.ts×1 visibility-oracle.states.ts×20 visibility-oracle.test.ts×1 | [ruled, amended in place 2026-07-06 (promoted from C4)] An active override is the displayed value until its transaction commits, and the graph's value until its own source answers — **Statement (curre… |
65
65
| A18 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:81` | action.ts×1 async.ts×2 core.ts×3 lanes.ts×8 scheduler.ts×2 types.ts×1 verdict.ts×1 map.ts×1 optimistic.ts×1 projection.ts×1 | body-end-supersession-visibility.test.ts×4 createOptimistic.test.ts×3 l2-fuzz-existing-rules.test.ts×2 lane-contract.test.ts×1 lane-frame-deferred-run-3662.test.ts×1 lane-outside-view.test.ts×1 lane-uninitialized-landing-3648.test.ts×5 optimistic-move-duplicate-3548.test.ts×2 optimistic-read-lane-not-transaction-3698.test.ts×4 posture-store-parity.test.ts×5 spec-async-semantics.test.ts×5 flight-owned-transaction.test.ts×1 lane-authority-twins.test.ts×1 optimistic-list-mutation-matrix.test.ts×1 optimistic-untracked-reads-f3-f5.test.ts×1 signal-store-twins-qd.test.ts×1 unchanged-presence-no-hold-3743.test.ts×2 superseded-before-first-commit.test.ts×4 visibility-oracle-store.states.ts×8 visibility-oracle-store.test.ts×1 visibility-oracle.states.ts×19 visibility-oracle.test.ts×1 | [ruled, amended in place 2026-07-07 (promoted from B4)] An override lives exactly as long as its own transaction; a newer truth from the source supersedes it in the graph immediately, on screen at com… |
66
66
| A19 | amended |`docs/SPEC-ASYNC-SEMANTICS.md:151`| async.ts×1 constants.ts×1 core.ts×6 lanes.ts×1 scheduler.ts×2 seat.ts×1 types.ts×1 verdict.ts×6 store.ts×2 | create-deferred-3710.test.ts×2 derived-store-first-landing-verdict.test.ts×1 fuzz-findings-l2.test.ts×4 lane-uninitialized-landing-3648.test.ts×2 latest-memo-inline-parity.test.ts×1 latest-uninitialized-over-latest-4362.test.ts×2 mount-over-foreign-hold-3761.test.ts×2 spec-async-semantics.test.ts×3 derived-presence-async-3726.test.ts×2 superseded-before-first-commit.test.ts×3 uninitialized-visibility.test.ts×1 verdict-memo-flight-no-reask.test.ts×2 visibility-oracle-store.states.ts×8 visibility-oracle-store.test.ts×1 visibility-oracle.states.ts×14 visibility-oracle.test.ts×1 write-proposals-3494.test.ts×1 |[ruled, amended in place 2026-07-07 (promoted from C1)]`isPending(x)` ≡ the observable value is not final (three causes) — (was C1 — **partially reverses an earlier decision**) **Definition: `isPendi… |
0 commit comments