always use RefOne, RefMany should be used once load() returns another instance (otherwise you will not be able to laod a model, you must get it thru iterator first)

this is one strong advantage of hintable magic, thanks to #821 foreach value has correct type for phpstan as the iterated model

otherwise autohinting (from phpdoc) does not work

Why not add HasOne to Method Signature?

public function hasOne(string $link, array $defaults = []): Reference\HasOne

because it can be implemented by another class not based on this one

this is almost the no1 issue with Atk

so you mean a child class could e.g. implement
public function hasOne(string $link, array $defaults = []): Some\Other\Reference
and that would fail if we set the parent signature to Reference\HasOne?

yes

grml this is ugly. Do you really think adding Reference\HasOne would be an issue? I see return types in method signatures as an important part of good code. While this PR helps IDEs and phpstan and so on using comments, it weakens the method signatures which was something I liked about almost any of your PR: You created stricter, clearer method signatures.