perf: cut state hot-path overhead — deep-validation skip, proxy caching, dirty-propagation frontier

[Alek99]

Consolidates the state hot-path perf work from #6738 (ENG-10093), #6740 (ENG-10094), and the original scope of this PR (ENG-10095) into one review unit. All three edit the same few functions — BaseState.__setattr__, _get_attribute, _mark_dirty*, ComputedVar.__get__ — so reviewing the final shape of those functions once beats reviewing three interleaved rewrites. Commits are preserved per original PR for per-commit review. Stacked on #6735; #6744 continues on top of this branch.

Motivation: profiling the event loop on current main, a trivial event (counter += 1 from a button click) spends ~30% of framework CPU in _get_attribute (129 attribute reads, 121 isinstance calls per event) and ~25% in dirty-tracking/delta bookkeeping. This PR targets both buckets.

1. Skip deep type-validation on state var hot paths (from #6738)

__setattr__ and ComputedVar.__get__ ran _isinstance(value, field_type, nested=1) — walking every element of assigned/returned containers — only to gate a console.error diagnostic. Computed-var return types are now validated only on actual recompute (cache hits skip entirely), and element-wise validation depth becomes 1 in dev / 0 in prod via a cached _validation_depth() helper.

• read cached computed var returning 10k dicts: 13.8 ms → 0.0015 ms
• assign 100k-int list (prod): 90.9 ms → 0.02 ms
• cProfile of the same scenario: 10.5M calls / 3.06 s → 538 calls / 0.003 s

2. Cut MutableProxy per-element overhead; cache per-field proxies (from #6740)

The recursive wrap path walked 5 stack frames (dataclasses-internal check) for every element read through a proxy; immutable elements now skip wrapping and the frame walk entirely. _get_attribute built a fresh MutableProxy on every read of a mutable var; proxies are now cached per instance+field, invalidated by identity on reassignment, and excluded from pickling.

• iterate a 1000-int list via proxy: 0.98 ms → 0.22 ms (~4.5x)
• index 1000 elements: ~3.0x
• read a mutable var attribute: 2.8 us → 1.2 us (~2.4x)
• proxy micro-suite: 168k → 72k function calls

3. Only propagate newly-dirty vars in _mark_dirty_computed_vars (original scope)

Every setattr/proxied mutation re-scanned all computed vars for interval expiry and re-walked the dependency closure of the entire accumulated dirty_vars set. This adds per-class precomputed _interval_computed_vars (the expiry scan is skipped when none exist) and a per-instance propagated frontier so only newly-dirty vars are walked; a process-wide generation counter bumped on recompute resets the frontier to preserve mid-cycle invalidation correctness.

• proxied list append (state with 2 cached computed vars): 16.7 us → 8.6 us (~1.9x)
• int var setattr: 21.0 us → 9.3 us (~2.2x)
• _mark_dirty_computed_vars cumulative over 2000 appends: 0.102 s → 0.019 s

Review feedback from the folded threads, already incorporated

• Internal tracking state is declared as reserved state fields rather than raw __dict__ entries, per masenf's request on both Reduce MutableProxy per-element overhead and cache per-field proxies #6740 and perf: cut state hot-path overhead — deep-validation skip, proxy caching, dirty-propagation frontier #6743: _mutable_proxy_cache and the propagation-frontier fields are declared fields (excluded from pickles, safe against user-var name collisions).
• The per-field proxy cache entry is dropped/updated when a mutable var is reassigned, so a replaced value cannot be kept alive through a stale proxy (flagged and confirmed fixed on Reduce MutableProxy per-element overhead and cache per-field proxies #6740).
• Answering the open question on Skip deep type-validation on state var hot paths #6738 ("if we return early, how does the computed value get cached?"): the value is cached by the setattr(instance, self._cache_attr, ...) on the line immediately before that return — the early return only skips re-reading and re-validating the value that was just computed and stored.

Benchmark numbers are from the original PRs, measured on GitHub Actions runners over two passes.

[linear-code]

ENG-10095

[greptile-apps]

Greptile Summary

This PR improves state hot-path performance across validation, proxying, and dirty propagation. The main changes are:

• Shallow validation for state assignments and computed-var recomputes in production mode.
• Per-field caching for mutable state proxies with reassignment eviction.
• Dirty-propagation tracking that only walks newly dirty variables.
• Precomputed interval computed-var lists to skip unnecessary expiry scans.
• Tests for proxy caching, recompute behavior, and validation depth.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
reflex/state.py	Adds mutable proxy caching, cache eviction on reassignment, transient dirty-propagation state, interval computed-var precomputation, and serialization cleanup.
reflex/istate/proxy.py	Updates nested wrapping so existing proxies are unwrapped before the dataclasses-internal bypass is checked.
packages/reflex-base/src/reflex_base/vars/base.py	Adds computed-var recompute generation tracking and validates cached computed-var return types only when recomputed.
packages/reflex-base/src/reflex_base/utils/types.py	Adds reserved internal state field names and environment-based validation depth selection.
tests/units/istate/test_proxy.py	Adds tests for mutable proxy reuse, reassignment eviction, pickle behavior, and immutable element handling.
tests/units/test_state.py	Adds tests for assignment validation, computed-var recompute correctness, cross-state recompute behavior, and interval computed-var tracking.

_{Reviews (9): Last reviewed commit: "Address cubic review: strip env mode whi..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will improve performance by 5.02%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	Simulation	test_process_event	7.6 ms	7.2 ms	+5.02%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing claude/reflex-perf-optimizations-01l7a3-eng-10095 (f9e4010) with claude/reflex-compiler-perf-t8ztc9-11-memoize-dedup (460c941)}

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. ↩

[masenf]

if we already have the instance_dict, why not just shove the value in there?

[masenf]

why are we treating these new fields like this and not defining them as normal fields in a BaseState, like all the other fields

[greptile-apps]

Evict proxy assignments
This cache is invalidated from BaseState.__setattr__, but mutable state can also be reassigned through StateProxy in an async with self context. That path writes to the wrapped state without running this eviction, so a proxy cached before the context can keep wrapping the old list or dict after self.items = [...]. A later read can reuse that stale proxy and mutations can update the replaced object instead of the current state value. The assignment path used by StateProxy needs to clear the wrapped state's _mutable_proxy_cache for the reassigned field too.

[cubic-dev-ai]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>