Regarding 2. (ordered Lists as input and output types):

In lieu of javadocs stating something else, the method signature is the documentation.
Therefore the documentation says in this case:

Hey there... I accept objects in a certain order. If the order didn't matter, my author would have used the type Collection and not List. Also: I'm returning objects in a certain order. Again, otherwise my author would have used Collection instead of List.

Based on the method signature, these are reasonable assumptions about what the method does. After all, it's a Java method, not an SQL call. With my mind set on the underlying SQL implementation—yes, perhaps I would assume other behavior. But since Hibernate is an ORM, I side with typical behavior for Java (cause that's what it's all about).

Now, you are absolutely right, which order is chosen when object are returned, i.e. the principle that guides sorting in this case, is completely unspecified. Perhaps that's what you mean with "leap of logic" .

But let's not argue how APIs need to be interpreted. That's fun, but rarely leads to something.

All I'm really saying is, that I was surprised by what the method does. I had expected/wished for something else. That's why I filed the JIRA issue. Part 1 is most definitely a bug. But with 2 and 3, it's probably a matter of opinion, as you already stated. I'm not even sure if other people have use cases that require this kind of processing (I do though). Also, I don't have stakes in Hibernate as a developer, just as a consumer. As a consumer, I'd appreciate fixing of 1. and clarification of 2. I.e. either define the order of both lists somewhere, change the type to `Collection`, introduce a new method, ... there are a bunch of possibilities. Regarding 3—that would be nice and very Java-like in my eyes. But perhaps also quite unexpected for other people.

And yes, the behavior I suggest requires additional processing and therefore has a performance impact. With that in mind, a flag that allows turning this behavior on and off is probably a good idea. Or a second method. I don't have any strong opinions on this.

To summarize:

• Fix the bug in 1.
• Clarify the behavior somehow, via different types or javadocs.
• (Optionally) Add another behavior that is more like what I wished for and document what it does.

In any case, I appreciate you taking the time to work on this.