Skip to content

Commit 06307a4

Browse files
ryansolidClaude via Cursorcursoragent
committed
feat(signals,solid): createDeferred — an async memo that may lag, but never leads
A plain async memo holds: while a refetch is in flight its readers suspend and the write that caused it is held with it, so every commit in a tick waits on the slowest fetch. createDeferred opts one node out. Once it has a committed value, a refetch is served the previous answer: readers keep rendering, the input's write commits now, and the landing commits on its own schedule. The design is packages/signals/docs/create-deferred.md (propositions D1–D9); tests/createDeferred.test.ts pins one test per proposition plus §2.1, §8.1 and §8.2. Pay-for-use module, core/deferred.ts. The clamp is a compute wrapper over the commit-#0 loading window core already has: an answered node's pass re-opens the window (`_loading = true`) before the user's compute, so core serves the committed value or parks exactly as it does for loadingValue, and every site that makes an answer observable closes it. The verdict stays loud through the affects() mark channel: an open flight (`_loading` on a member of the module's flight set) is a mark markWalk finds, counted in activeAffectsMarks, re-polled at flight start and landing. Core carries, all in the floor: - recompute's pre-pass flag wipe keeps REACTIVE_REASK for the pass (the wrapper classifies a quiet re-ask, A24; the finally mask still drops it); - commitPendingNode's window close is gated on a staged value, so a flight queued as a pending node with nothing staged (never leads, D2) stays open; - one hook, GlobalQueue._deferredLanded, called with ?. from commitPendingNode (snap) and asyncWrite's direct branch. D9: refresh's waiter and until's predicate park on an unanswered flight (until transitively, through its current deps). A staged answer counts as answered, which is what lets `yield until(...)` inside the action whose own write asked the flight settle instead of deadlocking. solid-js: createDeferred hydrates like createMemo through the _hydrateSignalLike adapter slot (as createOptimistic), so hydrating bundles that never call it do not retain it; on the server it is createMemo (D7). Size: +40 B minified in every size scenario (the two hook calls and the mask); treeshake floor 26,678 -> 26,695. Brotli core floor +17 B; other scenarios move -26..+97 B brotli around the same 40 B. Caps not raised here. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent 644eaf3 commit 06307a4

16 files changed

Lines changed: 1405 additions & 232 deletions

File tree

‎.changeset/add-create-deferred.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+
Add `createDeferred`: an async memo that may lag the global clock but never leads it. Once it has a committed value, a refetch is served the previous answer instead of suspending — readers keep rendering, the input's write commits immediately, and the landing commits on its own schedule — while `isPending` stays loud (including through sync derivations and derived stores). The first load still suspends to the nearest `<Loading>`; `loadingValue` composes. A flight asked against a write another node holds reveals with that write. `refresh(d)` and `until` wait for the landed truth, including a predicate that reads the node through a derived memo. Errors propagate. On the server it is `createMemo`.

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
2222

2323
| vocabulary | rules | cited in src | cited in tests | cited nowhere |
2424
|---|---|---|---|---|
25-
| A | 34 | 19 | 34 | 0 |
25+
| A | 34 | 21 | 34 | 0 |
2626
| V | 5 | 2 | 5 | 0 |
2727
| B | 5 | 0 | 5 | 0 |
2828
| C | 4 | 0 | 3 | 1 |
@@ -61,17 +61,17 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
6161
| A14 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:165` | — | spec-async-semantics.test.ts×2 | [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:199` | async.ts×4 constants.ts×2 core.ts×6 lanes.ts×2 scheduler.ts×2 store.ts×1 | async-chain-supersession.test.ts×1 first-observer-stale-reader.test.ts×1 lane-frame-deferred-run-3662.test.ts×1 lane-hold-on-observation.test.ts×1 lane-outside-view.test.ts×1 lane-pass-stamped-effect-3662.test.ts×1 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 spec-async-semantics.test.ts×2 stale-read-uninitialized-cross-transition.test.ts×1 superseded-source-blocks-3462.test.ts×2 treeshake.test.ts×4 visibility-oracle-store.states.ts×6 visibility-oracle.states.ts×6 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 … |
6363
| A16 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:173` | verdict.ts×1 | 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-
| A17 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:31` | async.ts×5 constants.ts×3 core.ts×11 invariants.ts×3 optimistic.ts×8 scheduler.ts×2 verdict.ts×2 map.ts×1 signals.ts×2 optimistic.ts×1 store.ts×2 | lane-uninitialized-landing-3648.test.ts×5 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×1 optimistic-list-mutation-matrix.test.ts×1 optimistic-maparray-index-frame-f1.test.ts×1 optimistic-untracked-reads-f3-f5.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×23 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… |
64+
| A17 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:31` | async.ts×5 constants.ts×3 core.ts×11 invariants.ts×3 optimistic.ts×8 scheduler.ts×2 verdict.ts×2 map.ts×1 signals.ts×2 optimistic.ts×1 store.ts×2 | createDeferred.test.ts×1 lane-uninitialized-landing-3648.test.ts×5 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×1 optimistic-list-mutation-matrix.test.ts×1 optimistic-maparray-index-frame-f1.test.ts×1 optimistic-untracked-reads-f3-f5.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×23 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:41` | async.ts×3 constants.ts×1 core.ts×10 optimistic.ts×7 scheduler.ts×3 types.ts×2 verdict.ts×2 map.ts×1 optimistic.ts×1 store.ts×2 | body-end-supersession-visibility.test.ts×4 createOptimistic.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×3 flight-owned-transaction.test.ts×1 optimistic-list-mutation-matrix.test.ts×1 optimistic-untracked-reads-f3-f5.test.ts×1 superseded-before-first-commit.test.ts×5 visibility-oracle-store.states.ts×9 visibility-oracle-store.test.ts×1 visibility-oracle.states.ts×24 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 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:101` | async.ts×1 core.ts×3 optimistic.ts×2 verdict.ts×2 | lane-uninitialized-landing-3648.test.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:352` | 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:359` | — | 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… |
6969
| 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… |
71-
| 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… |
71+
| A24 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:109` | deferred.ts×2 | createDeferred.test.ts×1 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:253` | 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… |
7373
| A26 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:67` | core.ts×1 scheduler.ts×1 store.ts×1 | action-await-contract.test.ts×2 posture-store-parity.test.ts×2 visibility-oracle-store.states.ts×2 visibility-oracle.states.ts×1 visibility-oracle.test.ts×1 | [ruled 2026-07-17] An ambient transaction window is one flush; parking is flush-driven — (**ruled 2026-07-17**, #2913; **enforcement hardened 2026-08-31**, #3141 — parking is flush-driven, and a trans… |
74-
| A27 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:245` | — | loading-value.test.ts×2 visibility-oracle.states.ts×18 visibility-oracle.test.ts×1 | [ruled 2026-08-10] The commit-#0 loading window is loading-class and verdict-quiet — (**ruled 2026-08-10**) **The commit-#0 loading window is loading-class and verdict-quiet.** A node born committed v… |
74+
| A27 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:245` | deferred.ts×1 | loading-value.test.ts×2 visibility-oracle.states.ts×18 visibility-oracle.test.ts×1 | [ruled 2026-08-10] The commit-#0 loading window is loading-class and verdict-quiet — (**ruled 2026-08-10**) **The commit-#0 loading window is loading-class and verdict-quiet.** A node born committed v… |
7575
| A28 | ruled, mechanism landed | `docs/SPEC-ASYNC-SEMANTICS.md:51` | constants.ts×2 core.ts×20 optimistic.ts×2 scheduler.ts×3 types.ts×1 verdict.ts×6 optimistic.ts×3 store.ts×1 | createOptimistic.test.ts×5 held-derivation-not-a-proposal-3612.test.ts×1 latest-held-till-flush.test.ts×1 optimistic-store-layer-scope.test.ts×1 posture-store-parity.test.ts×5 question-scoped-pending.test.ts×3 snapshot-derived-store-rows.test.ts×1 createOptimisticStore.test.ts×10 optimistic-draft-visibility-3665.test.ts×5 optimistic-list-mutation-matrix.harness.ts×1 optimistic-list-mutation-matrix.test.ts×2 shallow.test.ts×1 woken-transaction-adopts-staged-bump.test.ts×1 treeshake.test.ts×2 visibility-oracle-store.states.ts×8 visibility-oracle.states.ts×8 | [ruled, mechanism landed 2026-09-15] A write becomes visible at flush — to every channel — (**ruled 2026-09-08**; supersedes the #2922 mid-tick pull) **A write becomes visible at flush — to every chan… |
7676
| A29 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:75` | boundaries.ts×1 action.ts×1 async.ts×1 constants.ts×1 core.ts×8 effect.ts×1 optimistic.ts×1 scheduler.ts×2 signals.ts×1 store.ts×5 | body-end-supersession-visibility.test.ts×1 born-held.test.ts×3 boundary-not-born-held-3540.test.ts×4 direct-commit-readers-posture.test.ts×1 held-conditional-memo.test.ts×1 held-frame-dependencies.test.ts×2 held-truth-lane-only.test.ts×3 latest-held-till-flush.test.ts×2 optimistic-read-lane-not-transaction-3698.test.ts×3 posture-store-parity.test.ts×6 optimistic-untracked-reads-f3-f5.test.ts×1 store-unchanged-read-independent-write-3688.test.ts×1 treeshake.test.ts×3 visibility-oracle-store.states.ts×5 visibility-oracle-store.test.ts×1 visibility-oracle.states.ts×7 visibility-oracle.test.ts×1 write-proposals-3494.test.ts×1 | [ruled, amended in place 2026-09-13 (#3408)] A tracked read served a live transaction's staged value enters that transaction — A tracked computation served a node's staged `_pendingValue` — a value a … |
7777
| A30 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:207` | async.ts×3 attribution.ts×1 constants.ts×1 core.ts×3 effect.ts×1 scheduler.ts×5 | async-landing-deps-3461.test.ts×3 held-conditional-effect.test.ts×1 held-conditional-memo.test.ts×1 held-frame-dependencies.test.ts×2 ispending-in-boundary-on-3528.test.ts×1 lane-frame-deferred-run-3662.test.ts×1 lane-frame-held-lane-3662.test.ts×1 posture-born-held-and-observation.test.ts×1 treeshake.test.ts×2 write-proposals-3494.test.ts×2 zombie-rerun-after-commit-3546.test.ts×2 | [ruled 2026-09-13 (#3410)] A memo's dependencies are the committed frame's until the frame is replaced — A pass that _staged_ its value has not replaced the committed frame, so the committed value sti… |
@@ -112,7 +112,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
112112
| INV-1 | live | `docs/INTERNALS-ASYNC-STATE.md:150` | invariants.ts×2 | — | - **INV-1 (high)** `pendingProbe` is non-null only inside an `isPending()` call |
113113
| INV-2 | live | `docs/INTERNALS-ASYNC-STATE.md:152` | invariants.ts×2 | — | - **INV-2 (high)** A node with an _active_ override (`hasActiveOverride`) is |
114114
| INV-3 | live | `docs/INTERNALS-ASYNC-STATE.md:156` | boundaries.ts×1 core.ts×2 invariants.ts×2 lanes.ts×1 scheduler.ts×2 | first-observer-stale-reader.test.ts×1 lane-hold-on-observation.test.ts×1 loading-reset-collects-forwarded-3459.test.ts×1 | - **INV-3 (high)** `_asyncReporters` gains entries only inside |
115-
| INV-4 | live | `docs/INTERNALS-ASYNC-STATE.md:163` | invariants.ts×3 verdict.ts×1 | inv4-projection-dispose-shadow.test.ts×3 posture-store-parity.test.ts×1 | - **INV-4 (medium)** After any of the three write paths completes for node `el` |
115+
| INV-4 | live | `docs/INTERNALS-ASYNC-STATE.md:163` | deferred.ts×1 invariants.ts×3 verdict.ts×1 | inv4-projection-dispose-shadow.test.ts×3 posture-store-parity.test.ts×1 | - **INV-4 (medium)** After any of the three write paths completes for node `el` |
116116
| INV-5 | live | `docs/INTERNALS-ASYNC-STATE.md:167` | invariants.ts×2 lanes.ts×1 | — | - **INV-5 (medium)** A lane in `activeLanes` has `_mergedInto === null` |
117117
| INV-6 | live | `docs/INTERNALS-ASYNC-STATE.md:173` | invariants.ts×2 | — | - **INV-6 (medium)** At the end of a completing-transition flush: every node in |
118118
| INV-7 | live | `docs/INTERNALS-ASYNC-STATE.md:176` | core.ts×1 invariants.ts×2 | action-completion-race.test.ts×2 | - **INV-7 (medium)** `_pendingValue !== NOT_PENDING` on a non-optimistic node |
@@ -385,7 +385,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
385385
| §5 | live | `docs/INTERNALS-STORE-STATE.md:190` | — | — | Laziness invariants (candidates for `__TEST__` assertions) |
386386
| §5b | live | `docs/INTERNALS-STORE-STATE.md:208` | target.ts×2 | — | Creation budget (phase-1 fitness) |
387387
| §5c | live | `docs/INTERNALS-STORE-STATE.md:227` | — | — | Comparison method (shipped vs rewrite) |
388-
| §6 | live | `docs/INTERNALS-STORE-STATE.md:278` | core.ts×1 invariants.ts×1 lanes.ts×1 optimistic.ts×1 store.ts×2 target.ts×1 | — | Structural edits — the key-set node (resolves O2, RUL-8) |
388+
| §6 | live | `docs/INTERNALS-STORE-STATE.md:278` | core.ts×1 invariants.ts×1 lanes.ts×1 verdict.ts×1 optimistic.ts×1 store.ts×2 target.ts×1 | — | Structural edits — the key-set node (resolves O2, RUL-8) |
389389
| §6b | live | `docs/INTERNALS-STORE-STATE.md:306` | reconcile.ts×2 | adoption-lane-rollback.test.ts×1 | Lane-aware adoption (RUL-5) |
390390
| §6c | live | `docs/INTERNALS-STORE-STATE.md:325` | projection.ts×2 store.ts×1 | createProjection.async.test.ts×1 flight-owned-transaction.test.ts×1 | Store-wide status gating (RUL-7) |
391391
| §6d | live | `docs/INTERNALS-STORE-STATE.md:338` | reconcile.ts×1 target.ts×2 | — | Diff reachability (RUL-11) |

0 commit comments

Comments
 (0)