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

package/dist/dev.js

@@ -232,7 +232,8 @@ const defaultOptions = {
   wideDeps: 30,
   hotTime: { budgetMs: 8, windowMs: 1000 },
   unstableMemos: 4,
-  wideWrites: 250
+  wideWrites: 250,
+  waterfalls: { minFlightMs: 50 }
 };
 let options = { ...defaultOptions };
 const listeners = new Set();
@@ -425,10 +426,13 @@ function checkDepWidth(el) {
   });
   console.warn(message);
 }
+const hotCauses = new Map();
+const HOT_FANOUT_FIRST_MILESTONE = 5;
 /**
  * Hot-scope warning — flags a scope that re-ran more than `count` times
  * inside one `windowMs` window. Warned once per window, with the most recent
  * cause chain named so the leaking signal is identified in the message.
+ * Fan-out spam is folded per root cause (see HotCauseWindow above).
  */
 function checkHotRuns(el, event) {
   const cfg = options.hotRuns;
@@ -443,22 +447,55 @@ function checkHotRuns(el, event) {
   node._devWinCount = (node._devWinCount ?? 0) + 1;
   if (node._devHotWarned || node._devWinCount < cfg.count) return;
   node._devHotWarned = true;
-  const rootCause = event.causes.map(c => `"${c.name}" (${c.kind})`).join(", ");
+  // Root-cause key: the set of originating writes behind this scope's latest
+  // re-run. Scopes hot from the SAME roots share one aggregation window.
+  const roots = new Set();
+  rootsOf(event.causes, roots);
+  const causeKey = roots.size > 0 ? [...roots].sort().join(", ") : "(untracked)";
+  let window = hotCauses.get(causeKey);
+  if (window === undefined || now - window.winStart > cfg.windowMs) {
+    window = { winStart: now, scopes: 0, runs: 0, nextMilestone: HOT_FANOUT_FIRST_MILESTONE };
+    hotCauses.set(causeKey, window);
+  }
+  window.scopes++;
+  window.runs += node._devWinCount;
+  if (window.scopes === 1) {
+    const rootCause = event.causes.map(c => `"${c.name}" (${c.kind})`).join(", ");
+    const message =
+      `[HOT_SCOPE_RERUNS] ${event.nodeKind} "${event.nodeName}" re-ran ${node._devWinCount} times ` +
+      `in ${Math.max(1, now - node._devWinStart)}ms — a hot signal is likely leaking into this ` +
+      `scope. Latest cause: ${rootCause || "(untracked pull)"}`;
+    emitDiagnostic({
+      code: "HOT_SCOPE_RERUNS",
+      kind: "perf",
+      severity: "warn",
+      message,
+      nodeName: event.nodeName,
+      data: {
+        runs: node._devWinCount,
+        windowMs: cfg.windowMs,
+        causes: event.causes.map(c => c.name)
+      }
+    });
+    console.warn(message);
+    return;
+  }
+  // Additional scopes hot from the same cause: silent until a milestone —
+  // the culprit is the cause, and it has already been named once.
+  if (window.scopes < window.nextMilestone) return;
+  window.nextMilestone *= 10;
   const message =
-    `[HOT_SCOPE_RERUNS] ${event.nodeKind} "${event.nodeName}" re-ran ${node._devWinCount} times ` +
-    `in ${Math.max(1, now - node._devWinStart)}ms — a hot signal is likely leaking into this ` +
-    `scope. Latest cause: ${rootCause || "(untracked pull)"}`;
+    `[HOT_SCOPE_FANOUT] ${window.scopes} scopes have gone hot (${window.runs} re-runs) within ` +
+    `${cfg.windowMs}ms, all driven by ${causeKey} — one hot cause is re-running a large part ` +
+    `of the graph. Per-scope warnings are suppressed; fix the cause. If consumers ask keyed ` +
+    `questions of it, invert with createSelector or createProjection.`;
   emitDiagnostic({
-    code: "HOT_SCOPE_RERUNS",
+    code: "HOT_SCOPE_FANOUT",
     kind: "perf",
     severity: "warn",
     message,
-    nodeName: event.nodeName,
-    data: {
-      runs: node._devWinCount,
-      windowMs: cfg.windowMs,
-      causes: event.causes.map(c => c.name)
-    }
+    nodeName: causeKey,
+    data: { cause: causeKey, scopes: window.scopes, runs: window.runs, windowMs: cfg.windowMs }
   });
   console.warn(message);
 }
@@ -637,6 +674,120 @@ function checkUnstableOutput(el, prevValue, newValue) {
   });
   console.warn(message);
 }
+// WeakMaps: an errored/abandoned flight must not leak its node or block GC.
+const liveFlights = new WeakMap();
+const landedFlights = new WeakMap();
+/**
+ * Flight-object identity → earliest known start. Fed by markFlight() (the
+ * cooperative preload/cache declaration — populated even while attribution
+ * is disabled, so navigation-time marks survive a later enable()) and by
+ * first sightings at registration.
+ */
+const flightOrigins = new WeakMap();
+let waterfallLog = [];
+/** Deepest landed-flight cause reachable through a cause list (derived links included). */
+function flightCauseIn(causes) {
+  let best = null;
+  for (const c of causes) {
+    let found = null;
+    if (c.kind === "async") found = landedFlights.get(c) ?? null;
+    else if (c.kind === "derived" && c.causes) found = flightCauseIn(c.causes);
+    if (found !== null && (best === null || found.chain.length > best.chain.length)) best = found;
+  }
+  return best;
+}
+function trackFlightStart(el, flight) {
+  if (options.waterfalls === false) return;
+  const at = now();
+  const origin = flightOrigins.get(flight) ?? at;
+  if (origin === at) flightOrigins.set(flight, at);
+  // Nearest enclosing frame with causes: create runs carry null (a node born
+  // inside a parent's recompute inherits the parent's causality — the
+  // boundary-reveal case, and the lazy sibling whose first pull is gated
+  // behind an earlier not-ready read), so walk down to the first re-run frame.
+  let parent = null;
+  for (let i = frames.length - 1; i >= 0; i--) {
+    const causes = frames[i].causes;
+    if (causes !== null) {
+      parent = flightCauseIn(causes);
+      break;
+    }
+  }
+  // The sequentiality test. A marked/previously-seen flight whose origin
+  // predates the upstream landing was in the air alongside it: parallel.
+  if (parent !== null && origin < parent.landedAt) parent = null;
+  liveFlights.set(el, {
+    origin,
+    startSeq: changeSeq,
+    chain: parent === null ? [] : [...parent.chain, { name: parent.name, ms: parent.ms }]
+  });
+}
+/**
+ * Flight landed (whether or not the value committed — the wall time was
+ * spent either way). Attach the measurement to the landing's fresh "async"
+ * stamp so downstream flights can chain through it, then judge the chain.
+ */
+function finalizeFlight(el) {
+  const flight = liveFlights.get(el);
+  if (flight === undefined) return;
+  liveFlights.delete(el);
+  const landedAt = now();
+  const ms = landedAt - flight.origin;
+  const record = el._devChange;
+  // Only a stamp this landing produced may carry the measurement — a stale
+  // async record from a previous landing must not be re-labeled.
+  if (record !== undefined && record.kind === "async" && record.seq > flight.startSeq)
+    landedFlights.set(record, { name: nodeName(el), ms, chain: flight.chain, landedAt });
+  checkWaterfall(el, flight.chain, ms);
+}
+function checkWaterfall(el, chain, ms) {
+  const cfg = options.waterfalls;
+  if (cfg === false) return;
+  if (chain.length > 0) {
+    waterfallLog.push({
+      chain: [...chain, { name: nodeName(el), ms }],
+      sequentialMs: chain.reduce((sum, l) => sum + l.ms, ms)
+    });
+    if (waterfallLog.length > options.historyLimit) waterfallLog.shift();
+  }
+  // The verdict: trailing run of links that were each a real wait. A fast
+  // tail (settled preload/cache hit) or a fast upstream breaks the sequence.
+  if (ms < cfg.minFlightMs) return;
+  let seq = 1;
+  let totalMs = ms;
+  for (let i = chain.length - 1; i >= 0 && chain[i].ms >= cfg.minFlightMs; i--) {
+    seq++;
+    totalMs += chain[i].ms;
+  }
+  if (seq < 2) return;
+  const node = el;
+  if ((node._devWaterfallWarnedAt ?? 0) >= seq) return;
+  node._devWaterfallWarnedAt = seq;
+  const links = [...chain.slice(chain.length - (seq - 1)), { name: nodeName(el), ms }];
+  const path = links.map(l => `"${l.name}" (${l.ms.toFixed(0)}ms)`).join(" → ");
+  const message =
+    `[ASYNC_WATERFALL] ${seq} sequential async flights — ${path} — ` +
+    `${totalMs.toFixed(0)}ms serialized: each began only after the previous resolved ` +
+    `(as far as this graph can see). If a later request doesn't need the earlier ` +
+    `response, derive both from the same inputs so they start together; if the ` +
+    `dependency is intrinsic, preload the dependent data or join the requests ` +
+    `server-side. If this work WAS already started elsewhere (a preloader or request ` +
+    `cache), have that layer stamp its promises with DEV.attribution.markFlight().`;
+  // Depth 2 is advisory-only (structured consumers see it; the console does
+  // not): a 2-chain can be an intrinsic data dependency or an unmarked
+  // preload. A 3+ chain that survived the origin test is near-certainly
+  // structural — that one earns the console.
+  const severity = seq > 2 ? "warn" : "info";
+  emitDiagnostic({
+    code: "ASYNC_WATERFALL",
+    kind: "perf",
+    severity,
+    message,
+    nodeName: nodeName(el),
+    data: { chain: links.map(l => ({ name: l.name, ms: l.ms })), sequentialMs: totalMs }
+  });
+  if (severity === "warn") console.warn(message);
+}
 // The engine's implementation of the core's dev hook points. Installed by
 // enable(), uninstalled by disable() — while uninstalled the core pays one
 // null check per site and nothing else.
@@ -710,6 +861,9 @@ const engineHooks = {
   refreshed(el) {
     stampWrite(el, "refresh");
   },
+  flightStart(el, flight) {
+    trackFlightStart(el, flight);
+  },
   asyncStart(el) {
     asyncStartSeq = el._devChange?.seq ?? 0;
     asyncStartTime = el._time;
@@ -726,6 +880,9 @@ const engineHooks = {
       const committed =
         el._value !== asyncStartValue || el._time !== asyncStartTime || el._pendingValue === value;
       if (committed) stampWrite(el, "async", prev === undefined ? NO_VALUES : prev, value);
+      // Flight over either way — an equality-swallowed landing still spent
+      // the wall time (finalizeFlight only chains through a fresh stamp).
+      finalizeFlight(el);
       return;
     }
     // Landed through setSignal: reclassify its "write" stamp as an async
@@ -734,6 +891,7 @@ const engineHooks = {
     const change = el._devChange;
     if (change !== undefined && change.seq > asyncStartSeq && change.kind === "write")
       stampWrite(el, "async", NO_VALUES, value);
+    finalizeFlight(el);
   }
 };
 const attribution = {
@@ -742,6 +900,8 @@ const attribution = {
     frames.length = 0;
     scopeCosts.clear();
     writeCosts.clear();
+    waterfallLog = [];
+    hotCauses.clear();
     setAttributionHooks(engineHooks);
   },
   disable() {
@@ -750,6 +910,8 @@ const attribution = {
     frames.length = 0;
     scopeCosts.clear();
     writeCosts.clear();
+    waterfallLog = [];
+    hotCauses.clear();
     setAttributionHooks(null);
   },
   subscribe(listener) {
@@ -775,6 +937,15 @@ const attribution = {
       writes: [...writeCosts.values()].sort((a, b) => b.downstreamMs - a.downstreamMs)
     };
   },
+  waterfalls() {
+    return waterfallLog;
+  },
+  markFlight(flight, startedAt = now()) {
+    // Earliest wins: re-marking (a cache re-serving the same promise) must
+    // not move the origin later.
+    const existing = flightOrigins.get(flight);
+    if (existing === undefined || startedAt < existing) flightOrigins.set(flight, startedAt);
+  },
   format: formatRerun
 };
 
@@ -1920,6 +2091,12 @@ function commitPendingNode(n) {
     n._pendingValue = NOT_PENDING;
     // Set _modified for effects, but not for tracked effects (they handle their own scheduling)
     if (n._type && n._type !== EFFECT_TRACKED) n._modified = true;
+    // A quiet re-ask classification preserved through a held landing dies
+    // with the value commit — the commit IS the reveal (#3178). Gated on the
+    // staged value: status propagation queues pending nodes whose windows
+    // are still OPEN (no staged value), and their live classification must
+    // survive this sweep.
+    if (n._x) n._x._reask = false;
   }
   // The committed hold is the first observable answer for a loading-window
   // node — the window closes here, not at compute time (#2990). Unconditional
@@ -2187,6 +2364,13 @@ function transitionComplete(transition) {
   done && (transition._done = true);
   return done;
 }
+/** A fresh, unentered transaction (#3146): the optimistic store's truth
+ * flight DECLARES an owned transaction instead of relying on whatever the
+ * ambient adoption machinery stamped on its firewall. Activate it with
+ * initTransition; it is a plain batch until then. */
+function createTransition() {
+  return createBatch();
+}
 function currentTransition(transition) {
   while (transition._done && typeof transition._done === "object") transition = transition._done;
   return transition;
@@ -2851,12 +3035,14 @@ function addPendingSource(el, source) {
   return true;
 }
 function removePendingSource(el, source) {
-  if (!el._x?._pendingSources?.delete(source)) return false;
-  if (el._x?._pendingSources.size === 0) if (el._x !== null) el._x._pendingSources = undefined;
+  const sources = el._x?._pendingSources;
+  if (!sources?.delete(source)) return false;
+  if (!sources.size) el._x._pendingSources = undefined;
   return true;
 }
 function clearPendingSources(el) {
-  el._x?._pendingSources?.clear();
+  // This set is node-owned and never shared; dropping the sole reference
+  // releases the set and every entry without a redundant clear() walk.
   if (el._x !== null) el._x._pendingSources = undefined;
 }
 // A rejection-pending only resolves through the settle sweep over the
@@ -2973,6 +3159,49 @@ function settleErroredDependents(el, error) {
   if (scheduled) schedule();
 }
 function settlePendingSource(el) {
+  // Invariant: walking a settle implies truth exists. A caller reaching this
+  // with an uninitialized source is announcing a settle that has not
+  // happened — parked readers would wake into a value that was never
+  // produced (the rc.5 regression: the recompute-side walk fired on a
+  // projection driver whose first flight was superseded before any commit
+  // reached the observable store). "Uninitialized" alone is not the tell,
+  // though: a first landing whose commit is transition-held (streamed
+  // hydration rides this) parks its value in `_pendingValue` with the flag
+  // still set, and a comparator throw on that landing leaves the node
+  // uninitialized but errored — both have real truth to reveal. Only an
+  // uninitialized node with neither a held value nor an error is a settle
+  // that never happened. Silent in production; loud in dev so a future
+  // call site that violates the contract fails in its author's test run
+  // instead of wedging a downstream app.
+  {
+    const sources = el._x?._pendingSources;
+    if (
+      el._statusFlags & STATUS_UNINITIALIZED &&
+      el._pendingValue === NOT_PENDING &&
+      !el._x?._error &&
+      // A replacement source makes this a cleanup-only transfer: removing
+      // self leaves the source and every propagated dependent parked. No
+      // sources (or self alone) would release readers without truth.
+      !(sources?.size && (sources.size > 1 || !sources.has(el)))
+    ) {
+      emitDiagnostic({
+        code: "SETTLE_WALK_UNINITIALIZED_SOURCE",
+        kind: "lifecycle",
+        severity: "error",
+        message:
+          "[SETTLE_WALK_UNINITIALIZED_SOURCE] settlePendingSource was called on a source that " +
+          "never produced a value. Settling parked readers requires truth to reveal — an " +
+          "uninitialized source waking its dependents serves them its initial face instead of " +
+          "settled data.",
+        ownerId: el.id,
+        ownerName: el._name
+      });
+    }
+  }
+  // The normal landing path already cleared the source's own set. Superseded
+  // re-parks arrive here with an abandoned self entry, which must retire in
+  // the same walk as its propagated copies.
+  removePendingSource(el, el);
   let scheduled = false;
   let released;
   const visited = new Set();
@@ -3069,6 +3298,12 @@ function handleAsync(el, result, setter) {
   // fired _flightTeardown. A future non-recompute registration path must
   // release it here before overwriting _inFlight.
   ext(el)._inFlight = result;
+  // Attribution hook: a new flight is registered. Fired here (not in the
+  // branches below) so every flight shape — plain thenable, iterator, the
+  // flattened combinations — is announced exactly once, while the recompute
+  // frame that caused it is still on the engine's stack. Not inside a try
+  // (#2883 — see attribution-hooks.ts).
+  if (attrHooks !== null) attrHooks.flightStart(el, result);
   let syncValue;
   // Settle-time transition re-entry. The loading rail is invisible to
   // transactions (#2933): a boundary-caught first load never registers as an
@@ -3127,6 +3362,10 @@ function handleAsync(el, result, setter) {
     }
     settleTransition();
     notifyStatus(el, stillPending ? STATUS_PENDING : STATUS_ERROR, error);
+    // A NotReady rejection is a landing into another pending source. The
+    // rejected flight will never settle its self entry, so transfer ownership
+    // after notifyStatus has propagated the replacement source.
+    if (stillPending) settlePendingSource(el);
     el._time = clock;
     // A real error settles derivatively-pending dependents (notifyStatus
     // cleared their pending sources), so stranded lazy ones release here —
@@ -3141,8 +3380,16 @@ function handleAsync(el, result, setter) {
     if (el._flags & (REACTIVE_DIRTY | REACTIVE_OPTIMISTIC_DIRTY)) return;
     settleTransition();
     const wasUninitialized = !!(el._statusFlags & STATUS_UNINITIALIZED);
+    // Captured before clearStatus wipes it: a quiet re-ask's landing may be
+    // transition-held below, and the displayed value keeps answering the same
+    // question until the hold commits — the classification must survive to
+    // that reveal or companion synchronization briefly classifies the held
+    // old value as pending, a one-frame pulse to direct observers (#3178).
+    // A truthy capture implies `_x` exists, so the restore writes it directly.
+    const wasReask = el._x?._reask;
     trimStaleDeps(el);
     clearStatus(el);
+    if (wasReask) el._x._reask = true;
     const lane = resolveLane(el);
     if (lane) lane._pendingAsync.delete(el);
     // Attribution hook: lets the engine snapshot state before the landing
@@ -3236,8 +3483,12 @@ function handleAsync(el, result, setter) {
     // (`_pendingValue` set above or inside setSignal) is not — the verdict's
     // held-value branch is window-gated, and commitPendingNode closes the
     // window when the hold commits, so no one-frame isPending pulse can leak
-    // to live observers between the landing and its commit (#2990).
-    if (el._pendingValue === NOT_PENDING) el._loading = false;
+    // to live observers between the landing and its commit (#2990). The
+    // quiet re-ask classification follows the same schedule (#3178).
+    if (el._pendingValue === NOT_PENDING) {
+      el._loading = false;
+      if (wasReask) el._x._reask = false;
+    }
     settlePendingSource(el);
     schedule();
     flush();
@@ -3701,8 +3952,7 @@ function recompute(el, create = false) {
   // settles synchronously, those dependents settle HERE — asyncWrite's
   // settlePendingSource walk never runs for a landing that was preempted
   // (#3181).
-  const wasPendingSource =
-    (el._statusFlags & STATUS_PENDING) !== 0 && el._x?._pendingSources?.has(el) === true;
+  const wasPendingSource = el._x?._pendingSources?.has(el);
   // Re-ask classification lives in the verdict module; capture the flag before
   // the recompute wipes _flags below.
   const hadReask = (el._flags & REACTIVE_REASK) !== 0;
@@ -3816,6 +4066,9 @@ function recompute(el, create = false) {
         undefined,
         notReady ? el._x?._optimisticLane : undefined
       );
+      // The replacement source is fully propagated now. If no new flight
+      // re-owned self, retire the superseded flight and its dependent copies.
+      if (notReady && wasPendingSource && !el._x?._inFlight) settlePendingSource(el);
       if (reaskChanged) GlobalQueue._repollVerdicts(el);
     }
   } finally {
@@ -3948,17 +4201,11 @@ function recompute(el, create = false) {
     // (el._x?._error re-set), so this only runs on a genuinely clean recovery.
     if (outgoingError !== undefined && !valueChanged && !el._x?._error)
       settleErroredDependents(el, outgoingError);
-    // Pending twin of the sweep above (#3181): a flight superseded by this
-    // synchronous settle leaves every registered dependent still flagged
-    // STATUS_PENDING with a pending source that will never land — asyncWrite
-    // owns the walk only for flights that actually land. An unchanged value
-    // is the dangerous shape (a projection reconciling in place: a memo over
-    // it re-throws its cached NotReadyError forever, and every reader that
-    // suspended through that memo re-parks on the dead source), but the walk
-    // runs on the changed shape too, exactly as the landing path does —
-    // insertSubs notifies value SUBSCRIBERS, not pending REGISTRANTS, and
-    // the two sets only partially overlap.
-    if (wasPendingSource && !(el._statusFlags & STATUS_PENDING)) settlePendingSource(el);
+    // #3181: a synchronous settle supersedes the old landing callback, so
+    // recompute owns its pending-source sweep. An uninitialized node without
+    // a replacement source still has no truth to reveal and must stay parked.
+    if (wasPendingSource && !(el._statusFlags & (STATUS_PENDING | STATUS_UNINITIALIZED)))
+      settlePendingSource(el);
   }
   // Attribution hook: fired before the lane restore so `currentOptimisticLane`
   // still reflects THIS run's posture. The facts distinguish an overlay
@@ -5467,7 +5714,11 @@ function computePendingState(el) {
   ) {
     if (hasActiveOverride$1(el))
       return !el._equals || !el._equals(el._pendingValue, unwrapOverride(el._x?._overrideValue));
-    return true;
+    // A quiet re-ask's held landing still answers the same question: the
+    // classification survives the landing (asyncWrite) and dies with the
+    // commit (commitPendingNode) — verdict-quiet through the reveal, like
+    // the loading window above (#3178).
+    if (!comp._x?._reask) return true;
   }
   return newQuestionInFlight(comp);
 }
@@ -6316,6 +6567,74 @@ function createSignal(first, second) {
 function createMemo(compute, options) {
   return accessor(computed(compute, options));
 }
+/**
+ * Creates a reactive effect with **separate compute and effect phases**.
+ *
+ * - `compute(prev)` runs reactively — *put all reactive reads here*. The
+ *   returned value is passed to `effect` and is also the new "previous" value
+ *   for the next run.
+ * - `effect(next, prev?)` runs imperatively (untracked) after the queue
+ *   flushes. *Put DOM writes / fetch / logging / subscriptions here.* It may
+ *   return a cleanup function which runs before the next effect or on
+ *   disposal.
+ *
+ * Reactive reads inside `effect` will *not* re-trigger this effect — that's
+ * intentional. If you need a single-phase tracked effect, use
+ * `createTrackedEffect` (with the tradeoffs noted there).
+ *
+ * Pass an `EffectBundle` (`{ effect, error }`) instead of a plain function to
+ * intercept **compute-phase** errors — errors thrown by `compute` or arriving
+ * from upstream reactive sources (including async rejections), which your own
+ * code has no frame to `try/catch`. The `error` handler is the error arm of
+ * the effect phase: it runs on the same schedule and in the same imperative,
+ * writable scope as `effect` (setting error state via signals is fine), and
+ * only for *settled* errors — a transient error that recovers before the
+ * effect phase runs `effect` with the recovered value instead, and a held
+ * transition defers it exactly as it defers `effect`. Without an `error`
+ * handler a compute-phase error is logged and the effect simply skips that
+ * run — a non-render effect's reactivity failing does not crash the app.
+ * Rethrowing from `error` escalates it to the nearest error boundary
+ * (halting the system if none exists).
+ *
+ * The **effect phase is different**: it is your own imperative code, so handle
+ * failures with `try/catch` where they occur. An uncaught effect-phase throw
+ * is treated as an unhandled application error — caught by the nearest
+ * `createErrorBoundary`/`<Errored>`, and permanently halting the reactive
+ * system if there is none. It is *not* routed to the bundle's `error` handler.
+ *
+ * ```typescript
+ * createEffect<T>(compute, effectFn | { effect, error }, options?: EffectOptions);
+ * ```
+ * @param compute a function that receives its previous value and returns a new value used to react on a computation
+ * @param effectFn a function that receives the new value and is used to perform side effects (return a cleanup function), or an `EffectBundle` with `effect` and `error` handlers
+ * @param options `EffectOptions` -- name, defer, schedule, transparent
+ *
+ * @example
+ * ```ts
+ * const [count, setCount] = createSignal(0);
+ *
+ * createEffect(
+ *   () => count(),                  // compute: tracks `count`
+ *   value => console.log(value)     // effect: side effect
+ * );
+ *
+ * setCount(1); // logs 1 after the next flush
+ * ```
+ *
+ * @example
+ * ```ts
+ * createEffect(
+ *   () => userId(),
+ *   id => {
+ *     const ctrl = new AbortController();
+ *     fetch(`/users/${id}`, { signal: ctrl.signal });
+ *     return () => ctrl.abort(); // cleanup before next run / disposal
+ *   }
+ * );
+ * ```
+ *
+ * @description https://docs.solidjs.com/reference/basic-reactivity/create-effect
+ */
 function createEffect(compute, effectFn, options) {
   if (effectFn === undefined) {
     const message =
@@ -8521,33 +8840,43 @@ function readSource(target) {
     const hv = heldMaskView(target);
     if (hv !== null) return hv;
   }
-  // Signal-parity visibility (core read(): owner-context reads serve
-  // _pendingValue, context-free reads serve committed — effects recompute
-  // BEFORE commitPendingNodes in the flush, so the pending view must be
-  // servable). Drafts (setter window OR projection write-override) and
-  // owner-context reads see the pending backing; context-free reads see
-  // committed. Node reads apply the same rule, so both homes agree.
-  if (
+  return pendingBackingVisible(target, false) ? target.pb : target.v;
+}
+/** The single pb-vs-committed visibility decision (#3147), shared by per-key
+ * backing reads (readSource) and deep()/snapshot composition (snapshotWalk)
+ * so the two reader families can never disagree about a HELD landing.
+ *
+ * Signal-parity visibility (core read(): owner-context reads serve
+ * _pendingValue, context-free reads serve committed — effects recompute
+ * BEFORE commitPendingNodes in the flush, so the pending view must be
+ * servable). Drafts (setter window OR projection write-override) and
+ * owner-context reads see the pending backing; context-free reads see
+ * committed. Node reads apply the same rule, so all homes agree.
+ *
+ * `speculative` is deep()/snapshot's posture: an untrack/deep PEEK that sees
+ * ordinary pending staging regardless of owner context (the documented
+ * divergence from context-free per-key reads) — but never through a hold:
+ * held truth stays masked exactly as it is for per-key readers. */
+function pendingBackingVisible(target, speculative) {
+  return (
     target.pb !== null &&
     (inDraft(target) ||
       getWriteOverride() ||
-      // Owner-context readers see the pending backing — EXCEPT held truth
-      // on an optimistic family (#3164 fold): a live pb on an opt family
-      // outside the draft/write-override windows is a staged landing
-      // (tentative drafts never outlive their setter), and only the
-      // authoritative postures and latest() see it (the backing-level twin
-      // of core read()'s A17-for-held-truth arm; ordinary readers keep
-      // committed until the transaction's reveal).
-      (inOwnerContext() && !heldTruthMasked(target)) ||
+      // Owner-context (and speculative-peek) readers see the pending
+      // backing — EXCEPT held truth on an optimistic family (#3164 fold):
+      // a live pb on an opt family outside the draft/write-override windows
+      // is a staged landing (tentative drafts never outlive their setter),
+      // and only the authoritative postures and latest() see it (the
+      // backing-level twin of core read()'s A17-for-held-truth arm;
+      // ordinary readers keep committed until the transaction's reveal).
+      ((speculative || inOwnerContext()) && !heldTruthMasked(target)) ||
       // A projection's pending backing is authoritative-elect: serve it to
       // context-free readers too UNLESS a transition is holding the node
       // commits (downstream async hold — stale committed is the contract)
       // or the reader is a CHILDREN_FORBIDDEN scope, which never observes
       // its own unsettled write (#3082, signal parity per #3006).
       (target.fam !== null && !heldTruthMasked(target) && !foldHeld(target) && !inForbiddenScope()))
-  )
-    return target.pb;
-  return target.v;
+  );
 }
 /** #3164 fold: HELD truth on an optimistic family — a pending backing
  * stamped by a live transition that retains optimism — is masked from
@@ -9275,10 +9604,15 @@ function snapshotWalk(value, seen, fam) {
     if (t === undefined) break;
     if (t.fam !== null) fam = t.fam;
     if (t.fam?.opt === true) (optOwners ??= []).push(t);
+    // The shared visibility decision (#3147): the speculative peek serves
+    // pending staging, but a HELD landing is masked to committed exactly as
+    // it is for per-key readers — the two families must answer alike while
+    // a transaction holds store landings.
+    const usePB = pendingBackingVisible(t, true);
     // Snapshot runs mid-flush (tracked memos execute before commit), so a
     // pending prototype overlay must present as a REAL merged container.
-    if (t.ovl) materializePB(t);
-    const backing = t.pb ?? t.v;
+    if (usePB && t.ovl) materializePB(t);
+    const backing = usePB ? t.pb : t.v;
     if (backing === src) break;
     src = backing;
   }
@@ -10772,14 +11106,21 @@ function installNextBlockedHalf() {
   GlobalQueue._transitionBlocked = transition => {
     for (const store of transition._optimisticStores) {
       const t = store?.[$TARGET];
-      const fw = t?.fam?.node;
+      const fam = t?.fam;
+      const fw = fam?.node;
       // The hold exists to keep optimistic state alive until the store's own
       // truth lands (#2951). Once the family carries NO live overrides (a
       // landing consumed them, or they never existed), a pending firewall is
       // no reason to park the transaction — blocking then leaks it forever
       // when the in-flight question is never answered (undisposed fixtures).
-      if (fw != null && fw._statusFlags & STATUS_PENDING && familyHasLiveOverrides(t.fam))
-        return true;
+      if (fw == null || !(fw._statusFlags & STATUS_PENDING)) continue;
+      // Ownership is declared (#3146): only the flight's OWN transaction
+      // parks on the flight (the #2951 anchor routed the bare write there).
+      // A transaction that merely brushed the store never waits for truth
+      // it does not carry.
+      const ft = fam.ft != null ? liveTransition(fam.ft) : null;
+      if (ft !== null && ft !== currentTransition(transition)) continue;
+      if (familyHasLiveOverrides(fam)) return true;
     }
     return chained(transition);
   };
@@ -10837,15 +11178,35 @@ function createOptimisticStoreNext(first, second, options) {
   }
   if (derived) {
     const fn = first;
+    // #3146: an async settle event belongs to the flight's OWN transaction.
+    // A live declared one re-enters (a merge if the generic settle path
+    // already entered a graph-stamped stranger — the landing supersedes any
+    // recompute deriving from that stranger's world); a dead one renews (per
+    // A18(1) each arrival reveals on its own schedule, so per-yield
+    // transactions die with their commit and the next settle event opens the
+    // flight's next one — still declared, never anonymous). An UNDECLARED
+    // flight (loading window) keeps the ambient reveal (#2933: the loading
+    // rail is transaction-invisible).
+    const enterFlightTransition = () => {
+      const declared = fam.ft;
+      if (declared == null) return;
+      let ft = liveTransition(declared);
+      if (ft === null) fam.ft = ft = createTransition();
+      fam.node._transition = ft;
+      globalQueue.initTransition(ft);
+    };
     // Landing router (#3164 fold ruling): while a transaction retains
     // optimistic edits on this family, truth landings stage INTO it and
     // reveal atomically at settle; with no retainer they commit immediately
     // under the authoritative posture (async commits land outside the
-    // computed's sync body, so the posture is re-applied here).
+    // computed's sync body, so the posture is re-applied here) — inside the
+    // flight-owned transaction (#3146). Sync commits (the derive's body,
+    // owner is the firewall itself) reveal with their own recompute's flush.
     const wrapCommit = (write, value) => {
       const txn = retainingTransition(fam);
-      if (txn === null) runAuthoritative(write);
-      else stageLanding(fam, txn, value);
+      if (txn !== null) return void stageLanding(fam, txn, value);
+      if (getOwner() !== fam.node) enterFlightTransition();
+      runAuthoritative(write);
     };
     // Draft writes (the derive mutating its draft, sync body and post-await
     // continuations alike) are the same truth channel per-operation: bind
@@ -10858,19 +11219,56 @@ function createOptimisticStoreNext(first, second, options) {
       if (txn === null) op();
       else runFolded(txn, op);
     };
+    // Flight declaration (#3146): a recompute that registered a truth-flight
+    // OWNS its transaction. The ask's transaction is recorded on the family
+    // (created by the flight's own pending throw when none was ambient, the
+    // causing write's/refresh's when one was — graph-driven causality) and
+    // the firewall is stamped so every settle path resolves the flight's
+    // transaction by construction, not by whatever last brushed the node.
+    // When the ask took none (a dead stale stamp — the previous flight's,
+    // cleared nowhere — bare-returns the pre-throw entry), the flight opens
+    // its own here, same activation point as the pre-throw's creation: the
+    // ambient batch (the causing write, same-tick bare optimism) adopts into
+    // it exactly as it would have there, and the pending notification that
+    // follows this unwind registers observers against it. The flight
+    // also registers as its own async reporter: the transaction lives
+    // exactly as long as the question is unanswered, observed or not — the
+    // #2951 refetch-hold no longer depends on a tracked observer having
+    // happened to register one. Loading-window flights declare nothing
+    // (#2933: the loading rail is transaction-invisible); a sync run clears
+    // the declaration.
+    const declareFlight = self => {
+      if (self._x?._inFlight == null) {
+        if (!self._loading) fam.ft = null;
+        return;
+      }
+      if (self._loading) return;
+      let txn = activeTransition;
+      if (txn === null) globalQueue.initTransition((txn = createTransition()));
+      fam.ft = txn;
+      self._transition = txn;
+      let reporters = txn._asyncReporters.get(self);
+      if (reporters === undefined) txn._asyncReporters.set(self, (reporters = new Set()));
+      reporters.add(self);
+    };
     let nodeOptions;
     if (options?.seedLoadingValue) nodeOptions = { loadingValue: undefined };
     if (options?.name) nodeOptions = { ...nodeOptions, name: options.name };
     const node = computed(() => {
-      runAuthoritative(() =>
-        runProjectionComputedNext(
-          store,
-          fn,
-          options?.key === undefined ? "id" : options.key,
-          wrapCommit,
-          aroundDraftWrite
-        )
-      );
+      const self = getOwner();
+      try {
+        runAuthoritative(() =>
+          runProjectionComputedNext(
+            store,
+            fn,
+            options?.key === undefined ? "id" : options.key,
+            wrapCommit,
+            aroundDraftWrite
+          )
+        );
+      } finally {
+        declareFlight(self);
+      }
     }, nodeOptions);
     node._config &= ~CONFIG_AUTO_DISPOSE;
     fam.node = node;
@@ -11071,13 +11469,18 @@ function stagedApply(cur, incoming, keyFn) {
  * for exactly the changed keys. Visible-view diffing keeps no-op writes from
  * entangling lanes (RUL-10 / opt R38). */
 function notifyOptimisticWrites(t, pb) {
-  // A bare write while the store's own truth is in flight rides THAT
-  // transaction (#2951, legacy parity): entangle the firewall's transition so
-  // the override survives until the refetch settles instead of flash-reverting
+  // A bare write while the store's own truth is in flight rides the FLIGHT'S
+  // OWN transaction (#2951 via the #3146 declaration): entangle it so the
+  // override survives until the refetch settles instead of flash-reverting
   // at plain flush end. The blocked-check store-half keeps that transaction
-  // from settling while the firewall is pending.
-  const fw = t.fam?.node;
-  if (fw?._transition) globalQueue.initTransition(fw._transition);
+  // from settling while the firewall is pending. Declared ownership replaces
+  // the old circumstantial route through the firewall's `_transition` stamp,
+  // which was whatever last brushed the node.
+  const declared = t.fam?.ft;
+  if (declared != null) {
+    const ft = liveTransition(declared);
+    if (ft !== null) globalQueue.initTransition(ft);
+  }
   const old = t.v;
   // Patch channel (override-application site): the draft IS the intended
   // visible state; prev is the view before these overrides apply. Bypasses