perf: benchmark singletons — they're slower, keep them off

[AmitMY]

Summary

• Add benchmarks/bench_singletons.py comparing singleton vs non-singleton performance
• Add tests verifying identical merge output and regression guard

Stacked on #7.

What improved

• Documented that singletons are 1.5-2x slower and use more memory due to cache overhead
• Confirmed non-singleton mode should remain the default

Results (50 samples, 100 merges)

Mode	Time	Peak Memory	Cache entries
No singletons	3.8s	2.4 MB	0
Singletons	7.2s	5.3 MB	7,431

Test plan

• All tests pass
• ruff check . passes

🤖 Generated with Claude Code

[AmitMY]

why is it the case? cache check should be fast, and given we do see there are cache entries, i don't understand why it would be slower.

[AmitMY]

The cache lookup is fast, but the cache key construction on every Node() call is the bottleneck. Each call to __new__ builds:

key = (cls, args, tuple(sorted(kwargs.items())))

This tuple creation + dict lookup costs more than just allocating a fresh frozen dataclass with __slots__ (which is essentially a single object.__setattr__ call).

Profiling shows:

• Without singletons: __new__ = 0.007s for 26k calls (0.26μs/call)
• With singletons: __new__ = 0.086s for 26k calls (3.2μs/call) — 12x slower per call

The savings from singletons (fewer __eq__/__hash__ calls due to identity comparison) don't compensate because merge operations create thousands of new nodes per training step, each paying the __new__ tax.

Microbenchmark: 50k Node(value=b'x') calls takes ~1.6x longer with singletons than without. Added a test documenting this.

[AmitMY]

wow, ok! would singletons help in scale? or even then, not worth it? i am thinking about a test like: create 10k linked lists for the word "The" (t -> h -> e) - then run .merge(t, h)
so to test, create a text "the the the ....." 10k times - and run with and without singleton to see.

[AmitMY]

Fixed the key — the bug was that dataclass constructors pass fields as kwargs, not args. So the fast key (cls,) + args was just (cls,) for all instances of a class, causing self-referential cycles.

New key: (cls,) + args + tuple(kwargs.values()) — correct and still fast (~1.2x overhead vs 1.4x before).

Added a 10k-word scale test verifying identical merges with/without singletons.

At this scale (10k "the"), singletons add ~15% overhead but are correct. The overhead comes from the dict lookup per Node() call — still more expensive than raw frozen dataclass allocation, but much better than the old sorted(kwargs.items()) approach.