How a ref resolves, and when it goes stale
From top to bottom: a command receives a qualified ref. RefStore loads snapshots/snapshot_id/refmap.json, or fails with SNAPSHOT_NOT_FOUND. The ref maps to a RefEntry, or fails with STALE_REF when the key is missing. resolve_element_strict re-identifies the entry in the live tree: exactly one match lets the command act, zero matches is STALE_REF, and two or more is AMBIGUOUS_TARGET. Every failure is fixed by a fresh snapshot and its new ref.
@<snapshot_id>:eN
a qualified ref
RefStore
snapshots/<id>/refmap.json
gone
SNAPSHOT_NOT_FOUND
pruned, or another session
RefEntry
pid, role, path, identity, bounds
no key
STALE_REF
no live element matches
resolve_element_strict
re-identify in the live tree
0 matches
2+
AMBIGUOUS_TARGET
several elements match
exactly one match
act
on the resolved element
fresh snapshot
new snapshot_id, new ref