until() inside an action deadlocks when the confirming frame was staged before until() was called (regression from #3451)

[brenelz]

Describe the bug

yield until(predicate) inside an action() never resolves when the predicate reads the same createOptimisticStore a live stream feeds and the confirming frame landed before until() was called. With a timeout it rejects with TimeoutError; without one the action hangs forever.

This is the single-primitive shape the until() docstring recommends (optimistic row + socket echo), and it works when the frame lands after until() subscribed. The ordering that breaks is the natural one for a server that broadcasts to subscribers before it answers the mutation.

Regression. Bisected to d80cd1f "fix(signals): nodes created mainline during a hold are born held (A29 creation-time form) (#3451)". Its parent 61a114c passes, published @solidjs/signals@2.0.0-rc.8 passes, current next (37ea885) fails.

Mechanism. The action's transaction holds the staged frame under its optimism. until() creates its predicate effect from mainline code (after the await), so with #3451 that effect is born held: its synchronous first run is skipped and it is added to the transaction's _gatedSubs to be replayed at commit. But the commit is the action's settle, which is exactly what the until() promise is holding open. Deadlock.

CONFIG_DIRECT_COMMIT exists for this case (its comment: "a staged value with an immediate apply ... deadlocks the hold (until)"), but recompute's direct-commit branch is gated on bornHeld === null, so the born-held path pre-empts it.

Your Example Website or App

Vitest test against packages/signals (below). No app or extra dependencies needed. I hit it in a real app: a seat-reservation demo where a live() server function streams the seat map into an optimistic store and a reserve action does await reserveSeat(); yield until(() => data.reservations.some(r => r.id === saved.id)).

Steps to Reproduce the Bug or Issue

1. Check out next.
2. Save the test below as packages/signals/tests/until-held-frame-before-call.test.ts.
3. cd packages/signals && pnpm vitest run tests/until-held-frame-before-call.test.ts
4. It fails with expected TimeoutError ... to not be an instance of TimeoutError. Push the confirming frame after answer(...) instead and it passes.

import { expect, test } from "vitest";
import { action, createOptimisticStore, createRenderEffect, createRoot, flush, TimeoutError, until } from "../src/index.js";

type Row = { id: string; status: "pending" | "confirmed" };
type Snapshot = { rows: Row[] };

const settle = async (n = 3) => {
  for (let i = 0; i < n; i++) {
    await new Promise(r => setTimeout(r, 0));
    flush();
  }
};

// A manually pumped AsyncIterable — what a live() server-function stream
// materializes as on the client.
function stream<T>() {
  const buffered: IteratorResult<T>[] = [];
  let waiter: ((r: IteratorResult<T>) => void) | null = null;
  const iterable: AsyncIterable<T> = {
    [Symbol.asyncIterator]: () => ({
      next: () =>
        new Promise<IteratorResult<T>>(res => {
          if (buffered.length) res(buffered.shift()!);
          else waiter = res;
        }),
      return: () => Promise.resolve({ done: true as const, value: undefined })
    })
  };
  return {
    iterable,
    push(value: T) {
      const r = { done: false as const, value };
      if (waiter) {
        const w = waiter;
        waiter = null;
        w(r);
      } else buffered.push(r);
    }
  };
}

test("until() sees a confirming frame that landed on the held store before until() was called", async () => {
  const feed = stream<Snapshot>();
  let answer!: (row: Row) => void;
  const mutation = new Promise<Row>(res => (answer = res));
  const views: string[] = [];
  let reserve!: () => Promise<unknown>;

  createRoot(() => {
    const [store, setStore] = createOptimisticStore<Snapshot>(() => feed.iterable, { rows: [] }, { key: "id" });
    reserve = action(async function* () {
      setStore(d => {
        d.rows.push({ id: "temp", status: "pending" });
      });
      const saved = await mutation;
      yield until(() => store.rows.some(r => r.id === saved.id), { timeout: 200 });
    });
    createRenderEffect(
      () => store.rows.map(r => `${r.id}:${r.status}`).join(",") || "empty",
      v => {
        views.push(v);
      }
    );
  });

  feed.push({ rows: [] });
  await settle();
  expect(views.at(-1)).toBe("empty");

  const done = reserve().then(
    () => "settled",
    e => e
  );
  await settle();
  expect(views.at(-1)).toBe("temp:pending");

  // Server mutates and broadcasts first — the frame lands while the action
  // is still awaiting the mutation's answer, and is held under its optimism.
  feed.push({ rows: [{ id: "res_1", status: "confirmed" }] });
  await settle();
  expect(views.at(-1)).toBe("temp:pending");

  // Then it answers, and the action reaches its until().
  answer({ id: "res_1", status: "confirmed" });
  await settle();

  const outcome = await done;
  expect(outcome).not.toBeInstanceOf(TimeoutError);
  expect(outcome).toBe("settled");
  await settle();
  expect(views.at(-1)).toBe("res_1:confirmed");
});

Expected behavior

The held frame is the confirmation the predicate names, so until() should flip and the action should settle, revealing the frame with the overlay revert (the same outcome as when the frame lands after until() subscribed).

Screenshots or Videos

No response

Platform

• OS: macOS
• Node: 25.1.0
• @solidjs/signals: next @ 37ea885 (fails), 3fc2c54 (fails), d80cd1f (first bad), 61a114c (passes), 2.0.0-rc.8 published (passes)

Additional context

Proposed fix (one early return in enterStagedRead, mainline branch, after the _verdictPull check). A direct-commit reader is the documented tunnel through a hold and applies on its own microtask, so it should be neither entered nor born held, the same exemption verdict pulls and optimistic nodes already get:

     if (GlobalQueue._verdictPull) return;
+    // A promise-delivery effect (resolve()/until(), CONFIG_DIRECT_COMMIT)
+    // reads staged truth by contract — it is the tunnel that keeps a hold
+    // deadlock-free — and applies on its own microtask, so it is neither
+    // entered nor born held. Born held, an until() created mainline after
+    // the confirming frame was staged would replay only at the commit its
+    // own promise is holding open (#3451 follow-up).
+    if (ctx._config & CONFIG_DIRECT_COMMIT) return;
     if (
       ctx._flags & REACTIVE_RECOMPUTING_DEPS &&

With that change the test above passes, and so do until, until-entanglement, born-held, resolve, refresh-await, superseded-before-first-commit, visibility-oracle and the rest of the signals suite (including dist-artifacts after a rebuild). Happy to open a PR with the test and the fix.

Workaround in the meantime: settle the action with await mutation; yield refresh(store) instead of until(); the refreshed answer stages into the held transaction and reveals atomically with the overlay revert.

[ryansolid]

Confirmed against current next (c54e4c0ca, after tonight's #3479/#3488 landed in recompute's tail — neither touched this) and taken as #3490, with your test as the pin and you credited on the commit.

The fix is your proposed one: enterStagedRead's mainline arm exempts CONFIG_DIRECT_COMMIT readers alongside the verdict-pull exemption, so stagedEntry is never set for them and they fall into the direct-commit arm recompute already had for exactly this case. Your reading of the mechanism was exact — the born-held path pre-empting the tunnel on the bornHeld === null gate. Also added the control ordering (until() subscribed before the frame) to the same file so both are pinned together.

One note for your seat-reservation demo: this also covers resolve() and awaitable refresh()'s waiter, which share the flag and had the same latent hazard.

— Claude via Cursor

[ryansolid]

Thanks for the precise bisect and the reproduction — it made this quick to settle, and it turned up a documentation bug on our side.

The runtime is behaving as specified; the test is missing a bare yield after the await. Verified on next with your test unchanged except for that line:

as filed (await mutation; → yield until(...)): TimeoutError
with yield; inserted after the await: settled, view res_1:confirmed

const saved = await mutation;
yield; // re-enter the transaction after the await
yield until(() => store.rows.some(r => r.id === saved.id), { timeout: 200 });

Why. The runtime has no hook into an async generator's internal await continuations — that's why yield is the step primitive. Code between an await and the next yield runs outside the transaction. The action docstring says to put a bare yield before any writes that follow an await; the rule is broader than that, and that's on us: anything that creates a reader there — until(), latest(), a memo or effect, a mount — is created mainline. Your until(...) is evaluated as the argument expression before the yield happens, so its predicate effect is created outside the transaction, reads the action's held frame, and is born held (A29, #3451): replayed at the commit its own promise is holding open. Exactly the deadlock you traced.

Why not the proposed runtime fix. Exempting CONFIG_DIRECT_COMMIT readers from born-held in the mainline branch would make a correctly written mainline until() over a held frame evaluate against staged truth immediately rather than at the commit — a semantic change for correct code to accommodate the incorrect shape. Declined.

What we're fixing. The until() docstring's own example showed await socket.send(...) straight into yield until(...) — you followed our documentation. #3491 corrects both docstrings (action: "writes or reader creation, including the expression of the next yield"; until: the bare yield in the example plus a paragraph on why).

Closing as documented behavior once #3491 lands; please reopen if the corrected shape still hangs for you in the seat-reservation app.

— Claude via Cursor

[ryansolid]

Correction to my comment above: on a second look this is usage, not a runtime bug — though the docs led you there, so the fix is to the docs. #3490 is closed unmerged; #3491 is the resolution.

yield until(...) evaluates until(...) in the await continuation — before the yield re-enters the action's transaction. Per the action() docstring, code between an await and the next yield runs outside the transaction (the runtime cannot hook an async generator's internal await continuations), so the predicate effect is created mainline and, reading the held frame, is born held (A29): replayed at the commit its own promise holds open. A bare yield re-enters first:

const saved = await mutation;
yield; // re-enter the transaction
yield until(() => store.rows.some(r => r.id === saved.id), { timeout: 200 });

With that line your test settles with the view at res_1:confirmed, both frame orderings. Inside the transaction the existing DIRECT_COMMIT arm delivers the predicate's result on its microtask under the action's own hold — the case it was built for.

The until() docstring's own example showed the broken shape (await socket.send(...); yield until(...)), and the action() docstring only called out writes after an await, not reader creation. #3491 fixes both. The proposed enterStagedRead exemption was declined because CONFIG_DIRECT_COMMIT also covers resolve() and awaitable refresh(), which are routinely called outside actions — from mainline against an unrelated action's hold they would have resolved with that action's uncommitted frame.

Thanks for the precise bisect and mechanism write-up; it made the doc gap unambiguous.

— Claude via Cursor

[ryansolid]

Resolved: #3491 (docs — action() now states that code between an await and the next yield creates readers mainline too, including the expression of yield until(...); the until() example gained the bare yield) and #3492 (pins for until()/resolve() by posture over a held frame, including the as-filed ordering and the foreign-hold case). Both merged to next. No runtime change — the fix in your code is the bare yield; after the await.

— Claude via Cursor

[brenelz]

Ah that makes sense. I guess its tricky for LLMs to learn this