A developer calls merge() on a detached JPA entity, keeps mutating the variable they passed in, and the later changes never reach the database. Explain what merge actually did and how the persistence context's one-instance-per-identity rule forces that behaviour.

## The invariant that drives everything A persistence context is a map from *entity identity* (entity type + primary key) to a single Java instance. This is what makes the first-level cache behave like an identity map: two `find` calls for the same id in the same context return `==` the same object. Hibernate relies on this to do dirty checking against exactly one snapshot per row and to avoid emitting two conflicting UPDATE statements for the same row. Now imagine `merge` attached your detached instance directly. If the context had already loaded that row — say some validation code called `find` earlier in the request — there would be two managed objects claiming the same identity, each with its own field values and its own snapshot. Hibernate would have no defensible answer for which wins. JPA therefore specifies merge as a **state copy onto the canonical instance**, not an attach. ## What merge does step by step 1. **Already managed?** If `em.contains(arg)` is true, merge returns the argument itself and does nothing else. 2. **Removed?** Merging an instance scheduled for removal is illegal and throws `IllegalArgumentException`. 3. **No identifier?** Treated as new: Hibernate creates a fresh instance, copies the state, persists it, and returns the new instance. The generated id appears on the copy, not on your object. 4. **Has an identifier?** Hibernate resolves the managed target — from the persistence context if present, otherwise by loading it (a SELECT, possibly served by the second-level cache). If no row exists, the outcome depends on the mapping and provider: classically, Hibernate treats it as a new instance to insert, which is why merge is often described as 'insert-or-update'. 5. **Copy.** Basic properties, embeddables and mapped associations are copied. Associations annotated with `CascadeType.MERGE` (or `ALL`) are merged recursively; associations without it are not, and referencing a transient object through such an association will blow up at flush with 'object references an unsaved transient instance'. 6. **Return** the managed target. ## Symptoms candidates should recognise - **Lost updates after merge** — the classic. Mutations go to the detached argument. - **`==` surprises** — `merged != original` in the common case, so code that later compares references, or holds the original in a collection/map, silently works on the wrong object. - **Identifier still null** — after merging a new instance, the caller's object has no id and the code that returns `order.getId()` to the client returns null. - **Version field not advanced on your copy** — the optimistic-lock version is incremented on the managed instance; the detached one keeps the stale value, so reusing it for a second merge later can fail. ## Diagnosing and avoiding it `em.contains(x)` is the direct test: it answers 'is this exact instance managed in this context'. In review, the smell is any statement of the form `em.merge(x);` where the return value is discarded, or `x` is used afterwards. Treat `merge` like `String.toUpperCase()` — it produces a new thing rather than modifying in place; discarding the result is almost always a bug. The deeper avoidance strategy is to not round-trip entities through the client at all. Load the entity by id inside the transaction, apply the fields the use case permits, and let dirty checking write the UPDATE. That eliminates both the merge SELECT and the whole class of 'which instance is the real one' confusion. Merge earns its place when you genuinely hold a detached graph — for instance state carried across a long conversation, or an object deserialised from an outbox/import file — and you want insert-or-update semantics for it. Finally, note the asymmetry with the legacy native alternative: Hibernate's old `Session.update()` re-attached your actual instance and therefore threw `NonUniqueObjectException` when the context already held that id. Merge's copy semantics are exactly what buys you the ability to call it unconditionally.