Implement an immutable USD money value object in Java

• Use BigDecimal, never double or float.
• Normalize every accepted amount to scale 2.
• Reject null, negative amounts, and values that need rounding.
• Return a new value from arithmetic; never mutate an instance.
• Make equality consistent with the normalized representation.

1. Put the invariant in the record constructor so every creation path is checked.
2. Normalize with setScale(2, RoundingMode.UNNECESSARY); this accepts 2.0 but rejects 1.005.
3. Reject negative values after normalization.
4. Implement addition by constructing a new UsdMoney, so the same invariant is reused.
5. Use BigDecimal.compareTo for ordering and test equality separately.

import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.Objects;

public record UsdMoney(BigDecimal amount)
        implements Comparable<UsdMoney> {

    public UsdMoney {
        Objects.requireNonNull(amount, "amount");
        amount = amount.setScale(2, RoundingMode.UNNECESSARY);
        if (amount.signum() < 0) {
            throw new IllegalArgumentException("amount must be non-negative");
        }
    }

    public static UsdMoney of(String amount) {
        return new UsdMoney(new BigDecimal(amount));
    }

    public UsdMoney add(UsdMoney other) {
        Objects.requireNonNull(other, "other");
        return new UsdMoney(amount.add(other.amount));
    }

    @Override
    public int compareTo(UsdMoney other) {
        Objects.requireNonNull(other, "other");
        return amount.compareTo(other.amount);
    }
}

Construction and addition are O(n) in the number of decimal digits handled by BigDecimal; comparison is also proportional to numeric representation size. The object itself stores one immutable reference.

• 2, 2.0, and 2.00 normalize to the same record value.
• 1.005 is rejected instead of being rounded without a stated rule.
• Adding two valid values still runs the constructor invariant.
• Very large values may be valid mathematically but still need a separate product limit.

• Construct equivalent values with different input scales and verify equals and hashCode agree.
• Attempt negative, null, and over-precision values.
• Verify add leaves both operands unchanged.
• Verify ordering around zero and values with different integer lengths.

• Using BigDecimal.equals before normalization makes 2.0 and 2.00 unequal.
• Using HALF_UP silently invents a rounding policy the problem did not authorize.
• Validating only in a factory leaves the public constructor as an invalid creation path.
• Using double introduces binary floating-point error before BigDecimal receives the value.