# Versioned payload contract

`upgrade_payload` must return a new mapping, preserve unknown fields, read legacy `userId`, write canonical `user_id`, remove only the legacy alias, reject conflicting aliases, and never mutate caller-owned nested data.