Cascade plan registry & Redis key scheme key on cls.__name__ — same-named models in different modules can cross-wire

[yedidyakfir]

Summary

Model identity throughout rapyer is derived from class_key_initials(), which returns cls.__name__ (rapyer/base.py). The cascade-TTL plan registry and the Lua class_of(key) lookup both key on this name. Two AtomicRedisModel subclasses that share a class name but live in different modules collide on this identity.

This is pre-existing to the entire Redis key scheme — it is not introduced by the cascade TTL feature (#116). It surfaced during the #116 code review, which noted that cascade amplifies the consequence of a collision. Filing as a tracked follow-up.

Details

• class_key_initials() -> cls.__name__ is the identity used for Redis keys ({__name__}:{pk}), the cascade plan registry keys, and the Lua-side class_of(key) lookup during traversal.
• The duplicate-registration case is already guarded at class-build time by DuplicateModelNameError in __init_subclass__, so two same-named models registered in one process raise loudly today.
• However, the broader durability of cascade traversal — which edges and special-field suffixes get applied to a given target as recursion walks the graph — rests entirely on global model-__name__ uniqueness. If that assumption is ever violated (e.g. registration guard bypassed, models loaded across boundaries, future dynamic models), traversal would silently cross-wire which edges/special-suffixes apply to a target rather than failing.

Severity

Low / medium. Guarded for the duplicate-registration path today; this issue is about hardening the assumption and documenting it, not a live bug. Not a blocker for #116.

Implementation Considerations (suggested directions)

• Key model identity on a fully-qualified name (__module__ + __qualname__) or an explicit per-model identifier instead of bare __name__.
• Or, at minimum, document the global-uniqueness requirement prominently as a hard constraint of the key scheme.
• Any change here touches the on-disk key format, so it needs a migration/compat consideration.

List tasks

• Decide approach: fully-qualified identity vs. explicit identifier vs. document-only
• If changing the key scheme, assess on-disk key-format migration impact
• Ensure the cascade plan registry and Lua class_of() lookup use the chosen identity consistently
• Document the model-name-uniqueness constraint in the docs
• Add a test covering the collision/uniqueness behavior

Surfaced during review of #116 (full cascade TTL).

[linear-code]

YED-105