Does == actually work the same or different when comparing two primitives vs two Objects in Java?
As other answers / comments say, at the Java language level the == operator semantics are specified (in JLS 15.21) in an implementation independent way. Strictly speaking, you cannot infer the "under the hood" implementation details from the JLS text. All that you can say is that any conformant implementation of == must behave in a certain way.
I will assume that we are talking about conventional JVMs where the actual machine representation of a reference is a machine address. It is possible to implement references in other ways; e.g using some kind of indirect addressing mechanism such as a PIDLAM.
At the bytecode level, there are a number of different bytecode instructions that implement the logic of == depending on the type (int, long or reference). However, the semantic of the comparisons are similar. Once the bytecodes have been verified as type-safe, integers and addresses can be handled the same for the purposes of == comparison at the hardware level.
At the hardware (machine instruction) level == works the same for primitive integral types and non-primitive values. In both cases it will be executing a machine instruction that compares two "words" taken from a register or from memory (heap or stack).
The JLS specified semantics of == for float and double are a bit different because the special values (infinities and not-a-number values) need special treatment. For example: NaN == NaN is false. See also the IEEE 754 floating point standard.
There are different bytecodes for this, and at the hardware level the instructions used are different to those used in the integer and reference cases. (The treatment of special values is typically handled in the floating hardware.)
The JLS specified semantics of == for boolean, byte, short and char is to promote the values to another type (int, long, float or double) before comparing them. Promotion also occurs with other cases if the operands have different (unboxed) types.
In addition, unboxing occurs if one (but not both!) of the operands is boxed. If both operands are boxed, then == is a reference comparison.
Summarizing the above ...
Have I mis-understood something, or does == actually behave the same in all situations?
No it doesn't, if you include floating point types, and the considerations of primitive widening and unboxing.
Bonus points if you can point me to documentation on how this really works under the covers.
There is no official (Oracle) public documentation for this. The JLS and JVM spec do not prescribe implementation strategies.
I understand your explanation, and it is right given certain definitions of terms. But it does not fit the way Java talks of objects and primitives.
The idea of a 'reference' to an object in Java is seriously downplayed; I think it is possible to be a 'Java programmer' and not really understand what a reference is. You can memorize the rules where it makes a difference -- the '==' operator, the passing of parameters to methods -- and not understand how it is, or could be, implemented.
So I think it would be confusing to many people who program in Java to say that == 'behaves the same in all situations', because that involves too much 'under the covers' knowledge. Java doesn't encourage you (or require you) to look 'under the covers' to that extent.