RFC(events): selective clean via a resolution-dirt ledger

[adhami3310]

RFC / draft for discussion — the second of two competing shapes for hardening the delta-flush path after #6920. Not intended to merge as-is.

#6920 gates the one caller that flushed a shared root without the token lock. An atomic snapshot-and-clean in chain_updates — protection at the primitive — was attempted there and reverted, because _clean() faced two indistinguishable producers of post-snapshot dirt: a concurrent writer's update (must survive) and resolution's own side effects via the SharedState patch machinery (must be captured for fan-out, then discarded). One dirty set cannot serve both.

This RFC separates the ledgers:

• _record_dirty_var becomes the single choke point for "a var became dirty" (__setattr__, computed-var marking, MutableProxy).
• During _resolve_delta, a task-local contextvar routes the resolving task tree's marks into a ledger. Contextvars are inherited by tasks created during resolution but not by concurrent events' tasks, so task-locality is what distinguishes the writers.
• chain_updates cleans selectively: dirty snapshot ∪ resolution ledger. The clean still runs after resolution; SharedState's fan-out capture is computed from those same sets (including backend vars like _who, which never reach a delta but must fan out); a foreign write mid-resolution is in neither set and survives.

The proof obligations from the #6920 revert are both met: the atomicity regression test is un-reverted and passes, and tests/integration/test_linked_state.py — the test that forced the revert — passes on every leg I can run locally. Suite baseline unchanged; 3.10 and 3.14 green.

Known costs and open questions: after three CodSpeed rounds (-4.8% naive, -4.35% with a depth-counter gate, -3.99% with a hot/cold mark split), the machinery now engages only for flushes whose delta contains coroutines — a coroutine-free resolution never yields the loop, so the selective clean protects nothing there and those flushes take the pipeline's original path (for a hypothetical unlocked caller, a sync-delta flush's emit await reverts to full-clean semantics, identical to the shipped pipeline); a name-only boundary the review surfaced: a concurrent rewrite of a var already in a flush's snapshot, landing mid-resolution, is still cleaned with it (unreachable while every flush holds the lock, which all current callers do; closing it for hypothetical unlocked callers needs per-var write versions); the other three flush sites (app.modify_state, StateProxy.__aexit__, hydrate) still full-clean under their locks, which is safe but could adopt the same shape via a shared DeltaFlush helper; and _snapshot_dirty_vars walks the dirty chain once more per flush.

Competing RFC: #6921 — instead of making the flush safe, it makes lock ownership a required capability (LockedRoot), so an unlocked flush is a TypeError rather than a race. The two compose: #6921 is the guard rail, this is the reason the rail could eventually come down.

[greptile-apps]

Greptile Summary

This RFC introduces task-local resolution-dirt tracking so asynchronous delta flushes selectively clean the names they snapshotted or dirtied during resolution.

• Routes state mutations through _record_dirty_var and records resolution-created dirt in a context-local ledger.
• Adds selective snapshot and cleaning behavior, including SharedState fan-out handling.
• Adds regression coverage for writes made during delta resolution and partially attached state trees.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the scope of this follow-up review.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py	Splits synchronous and asynchronous delta resolution, using snapshot-and-selective-clean behavior for coroutine-bearing deltas.
reflex/state.py	Centralizes dirty-var recording and adds the resolution ledger, dirty snapshot, and selective-clean primitives.
reflex/istate/shared.py	Extends selective cleaning to preserve SharedState fan-out capture semantics.
reflex/istate/proxy.py	Routes mutable-proxy mutations through the centralized dirty-var recorder.
tests/units/reflex_base/event/processor/test_base_state_processor.py	Covers preservation and later publication of a different variable written during asynchronous delta resolution.
tests/units/test_state.py	Covers delta traversal when a dirty substate name has no attached instance.

_{Reviews (8): Last reviewed commit: "RFC(events): selective clean only for fl..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 27 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing khaleel/rfc-resolution-ledger (41200db) with khaleel/background-unlocked-trailing-clean (3d4975b)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩