How a ref resolves, and when it goes stale
From top to bottom: a command uses a ref such as @s…:e6, and the refmap returns its RefEntry, or STALE_REF when the key is missing. If the entry carries a retained object (on macOS, the element's own address), resolve_element_strict turns it back into that exact element: if it is alive and its pid, role and recorded id still match, the command acts on it, otherwise STALE_REF. No search runs. If the entry has no retained object, unique_at_capture decides: not unique at capture is AMBIGUOUS_TARGET. If it was unique, FullPredicate counts the live elements that match the same predicate: exactly one lets the command act, none is STALE_REF, and two or more is AMBIGUOUS_TARGET.
@s…:e6
a command uses a ref
RefEntry
refmap lookup by key
no key
STALE_REF
key not in the refmap
element_token(entry)
retained object on the entry?
yes
resolve_element_strict
macOS: address back to the same element
dead or mismatched
STALE_REF
dead, or pid, role or id differ
no retained object
unique_at_capture
complete evidence, full predicate
no
AMBIGUOUS_TARGET
not unique at capture, or 2+ live matches
yes
FullPredicate
count live matches in the window
2+ matches
none
STALE_REF
no live element matches
exactly 1 match
act
on the resolved element
alive, fields match