@solidjs/signals 2.0.0-rc.6 → 2.0.0-rc.8

package/dist/observe/core/optimistic.js

@@ -0,0 +1,438 @@
+import { NOT_PENDING, unwrapOverride, STATUS_UNINITIALIZED, REACTIVE_DIRTY, REACTIVE_CHECK, CONFIG_HAS_LANE, OVERRIDE_UNDEFINED, STATUS_PENDING, CONFIG_OVERRIDE_SUPERSEDED, EFFECT_RENDER, CONFIG_AUTHORITATIVE_OBSERVED, REACTIVE_MANUAL_WRITE, REACTIVE_OPTIMISTIC_DIRTY, LANE_RUN, EFFECT_USER } from "./constants.js";
+
+import { attrHooks } from "./attribution-hooks.js";
+
+import { ext, stale, latestReadActive, currentOptimisticLane } from "./core.js";
+
+import { NotReadyError } from "./error.js";
+
+import "./invariants.js";
+
+import { resolveTransition, getOrCreateLane, hasActiveOverride, activeLanes, signalLanes, laneHeld, findLane, resolveLane, assignOrMergeLane } from "./lanes.js";
+
+import { GlobalQueue, activeTransition, globalQueue, origin, clock, insertSubs, schedule, queuePendingNode } from "./scheduler.js";
+
+/**
+ * The optimistic write engine, moved out of core.ts/scheduler.ts. Everything
+ * here serves only optimistic overrides — createOptimistic,
+ * createOptimisticStore (and its store-node writes), and the verdict layer's
+ * companions (which are optimistic nodes). Modules that can create optimistic
+ * state call `installOptimisticEngine()` before creating it; apps that never
+ * import one of those APIs never retain any of this.
+ *
+ * Core call sites fire the hooks behind guards on state only this module can
+ * create (`_overrideValue !== undefined`, `currentOptimisticLane !== null`,
+ * `_optimisticNodes.length`, `activeLanes.size`), so `!` invocations are safe
+ * once the gate holds — the same late-binding contract as verdict.ts.
+ */
+/** The optimistic half of setSignal, fired when `_overrideValue !== undefined`. */ function optimisticWrite(e, n) {
+    const i = e.o?.De !== NOT_PENDING;
+    const t = i ? unwrapOverride(e.o?.De) : e.ge;
+    if (typeof n === "function") n = n(t);
+    const u = !!(e.S & STATUS_UNINITIALIZED) || 
+    // A dirty node's _value is stale (its queued recompute hasn't run — e.g.
+    // a latest() shadow marked by the previous landing's companion snap), so
+    // equality against it must not swallow the write. Without this, a sync
+    // push returning the shadow to that stale value was dropped, the snap
+    // recompute then committed the parent's old value, and the banner showed
+    // the previous transition's target (#3041 follow-up).
+    !!((e.it ?? 0) & (REACTIVE_DIRTY | REACTIVE_CHECK)) || !e.Ue || !e.Ue(t, n);
+    if (!u) {
+        // Same-value write with an active override still entangles the current
+        // action's transition — the hold must outlast all overlapping actions —
+        // and renews the override's PROVENANCE: the newer action re-asks the
+        // question, so an older action's answer arriving later is stale to it
+        // too (#3331; a same-value re-prediction otherwise let the first
+        // action's slow source supersede and restart the downstream flight).
+        if (i) {
+            const n = resolveTransition(e);
+            if (n && activeTransition !== n) globalQueue.initTransition(n);
+            if (origin > e.o.Zt) e.o.Zt = origin;
+        }
+        return n;
+    }
+    if (i) globalQueue.initTransition(resolveTransition(e));
+    // No revert target is stashed: while the override is active every reader
+    // sees it (A17), so authoritative arrivals commit silently into _value and
+    // reverting is just dropping the override — _value is already correct.
+     else globalQueue.m.en.push(e);
+    // Stamp ownership on the node (post-merge, so entangled writers share the
+    // joint root). resolveTransition prefers this over the lane's _transition,
+    // which a shared subscriber can merge across transactions (#2912).
+        ext(e).Yt = activeTransition;
+    ext(e).Lt = clock;
+    // Provenance: the action asking. An answer an OLDER action's flight brings
+    // back is a stale question and holds silently to commit (#3331).
+        ext(e).Zt = origin;
+    const r = getOrCreateLane(e);
+    ext(e).Te = r;
+    // A fresh override re-masks: whatever truth is staged, this write is the
+    // value for the graph again until the source answers it (#3331).
+        e.T = (e.T | CONFIG_HAS_LANE) & ~CONFIG_OVERRIDE_SUPERSEDED;
+    // Literal undefined must not land raw: the slot doubles as the optimistic
+    // brand, and erasing it makes the write invisible and routes follow-up
+    // writes off the optimistic path into permanent commits (#2898).
+        ext(e).De = n === undefined ? OVERRIDE_UNDEFINED : n;
+    // syncCompanions only pokes _pendingSignal/_latestValueComputed — with
+    // neither companion present the call is a guaranteed no-op.
+        (e.o?.be !== undefined || e.o?.pe !== undefined) && GlobalQueue.Ae !== null && GlobalQueue.Ae(e, n);
+    if (e.ot !== undefined) e.ae = clock;
+ // §12e: computed-only slot
+        insertSubs(e, true);
+    schedule();
+    return n;
+}
+
+/**
+ * transitionComplete's override blockage: a settling transition stays open
+ * while one of its optimistic nodes holds an active override that is still
+ * pending on real (non-affects-sentinel) async.
+ */ function transitionBlocked(e) {
+    for (let n = 0; n < e.en.length; n++) {
+        const i = e.en[n];
+        if (hasActiveOverride(i) && "S" in i && i.S & STATUS_PENDING && i.o?._ instanceof NotReadyError) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function resolveOptimisticNodes(e) {
+    // Settlement writes below (snapCompanionsToState → updatePendingSignal-style
+    // notifications) may push fresh optimistic nodes; only this batch settles
+    // now, so iterate a fixed window and splice it out at the end.
+    const n = e.length;
+    for (let i = 0; i < n; i++) {
+        const n = e[i];
+        if (n.o !== null) n.o.Te = undefined;
+        // Revert is a pure drop: there is no revert target to commit —
+        // override-covered authoritative values hold in _pendingValue and
+        // elevate on their OWN transition's schedule (A18 as re-ruled 2026-07-07).
+                if (!(n.S & STATUS_PENDING)) n.S &= ~STATUS_UNINITIALIZED;
+        const t = n.o?.De;
+        ext(n).De = NOT_PENDING;
+        // A superseded override's subscribers already re-derived from the truth
+        // when it arrived (#3331) — the drop changes nothing they read. Everyone
+        // else learns of the correction here: this drop IS their notification.
+                const u = (n.T & CONFIG_OVERRIDE_SUPERSEDED) !== 0;
+        n.T &= ~CONFIG_OVERRIDE_SUPERSEDED;
+        if (!u && t !== NOT_PENDING && n.ge !== unwrapOverride(t)) insertSubs(n, true);
+        n.Ee = null;
+        if (n.o !== null) n.o.Yt = null;
+    }
+    // Settlement checkpoint (#2838): companions caught in this batch (or owned
+    // by a node in it) re-derive from committed state, so verdicts survive the
+    // transition that produced them (A19 — pending is a property of the data).
+        for (let i = 0; i < n; i++) {
+        const n = e[i];
+        if (n.o?.be || n.o?.pe) GlobalQueue.Dn(n);
+        const t = n.o?.Qe;
+        if (t && (t.o?.be === n || t.o?.pe === n)) GlobalQueue.Dn(t);
+    }
+    e.splice(0, n);
+}
+
+/**
+ * A18 supersession (#3331): the node's own source arrived with a value that
+ * differs from its active override. "Knowing otherwise" ends the optimism for
+ * the graph at once: the override stays only as the DISPLAYED value (untracked
+ * reads, the applied frame) until the owning transaction commits, while
+ * tracked readers see the staged truth and re-derive from it as that
+ * transaction's held work — so async downstream restarts now, not at the
+ * revert (no waterfall).
+ *
+ * The lane's job for this node is over: a lane applies an optimistic view
+ * ahead of its transaction, and there is no optimistic view left — the
+ * corrected cascade is plain transaction-held work (staged memos, effect runs
+ * in the stashable queues). Demote the node and every cascade member that
+ * rides this lane; the caller then notifies on the plain channel. Runners the
+ * lane still holds for demoted effects (the optimistic frame that never got to
+ * apply) defer to the regular queue in runEffect. In a lane merged with a
+ * still-optimistic source, members shared with that source lose their lane
+ * too and simply wait for the transaction — less optimistic, never torn.
+ *
+ * A later arrival EQUAL to the override (an earlier action's answer superseded
+ * this one's; now this one's answer confirms it) ends the supersession: the
+ * graph re-derives from the override, which is the truth again. Notifies the
+ * subscribers in both cases. A plain matching confirmation (no supersession
+ * in force) is A17-silent for ordinary subscribers and wakes only an
+ * authoritative-view reader (until()'s predicate, refresh()'s waiter) that
+ * observed this node past its override — "authoritative arrival equal to the
+ * override" is exactly the acknowledgment it waits for (#3164, #3303). The
+ * wake hook is installed by the setters of that bit; optional here because
+ * the bit only implies the optimistic engine was consulted.
+ */ function supersedeOverride(e, n) {
+    const i = !e.Ue || !e.Ue(n, unwrapOverride(e.o.De));
+    if (!i) {
+        if (!(e.T & CONFIG_OVERRIDE_SUPERSEDED)) {
+            if (e.T & CONFIG_AUTHORITATIVE_OBSERVED) GlobalQueue.En?.(e);
+            return;
+        }
+        e.T &= ~CONFIG_OVERRIDE_SUPERSEDED;
+    } else {
+        // Provenance (#3331): an answer brought back by an OLDER action than the
+        // one that wrote this override answers a question the user has since
+        // changed. It is staged like any other landing and reveals if it is
+        // still the truth when the transaction commits, but it does not move the
+        // graph now — a slow source must not leak back in over a newer intent.
+        // 0 is mainline (no action): always the current question.
+        if (origin && origin < e.o.Zt) return;
+        e.T |= CONFIG_OVERRIDE_SUPERSEDED;
+        const n = e.o?.Te;
+        if (n) {
+            const i = findLane(n);
+            const t = [ e ];
+            while (t.length) {
+                const e = t.pop();
+                const n = e.o?.Te;
+                if (!n || findLane(n) !== i) continue;
+                e.o.Te = undefined;
+                i._e.delete(e);
+                for (let n = e.u; n !== null; n = n.se) t.push(n.le);
+            }
+        }
+    }
+    if (attrHooks !== null) attrHooks.asyncEnd(e, undefined, n, true);
+    insertSubs(e);
+}
+
+/** read()'s value for a tracked reader of a superseded node: the truth —
+ * staged, or already committed (a mainline landing commits at the head of
+ * its flush, ahead of the heap run, and the override drops only at the
+ * batch's end; in between the graph must not fall back to the override it
+ * has left) — or the displayed override for a stale (render) reader of some
+ * OTHER transaction, the same visibility a foreign transaction's staged
+ * write has. */ function supersededRead(e) {
+    if (stale && e.Ee && activeTransition !== e.Ee) return unwrapOverride(e.o?.De);
+    return e.Pe !== NOT_PENDING ? e.Pe : e.ge;
+}
+
+/**
+ * An authoritative store landing on an override-covered node — a derived
+ * optimistic store's own truth arriving over a tentative edit through the
+ * projection-write channel (setSignal under projectionWriteActive). The
+ * store twin of asyncWrite's override branch: the truth stages for its
+ * transaction's commit whatever its relation to the committed value (a
+ * landing equal to committed still differs from the override), companions
+ * learn of it, and supersedeOverride decides the rest — A18 supersession with
+ * action provenance, or an A17-silent confirmation (#3331). Before this the
+ * landing took setSignal's plain path: a differing truth staged silently
+ * under the override and the graph never moved until the commit.
+ */ function landOnOverride(e, n) {
+    const i = e.Pe === NOT_PENDING ? e.ge : e.Pe;
+    if (typeof n === "function") n = n(i);
+    if (attrHooks !== null) attrHooks.write(e, i, n);
+    if (e.Pe === NOT_PENDING) queuePendingNode(e);
+    e.Pe = n;
+    GlobalQueue.Ae?.(e, n);
+    supersedeOverride(e, n);
+    schedule();
+    return n;
+}
+
+function runQueue(e, n) {
+    for (let i = 0; i < e.length; i++) e[i](n | LANE_RUN);
+}
+
+/**
+ * Run effects from all lanes that are ready (no OBSERVED pending async — see
+ * laneHeld).
+ */ function runLaneEffects(e) {
+    for (const n of activeLanes) {
+        if (n.gn || laneHeld(n)) continue;
+        const i = n.vn[e - 1];
+        if (i.length) {
+            n.vn[e - 1] = [];
+            runQueue(i, e);
+        }
+    }
+    // Optimistic patch applications ride the same visibility slot as lane
+    // effects (in-flight DOM updates); no-op unless patches registered.
+        if (e === EFFECT_RENDER) GlobalQueue.bn?.();
+}
+
+function cleanupCompletedLanes(e) {
+    for (const n of activeLanes) {
+        const i = e ? n.Ee === e : !n.Ee;
+        if (!i) continue;
+        if (!n.gn) {
+            if (n.vn[0].length) runQueue(n.vn[0], EFFECT_RENDER);
+            if (n.vn[1].length) runQueue(n.vn[1], EFFECT_USER);
+        }
+        if (n.Ln.o?.Te === n) if (n.Ln.o !== null) n.Ln.o.Te = undefined;
+        n._e.clear();
+        n.vn[0].length = 0;
+        n.vn[1].length = 0;
+        activeLanes.delete(n);
+        signalLanes.delete(n.Ln);
+    }
+}
+
+/** read()'s per-lane suspension test (pending-throw path, lane context). */ function laneSuspends(e) {
+    // An UNINITIALIZED async source suspends regardless of lane (#3276): a
+    // lane mismatch preserves an already-committed stale value, but a source
+    // with no committed truth has nothing to serve — the cross-lane read
+    // surfaced a fabricated `undefined` where latest() itself suspends
+    // (latestRead rethrows NotReady for tracked uninitialized reads). Lives
+    // here rather than read()'s throw path so the floor bundles don't pay:
+    // this is only reachable under a lane, which implies the engine.
+    if (e.S & STATUS_UNINITIALIZED) return true;
+    // Per-lane suspension: only throw if in same lane as pending async
+    // AND the node doesn't have an active override (overrides are the visible value,
+    // downstream in the lane should read the override, not throw)
+        const n = e.o?.Te;
+    if (!n) return false;
+    return findLane(n) === findLane(currentOptimisticLane) && !hasActiveOverride(e);
+}
+
+/**
+ * read()'s reveal carve-out asks whether a pending node is routed through a
+ * LIVE lane: a lane-derived flight's inputs are already revealed through the
+ * lane (the override, or latest()'s fresh value), so a stale reader of another
+ * transaction must hold on the flight rather than show the node's committed
+ * value beside them (#3334). Exact, not sticky: `resolveLane` clears a lane
+ * reference the engine has since retired, so a node that was once lane-routed
+ * and is now pending under a plain hold is judged by that hold alone.
+ */ function laneLive(e) {
+    return resolveLane(e) !== undefined;
+}
+
+/**
+ * read()'s entanglement gate: a reader recomputing under an optimistic lane
+ * that reads a pending mid-transition write sees the committed value; the sub
+ * is recorded for replay at commit.
+ */ function gatedRead(e, n, i) {
+    if (latestReadActive || e.Pe === NOT_PENDING || e.ot || n !== e && !(n.it & REACTIVE_MANUAL_WRITE)) {
+        return false;
+    }
+    activeTransition.ht.add(i);
+    return true;
+}
+
+/**
+ * read()'s value selection under a lane: return the committed `_value` for
+ * optimistic/lane-assigned signals, stale-mode reads, and pending owners.
+ */ function laneReadsCommitted(e, n, i) {
+    if (e.o?.De !== undefined || !!e.o?.Te || !!(n.S & STATUS_PENDING)) {
+        // The committed view hides a staged in-flight value that will promote
+        // silently (commitPendingNode never re-notifies). gatedRead records plain
+        // signals for replay at commit; async memos are excluded from it by the
+        // `_fn` check and reach here instead — a lane-assigned source whose async
+        // already settled (laneAsyncSettled keeps _optimisticLane) served its
+        // committed value to a reader that never re-ran after the landing, so a
+        // pending-gated branch stayed one value behind permanently (#3041
+        // follow-up). Record the reader under the same replay contract — when
+        // the commit will actually change what it read: a staged value equal to
+        // the committed one (a lane recompute already published it, INV-11)
+        // promotes to the same view, and a replay would only re-run effects
+        // against an unchanged frame (#3330). An override-covered node's revert
+        // notifies its own subscribers when the truth differs (resolveOptimistic
+        // Nodes), so the reader is recorded only for the staged-vs-committed gap.
+        if (e.Pe !== NOT_PENDING && e.Pe !== e.ge) (activeTransition ?? globalQueue.m).ht.add(i);
+        return true;
+    }
+    if (n === e && stale && i.o?.Qe !== e) {
+        // The committed view can hide a staged write (a lane member — even just
+        // an isPending companion flip — puts the reader "under a lane"). The
+        // staged value commits with no re-delivery (commitPendingNode never
+        // re-notifies), so record the reader for replay at commit — the same
+        // contract gatedRead provides (#2963). gatedRead itself only covers
+        // signal reads where the reading computed differs from the source; the
+        // owner === el memo/self read lands here instead. With a transaction
+        // active the staged value promotes silently at ITS landing, so record
+        // into the transaction (#3041 follow-up: a pending-gated branch that
+        // first read its async source during the landing flush stayed one value
+        // behind permanently); with none, into the ambient batch.
+        if (e.Pe !== NOT_PENDING) (activeTransition ?? globalQueue.m).ht.add(i);
+        return true;
+    }
+    return false;
+}
+
+/**
+ * recompute()'s lane posture: resolve the node's own lane (own=true), or adopt
+ * a dependency's optimistic lane (own=false — parent-deeper-than-owned-child
+ * can run before its OPT-dirty child propagates).
+ */ function recomputeLane(e, n) {
+    if (n) {
+        const n = resolveLane(e);
+        if (!n) return null;
+        // Wake-only lane demotion (#3009): a plain write to a latest()-tracked
+        // source rides the optimistic channel only to wake verdict companions —
+        // its lane is sourced by the companion shadow (_parentSource set) and owns
+        // no transaction. When such a node is pulled mid-tick by a latest()/
+        // isPending() probe, lane posture would direct-commit _value, leaking the
+        // queued write into committed reads before the flush. Return `false` so
+        // recompute() runs plain: the value stages and commits with the flush.
+        // (el's own override slot excludes companions themselves; a lane merged
+        // into a real optimistic lane resolves to a non-companion source.)
+                if (!globalQueue.Qn && !activeTransition && !n.Ee && n.Ln.o?.Qe !== undefined && e.o?.De === undefined) {
+            if (e.o !== null) e.o.Te = undefined;
+            return false;
+        }
+        return n;
+    }
+    for (let n = e.te; n; n = n.ne) {
+        const i = n.oe;
+        if (i.it & REACTIVE_OPTIMISTIC_DIRTY) {
+            const n = resolveLane(i);
+            if (n) {
+                e.it |= REACTIVE_OPTIMISTIC_DIRTY;
+                assignOrMergeLane(e, n);
+                return n;
+            }
+        }
+    }
+    return null;
+}
+
+/** recompute()'s catch path: record the pending async as the current lane's
+ * (ownership — laneHeld decides the hold). The lane source's isPending
+ * companion is NOT refreshed here: its verdict never read _pendingAsync, and
+ * the source's own write/commit/settlement paths keep it current. */ function laneAsyncPending(e) {
+    const n = findLane(currentOptimisticLane);
+    if (n.Ln !== e) {
+        n._e.add(e);
+        ext(e).Te = n;
+        e.T |= CONFIG_HAS_LANE;
+    }
+}
+
+/** recompute()'s success path: the node's async settled, clear it from its lane. */ function laneAsyncSettled(e) {
+    const n = resolveLane(e);
+    if (n) {
+        n._e.delete(e);
+    }
+}
+
+function trackOptimisticStore(e) {
+    // After initTransition, globalQueue._batch IS activeTransition (same reference)
+    globalQueue.m.nn.add(e);
+    schedule();
+}
+
+/**
+ * Installs the engine's hooks. Idempotent; called by every module that can
+ * create optimistic state (verdict.ts at module top level, createOptimistic
+ * and createOptimisticStore at first call) BEFORE any optimistic node exists.
+ */ function installOptimisticEngine() {
+    if (GlobalQueue.pn !== null) return;
+    GlobalQueue.pn = optimisticWrite;
+    GlobalQueue.Un = resolveOptimisticNodes;
+    GlobalQueue.Pn = transitionBlocked;
+    GlobalQueue.Fn = cleanupCompletedLanes;
+    GlobalQueue.Vn = runLaneEffects;
+    GlobalQueue.Oe = supersedeOverride;
+    GlobalQueue.Sn = supersededRead;
+    GlobalQueue.Rn = landOnOverride;
+    GlobalQueue.An = gatedRead;
+    GlobalQueue.dn = laneSuspends;
+    GlobalQueue.Tn = laneLive;
+    GlobalQueue.On = laneReadsCommitted;
+    GlobalQueue.Ft = recomputeLane;
+    GlobalQueue.vt = laneAsyncPending;
+    GlobalQueue.Ht = laneAsyncSettled;
+    GlobalQueue.Hn = trackOptimisticStore;
+}
+
+export { installOptimisticEngine };