fix(signals): writes become visible at flush — latest() reads the flushed staged world (A28)

[ryansolid]

Summary

A write is unflushed between set() and the next flush(): not the committed value, not the staged value latest()/isPending() serve, and not an input to any recompute. latest(count) after setCount(30) answers the pre-write value until the flush that carries the write; after it, latest(count) is 30 and latest(doubled) is 60 in the same instant.

This gives latest one rule regardless of reader — event handler, memo, prop getter. Wrapping a latest read in a memo answers the same as the bare read, so the visibility mismatch GabbeV raised (which motivated a separate readStaged) does not arise: there is no "read your own write" channel that bypasses the flush, because no channel can show downstream of an unflushed write, and a channel that shows the write alone tears against every derivation.

Ruled 2026-09-08: "since we can't derive downstream before flush happens I do like latest being invisible until flush… nothing should be 30 pre flush because double count can't be 60… latest opts into the tearing but really only after a flush." Recorded as A28 in SPEC-ASYNC-SEMANTICS.md.

Mechanics

Every write takes one path: stage _pendingValue, mark CONFIG_UNFLUSHED (stashing the last-flushed staged value in _x._flushedStaged when rewriting a node a transition already holds), schedule. Consumers promote:

• flush() promotes at the start of each round and before every clock++ (fast path, stash path, completion path, and inside finalizePureQueue before the heap runs) so writes issued by commit hooks and boundary sweeps land in the same round — otherwise the error-boundary retry loop (owner._time < clock) never converges.
• recompute promotes at its tail for the writes it issued.

Promotion clears the mark, restores the flushed view, syncs companions (isPending/latest shadows), and walks subscribers. Reads of an unflushed node (read, readNodeFast, flushedStaged() in verdict) serve the flushed view.

Removed, because the single path makes them redundant:

• the eager-vs-deferred write heuristic (globalQueue._running || context._fn) — tried two variants, both left gaps (store projections, error-boundary lazy builds);
• the 2.0.0-beta.20: latest() only works once on memos #2922 mid-tick shadow pull in latestRead (2.0.0-beta.20: latest() only works once on memos #2922 is re-pinned under the new semantics: latest(memo) recomputes at each flush, not each write);
• the _notifiedAt / notifyEpoch / reaskArmed duplicate-walk dedupe (§12d) — the unflushed mark is the dedupe.

Behavior changes pinned in tests

• latest(x) / isPending(x) pre-flush for an unflushed write: pre-write value / false (latest-held-till-flush.test.ts — 12 cases incl. held transitions, memo transparency, lazily created companions).
• createTrackedEffect "documented gap" (a same-pass write to a not-yet-read signal wasn't seen) is closed: the effect now re-runs next round.
• Async memo landings and store landings go through the same mark + promotion (were asymmetric: asyncWrite synced companions eagerly).

#3336 — lazily created companions and store keys carry the hold (second commit)

A latest() shadow or isPending companion created for a node whose write a live transaction already holds was backfilled through the ambient batch, so the backfill reverted at round end and the companion showed the committed value while its node was pending. backfillCompanion runs the backfill as the holding transaction's batch, where a companion that had existed at write time would have been placed.

Stores, same rule through every channel: a key first read under a hold is born holding (stageHeldKey — committed value, the transaction's write staged), and the backing-level visibility decision carries core read()'s committed clause (heldFromReader / foreignHold): while a live foreign transaction holds the pending backing, a stale (render) reader and an owner-less reader see committed through untracked reads, in, Object.keys, deep()/snapshot() and the adoption-hold view — as the tracked read already did through the node. A stale reader the holding transaction itself recomputes sees the staged world (core: activeTransition !== el._transition), so it composes its view — and its deep() subscriptions — from one world. Non-stale owner-context readers keep speculation; a pending backing with no transaction keeps the same-tick snapshot peek.

Pinned in latest-held-till-flush.test.ts (21 cases); SPEC A28 consequence (3), INTERNALS-ASYNC §4, INTERNALS-STORE invariants.

CodSpeed regression — fixed, with a residual (244efce3)

CodSpeed flagged 13 benchmarks (up to −13.9%). Root cause was implementation, not the design: recompute called unflushedCursor() + promoteUnflushed(from) through the scheduler module on every run, and promoteUnflushed truncated an empty list each time (length = is a runtime call, not inlined). Under the test transform's live-binding getters that is two cross-module calls per recompute. Fix: the list lives in core.ts so recompute compares lengths locally and calls promote only when the run wrote something; promote returns before truncating an empty list; plain nodes skip the override probe.

Measured (dev tier, update1to1): base 0.65 ms → head 0.87 → fixed 0.71. propagation:diamond and update1to1000 back to parity; dbmon/deep-reconcile within noise. Residual: update1to1 stays ~5–10% slower, and that part is the design — A28 adds one phase (write → mark+push → flush walks the list → seeds the heap), i.e. one extra pass over written nodes per flush. On the one-write-one-memo bench that constant reads as a percentage; anywhere the flush does real work it amortizes out. It is the price of "writes visible at flush", stated here as a trade rather than a regression.

Optimistic writes are writes — A28(5) (50225d04, 05bcc711)

Ruled 2026-09-10: "My gut is to match. I'm gathering React does." — React's useOptimistic shows the optimistic value on the next render, never synchronously. setOptimistic(x) / an optimistic store setter now parks the value (_x._pendingOverride) and marks the node unflushed; the flush's promotion installs it as the active override (promoteOverride). Until then plain reads, snapshot() and isPending() answer the flushed value. An ambient write (no action in flight) is shown by its flush to effects ([1, 2, 1]) and reverted at its end; one an action holds stays readable after the flush.

Writer channels still compose on the tick's own writes: the functional updater reads the parked value, and store drafts read through draftOverride (parked write ahead of the flushed override) at seeding, in-draft reads, the draft length view and notifyOptimisticWrites' diff base — so two count++ are +2, a push after a push lands in the next slot, and a toggle toggled back emits the cancelling write (without this the second toggle diffed against the flushed view and emitted nothing, leaving the first parked — a real bug, not a re-expectation). Engine companions (_parentSource set) are the system's own overrides written inside the flush and install eagerly.

The writer channels compose on the tick's own parked writes: the functional updater, a store setter's draft (two count++ are +2; a push after a push lands in the next slot; a toggle toggled back cancels), and the affects() declaration walk — tagging a parent covers the whole record as the writer sees it, the row this tick pushed included (05bcc711; 50225d04 had left the walk on the reader view, which made a same-tick affects(state) miss the pushed row while the same shape on a plain store covered it). Only the slot form on a row born this tick names the draft (affects(s.rows[i], key) inside the setter) — state.rows[i] is not readable before the flush. Pinned in question-scoped-pending.test.ts; MIGRATION note added; mined rules R2/R1/R34 marked superseded.

31 tests re-expected across 6 files (pre-flush reads of the optimistic value; the 3.6 slot-form declaration moved onto the draft).

Size

Core floor 22,866 B on next @ b5bd6fb (next itself is 22,457 after #3370; budget 22,900 B; +409 B over next). A28: +316 B, the write path itself, part paid by the §12d removal. Hot-path fix: +27 B. A28(5): +52 B — the _pendingOverride slot initializer, the promote arm, the hook slot; the install rides the optimistic module. The remaining ~14 B is how the lane-authority dispatch minifies in promoteUnflushed's override arm versus inline in asyncWrite. Brotli caps ratcheted per scenario with notes; this branch's own cost over next (= over #3370) per scenario: core floor +155 B, createStore +383 (A28 + #3336's store half), isPending/latest +270 (the optimistic module), simple app +140, hydrating +176 / +427 with every store family, CSR +141, observe +216, attribution +146.

Verification

Rebased on next @ b5bd6fb (2026-09-11, after #3370 merged). Source after the rebase is identical to fix/lane-authority @ fae8b76 (the lane fixes as originally developed on top of this branch) apart from the order of two adjacent function declarations — git diff fae8b766 HEAD -- packages/signals/src is a pure move — and the floor measures the same 22,866 B fae8b76 did. Head 20f31433. signals 1767 passed / 1 skipped · solid 595 · web 734 · tsc -p tsconfig.build.json clean · full pnpm build · size-limit green.

next's heap-mark-incremental mid-tick-pull test remains re-expected under A28 ([n=0 ×3, n=26 ×3]: each row's first run answers the flushed value, the promotion lands the last write within the same flush). This is the one observable place the deferred mechanism differs from an eager one (an eager walk gives [22, 24, 26, 26, 26] — each effect sees the write before it within one flush); the A28 reading is that a run does not derive from its own unflushed write. Worth pinning as an explicit A28 consequence in the spec rather than inheriting it from the mechanism.

Not in this PR

#3330, #3331, #3333, #3334, #3335 all reproduce identically on next and on this branch — they are lane/optimistic-layer bugs about which record is authoritative (hold-is-per-async-node, compare-against-published-view, arrival-supersedes-override), not write-path bugs. They were #3347 (stacked on this branch), now re-based directly onto next as #3370 so they ship in this rc while this PR is considered longer.

Rebase onto #3370 — done (2026-09-11)

#3370 merged as next @ b5bd6fb; this branch was rebased onto it. The conflicts resolved as predicted: asyncWrite's pending-node branch keeps the A28 deferral (markUnflushed + schedule()) and promoteUnflushed's override arm dispatches _supersedeOverride (the A18 supersession decision lands at promotion, still under the flight's provenance); recompute's override branches take #3370's; optimistic.ts imports both attrHooks and markUnflushed; getNode's born-holding block re-composes #3370's held-adoption case with #3336's held-fold case through one stageHeldKey(node, nv, txn); spec, treeshake note and size caps re-measured on the merged base.

Alternative mechanism considered and rejected

A spike (spike/a28-eager-walk, local) tried keeping next's eager subscriber walk and getting A28's read-side semantics by marking late linkers at read plus a _writeClock stamp for the repeat-write skip. Clean negative: Tier-1 propagation benches −20% (the per-write repeat-path check is four to five loads where the deferred list's is one bit test), core floor +616 B over this branch, and the unflushed list survives anyway for overrides and companions. The deferred list is the cheaper A28 implementation; this PR's mechanism is unchanged.

Co-authored-by: Claude via Cursor

[changeset-bot]

🦋 Changeset detected

Latest commit: 20f3143

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@solidjs/signals	Patch
test-integration	Patch
@solidjs/web	Patch
@solidjs/babel-plugin	Patch
@solidjs/compiler	Patch
@solidjs/diagnostics	Patch
@solidjs/element	Patch
@solidjs/h	Patch
@solidjs/html	Patch
solid-js	Patch
@solidjs/universal	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[GabbeV]

AI review based on the context where i discovered the issues:

The pre-flush change addresses the immediate-write visibility mismatch described in this PR. Testing 0f4d5f7b leaves a question about the boundary between “flushed staged world” and A28’s phrase “no held lane withholds.”

Consider this graph, with everything created inside a root:

const [input, setInput] = createSignal(0);
const value = () => latest(input);
const identity = createMemo(value);

const requests = [];
const details = createMemo(() => {
  const n = identity();
  return new Promise(resolve => {
    requests.push(() => resolve(n));
  });
});

let shownValue;
let shownDetails;

createRenderEffect(identity, n => {
  shownValue = n;
});
createRenderEffect(details, n => {
  shownDetails = n;
});

const update = action(function* () {
  setInput(1);
  yield new Promise(() => {}); // Keep the parent action open.
});

After resolving the initial request and letting everything settle:

update();

// Before flush:
value();       // 0
identity();    // 0
shownValue;    // 0
shownDetails;  // 0

flush();

// The request for details(1) has started but remains unresolved:
value();       // 1
identity();    // 1
shownValue;    // 0
shownDetails;  // 0

// Resolve details(1), then let the runtime settle:
// All four become 1, while the parent action remains open.

The getter and synchronous memo agree, so this does not contradict the synchronous memo-transparency case demonstrated by the PR. However, outside reads advance before the lane’s effects publish.

Is that intentional under “flushed staged world,” or should the observed downstream async also hold these reads? The PR’s acknowledgement of post-flush tearing suggests this is intentional, whereas “no held lane withholds” sounds like it promises publication atomicity for the lane.

There’s a separate scope question around “every write.” Replacing the latest-based input with an explicit optimistic override:

const [value, setValue] = createOptimistic(input);
// Same identity memo and observed async details.

const update = action(function* () {
  setInput(1);
  setValue(1);
  yield new Promise(() => {});
});

update();

// Before flush:
value();     // 1
identity();  // 0
shownValue;  // 0

That remains observable on this PR. Is optimistic-write timing deliberately excluded from A28 for now?

The history-dependent Show repro in #3336 also still reproduces on this head. Since #3347 explicitly identifies that as follow-up work, that looks like an acknowledged omission rather than a new finding.

[coveralls]

Coverage Report for CI Build 34587680444

Warning

No base build found for commit b5bd6fb on next.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 71.842%

Details

• Patch coverage: No coverable lines changed in this PR.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

Requires a base build to compare against. How to fix this →

---

Coverage Stats

Relevant Lines:	1007
Covered Lines:	772
Line Coverage:	76.66%
Relevant Branches:	790
Covered Branches:	519
Branch Coverage:	65.7%
Branches in Coverage %:	Yes
Coverage Strength:	15.01 hits per line

---

💛 - Coveralls

[codspeed-hq]

Merging this PR will regress 3 benchmarks

⚡ 3 improved benchmarks
❌ 3 regressed benchmarks
✅ 154 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	input burst: 200 single-key writes, 1 subscriber	4.6 ms	5 ms	-7.63%
❌	selection map: toggle 2 of 1000 subscribed keys	4.4 ms	4.7 ms	-6.96%
❌	updateSignals:update1to1	62 ms	65.8 ms	-5.68%
⚡	projection derive: write one NESTED field (reference)	807.9 µs	211.7 µs	×3.8
⚡	propagation:avoidable	1.7 ms	1.6 ms	+6.05%
⚡	propagation:diamond	1.7 ms	1.6 ms	+5.99%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing latest-held-till-flush (20f3143) with next (b5bd6fb)}

[ryansolid]

Thanks — three good questions, taking them in order.

1. Post-flush reads advance before the lane's effects publish — intentional. A28 draws exactly one line: the flush. Before it, nothing shows the write (no channel can show downstream of an unflushed write). After it, latest() reads the flushed staged value whether or not a transaction still holds that value from the committed view. The hold governs what effects publish (the frame stays coherent: shownValue/shownDetails move together when details(1) lands); latest is the channel that opts into reading ahead of the frame, and the ruling was that it does so only once a flush has carried the write. So value() === identity() === 1 while shownValue === 0 is the shape A28 describes, not a leak.

You're right that "no held lane withholds" reads like a publication-atomicity promise for the lane — it was meant to say the opposite (a hold doesn't withhold from latest). Reworded in 2e7b986: "the newest value a flush has processed, held or not (a transaction's hold governs what effects publish, not what latest answers; latest opts into that tearing, but only once a flush has carried the write)".

2. Optimistic-write timing — excluded from A28 today, and that is an honest gap rather than a ruling. A28 took the staged write path: stage + mark unflushed + schedule, promoted at flush. setValue(1) on a createOptimistic is not a staging — it installs the override directly onto the node (A17), which is why value() answers 1 before the flush while identity() is still 0. That is the same tear A28 exists to rule out for plain writes, so the question of whether overrides should be held to the same flush boundary is real. I'd rather not rule it from inside this PR; flagging it for Ryan as a follow-up so it gets a deliberate verdict (and a spec line either way).

3. #3336 Show repro — fixed in the second commit on this branch (b722898: a store key first read under a hold is born with the committed value and the held write staged as the holding transaction's, so it reverts with the hold rather than at the reader's flush end). It reproduced on the head you tested because that head predated it.

— Claude via Cursor

[GabbeV]

The main issue with the latest ruling is that it might not be obvious that something is read through latest when reading a prop for example, leading to issues where the jsx made a decision using one value and then the event handler sees another value. However I also understand the desire to avoid needing a latest of latest and things like that. It would be nice if some naming pattern made it natural to have one util for the reactive side and another for the imperative side so that this hidden latest through a prop getter wasn't an issue but maybe this async derived from latest is going to be used so little that this will never matter in practice anyway.