Skip to content

Commit 46ab2dd

Browse files
ryansolidcursoragentclaude
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]>
1 parent 3b0dde7 commit 46ab2dd

19 files changed

Lines changed: 1012 additions & 15 deletions

File tree

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+
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.

‎documentation/solid-2.0/08-dev-diagnostics.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -392,6 +392,40 @@ It covers native Promise computations. Not covered: `async function*` bodies (as
392392

393393
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.
394394

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+
const label = createMemo(() => {
408+
try {
409+
return user().name;
410+
} catch {
411+
return "…";
412+
}
413+
});
414+
415+
// Fix: branch on readiness, or show the last value ahead of the landing
416+
const label = createMemo(() => (isPending(user) ? "…" : user().name));
417+
const label = createMemo(() => latest(() => user().name));
418+
419+
// Fix: let the read suspend and put the placeholder in a boundary
420+
<Loading fallback="…">{user().name}</Loading>;
421+
422+
// Errors: a boundary, or the effect's error arm
423+
<Errored fallback={e => <p>{e().message}</p>}>{user().name}</Errored>;
424+
createEffect(() => user().name, { effect: show, error: showError });
425+
```
426+
427+
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+
395429
#### `NO_OWNER_EFFECT`
396430

397431
**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
9741008
| `STRICT_READ_UNTRACKED` | warn | strict-read | Untracked reactive read in component/effect body |
9751009
| `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) |
9761010
| `PENDING_ASYNC_FORBIDDEN_SCOPE` | warn | async | Pending async read in trackedEffect/onSettled |
1011+
| `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 |
9771012
| `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 |
9781013
| `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 |
9791014
| `NO_OWNER_EFFECT` | warn | lifecycle | Effect created without reactive owner |

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -370,7 +370,7 @@ And when the catch does run it severs the channel: the computation completes wit
370370

371371
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.
372372

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.
374374

375375
**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).
376376

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
6060
| 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 … |
6161
| 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… |
6262
| A15 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:251` | async.ts×2 constants.ts×1 core.ts×4 lanes.ts×6 scheduler.ts×16 seat.ts×1 verdict.ts×4 store.ts×1 | async-chain-supersession.test.ts×1 boundary-output-frame-reader.test.ts×1 create-deferred-3710.test.ts×2 first-observer-stale-reader.test.ts×1 fuzz-findings-l2.test.ts×17 held-restore.test.ts×1 hold-recovers-landing-reruns-4469.test.ts×1 l2-contract.test.ts×7 l2-fuzz-existing-rules.test.ts×2 lane-contract.test.ts×1 lane-hold-on-observation.test.ts×1 lane-outside-view.test.ts×1 lane-pass-stamped-effect-3662.test.ts×1 latest-memo-inline-parity.test.ts×1 latest-uninitialized-over-latest-4362.test.ts×1 loading-fallback-in-flush-3540.test.ts×4 mount-over-foreign-hold-3761.test.ts×2 overlapping-flights.test.ts×3 posture-born-held-and-observation.test.ts×4 posture-store-parity.test.ts×2 reveal-carve-out.test.ts×2 shared-effect-no-entangle.test.ts×1 show-stale-child-in-action-4137.test.ts×1 spec-async-semantics.test.ts×2 stale-read-uninitialized-cross-transition.test.ts×1 superseded-source-blocks-3462.test.ts×2 tick-scoped-pass-transaction.test.ts×1 treeshake.test.ts×4 unread-derive-midflight-mount-4491.test.ts×1 verdict-memo-flight-no-reask.test.ts×1 visibility-oracle-store.states.ts×6 visibility-oracle.states.ts×7 visibility-oracle.test.ts×1 write-proposals-3494.test.ts×1 | [ruled, amended in place 2026-07-06 (promoted from B3)] Transition entanglement is graph-driven; lanes settle as one reveal — (was B3) Transition entanglement is graph-driven: writes whose async work … |
63-
| 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… |
6464
| 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… |
6565
| 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… |
6666
| 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… |

‎packages/signals/src/boundaries.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ import {
5959
STATUS_UNINITIALIZED
6060
} from "./core/constants.js";
6161
import { computed, read, recompute, runWithOwner, setSignal, signal } from "./core/core.js";
62-
import { emitDiagnostic, reportDiagnostic } from "./core/dev.js";
62+
import { emitDiagnostic, forgetThrownRead, reportDiagnostic } from "./core/dev.js";
6363
import { shadowSeatRestore, shadowSeatSave, shadowSwapSeat } from "./core/seat.js";
6464
import { NotReadyError, unwrapStatusError } from "./core/error.js";
6565
import { reportClientError } from "./core/error-hooks.js";
@@ -644,6 +644,8 @@ function createBoundary<T>(
644644
const deps = onFn();
645645
if (__DEV__ && !mounted && typeof deps === "function") reportOnAccessor(b);
646646
} catch (e) {
647+
// (D-42, dev: this catch is the re-arm's mechanism, not a user's.)
648+
if (__DEV__) forgetThrownRead();
647649
if (!(e instanceof NotReadyError)) {
648650
if (!globalQueue.notify(getOwner() as Computed<any>, STATUS_ERROR, STATUS_ERROR, e)) {
649651
if (__DEV__) haltReactivityAt(e, getOwner()!);
@@ -751,6 +753,8 @@ function createBoundary<T>(
751753
} catch (e) {
752754
if (e instanceof NotReadyError ? type === STATUS_PENDING : type === STATUS_ERROR) {
753755
if (isCollecting(b)) {
756+
// (D-42, dev: the boundary IS the catcher the throw is addressed to.)
757+
if (__DEV__) forgetThrownRead();
754758
caught(b, tree, e);
755759
return fallback(b);
756760
}

‎packages/signals/src/core/async.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,12 @@ import {
2929
import { attrHooks } from "./attribution-hooks.js";
3030
import { context, setSignal, untrack, ext, statusNotifierOf } from "./core.js";
3131
import { devTrackHeldPending } from "./invariants.js";
32-
import { emitDiagnostic, reportDiagnostic, watchAsyncTail } from "./dev.js";
32+
import {
33+
caughtReadFlightSettled,
34+
emitDiagnostic,
35+
reportDiagnostic,
36+
watchAsyncTail
37+
} from "./dev.js";
3338
import { NotReadyError, StatusError } from "./error.js";
3439
import { trimStaleDeps, unobserved } from "./graph.js";
3540
import { enqueueSub } from "./heap.js";
@@ -534,6 +539,8 @@ export function handleAsync<T>(
534539

535540
const handleError = (error: any) => {
536541
if (el._x?._inFlight !== result) return;
542+
// D-42 (dev): a rejection is the read's throw continuing, not a catch.
543+
if (__DEV__) caughtReadFlightSettled(el, result as object, false);
537544
// NotReadyError from rejected promises should be treated as pending, not error
538545
let stillPending = error instanceof NotReadyError;
539546
// Dev-only authorship diagnostic (#2987): no edge means a post-`await`
@@ -588,6 +595,9 @@ export function handleAsync<T>(
588595

589596
const asyncWrite = (value: T, then?: () => void) => {
590597
if (el._x?._inFlight !== result) return;
598+
// D-42 (dev): the flight landed a value after a read threw into the pass
599+
// that started it — the body caught the throw (CAUGHT_REACTIVE_READ).
600+
if (__DEV__) caughtReadFlightSettled(el, result as object, true);
591601
// If the node was dirtied by a newer write (optimistic override or regular),
592602
// skip this stale async result — the upcoming flush will recompute the node
593603
// with the new value, creating a fresh Promise that supersedes this one.
@@ -918,6 +928,9 @@ export function handleAsync<T>(
918928
el._loading = false;
919929
}
920930

931+
// D-42 (dev): a flight that answered synchronously (a sync-settled
932+
// thenable, a live first yield) landed a value like asyncWrite's.
933+
if (__DEV__) caughtReadFlightSettled(el, result as object, true);
921934
return syncValue!;
922935
}
923936

0 commit comments

Comments
 (0)