Psalm annotations

I'm currently using this project and Psalm. Obviously static analysis has some issues to understand what this mapper does, but I think that with a couple of annotations it would be fairly easy to explain what's happening type-wise.

Would you be interested in a PR that adds annotations for improving static analysis?
Would you prefer replacing the current annotations or just adding `@psalm-*` ones beside the existing ones?

The issue names no files, tests, or entry points. Start by locating the mapper code and its existing annotations, then run Psalm to identify the reported gaps and determine whether annotations should be replaced or supplemented. Done means the mapper has useful Psalm coverage without breaking existing annotations or behavior.

Written by the indexing model from the issue text.