whittaker_tech-midas 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79ce2a5c7e59f15a9ca7af2ea759c514a32fcdc67915618d01d4f1cf2c00bd9a
-  data.tar.gz: 149f3fa609b856dffdef559835f668bb47758c00262d5cb2d4517ef21f3c1892
+  metadata.gz: fe9c21222c40c9da18f01c21076e775b5d00f6f7b817f2c06c05223cdd88de8b
+  data.tar.gz: 50ec83ec5d2b1fbe82e3856180ce63c8bc35f458679f14ab3fdd800229ef519d
 SHA512:
-  metadata.gz: f446717fbf1acd4e4a3648eec3aeadbaa71e6263b60e77b68e3c960cfaa10a958783888d5bfa0df53c39cbff8e4849193a173aaa423fd4e92830bd7a954c22a5
-  data.tar.gz: 538185c60138515129e23ad762985a2bed02ebb369c6c02311107a06c876f481a66df71c4d4437ff99d39d43d67974e18f81b4c172c4d50dde16945dff0b1d34
+  metadata.gz: 4833df22795e85d8e837bd2c0fa81ee6cf593a401463daf7ca42b6adf659be45cecd497213a0641d363c1523019fd2ac616265212aca85e531ee56d9d50efb7f
+  data.tar.gz: bdcf127c769350759698cfefb12babe569c5c0c2ed907b3127212e2d806ff3c8eec0d9dedde9f62b6ec59721683e8fa99b21eeef883a6148166d567673dce20a

data/README.md

@@ -1,7 +1,7 @@
 # WhittakerTech::Midas
 
 [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](MIT-LICENSE)
-![Ruby 3.4](https://img.shields.io/badge/ruby-3.4+-red.svg)
+![Ruby 3.2](https://img.shields.io/badge/ruby-3.2+-red.svg)
 ![Rails 7.1](https://img.shields.io/badge/rails-7.1+-crimson.svg)
 [![Gem Version](https://badge.fury.io/rb/whittaker_tech-midas.svg)](https://badge.fury.io/rb/whittaker_tech-midas)
 [![CI](https://github.com/WhittakerTech/midas/actions/workflows/ci.yml/badge.svg)](https://github.com/WhittakerTech/midas/actions)
@@ -22,6 +22,7 @@ This design keeps your pricing, billing, and financial reporting consistent acro
 - Automatic minor-unit conversion for all input types (int, float, Money)
 - Multi-currency support with configurable exchange rates
 - Headless currency input UI for form builders
+- **Additive double-entry bookkeeping** via `Ledger` (accounts + balanced, immutable postings) — see [Ledger](#ledger--double-entry-bookkeeping) below
 - Test suite with >90% coverage
 - Zero schema duplication—no proliferation of `_cents` columns
 
@@ -77,7 +78,7 @@ product.set_price(amount: 2999, currency_code: 'USD')
 product.price              # => Coin object
 product.price_amount       # => Money object (#<Money @cents=2999 @currency="USD">)
 product.price_format       # => "$29.99"
-product.price_in('EUR')    # => "€26.85" (if exchange rates configured)
+product.price_in('EUR')    # => "€26.85"
 ```
 
 ## Usage Guide
@@ -196,7 +197,7 @@ Money.default_formatting_rules = {
 
 ### Exchange Rates
 
-Set up exchange rates for currency conversion:
+Set up exchange rates on `Money.default_bank` as usual:
 ```ruby
 # In your app
 Money.default_bank.add_rate('USD', 'EUR', 0.85)
@@ -211,6 +212,135 @@ For production, integrate with an exchange rate API:
 - [money-open-exchange-rates](https://github.com/spk/money-open-exchange-rates)
 - [google_currency](https://github.com/RubyMoney/google_currency)
 
+#### How conversion works
+
+`Coin` conversion is provider-agnostic. By default it wraps whatever bank is
+set on `Money.default_bank` (via `Coin::Converter::BankProvider`), so any of
+the gems above work unmodified. You can also convert directly:
+
+```ruby
+coin = product.price
+coin.convert_to('EUR')    # => new, persisted Coin in EUR
+coin.exchange_to('EUR')   # => alias for convert_to
+```
+
+Every conversion — whether via `convert_to`, `exchange_to`, `#{name}_in`, or
+`Coin#format(to:)` — writes an immutable `WhittakerTech::Midas::Exchange`
+audit row recording the `from`/`to` coins, the `rate` used, the provider
+`source`, and the timestamp (`at`). This is a write-only audit log, not a
+rate cache: `convert_to` never reads past `Exchange` rows back to resolve a
+rate, it always asks the provider fresh.
+
+```ruby
+result = coin.convert_to('EUR')
+exchange = WhittakerTech::Midas::Exchange.last
+exchange.from   # => Coin copy of the original value (USD)
+exchange.to     # => the converted result (== `result`)
+exchange.rate   # => BigDecimal rate used
+exchange.source # => "money:Money::Bank::VariableExchange"
+exchange.at     # => Time the conversion was made
+```
+
+**`format(to:)` converts on every call.** If you need the same converted
+value multiple times, convert once and reuse the result instead of calling
+`format(to:)` repeatedly — each call performs a live conversion and writes a
+new `Exchange` row:
+
+```ruby
+# Avoid — converts and audits twice
+coin.format(to: 'EUR')
+coin.format(to: 'EUR')
+
+# Prefer — convert once, format many times
+converted = coin.convert_to('EUR')
+converted.amount.format
+```
+
+**Historical rates.** Passing `at:` requires a provider that implements
+`#exchange_at(money, currency_code, at:)` — the default `BankProvider` does
+not, since `Money::Bank::VariableExchange` has no historical capability.
+Passing `at:` against the default provider raises `ArgumentError`. Supply a
+custom provider via `using:` for historical support:
+
+```ruby
+coin.convert_to('EUR', at: 3.months.ago, using: my_historical_provider)
+```
+
+**Custom providers.** Any object responding to `#exchange(money, currency_code)`
+and `#name` can be passed as `using:` to override the default bank-backed
+provider — useful for testing or wiring in a rate API directly:
+
+```ruby
+coin.convert_to('EUR', using: my_provider)
+```
+
+## Ledger — Double-Entry Bookkeeping
+
+*Since 0.4.0.* `Ledger` is **additive** to Coin/Bankable, not a replacement — most monetary
+attributes should keep using `has_coin`/`has_coins`. Reach for `Ledger` when you need a full,
+audited double-entry trail (billing, subscriptions, anything where "why is this balance what it
+is" needs a real answer).
+
+### Accounts
+
+An `Ledger::Account` is either a **system account** (no owner — e.g. a per-currency suspense or
+revenue account, disambiguated by `slug`) or an **owned account** (a polymorphic `owner`, e.g. a
+Customer):
+
+```ruby
+revenue  = WhittakerTech::Midas::Ledger::Account.create!(kind: :revenue, slug: 'revenue', currency_code: 'USD')
+customer = WhittakerTech::Midas::Ledger::Account.create!(kind: :asset, owner: current_customer, currency_code: 'USD')
+
+# Per-currency suspense account, for posting out-of-order events against
+suspense = WhittakerTech::Midas::Ledger::Account.suspense_for('USD')
+```
+
+`kind` is one of `asset`, `liability`, `equity`, `revenue`, `expense`, `suspense`.
+
+### Recording a balanced entry
+
+`Ledger::Entry.record!` is the **only** sanctioned way to create an entry — it's the one call
+that guarantees the result balances:
+
+```ruby
+WhittakerTech::Midas::Ledger::Entry.record!(
+  currency_code: 'USD',
+  occurred_at: Time.current,
+  lines: [
+    { account: customer, direction: :debit,  amount: 1000 },
+    { account: revenue,  direction: :credit, amount: 1000 }
+  ]
+)
+```
+
+An entry with mismatched debits/credits, a mixed-currency line, a zero-amount posting, or no
+lines at all raises `ActiveRecord::RecordInvalid` and rolls back entirely — nothing partial is
+ever left behind.
+
+Entries and their postings are **immutable** once the entry finalizes. Attempting to add,
+destroy, or reattach an amount to a posting on an already-finalized entry raises
+`WhittakerTech::Midas::Ledger::UnbalancedEntryError`.
+
+### Balances
+
+```ruby
+customer.balance  # => 1000  (raw debit-normal; only counts postings on finalized entries)
+revenue.balance   # => -1000
+```
+
+### Suspense accounts for out-of-order events
+
+If an external event arrives out of order (e.g. a refund webhook before its charge), post it
+against `Account.suspense_for(currency_code)` — reclassifying later is just recording a second
+balanced entry that debits suspense and credits the now-known correct account; entries are
+immutable, so reclassification is never a mutation of the original.
+
+### What's deferred
+
+Monthly partitioning of the postings table, a DB-level balance-invariant backstop,
+reclassification tooling/aging alerts, and multi-currency entries are intentionally out of scope
+for this release — see `CHANGELOG.md`.
+
 ## Advanced Usage
 
 ### Multiple Coins on One Resource
@@ -230,7 +360,7 @@ order.set_shipping(amount: 850, currency_code: 'EUR')
 
 order.subtotal_format     # => "$100.00"
 order.shipping_format     # => "€8.50"
-order.shipping_in('USD')  # => "$10.00" (with exchange rate)
+order.shipping_in('USD')  # => "$10.00"
 ```
 
 ### Working with Coin Objects Directly
@@ -366,11 +496,18 @@ bin/rails server
 
 ### Exchange rates not working
 
-Make sure you've configured exchange rates:
+Make sure you've configured exchange rates on `Money.default_bank` (the
+default provider raises whatever error the underlying bank raises, e.g.
+`Money::Bank::UnknownRate`, if a rate is missing):
 ```ruby
 Money.default_bank.add_rate('USD', 'EUR', 0.85)
 ```
 
+### `ArgumentError` mentioning "historical" from `convert_to`
+
+You passed `at:` without a provider that supports it. Either omit `at:` or
+supply `using:` with a provider implementing `#exchange_at`.
+
 ### Input field not formatting
 
 Check that Stimulus is loaded and the controller is registered:

data/app/controllers/concerns/whittaker_tech/midas/paramable.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Paramable provides Strong Params integration for Bankable coin attributes.
+#
+# Mix into any controller that needs to permit and apply coin parameters.
+# Accepts two input formats per role:
+#
+# **Combined** — one field, colon-delimited minor units and ISO currency code:
+#
+#   price: "1245:USD"
+#
+# **Split** — two fields, minor units and currency code separately:
+#
+#   price_minor: 1245, price_currency: "USD"
+#
+# Both formats coerce to the same `set_*` call on the record. The combined
+# format is convenient for JSON APIs; the split format matches what
+# `midas_currency_field` emits from the browser.
+#
+# @example
+#   class ProductsController < ApplicationController
+#     include WhittakerTech::Midas::Paramable
+#
+#     def create
+#       @product = Product.new(product_params.except(*coin_permit_keys(:price, :cost)))
+#       @product.save!
+#       assign_coins(@product, product_params, :price, :cost)
+#     end
+#
+#     private
+#
+#     def product_params
+#       params.require(:product).permit(:name, *coin_permit_keys(:price, :cost))
+#     end
+#   end
+#
+# @since 0.3.0
+module WhittakerTech::Midas::Paramable
+  extend ActiveSupport::Concern
+
+  COMBINED_PATTERN = /\A(-?\d+):([A-Za-z]{3})\z/
+
+  # Returns the list of param field names to pass to ActionController::Parameters#permit
+  # for the given coin roles. Always includes keys for both formats so either works.
+  #
+  # @param roles [Array<Symbol>]
+  # @return [Array<Symbol>]
+  #
+  # @example
+  #   coin_permit_keys(:price, :cost)
+  #   # => [:price, :price_minor, :price_currency, :cost, :cost_minor, :cost_currency]
+  def coin_permit_keys(*roles)
+    roles.flat_map { |r| [r.to_sym, :"#{r}_minor", :"#{r}_currency"] }
+  end
+
+  # Calls `set_#{role}` on +record+ for each role that has params present.
+  # Skips roles whose params are entirely absent; raises nothing for missing data.
+  #
+  # Combined format takes priority when both formats appear for the same role.
+  #
+  # @param record [ActiveRecord::Base] a model that includes Bankable
+  # @param permitted_params [ActionController::Parameters, Hash]
+  # @param roles [Array<Symbol>]
+  def assign_coins(record, permitted_params, *roles)
+    roles.each do |role|
+      data = extract_coin(permitted_params, role)
+      record.public_send(:"set_#{role}", **data) if data
+    end
+  end
+
+  private
+
+  def extract_coin(params, role)
+    combined = params[role]
+    if combined.present?
+      parse_combined_coin(combined.to_s)
+    elsif params[:"#{role}_minor"].present? && params[:"#{role}_currency"].present?
+      {
+        amount: params[:"#{role}_minor"].to_i,
+        currency_code: params[:"#{role}_currency"].to_s.upcase
+      }
+    end
+  end
+
+  def parse_combined_coin(value)
+    match = COMBINED_PATTERN.match(value.strip)
+    return nil unless match
+
+    { amount: match[1].to_i, currency_code: match[2].upcase }
+  end
+end

data/app/models/concerns/whittaker_tech/midas/bankable.rb

@@ -52,6 +52,8 @@
 # - `name`: Returns the associated Coin object
 # - `name_amount`: Returns the Money object representing the amount
 # - `name_format`: Returns a formatted string representation of the amount
+# - `name_in(currency_code)`: Converts and formats the coin in another currency
+#   (writes an Exchange audit row on every call — see `Coin::Converter`)
 # - `set_name(amount:, currency_code:)`: Sets the coin value with the given amount and currency
 #
 # == Supported Amount Types
@@ -129,7 +131,7 @@ module WhittakerTech::Midas::Bankable
 
       define_method("#{name}_amount")   { public_send(name)&.amount }
       define_method("#{name}_format")   { public_send(name)&.amount&.format }
-      # define_method("#{name}_in")       { |to| public_send(name)&.exchange_to(to)&.format }
+      define_method("#{name}_in") { |to| public_send(name)&.exchange_to(to)&.format }
 
       # Sets the coin value with the specified amount and currency.
       #

data/app/models/whittaker_tech/midas/coin/converter/bank_provider.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Default currency-conversion provider: wraps Money.default_bank (or any
+# explicit Money::Bank::* instance) behind the adapter interface
+# WhittakerTech::Midas::Coin::Converter expects.
+#
+# Adapter interface (duck-typed):
+#   #exchange(money, currency_code) -> Money
+#   #name -> String                             (recorded as Exchange#source)
+#   #exchange_at(money, currency_code, at:) -> Money   (optional; only
+#     needed to support a non-default at:. This provider does not define
+#     it — the default Money::Bank::VariableExchange has no historical
+#     capability at all.)
+#
+# @since 0.3.0
+class WhittakerTech::Midas::Coin::Converter::BankProvider
+  def initialize(bank = Money.default_bank)
+    @bank = bank
+  end
+
+  # @param money [Money] the value to convert (native currency)
+  # @param currency_code [String] target ISO 4217 code
+  # @return [Money]
+  def exchange(money, currency_code)
+    # NOTE: deliberately NOT `money.exchange_to(currency_code)` — that
+    # method hardcodes Money.default_bank internally (money gem 6.x) and
+    # would silently ignore a `using:` override. Call the bank directly.
+    @bank.exchange_with(money, Money::Currency.new(currency_code))
+  end
+
+  # @return [String] recorded on Exchange#source
+  def name
+    "money:#{@bank.class.name}"
+  end
+end

data/app/models/whittaker_tech/midas/coin/converter.rb

@@ -1,32 +1,79 @@
 # frozen_string_literal: true
 
-# Converter is a reserved module for future currency conversion logic.
+# Converter implements cross-currency conversion for Coin, backed by a
+# provider-agnostic adapter (default: Coin::Converter::BankProvider wrapping
+# Money.default_bank). Every successful conversion writes an immutable
+# WhittakerTech::Midas::Exchange audit row, which owns both a copy of the
+# source value (`from`) and the converted result (`to`).
 #
-# It exists as a clear architectural placeholder to separate concerns:
-#
-# Related modules:
-#
-# - `Arithmetic`: Integer arithmetic on minor units
-# - `Allocation`: Per-unit pricing interpretation
-# - `Converter`: Cross-currency rate conversion (planned)
-#
-# When implemented, Converter will handle:
-# - Exchange rate sources (live API, snapshot, historical)
-# - Historical conversions with a specific timestamp
-# - Regulatory rounding rules per jurisdiction
-#
-# @note All methods in this module raise `NotImplementedError` intentionally.
-#   Use the Money gem's exchange rate infrastructure directly for now.
-# @since 0.1.0
+# @since 0.3.0
 module WhittakerTech::Midas::Coin::Converter
   # Converts this Coin to another currency.
   #
+  # The receiver does not need to be persisted — it's only ever read, never
+  # mutated or reassigned. The result is a brand-new, persisted Coin owned
+  # by a newly created Exchange audit row (not linked back to this Coin's
+  # own resource).
+  #
   # @param currency_code [String] target ISO 4217 currency code
-  # @param at [Time] the rate timestamp (for historical conversions)
-  # @param using [Object, nil] exchange rate provider / bank override
-  # @return [Coin]
-  # @raise [NotImplementedError] — not yet implemented
-  def convert_to(currency_code, at: Time.current, using: nil)
-    raise NotImplementedError
+  # @param at [Time, nil] rate timestamp; nil (default) means "now". A
+  #   non-nil value requires `using:` to supply a provider implementing
+  #   `#exchange_at`.
+  # @param using [Object, Money::Bank::Base, nil] provider override; any
+  #   object responding to `#exchange(money, currency_code)` and `#name`,
+  #   or a raw `Money::Bank::*` instance (auto-wrapped in BankProvider)
+  # @return [Coin] the persisted `to` Coin (the converted result), owned by
+  #   the newly created Exchange audit row
+  # @raise [ArgumentError] if `at` is given and the resolved provider has
+  #   no `#exchange_at`
+  def convert_to(currency_code, at: nil, using: nil)
+    provider = resolve_provider(using)
+    iso = currency_code.to_s.strip.upcase
+
+    if currency_minor.zero?
+      converted_cents = 0
+      rate = BigDecimal(0)
+    else
+      converted = fetch_rate(provider, iso, at)
+      converted_cents = converted.cents
+      rate = BigDecimal(converted_cents) / BigDecimal(currency_minor)
+    end
+
+    persist_conversion(provider, iso, at, converted_cents, rate)
+  end
+  alias exchange_to convert_to
+
+  private
+
+  def resolve_provider(using)
+    case using
+    when nil then WhittakerTech::Midas::Coin::Converter::BankProvider.new
+    when Money::Bank::Base then WhittakerTech::Midas::Coin::Converter::BankProvider.new(using)
+    else using
+    end
+  end
+
+  def fetch_rate(provider, iso, at)
+    return provider.exchange(amount, iso) if at.nil?
+
+    unless provider.respond_to?(:exchange_at)
+      raise ArgumentError,
+            "#{provider.respond_to?(:name) ? provider.name : provider.class.name} does not support " \
+            'historical rates (at:); omit at: or supply a provider implementing #exchange_at'
+    end
+
+    provider.exchange_at(amount, iso, at:)
+  end
+
+  def persist_conversion(provider, iso, at, minor, rate)
+    source = provider.respond_to?(:name) ? provider.name : provider.class.name
+    stamp = at || Time.current
+
+    WhittakerTech::Midas::Coin.transaction do
+      exchange = WhittakerTech::Midas::Exchange.create!(rate:, source:, at: stamp)
+      exchange.set_from(amount: currency_minor, currency_code: currency_code)
+      exchange.set_to(amount: minor, currency_code: iso)
+      exchange.to
+    end
   end
 end

data/app/models/whittaker_tech/midas/coin.rb

@@ -27,7 +27,7 @@
 #   +------------+----------------------------------------------+
 #   | Arithmetic | +, -, *, /, %, negate, equality              |
 #   | Bidi       | Unicode bidirectional text isolation         |
-#   | Converter  | Currency conversion (reserved, not yet live) |
+#   | Converter  | Currency conversion (live, audited via Exchange) |
 #   | Presenter  | Token-based formatting grammar               |
 #   +------------+----------------------------------------------+
 #
@@ -46,13 +46,12 @@
 # - `WhittakerTech::Midas::Coin::Arithmetic`
 # - `WhittakerTech::Midas::Coin::Allocation`
 # @since 0.1.0
-# rubocop:disable Metrics/ClassLength
 class WhittakerTech::Midas::Coin < WhittakerTech::Midas::ApplicationRecord
   # Arithmetic: exact arithmetic and equality semantics
   include Arithmetic
   # Bidi: bidirectional currency conversion
   include Bidi
-  # Converter: future currency conversion logic
+  # Converter: live currency conversion + Exchange audit trail
   include Converter
   # Presenter: formatting and presentation logic
   include Presenter
@@ -127,16 +126,18 @@ class WhittakerTech::Midas::Coin < WhittakerTech::Midas::ApplicationRecord
   # This is a convenience wrapper around the Money gem's `#format`. For
   # richer formatting use `#present` with a pattern string.
   #
+  # @note When `to` is given, this performs a live conversion (via
+  #   `#convert_to`) and writes an Exchange audit row on every call. If
+  #   formatting the same converted value repeatedly (e.g. in a view loop),
+  #   convert once and reuse the result's `#amount.format` instead.
+  #
   # @param to [String, nil] target ISO 4217 currency code for conversion,
   #   or `nil` to format in the native currency.
   # @return [String] the formatted monetary string, e.g. `"$29.99"`
   def format(to: nil)
-    if to
-      raise NotImplementedError,
-            'Currency conversion is not yet implemented. Use #amount.format for native formatting.'
-    end
+    return amount.format unless to
 
-    amount.format
+    convert_to(to).amount.format
   end
 
   # @return [Integer] the raw minor-unit count (alias for `#currency_minor`)
@@ -276,35 +277,6 @@ class WhittakerTech::Midas::Coin < WhittakerTech::Midas::ApplicationRecord
     end
   end
 
-  # ── Deprecated ────────────────────────────────────────────────────────── #
-
-  # @deprecated Use `#resource_role` instead. Will be removed in v0.3.0.
-  def resource_label
-    WhittakerTech::Midas::Deprecation.warn(
-      'Coin#resource_label is deprecated. Use Coin#resource_role instead.',
-      caller_locations(1, 1)&.first
-    )
-    resource_role
-  end
-
-  # @deprecated Use `#resource_role=` instead. Will be removed in v0.3.0.
-  def resource_label=(value)
-    WhittakerTech::Midas::Deprecation.warn(
-      'Coin#resource_label= is deprecated. Use Coin#resource_role= instead.',
-      caller_locations(1, 1)&.first
-    )
-    self.resource_role = value
-  end
-
-  # @deprecated Use `for_role` instead. Will be removed in v0.3.0.
-  def self.for_label(label)
-    WhittakerTech::Midas::Deprecation.warn(
-      'Coin.for_label is deprecated. Use Coin.for_role instead.',
-      caller_locations(1, 1)&.first
-    )
-    for_role(label)
-  end
-
   private
 
   # Normalizes currency_code before validation.
@@ -316,4 +288,3 @@ class WhittakerTech::Midas::Coin < WhittakerTech::Midas::ApplicationRecord
     self.currency_code = currency_code.to_s.strip.upcase.presence if currency_code
   end
 end
-# rubocop:enable Metrics/ClassLength

data/app/models/whittaker_tech/midas/exchange.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Exchange is an immutable audit record of a single currency conversion.
+#
+# It owns two Coins via the standard Bankable DSL — `from` (a copy of the
+# value being converted) and `to` (the converted result) — plus the rate,
+# provider, and timestamp used.
+#
+# Exchange is write-only: nothing reads it back to resolve future
+# conversions. It exists purely as an auditable record of what was
+# converted, at what rate, using which provider, and when.
+#
+# @since 0.3.0
+class WhittakerTech::Midas::Exchange < WhittakerTech::Midas::ApplicationRecord
+  include WhittakerTech::Midas::Bankable
+
+  self.table_name = WhittakerTech::Midas.table_name('exchanges')
+
+  # Gives #from/#to (Coin readers), #from_amount/#to_amount,
+  # #from_format/#to_format, and #set_from/#set_to.
+  has_coins :from, :to
+
+  validates :rate,   presence: true
+  validates :source, presence: true
+  validates :at,     presence: true
+
+  before_update :block_updates
+
+  private
+
+  # Exchange rows are set once at creation and never touched again — the
+  # coins it owns attach separately via Bankable and don't trigger this
+  # callback. Does not block #destroy.
+  def block_updates
+    raise ActiveRecord::ReadOnlyRecord, 'WhittakerTech::Midas::Exchange records are immutable after creation'
+  end
+end

data/app/models/whittaker_tech/midas/ledger/account.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# Ledger::Account is a chart-of-accounts entry for Midas's double-entry
+# ledger. An Account is either a system account (no owner — e.g. a
+# per-currency suspense or platform-revenue account) or an owned account
+# (belongs polymorphically to some domain resource, e.g. a Customer or
+# Organization).
+#
+# Accounts are additive to Coin/Bankable, not a replacement — most Midas
+# consumers should keep using `has_coin`/`has_coins` for simple stored
+# values. Ledger::Account exists for models that need a full double-entry
+# audit trail.
+#
+# @since 0.4.0
+class WhittakerTech::Midas::Ledger::Account < WhittakerTech::Midas::ApplicationRecord
+  include Poly::Joins
+
+  self.table_name = WhittakerTech::Midas.table_name('ledger_accounts')
+
+  # nil owner => a system-level account (suspense, platform revenue, ...).
+  # present owner => a per-resource account (Customer, Organization, ...).
+  belongs_to :owner, polymorphic: true, optional: true
+
+  has_many :postings,
+           class_name: 'WhittakerTech::Midas::Ledger::Posting',
+           dependent: :restrict_with_error,
+           inverse_of: :account
+
+  enum :kind, {
+    asset: 'asset',
+    liability: 'liability',
+    equity: 'equity',
+    revenue: 'revenue',
+    expense: 'expense',
+    suspense: 'suspense'
+  }, validate: true
+
+  before_validation :normalize_currency_code
+
+  validates :currency_code, presence: true, length: { is: 3 }
+  validates :slug, presence: true, if: -> { owner_type.nil? }
+  # System accounts are disambiguated by slug, not kind — e.g. a
+  # 'platform-revenue' and a 'fees-revenue' system account can coexist in
+  # the same currency, both kind: :revenue. Matches the DB partial unique
+  # index on (slug, currency_code) WHERE owner_id IS NULL.
+  validates :slug, uniqueness: { scope: :currency_code },
+                   if: -> { owner_type.nil? }
+  validates :kind, uniqueness: { scope: %i[owner_type owner_id currency_code] },
+                   if: -> { owner_type.present? }
+
+  class << self
+    # Finds or creates the singleton suspense account for a given currency.
+    #
+    # Wrapped in a bounded retry: concurrent callers (e.g. two webhooks
+    # racing to post the first out-of-order event in a currency) can both
+    # miss the `find_by` and attempt to create — the partial unique index
+    # on `(slug, currency_code) WHERE owner_id IS NULL` makes the loser's
+    # insert raise `RecordNotUnique` rather than silently duplicating, and
+    # the retry then finds the winner's row.
+    #
+    # @param currency_code [String] ISO 4217 currency code
+    # @return [Account]
+    def suspense_for(currency_code)
+      iso = currency_code.to_s.strip.upcase
+      attempts = 0
+      begin
+        find_or_create_by!(kind: :suspense, slug: 'suspense', currency_code: iso)
+      rescue ActiveRecord::RecordNotUnique
+        attempts += 1
+        retry if attempts <= 1
+        raise
+      end
+    end
+  end
+
+  # Raw debit-normal balance: sum(debits) - sum(credits), reading the
+  # denormalized `currency_minor` column on Posting directly (not joining
+  # Coin) so this stays cheap even before Phase 2 partitioning. Only counts
+  # postings on finalized entries — Entry.create! (bypassing `record!`) is
+  # a live, if unsanctioned, path to an unfinalized entry with postings
+  # attached, and those must never contribute to a real balance.
+  #
+  # This is intentionally kind-agnostic. Presenting a liability/equity/
+  # revenue account's balance as conventionally credit-positive is a
+  # display concern layered on top of this raw number, not baked in here.
+  #
+  # @return [Integer]
+  def balance
+    entry_class = WhittakerTech::Midas::Ledger::Entry
+    finalized = postings.joins(:entry).merge(entry_class.where.not(finalized_at: nil))
+    finalized.debit.sum(:currency_minor) - finalized.credit.sum(:currency_minor)
+  end
+
+  private
+
+  def normalize_currency_code
+    self.currency_code = currency_code.to_s.strip.upcase.presence if currency_code
+  end
+end

data/app/models/whittaker_tech/midas/ledger/entry.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+# Ledger::Entry is a balanced double-entry transaction: a group of Postings
+# (debits and credits) that must sum to zero within a single currency.
+#
+# `Ledger::Entry.record!` is the only sanctioned way to create an Entry —
+# see its documentation for why. Entries (and their Postings) are immutable
+# once finalized.
+#
+# @since 0.4.0
+class WhittakerTech::Midas::Ledger::Entry < WhittakerTech::Midas::ApplicationRecord
+  self.table_name = WhittakerTech::Midas.table_name('ledger_entries')
+
+  belongs_to :source, polymorphic: true, optional: true
+
+  has_many :postings,
+           class_name: 'WhittakerTech::Midas::Ledger::Posting',
+           dependent: :restrict_with_error,
+           inverse_of: :entry
+
+  before_validation :normalize_currency_code
+
+  validates :currency_code, presence: true, length: { is: 3 }
+  validates :occurred_at, presence: true
+
+  # These only run meaningfully in the :finalize context (see `finalize!`)
+  # — at initial `create!` time postings don't exist yet (Coin's FK
+  # requires a persisted Posting before it can attach, which in turn
+  # requires a persisted Entry — see `record!`), so validating balance at
+  # `:create` would either see zero postings or incomplete data. This is
+  # also why amount-positivity and per-posting currency-match checks live
+  # here rather than on Posting itself — by finalize time every Posting's
+  # Coin actually exists.
+  validate :postings_balance, on: :finalize
+  validate :postings_single_currency, on: :finalize
+  validate :postings_amounts_positive, on: :finalize
+  validate :postings_present, on: :finalize
+
+  before_update :block_updates
+
+  class << self
+    # The only sanctioned way to build a balanced Entry. Constructs the
+    # Entry, then each Posting, then each Posting's Coin, sequentially
+    # (required by Coin's own FK — see WhittakerTech::Midas::Coin::Converter
+    # for the identical Exchange precedent), all inside one transaction —
+    # then finalizes the Entry, which validates the fully-persisted result
+    # actually balances before stamping it immutable-and-closed. Any
+    # failure (unbalanced, mixed currency, invalid line) rolls the whole
+    # transaction back — nothing partial is ever left behind.
+    #
+    # @param currency_code [String] ISO 4217 currency code for the entry
+    # @param occurred_at [Time] business-meaningful time of the transaction
+    # @param lines [Array<Hash>] each a `{account:, direction:, amount:,
+    #   currency_code: (optional, defaults to the entry's)}` hash
+    # @param source [ActiveRecord::Base, nil] optional polymorphic source
+    #   (an Invoice, a webhook event, a reclassification's original Entry)
+    # @param memo [String, nil]
+    # @return [Entry] the persisted, finalized Entry
+    # @raise [ActiveRecord::RecordInvalid] if any line or the final balance
+    #   check fails
+    def record!(currency_code:, occurred_at:, lines:, source: nil, memo: nil)
+      iso = currency_code.to_s.strip.upcase
+
+      transaction do
+        entry = create!(currency_code: iso, occurred_at:, source:, memo:)
+
+        lines.each do |line|
+          posting = entry.postings.create!(
+            account: line.fetch(:account),
+            direction: line.fetch(:direction),
+            occurred_at: line[:occurred_at] || occurred_at
+          )
+          posting.set_amount(amount: line.fetch(:amount), currency_code: line[:currency_code] || iso)
+        end
+
+        entry.send(:finalize!)
+        entry
+      end
+    end
+  end
+
+  # @return [Boolean] whether this Entry has completed construction —
+  #   Postings may only be added/removed while an Entry is not yet
+  #   finalized (i.e. during `record!`'s own construction).
+  def finalized?
+    finalized_at.present?
+  end
+
+  private
+
+  # Reloads postings fresh from the DB (so amounts attached via `set_amount`
+  # after each Posting's own creation are visible), re-validates balance
+  # and currency consistency in the :finalize context, and — only if
+  # valid — stamps `finalized_at` via `update_column` (deliberately
+  # bypassing `block_updates`, since this is the one sanctioned internal
+  # state transition, not an external mutation).
+  def finalize!
+    postings.reload
+    raise ActiveRecord::RecordInvalid, self unless valid?(:finalize)
+
+    update_column(:finalized_at, Time.current) # rubocop:disable Rails/SkipsModelValidations
+  end
+
+  # Only checks non-empty, not "at least one debit and one credit" — the
+  # balance and positive-amount checks together already rule out a
+  # one-sided entry (a lone debit or lone credit can never balance against
+  # nothing), so this doesn't need to duplicate that logic.
+  def postings_present
+    errors.add(:base, 'an entry must have at least one posting') if postings.empty?
+  end
+
+  def postings_balance
+    debits = postings.debit.sum(:currency_minor)
+    credits = postings.credit.sum(:currency_minor)
+    errors.add(:base, "postings do not balance (#{debits} debit vs #{credits} credit)") if debits != credits
+  end
+
+  def postings_single_currency
+    coin_table = WhittakerTech::Midas::Coin.table_name
+    mismatched = postings.joins(:amount_coin).where.not(coin_table => { currency_code: currency_code }).exists?
+    errors.add(:base, 'all postings must share the entry currency_code') if mismatched
+  end
+
+  def postings_amounts_positive
+    missing = postings.where('currency_minor IS NULL OR currency_minor <= 0').exists?
+    errors.add(:base, 'all postings must have a positive amount') if missing
+  end
+
+  def normalize_currency_code
+    self.currency_code = currency_code.to_s.strip.upcase.presence if currency_code
+  end
+
+  def block_updates
+    raise ActiveRecord::ReadOnlyRecord, 'WhittakerTech::Midas::Ledger::Entry records are immutable after creation'
+  end
+end

data/app/models/whittaker_tech/midas/ledger/posting.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Ledger::Posting is a single debit or credit line within a balanced
+# Ledger::Entry. Its amount is stored twice, deliberately: via the standard
+# Bankable/Coin mechanism (`amount`, `amount_format`, `amount_in`, etc. —
+# for presentation/conversion parity with the rest of the engine) and
+# denormalized onto `currency_minor` directly on this table, which is what
+# every balance/aggregation query actually reads. This exists so Phase 2
+# partitioning of this table (by `occurred_at`) pays off — if the amount
+# only lived on the joined Coin row, partitioning postings wouldn't help
+# any query that also needs the amount.
+#
+# Postings are immutable once created, and may only be added to or removed
+# from an Entry before that Entry is finalized — see `Ledger::Entry.record!`
+# and `Ledger::Entry#finalized?`.
+#
+# @since 0.4.0
+class WhittakerTech::Midas::Ledger::Posting < WhittakerTech::Midas::ApplicationRecord
+  include WhittakerTech::Midas::Bankable
+
+  self.table_name = WhittakerTech::Midas.table_name('ledger_postings')
+
+  belongs_to :entry, class_name: 'WhittakerTech::Midas::Ledger::Entry', inverse_of: :postings
+  belongs_to :account, class_name: 'WhittakerTech::Midas::Ledger::Account', inverse_of: :postings
+
+  has_coin :amount
+  # Bankable's `has_coin` defines `set_amount` directly on this class (via
+  # `define_method` called with `self` as the includer), not through a
+  # separate module in the ancestor chain — so a `def set_amount; super;
+  # end` below would have no ancestor to reach. Alias the original before
+  # overriding so it can still be called.
+  alias attach_amount_coin set_amount
+
+  enum :direction, { debit: 'debit', credit: 'credit' }, validate: true
+
+  validates :occurred_at, presence: true
+  # account/entry are both present at creation time (before any amount is
+  # attached — see `set_amount` below), so this validates meaningfully.
+  # Amount-dependent checks (positivity, currency match) can't run at
+  # Posting-creation time at all — Coin requires a persisted `resource`
+  # before it can attach (the Exchange/Converter precedent), so `amount`
+  # is always nil until `set_amount` is called afterward. Those checks
+  # live in `Entry#finalize!` instead, where real amount data exists.
+  validate :account_currency_matches_entry, if: -> { entry && account }
+
+  before_create :ensure_entry_not_finalized!
+  before_update :block_updates
+  before_destroy :ensure_entry_not_finalized!
+
+  # Overrides Bankable's generated `set_amount` to keep the denormalized
+  # `currency_minor` column in sync with the Coin it just attached. Business
+  # validation of the resulting amount (positive, currency matches entry)
+  # happens in `Entry#finalize!`, not here — see class comment.
+  #
+  # @param amount [Money, Integer, Numeric]
+  # @param currency_code [String]
+  # @return [WhittakerTech::Midas::Coin]
+  def set_amount(amount:, currency_code:)
+    ensure_entry_not_finalized!
+
+    coin = attach_amount_coin(amount:, currency_code:)
+    update_column(:currency_minor, coin.currency_minor) # rubocop:disable Rails/SkipsModelValidations
+    coin
+  end
+
+  private
+
+  def account_currency_matches_entry
+    errors.add(:account, 'currency must match the entry currency') if account.currency_code != entry.currency_code
+  end
+
+  def ensure_entry_not_finalized!
+    return unless entry.finalized?
+
+    raise WhittakerTech::Midas::Ledger::UnbalancedEntryError,
+          'cannot add or remove postings on a finalized entry'
+  end
+
+  def block_updates
+    raise ActiveRecord::ReadOnlyRecord, 'WhittakerTech::Midas::Ledger::Posting records are immutable after creation'
+  end
+end

data/app/models/whittaker_tech/midas/ledger/unbalanced_entry_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Raised when a Posting write (create, destroy, or reattaching its amount
+# via #set_amount) is attempted against an already-finalized Entry. This is
+# the defense-in-depth backstop for any write path that bypasses
+# `Ledger::Entry.record!` — see `Ledger::Posting`'s `before_create`/
+# `before_destroy` guard (and the `set_amount` override).
+#
+# @since 0.4.0
+class WhittakerTech::Midas::Ledger::UnbalancedEntryError < StandardError; end

data/db/migrate/20260707000000_create_midas_exchanges.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'whittaker_tech/midas'
+
+class CreateMidasExchanges < ActiveRecord::Migration[8.0]
+  def change
+    create_table WhittakerTech::Midas.table_name('exchanges') do |t|
+      t.decimal :rate, precision: 24, scale: 12, null: false
+      t.string  :source, null: false
+      t.datetime :at, null: false
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260713000001_create_midas_ledger_accounts.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'whittaker_tech/midas'
+
+class CreateMidasLedgerAccounts < ActiveRecord::Migration[8.0]
+  def change
+    create_table WhittakerTech::Midas.table_name('ledger_accounts') do |t|
+      t.references :owner, polymorphic: true, null: true, index: true
+      t.string :kind, null: false
+      t.string :slug, limit: 64
+      t.string :currency_code, null: false, limit: 3
+      t.string :name
+
+      t.timestamps
+
+      t.index %i[owner_type owner_id kind currency_code],
+              unique: true,
+              name: 'index_ledger_accounts_on_owner_kind_currency'
+
+      t.index %i[slug currency_code],
+              unique: true,
+              where: 'owner_id IS NULL',
+              name: 'index_ledger_accounts_on_slug_currency_when_system'
+    end
+  end
+end

data/db/migrate/20260713000002_create_midas_ledger_entries.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'whittaker_tech/midas'
+
+class CreateMidasLedgerEntries < ActiveRecord::Migration[8.0]
+  def change
+    create_table WhittakerTech::Midas.table_name('ledger_entries') do |t|
+      t.string :currency_code, null: false, limit: 3
+      t.datetime :occurred_at, null: false
+      t.text :memo
+      t.references :source, polymorphic: true, null: true, index: true
+      t.datetime :finalized_at
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260713000003_create_midas_ledger_postings.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'whittaker_tech/midas'
+
+class CreateMidasLedgerPostings < ActiveRecord::Migration[8.0]
+  def change
+    create_table WhittakerTech::Midas.table_name('ledger_postings') do |t|
+      t.references(
+        :entry, null: false, index: true,
+                foreign_key: { to_table: WhittakerTech::Midas.table_name('ledger_entries') }
+      )
+      t.references(
+        :account, null: false, index: true,
+                  foreign_key: { to_table: WhittakerTech::Midas.table_name('ledger_accounts') }
+      )
+      t.string :direction, null: false
+      # Nullable: populated by #set_amount after the row is created (Coin
+      # requires a persisted `resource`, so a Posting always exists briefly
+      # without an amount). Entry#finalize! rejects any posting still nil.
+      t.bigint :currency_minor
+      t.datetime :occurred_at, null: false
+
+      t.timestamps
+
+      t.index %i[account_id occurred_at], name: 'index_ledger_postings_on_account_and_occurred_at'
+    end
+
+    add_check_constraint(
+      WhittakerTech::Midas.table_name('ledger_postings'),
+      "direction IN ('debit', 'credit')",
+      name: 'ledger_postings_direction_check'
+    )
+  end
+end

data/lib/whittaker_tech/midas/version.rb

@@ -1,5 +1,5 @@
 module WhittakerTech; end
 
 module WhittakerTech::Midas
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.4.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whittaker_tech-midas
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Lee Whittaker
@@ -206,6 +206,7 @@ files:
 - Rakefile
 - app/assets/config/whittaker_tech_midas_manifest.js
 - app/assets/stylesheets/whittaker_tech/midas/application.css
+- app/controllers/concerns/whittaker_tech/midas/paramable.rb
 - app/controllers/whittaker_tech/midas/application_controller.rb
 - app/helpers/whittaker_tech/midas/application_helper.rb
 - app/helpers/whittaker_tech/midas/form_helper.rb
@@ -220,8 +221,14 @@ files:
 - app/models/whittaker_tech/midas/coin/arithmetic.rb
 - app/models/whittaker_tech/midas/coin/bidi.rb
 - app/models/whittaker_tech/midas/coin/converter.rb
+- app/models/whittaker_tech/midas/coin/converter/bank_provider.rb
 - app/models/whittaker_tech/midas/coin/parser.rb
 - app/models/whittaker_tech/midas/coin/presenter.rb
+- app/models/whittaker_tech/midas/exchange.rb
+- app/models/whittaker_tech/midas/ledger/account.rb
+- app/models/whittaker_tech/midas/ledger/entry.rb
+- app/models/whittaker_tech/midas/ledger/posting.rb
+- app/models/whittaker_tech/midas/ledger/unbalanced_entry_error.rb
 - app/views/layouts/whittaker_tech/midas/application.html.erb
 - app/views/layouts/whittaker_tech/midas/shared/_currency_field.html.erb
 - config/locales/midas.en.yml
@@ -229,6 +236,10 @@ files:
 - db/migrate/20260101000001_create_midas_coins.rb
 - db/migrate/20260219120000_rename_resource_label_to_resource_role_in_wt_midas_coins.rb
 - db/migrate/20260219150000_rename_wt_midas_coins_to_midas_coins.rb
+- db/migrate/20260707000000_create_midas_exchanges.rb
+- db/migrate/20260713000001_create_midas_ledger_accounts.rb
+- db/migrate/20260713000002_create_midas_ledger_entries.rb
+- db/migrate/20260713000003_create_midas_ledger_postings.rb
 - lib/generators/whittaker_tech/midas/install/install_generator.rb
 - lib/tasks/whittaker_tech/midas_tasks.rake
 - lib/whittaker_tech/midas.rb