whittaker_tech-midas 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3fd5f9cd2e7d3ffac65eaedd6353fca8f73ad4e786207f8402791b485454ff0
-  data.tar.gz: 30445ce5ed3a5ebf775f56c8a05afaf9eb401bac0f0a84a624cc9d4ddafbe9b8
+  metadata.gz: fe9c21222c40c9da18f01c21076e775b5d00f6f7b817f2c06c05223cdd88de8b
+  data.tar.gz: 50ec83ec5d2b1fbe82e3856180ce63c8bc35f458679f14ab3fdd800229ef519d
 SHA512:
-  metadata.gz: 82e65cff44ba88558f2ee2563f107c88399ad41d65e008ae23b8d89846982c292be06c5dfbe3518810b11a1986359156b29119831614ac93d87d2ba5d28c99ef
-  data.tar.gz: b14740dd0c7ec5fc0d195fabf5bb81da564e456693a4cef8bca03f042a5964a03a7754776fa24cf9c2dca0b6bfb551ec075ef4da841cdfe674e1c50c9cb4b1c5
+  metadata.gz: 4833df22795e85d8e837bd2c0fa81ee6cf593a401463daf7ca42b6adf659be45cecd497213a0641d363c1523019fd2ac616265212aca85e531ee56d9d50efb7f
+  data.tar.gz: bdcf127c769350759698cfefb12babe569c5c0c2ed907b3127212e2d806ff3c8eec0d9dedde9f62b6ec59721683e8fa99b21eeef883a6148166d567673dce20a

data/README.md

@@ -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
 
@@ -273,6 +274,73 @@ provider — useful for testing or wiring in a rate API directly:
 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

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/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/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.3.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.3.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
@@ -224,6 +225,10 @@ files:
 - 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
@@ -232,6 +237,9 @@ files:
 - 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