docs: record why the alias proxy cache needs identity keys

[velo]

Documentation only, no behaviour change.

While auditing identity dependencies I looked at AliasFactory.proxyCache and
found two things worth writing down next to the field.

The weak keys do not actually evict. The inner map is a
WeakHashMap<Expression<?>, ManagedObject>, but the cached proxy delegates to a
PropertyAccessInvocationHandler that holds the same expression used as the key
(PropertyAccessInvocationHandler.java:51). Value strongly references key, so
entries stay reachable — the classic self-referential WeakHashMap case, and in
effect this is an unbounded strong cache.

I deliberately did not change it. createProxy generates and loads a fresh
ByteBuddy class on every call, so making the cache actually evict would trade
retained heap for unbounded class generation and metaspace growth. Both sides
need addressing together, which is a design call rather than a drive-by fix.
Flagging it in the code so the next person does not "fix" one half of it.

The keys have to be identity objects. Reference cannot refer to a value
object, so this cache is the thing that would stop Expression implementations
from ever being declared value classes under JEP 401.

Also checked while I was in there: there is no synchronized anywhere in the
main source tree across all library modules, and the remaining identity-keyed
maps are all safe — TemplateFactory keys on String, Templates and
CollQuerySerializer key on enum-backed Operator, MemFileSystemRegistry
keys on String.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WnNBe1GoG2SxfU3FN7bcAA