crates/vm/src/object/payload.rs (1)

25-34: Clarify safety docs and contract for validate_downcastable_from

downcastable_from now performs the typeid check itself and then calls validate_downcastable_from. The safety comment (“should only be called if payload_type_id matches the type of obj”) no longer reflects the actual behavior, and override implementations (like PyUtf8Str) rely on the fact that validate_downcastable_from is only invoked after the typeid equality has been verified.

To make this extension point safer for future implementors, I suggest:

• Update the doc comment on downcastable_from to describe what guarantees it provides (e.g., that it first checks obj.typeid() == Self::payload_type_id()).
• Add a brief doc comment on validate_downcastable_from stating that, when called via downcastable_from, obj is guaranteed to satisfy the payload_type_id check, and that callers should not invoke it directly without that precondition.

This documents the intended use and justifies unsafe downcasts inside overrides like PyUtf8Str::validate_downcastable_from.

crates/vm/src/builtins/str.rs (1)

1935-1939: Unsafe cast in PyUtf8Str::validate_downcastable_from is sound but deserves a slightly stronger comment

The implementation:

• Overrides payload_type_id() to return TypeId::of::<PyStr>().
• Relies on PyPayload::downcastable_from to check obj.typeid() == TypeId::of::<PyStr>() before calling validate_downcastable_from.
• Then performs unsafe { obj.downcast_unchecked_ref::<PyStr>() } and checks is_utf8().

Given this call pattern, the unsafe cast is valid: when validate_downcastable_from runs, obj’s payload is guaranteed to be a PyStr, and PyUtf8Str is repr(transparent) over PyStr.

To make the invariant clearer for future changes, consider expanding the comment to mention that:

• validate_downcastable_from is only meant to be called via PyPayload::downcastable_from, and
• the preceding typeid check, together with the overridden payload_type_id(), is what justifies using downcast_unchecked_ref::<PyStr>() here.

Functionally the change looks correct and nicely reuses the new hook to avoid duplicating the type-id logic.

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro