A team is puzzled that the same compiled application behaves identically everywhere but performs very differently across JVM builds and flags. How would you explain what the Java Virtual Machine specification actually mandates versus what each implementation is free to decide?

## Two different promises The Java platform makes one strong promise and one weak one, and conflating them is the root of the confusion in this question. The strong promise is **semantic portability**: a class file that runs on one conforming JVM produces the same observable behaviour on another. The weak promise — really, no promise at all — is about **performance and resource behaviour**. Timing, memory footprint, pause profile and throughput are explicitly implementation territory. ## What the specification actually mandates **The class file format.** Structure, constant-pool entry kinds, attribute semantics, and major/minor version rules. This is the interchange contract, which is why an artifact built once runs on any conforming JVM of a sufficient version. **Instruction semantics.** Every bytecode's effect on the operand stack, locals and heap is defined. Integer arithmetic overflow wraps in a specified way; floating point follows specified rules; array bounds are checked and produce a specific exception type. **Verification.** The rules a class file must satisfy before it may execute — type-safety of the operand stack and locals, valid branch targets, access rules. **Loading, linking, initialization.** The ordering, the triggers for initialization, the once-only and thread-safe execution of the class initializer, the erroneous-class state after a failed initializer. Whether resolution is eager or lazy is deliberately left open — but the *observable* consequences of either choice are constrained. **Exception and error behaviour.** Which conditions raise which throwable, and the fact that certain errors (out-of-memory, stack overflow) may occur at essentially any point. **The memory model.** The happens-before ordering rules that define when a write by one thread is visible to another, the special semantics of volatile and final fields, and the rules for 64-bit values. This is written as a specification precisely so that concurrent programs have portable meaning across wildly different hardware. ## What implementations are free to choose **Object layout.** Header size and contents, field ordering and padding, whether references are compressed on 64-bit heaps. The specification says an object has these fields with these semantics; it never says where the bytes sit. **Garbage collection.** Whether collection is generational, whether it moves objects, whether it is concurrent, how it is partitioned, what the pause profile looks like — all free. The specification requires only that unreachable objects may be reclaimed and that finalization-like mechanisms follow their documented rules. Even *which collector is the default* has changed across releases, which alone can make the same artifact behave differently on two JDK versions. **Execution strategy.** Whether bytecode is interpreted, compiled, or both; when compilation triggers; how aggressively methods are inlined; whether speculative optimizations are attempted and rolled back. A conforming JVM could interpret everything forever and still be correct — just slow. **Runtime data area representation.** How stacks are laid out, their default and maximum sizes, how the metadata area is organised and whether it is bounded, whether there is a code cache and how large. **Peripheral policies.** Interned-string capacity, thread scheduling (typically delegated to the OS), whether and how internal caches are sized. ## The engineering rules that follow 1. **Depend on documented semantics, never on observed mechanism.** Code that relies on identity comparison working for boxed values in a range, on finalization order, on a particular `hashCode` value, on when a static is initialized relative to another, or on a data race "working" is depending on the free half. It will pass tests and fail somewhere else. 2. **Treat performance characteristics as environment configuration.** JVM vendor, version, flags and container limits belong in the same tier as the database version: pinned, recorded, and changed deliberately with measurement. "It got slower after the platform upgrade" is a legitimate and expected class of change, not a bug in your code. 3. **Measure on the target, not on a laptop.** Because the engine may compile differently under different flags, heap sizes and core counts, a benchmark on an unrepresentative JVM configuration measures a machine you do not deploy. 4. **The memory model is the exception that proves the rule.** Concurrency is the one place where an implementation's freedom could have destroyed portability, so the platform spends a whole specification chapter constraining it. If your concurrent code is correct only against the ordering one CPU architecture happens to provide, it is broken by definition even where it currently runs. 5. **Some observable behaviour is intentionally unspecified.** Timing of collection, whether a reference is cleared before another, exactly when an out-of-memory error fires — these are legitimately non-deterministic, and designs must not depend on their ordering. ## The framing to leave with the team The specification is a contract about *what a program means*. Everything about *how fast and in how much memory* is an implementation's competitive space. That separation is the reason the ecosystem could evolve collectors and compilers radically without recompiling a line of application code — and it is the reason performance must be re-measured whenever any part of that free half changes underneath you.