Add explicit decimal precision to Money

[derikthiessen-shopify]

Part of #306

TL;DR

Added opt-in decimal precision to Money values, retained additional calculation digits until output boundaries, and preserved the precision contract through arithmetic, allocation, splitting, serialization, and money columns.

Why Change?

Some prices and thresholds need more decimal places than their currency supports, especially before quantities are applied. Rounding those values during construction loses information, while silently combining or persisting values with incompatible precision can change their meaning.

What Changed?

• Added a per-value decimal_precision option that defaults to the currency's minor units.
• Retained additional digits during calculations and rounded explicitly precise values when rendered, converted to subunits, allocated, split, or persisted through a money column.
• Preserved explicit precision through arithmetic and kept equality, hashing, and ordering value-based.
• Rejected arithmetic and allocation inputs with incompatible declared precision.
• Normalized allocation maxima only when their values are exactly representable at the receiver's precision.
• Preserved raw calculation values through YAML and Active Job transport while JSON uses the rendered value.
• Added fixed decimal_precision configuration for money columns so stored values reconstruct without losing their declared precision.
• Documented how to construct, calculate with, and persist subunit-precision values.

Fractional unit prices can retain calculation digits that are not individually payable:

unit_price = Money.new("0.0057", "USD", decimal_precision: 3)

unit_price.to_s         # => "0.006"
(unit_price * 100).to_s # => "0.570"

Allocation can use the same explicit units while preventing maxima from being rounded into larger limits:

amount = Money.new("0.057", "USD", decimal_precision: 3)
amount.allocate_max_amounts(["0.029", "0.028"]).map(&:to_s)
# => ["0.029", "0.028"]

Models can declare the precision used for database round trips:

class Product < ActiveRecord::Base
  money_column :price, currency_column: :price_currency, decimal_precision: 4
end

product = Product.create!(
  price: Money.new("0.0574", "USD", decimal_precision: 4),
)
product.reload.price.to_s # => "0.0574"

Tests

• Ran the complete local test suite: 781 examples, zero failures, and 100% line coverage.
• Passed RBS validation and Steep type checking.
• Passed RuboCop on all changed production Ruby files.
• Ran Binks and addressed its exact-allocation and subunit-rounding findings.

Risks

• The per-value decimal_precision: API follows the approach proposed in the issue rather than scoped/global configuration. This choice needs confirmation from the Money team before merge.
• Fixed money_column decimal_precision: is an explicit persistence contract: writes with a different declared precision are rejected, and explicit-precision writes are rejected when the column has no fixed precision. This policy also needs Money-team confirmation.
• Explicitly precise values may contain raw digits beyond decimal_precision; code reading value or to_d observes those digits, while rendered and discrete-unit output is rounded.

[derikthiessen-shopify]

so this would reject writes with a different declared precision. I'm not sure if that is the contract that the Money gem maintainers want, so calling it out here

[derikthiessen-shopify]

Inline usage examples for the public precision contracts introduced by this PR.

[derikthiessen-shopify]

Construction example — explicit precision retains extra calculation digits until an output boundary:

unit_price = Money.new("0.0057", "USD", decimal_precision: 3)

unit_price.value.to_s("F") # => "0.0057"
unit_price.to_s               # => "0.006"

[derikthiessen-shopify]

Arithmetic example — matching precision propagates through the result, while conflicting declared precision raises Money::IncompatiblePrecisionError:

price = Money.new("1.000", "USD", decimal_precision: 3)
tax = Money.new("0.057", "USD", decimal_precision: 3)

(price + tax).to_s # => "1.057"
(price * 2).to_s   # => "2.000"

[derikthiessen-shopify]

JSON is a rendered boundary, so it records the rounded value together with the precision needed to reconstruct its representation:

money = Money.new("0.0057", "USD", decimal_precision: 3)
money.as_json
# => { value: "0.006", currency: "USD", decimal_precision: 3 }

Money.from_json(money.to_json).to_s # => "0.006"

[derikthiessen-shopify]

Subunit conversion is also an output boundary and rounds instead of truncating retained digits:

Money.new("0.0099", "USD", decimal_precision: 2).subunits
# => 1

[derikthiessen-shopify]

All maximums are interpreted in the receiver's explicit units and must be exactly representable at that precision:

amount = Money.new("0.057", "USD", decimal_precision: 3)
amount.allocate_max_amounts(["0.029", "0.028"]).map(&:to_s)
# => ["0.029", "0.028"]

[derikthiessen-shopify]

Splitting uses the declared precision as its indivisible unit:

Money.new("0.057", "USD", decimal_precision: 3)
  .split(2)
  .map(&:to_s)
# => ["0.029", "0.028"]

[derikthiessen-shopify]

Active Job transport preserves both the raw calculation value and its declared precision:

money = Money.new("0.0574", "USD", decimal_precision: 3)
SomeJob.perform_later(money)
# The job receives value 0.0574 with decimal_precision 3.

[derikthiessen-shopify]

Model configuration example — the column owns the persistence precision, and explicitly precise assignments must match it:

class Product < ActiveRecord::Base
  money_column :price,
    currency_column: :price_currency,
    decimal_precision: 4
end

Product.create!(
  price: Money.new("0.0574", "USD", decimal_precision: 4),
)