Speed up memo-name hashing, move it into its own module, fix seven tag collisions

[masenf]

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)

New Feature Submission

• Does your submission pass the tests?
• Have you linted your code locally prior to submission?

Changes To Core Features

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you successfully ran tests with your changes locally?

Description

The deterministic hash exists for one purpose: giving an auto-memoized component a stable, non-colliding export name. Started as a profiling question about it, and grew into three related pieces.

1. The encoding is faster — measured against current main.

page	encoding	whole component_hash
memoization-heavy	1.31x	0.99x
_stateful_page	1.17x	1.03x
_complicated_page	0.1 ms either way, noise	1.00x

Min-of-11 on a live compile, caches cleared per run, main's encoder and artifact set reproduced in the same process. The columns differ because encoding is only ~13% of component_hash — the rest is render() and the _get_all_* walks, which this PR does not touch. @FarhanAliRaza independently measured 1.18–1.23x on a 201-component page, which agrees. CodSpeed reports the end-to-end effect on each push; see its comment rather than a number pasted here.

Earlier revisions of this description claimed 2.3–2.6x. That came from a corpus replayed several passes per timed run, so every pass after the first ran on warm caches and already-rendered components. It also predated #7012, which cut ImportVar encodes on my benchmark page from 1182 to 854 and removed much of the redundancy the caching exploits.

What makes it faster: the encoder writes into a bytearray flushed in 64 KiB chunks instead of one hasher.update() per node, resolves an encoder once per type instead of walking an isinstance ladder per value, caches each dataclass type's field layout with pre-encoded names, and caches the encoded form of short strings and of frozen dataclasses whose declared fields are all str/bool/None (ImportVar above all — 854 encodes across 22 distinct values on one page).

2. Moved into reflex_base/utils/deterministic_hash.py.

Nothing outside memo.py called Component._get_component_hash or Component._compute_memo_tag, and neither is a property of a component the way render() is. The hash itself is not a property of memoization either — it digests components, vars and rendered data, and auto-memoization is its only caller today — so it now lives in utils with its tests beside it. memo.py keeps component_hash, memo_tag and _component_artifacts. shallow became recursive, named for what it means there. Dead _hash_str helper dropped.

3. Seven memo-name collisions, each dropping compiled output.

The hashed artifact set has to match what compile_experimental_component_memo actually puts in the memo body, and the encoding has to be injective. Neither held:

Gap	Consequence
add_custom_code not hashed (only _get_custom_code)	Two bodies differing only in emitted module-level code shared one module; one code block dropped
_get_dynamic_imports not hashed at all	One of two dynamic import statements dropped
Class identified by __qualname__ alone	Two modules each defining class Card with identical output collided
Caches never released	A @dataclass defined in a function body is a fresh class per call; 50 stayed pinned through a gc.collect()
Dataclass branch ahead of the component branch	A component that also inherits a dataclass encoded as that mixin's field list, not as its render
Dataclasses encoded by field layout alone	Alpha(a="x") and Beta(a="x") — distinct types, identical digest
Enum members encoded as str(value)	IntEnum.ONE and 1 — identical digest, since 3.11 made IntEnum.__str__ the integer

The fifth is the broad one. Every component built on MarkdownComponentMap — rx.text, rx.heading and friends — inherits a dataclass that declares no fields, so on the old branch order _deterministic_hash(rx.text("a")) == _deterministic_hash(rx.text("bbbbb")): all of them encoded to the same nine bytes. Reachable through component_hash via app-wrap components, which the hash feeds in as components rather than as rendered dicts.

The last two predate this branch but live in code it rewrites, and the module claims injectivity, so they belong here. Both fixes are per-type and cached: the defining class goes into the dataclass layout header, and enums get their own tag plus qualified member name.

The module now reaches the digest rather than the tag prefix — format_state_name only maps dots to __, and those names become filenames, so a dotted path in the prefix would stretch every generated memo module name. The caches are released from App._compile in a finally: that's the single funnel every compile goes through, since reflex export and reflex compile reach it via get_compiled_app and never touch App.__call__.

Credit

The encoder table, the branch-order bug and the idea of generalizing the ImportVar cache to frozen dataclasses all come from @benedikt-bartscher's #6804, which landed on the same code independently. Two things are deliberately taken differently there:

• Cache keyed by value, not by id(). On a memoization-heavy page the hash sees 854 ImportVar encodes across 542 distinct ids but only 22 distinct values, so identity keying hits ~37% where value keying hits 98%. Measured per visit: ~220 ns for a value-keyed hit, ~160 ns for an id-keyed one, ~1930 ns to re-encode from scratch.
• Numbers excluded from the cacheable field types. _IMMUTABLE_FIELD_TYPES in improve compile perf #6804 includes int/float, which is sound under id keying but not under value keying — improve compile perf #6804 has its own test for exactly this (True vs 1), and reading declared annotations is what keeps that test passing here.

A narrowing that was tried and reverted

An earlier revision hashed only import library names, on the argument that a body reaches an import through the local name it binds, and every name it references is already in its render. @FarhanAliRaza showed that is wrong: a tagless ImportVar defaults to render=True and compile_imports emits it as a side-effect import (lucide-react/light.css), and Icon._get_imports builds a per-instance package_path and alias under one library key. Two such bodies rendered identically, shared a tag, and one body's import never reached the compiled module.

Reverted in 66a360f. Re-measuring on a live compile put the narrowing at ~4% of encoding, not the 23% an earlier harness of mine reported — that one charged its own projection wrapper to the full-dict side. Roughly 0.4 ms against a ~112 ms component_hash, so there was nothing to trade a dropped import for.

Note for reviewers

Generated memo module names change, for two independent reasons: item 3 deliberately folds new material into the digest, and merging main brought in #7012, which changes the import dicts the hash consumes. Nothing outside the compiled output refers to them, and no test pins them.

The main merge had two conflicts: component.py (this PR deletes the hashing block, main added PROHIBITED_LIBRARY_IMPORTS in the same region — both intents kept) and pyi_hashes.json (regenerated with make_pyi.py rather than picking a side).

Tests

In tests/units/reflex_base/utils/test_deterministic_hash.py (with the code under test), tests/units/components/test_memo.py and tests/units/test_app.py. Each collision fix has a regression test that was mutation-checked — reverting the fix fails the test.

Four tests passed for the wrong reason and were rewritten: two probe classes with different qualnames, where class identity alone separated them; two probes with different metaclasses, so the encoder-table test could not see the poisoning it was meant to catch; a parametrized case labelled "dataclasses of the same shape but different types" that compared two instances of one type; and an assertion about a Var's type tag that held only because LiteralStringVar._js_expr is the quoted form.

Also covers encoding injectivity, cache-key correctness by value, a frozen dataclass holding a value its annotation does not admit (unhashable, so it cannot key the cache), strings and dataclass encodings past the cache limits, a single leaf larger than the flush buffer (a LiteralStringVar at 3x the flush size peaks at 196,621 B against a 65,536 B threshold — a leaf is appended whole, so it is the one value the flush size cannot bound), digest equality across flush sizes from 1 byte to 1 GiB, dataclasses that can still change, runtime-synthesized dataclass subclasses (MutableProxy copies __dataclass_fields__ without __dataclass_params__), and a clean_hash_caches fixture so cache-state tests are order-independent under pytest-randomly.

Not in this PR

• component_hash is still ~45% of compile wall time on a foreach/cond-heavy page (~112 ms of ~250 ms on one page here), and encoding is only ~13% of that. The rest is per-node artifact gathering plus render() over snapshot subtrees, and reusing it needs the page walk to descend into snapshot subtrees with the collector sealed off — the _memoize_structural_child machinery Implement client state with useClientState hook #6936 is adding. Should build on that rather than race it. (Fusing the five _get_all_* traversals into one was tried and measured ~2% slower: they already share cached per-node results, so the aggregation was never the cost.)
• RadixThemesComponent._get_app_wrap_components builds a fresh provider per call — 114 values reaching the hash across 113 distinct objects on one page, ~30% of encoder time, all of it re-rendering equivalent objects. Filed as Memoize RadixThemesColorModeProvider instead of building a fresh instance per component #7013.
• For a passthrough memo, compile_experimental_component_memo pulls the whole subtree's imports into the body (utils.py:409) while the hash's own-node branch feeds only component._get_imports(). Two passthrough memos with identical roots and differing descendants therefore share a tag while their emitted import blocks differ. Confirmed at the hash level, no end-to-end repro yet; either the hash should match the compile there or utils.py:409 should narrow to the root. Belongs in its own change.
• GLOBAL_CACHE.clear() has the same ASGI-only gap as the old cache-release site, so reflex export never frees the var cache either. Pre-existing and unrelated; belongs in its own commit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F1fNEq67sbXeXDZGjLX16c

[codspeed-hq]

Merging this PR will improve performance by 4.8%

⚠️ 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

⚡ 3 improved benchmarks
✅ 29 untouched benchmarks
⏩ 8 skipped benchmarks¹

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	Simulation	test_compile_all_artifacts[_stateful_page]	26.9 ms	25.5 ms	+5.48%
⚡	Simulation	test_compile_page[_stateful_page]	30.4 ms	29 ms	+4.84%
⚡	Simulation	test_compile_page_full_context[_stateful_page]	34.4 ms	33.1 ms	+4.07%

Tip

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

---

_{Comparing claude/optimize-deterministic-hash-u1dl2j (0d12a44) with main (3013a6b)²}

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

2. No successful run was found on main (6beb371) during the generation of this report, so 3013a6b was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[greptile-apps]

Greptile Summary

The PR moves deterministic component hashing into a dedicated reflex-base utility, expands memo-name inputs to prevent collisions, and clears encoder caches after compilation.

• Adds buffered, type-dispatched deterministic encoding with bounded value caches.
• Moves memo hash and tag construction into the memo module.
• Includes additional component artifacts in generated memo identities.
• Clears hash caches from App._compile on both success and failure.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/utils/deterministic_hash.py	Introduces the buffered deterministic encoder, type dispatch, bounded caches, and explicit cache cleanup.
packages/reflex-base/src/reflex_base/components/memo.py	Centralizes component artifact hashing and memo-tag generation while covering additional compiled artifacts.
packages/reflex-base/src/reflex_base/components/component.py	Removes the former component-local hashing and memo-tag implementation.
reflex/app.py	Ensures deterministic-hash caches are cleared after every compile attempt.
tests/units/components/test_memo.py	Adds regression coverage for memo-name collision cases and artifact-sensitive hashing.
tests/units/reflex_base/utils/test_deterministic_hash.py	Adds extensive coverage for encoding injectivity, dispatch, buffering, caching, and cleanup.
tests/units/test_app.py	Covers hash-cache cleanup through application compilation paths.

_{Reviews (19): Last reviewed commit: "test: isolate the annotation-mismatch te..." | Re-trigger Greptile}

[cubic-dev-ai]

All reported issues were addressed across 2 files

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

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 5 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 7 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[FarhanAliRaza]

Clear the caches in a finally inside compiler.compile_app instead, and leave _compile as it was.

compiler.compile_app has exactly one caller, so the guarantee is identical. It also puts the cache lifetime next to the only consumer of those caches, and the 20-line restructure of the telemetry control flow here — which exists only to host this one call — goes away.

[masenf]

Agreed the re-indent is ugly — the whole method body moved a level in to host one line. I've left it as is for one concrete reason, but I'm happy to be overruled.

The guarantee is identical either way, so this is placement. What decides it for me is the test. test_compile_releases_hash_caches patches reflex.compiler.compiler.compile_app with a stub that seeds a cache entry and optionally raises, then asserts App._compile() leaves the caches empty on both paths. Move the finally inside compile_app and that patch replaces the code under test, so the test would pass while exercising nothing. Testing it in the new position means either driving a real compile_app in a unit test, or patching something one level further in (_apply_decorated_pages, the plugin pipeline) — a heavier and more coupled test than the one-line stub it replaces.

One correction on the premise: compile_app has two call sites, not one — app.py:1665 on the no-telemetry path and app.py:1676 inside the with ctx: block. That doesn't undercut your suggestion, since a finally inside compile_app covers both, but it is why the finally here had to wrap the whole method rather than one call.

If you'd still prefer it in compile_app, say so and I'll move it and rework the test to drive the real function through the _should_compile() short-circuit — that path returns early inside compile_app, so it exercises the release without a full compile.

---

Generated by Claude Code

[FarhanAliRaza]

I tested this in a real app against the merge base (3573364f8).

I built an app with custom components forced to MemoizationDisposition.ALWAYS. One varies its add_custom_code per instance. One varies its ImportVar per instance under a fixed library key. Both render identical JSX in either case. I compiled the app on both branches and diffed the generated memo module.

The PR's own fix is confirmed. The base emits only const PROBE_B and one memo. This head emits PROBE_A and PROBE_B and two distinct memo names.

The import case moves the other way. The base emits two memos and both stylesheet imports. This head emits one memo, and one stylesheet import is gone from the compiled module with no error.

I also ran a valid app in dev mode. State events, rx.cond, rx.foreach, two-way rx.input binding, rx.upload, and two ALWAYS-memoized probes all work. Each probe compiles to its own memo module. The browser console reports no errors or warnings after interaction.

Test runs are clean: 295 unit tests in test_deterministic_hash.py, test_memo.py and test_app.py, ruff check, ruff format --check, and pyright.

I measured the hashing speedup with 201 component_hash calls on a 201-component page, median of 9 runs.

Five requested changes are inline.

[cubic-dev-ai]

All reported issues were addressed across 5 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>