wallets 0.1.0 → 0.4.1

data/lib/generators/wallets/install_generator.rb

@@ -30,7 +30,7 @@ module Wallets
         say "  2. Add 'has_wallets' to any model that should own wallets."
         say "  3. Adjust config/initializers/wallets.rb for your default asset, categories, and callbacks."
         say "  4. Use owner.wallet(:asset_code) to start crediting, debiting, and transferring value."
-        say "\nYou now have an append-only wallet ledger with balances, allocations, and transfers.\n", :green
+        say "\nYou now have an append-oriented wallet ledger with balances, allocations, and transfers.\n", :green
       end
 
       private

data/lib/generators/wallets/templates/add_wallets_holds.rb.erb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+# Adds holds and reservations (wallets 0.4) to an existing wallets 0.1, 0.2
+# or 0.3 installation: the holds table, and the wallets' ledger revision.
+class AddWalletsHolds < ActiveRecord::Migration<%= migration_version %>
+  def up
+    # Incremented by every command, so a stale database snapshot can always
+    # be told from a current one, whatever the clock or a `touch` says.
+    unless column_exists?(wallets_table, :ledger_revision)
+      add_column wallets_table, :ledger_revision, :bigint, null: false, default: 0
+    end
+
+    # An app that installed 0.4 directly already has the table.
+    return if table_exists?(holds_table)
+
+    # Holds keep value in the ledger but out of the available balance: a hold
+    # on one credit, a hold on the whole wallet, or a reservation of an amount.
+    create_table holds_table, id: holds_primary_key_type do |t|
+      t.references :wallet, null: false, **key_type_of(wallets_table),
+                            foreign_key: { to_table: wallets_table },
+                            index: false
+
+      # The credit a credit hold covers. Wallet holds and reservations have none.
+      t.references :transaction, **key_type_of(transactions_table),
+                                 foreign_key: { to_table: transactions_table },
+                                 index: false
+
+      # The debit a reservation was captured into.
+      t.references :capture_transaction, **key_type_of(transactions_table),
+                                         foreign_key: { to_table: transactions_table },
+                                         index: { unique: true, name: index_name("holds_on_capture_tx") }
+
+      t.bigint :amount # reservations only
+      t.string :category, null: false
+      t.datetime :releases_at # the scheduled end
+      t.datetime :released_at # the explicit end: a release or a capture
+      t.string :release_reason
+      t.send(json_column_type, :metadata, null: false, default: json_column_default)
+      t.send(json_column_type, :release_metadata, null: false, default: json_column_default)
+
+      t.timestamps
+
+      # Ordinary composite indexes, which every adapter supports; correctness
+      # never depends on a partial index. They also serve the wallet_id and
+      # transaction_id foreign keys, and live inside the table so that MySQL
+      # can drop the table without first dropping an index a key still needs.
+      t.index [:wallet_id, :released_at], name: index_name("holds_on_wallet_and_released_at")
+      t.index [:transaction_id, :released_at], name: index_name("holds_on_tx_and_released_at")
+      t.index :releases_at, name: index_name("holds_on_releases_at")
+
+      t.check_constraint "amount IS NULL OR amount > 0", name: constraint_name("holds_amount_positive")
+      # A credit hold holds the credit's whole remaining value, never an amount.
+      t.check_constraint "transaction_id IS NULL OR amount IS NULL", name: constraint_name("holds_credit_hold_has_no_amount")
+      # Only an ended reservation can name the debit it was captured into.
+      t.check_constraint "capture_transaction_id IS NULL OR " \
+                         "(transaction_id IS NULL AND amount IS NOT NULL AND released_at IS NOT NULL)",
+                         name: constraint_name("holds_capture_ends_reservation")
+    end
+  end
+
+  # Rolling back must never delete holds, including holds this migration did
+  # not create (its `up` is a no-op when the table already exists). An empty
+  # table goes, and the ledger revision with it: the schema is 0.3's again.
+  # A table with rows stays, and says so.
+  def down
+    return unless table_exists?(holds_table)
+
+    if select_value("SELECT 1 FROM #{quote_table_name(holds_table)} LIMIT 1")
+      raise ActiveRecord::IrreversibleMigration,
+        "#{holds_table} still has holds, and rolling back would delete them. " \
+        "Drop the table deliberately if that is what you mean."
+    end
+
+    drop_table holds_table
+    remove_column wallets_table, :ledger_revision if column_exists?(wallets_table, :ledger_revision)
+  end
+
+  private
+
+  # Key types come from the tables that already exist, read when the migration
+  # runs, never from today's generator settings: the ledger may predate them,
+  # and MySQL refuses a foreign key whose column differs from the key it
+  # references (int against bigint, signed against unsigned).
+  def key_type_of(table)
+    key = primary_key_column(table)
+    options = { type: key.type }
+
+    # An integer key keeps its exact width. SQLite reports none: its rowid
+    # keys are 64-bit, which is what the install template declares.
+    if key.type == :integer && key.limit
+      options[:limit] = key.limit
+    elsif key.type == :integer
+      options[:type] = :bigint
+    end
+    options[:unsigned] = true if key.respond_to?(:unsigned?) && key.unsigned?
+
+    options
+  end
+
+  # The holds table's own key follows the ledger's: uuid for a uuid ledger,
+  # the adapter's default auto-increment key for an integer one.
+  def holds_primary_key_type
+    key = primary_key_column(wallets_table)
+    key.type == :integer ? :primary_key : key.type
+  end
+
+  def primary_key_column(table)
+    primary_key = connection.primary_key(table)
+    connection.columns(table).find { |column| column.name == primary_key }
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+
+    :json
+  end
+
+  # MySQL does not allow defaults on JSON columns, so models treat nil metadata
+  # the same as an empty hash when records are loaded. Rails' Trilogy adapter
+  # talks to MySQL too, under its own name.
+  def json_column_default
+    return nil if connection.adapter_name.match?(/mysql|trilogy/i)
+
+    {}
+  end
+
+  def table_prefix
+    Wallets.configuration.table_prefix
+  end
+
+  def wallets_table
+    "#{table_prefix}wallets"
+  end
+
+  def transactions_table
+    "#{table_prefix}transactions"
+  end
+
+  def holds_table
+    "#{table_prefix}holds"
+  end
+
+  def index_name(suffix)
+    "index_#{table_prefix}#{suffix}"
+  end
+
+  def constraint_name(suffix)
+    "check_#{table_prefix}#{suffix}"
+  end
+end

data/lib/generators/wallets/templates/create_wallets_tables.rb.erb

@@ -8,6 +8,9 @@ class CreateWalletsTables < ActiveRecord::Migration<%= migration_version %>
       t.references :owner, polymorphic: true, null: false, type: foreign_key_type
       t.string :asset_code, null: false
       t.bigint :balance, null: false, default: 0
+      # Incremented by every command, so a stale database snapshot can always
+      # be told from a current one, whatever the clock or a `touch` says.
+      t.bigint :ledger_revision, null: false, default: 0
       t.send(json_column_type, :metadata, null: false, default: json_column_default)
 
       t.timestamps
@@ -38,7 +41,7 @@ class CreateWalletsTables < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
 
-    # Allocations are the basis for the bucket-based, FIFO inventory system.
+    # Allocations are the basis for the bucket-based, first-expiring-first-out inventory system.
     create_table allocations_table, id: primary_key_type do |t|
       # The negative spend transaction that is consuming value.
       t.references :transaction, null: false, type: foreign_key_type,
@@ -55,6 +58,63 @@ class CreateWalletsTables < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
 
+    # Holds keep value in the ledger but out of the available balance: a hold
+    # on one credit, a hold on the whole wallet, or a reservation of an amount.
+    create_table holds_table, id: primary_key_type do |t|
+      t.references :wallet, null: false, type: foreign_key_type,
+                            foreign_key: { to_table: wallets_table },
+                            index: false
+
+      # The credit a credit hold covers. Wallet holds and reservations have none.
+      t.references :transaction, type: foreign_key_type,
+                                 foreign_key: { to_table: transactions_table },
+                                 index: false
+
+      # The debit a reservation was captured into.
+      t.references :capture_transaction, type: foreign_key_type,
+                                         foreign_key: { to_table: transactions_table },
+                                         index: { unique: true, name: index_name("holds_on_capture_tx") }
+
+      t.bigint :amount # reservations only
+      t.string :category, null: false
+      t.datetime :releases_at # the scheduled end
+      t.datetime :released_at # the explicit end: a release or a capture
+      t.string :release_reason
+      t.send(json_column_type, :metadata, null: false, default: json_column_default)
+      t.send(json_column_type, :release_metadata, null: false, default: json_column_default)
+
+      t.timestamps
+
+      # Ordinary composite indexes, which every adapter supports; correctness
+      # never depends on a partial index. They also serve the wallet_id and
+      # transaction_id foreign keys, and live inside the table so that MySQL
+      # can drop the table without first dropping an index a key still needs.
+      t.index [:wallet_id, :released_at], name: index_name("holds_on_wallet_and_released_at")
+      t.index [:transaction_id, :released_at], name: index_name("holds_on_tx_and_released_at")
+      t.index :releases_at, name: index_name("holds_on_releases_at")
+
+      t.check_constraint "amount IS NULL OR amount > 0", name: constraint_name("holds_amount_positive")
+      # A credit hold holds the credit's whole remaining value, never an amount.
+      t.check_constraint "transaction_id IS NULL OR amount IS NULL", name: constraint_name("holds_credit_hold_has_no_amount")
+      # Only an ended reservation can name the debit it was captured into.
+      t.check_constraint "capture_transaction_id IS NULL OR " \
+                         "(transaction_id IS NULL AND amount IS NOT NULL AND released_at IS NOT NULL)",
+                         name: constraint_name("holds_capture_ends_reservation")
+    end
+
+    add_check_constraint transfers_table,
+                         "amount > 0",
+                         name: constraint_name("transfers_amount_positive")
+    add_check_constraint transfers_table,
+                         "from_wallet_id <> to_wallet_id",
+                         name: constraint_name("transfers_distinct_wallets")
+    add_check_constraint transactions_table,
+                         "amount <> 0",
+                         name: constraint_name("transactions_amount_nonzero")
+    add_check_constraint allocations_table,
+                         "amount > 0",
+                         name: constraint_name("allocations_amount_positive")
+
     add_index transactions_table, :category
     add_index transactions_table, :expires_at
     add_index transactions_table, [:wallet_id, :amount], name: index_name("transactions_on_wallet_id_and_amount")
@@ -80,9 +140,10 @@ class CreateWalletsTables < ActiveRecord::Migration<%= migration_version %>
   end
 
   # MySQL does not allow defaults on JSON columns, so models treat nil metadata
-  # the same as an empty hash when records are loaded.
+  # the same as an empty hash when records are loaded. Rails' Trilogy adapter
+  # talks to MySQL too, under its own name.
   def json_column_default
-    return nil if connection.adapter_name.downcase.include?("mysql")
+    return nil if connection.adapter_name.match?(/mysql|trilogy/i)
 
     {}
   end
@@ -107,7 +168,15 @@ class CreateWalletsTables < ActiveRecord::Migration<%= migration_version %>
     "#{table_prefix}transfers"
   end
 
+  def holds_table
+    "#{table_prefix}holds"
+  end
+
   def index_name(suffix)
     "index_#{table_prefix}#{suffix}"
   end
+
+  def constraint_name(suffix)
+    "check_#{table_prefix}#{suffix}"
+  end
 end

data/lib/generators/wallets/templates/initializer.rb

@@ -17,6 +17,15 @@ Wallets.configure do |config|
   # config.table_prefix = "wallets_"
 
   # Set to true only if your domain explicitly supports debt or overdrafts.
+  # Applies consistently to `debit`, `transfer_to`, `reserve` and `capture!`:
+  # each may then go beyond the available balance. Cap how negative a
+  # wallet can go in your own service layer (the flag is binary).
+  #
+  # The flag decides what commands may do, not what the balance may read.
+  # With it off, the available balance can still go negative when a hold
+  # covers value that is also reserved, or when reserved value expires.
+  # Such wallets stay saveable: they take credits and releases, and refuse
+  # new spending, so turning the flag off is safe at any time.
   #
   # config.allow_negative_balance = false
 
@@ -27,7 +36,8 @@ Wallets.configure do |config|
 
   # Extra business event labels so the ledger stays readable.
   # These extend the built-in defaults:
-  # :credit, :debit, :transfer, :expiration, :adjustment
+  # :credit, :debit, :transfer_in, :transfer_out, :refund,
+  # :reward, :purchase, :top_up, :adjustment
   #
   # config.additional_categories = %w[
   #   ride_fare
@@ -48,22 +58,38 @@ Wallets.configure do |config|
   #   on_balance_credited      - After value is added to a wallet
   #   on_balance_debited       - After value is deducted from a wallet
   #   on_transfer_completed    - After a transfer between wallets succeeds
-  #   on_low_balance_reached   - When balance drops below the threshold
-  #   on_balance_depleted      - When balance reaches exactly zero
-  #   on_insufficient_balance  - When a debit or transfer is rejected
+  #   on_low_balance_reached   - When the available balance drops to the
+  #                              threshold or below (one-shot per crossing)
+  #   on_balance_depleted      - When the available balance drops from
+  #                              positive to zero or below: a debit, a hold
+  #                              or a reservation (one-shot per crossing)
+  #   on_insufficient_balance  - When a debit, transfer, reservation or
+  #                              capture is refused for lack of funds
+  #   on_hold_created          - After a hold or a reservation is placed
+  #   on_hold_released         - After hold.release! or capture! ends a hold
+  #                              (a deadline passing is computed, never
+  #                              announced)
+  #
+  # Balances work like a bank statement: wallet.balance is the AVAILABLE
+  # balance (what can be spent now), wallet.held_balance is what holds and
+  # reservations keep pending, and wallet.total_balance is both together.
+  # previous_balance and new_balance always report the available balance.
   #
   # Context object properties (available depending on event):
   #   ctx.event            # Symbol - the event name
   #   ctx.owner            # The wallet owner (User, Team, Guild, etc.)
   #   ctx.wallet           # The Wallets::Wallet instance
-  #   ctx.amount           # Balance involved
-  #   ctx.previous_balance # Balance before the operation
-  #   ctx.new_balance      # Balance after the operation
-  #   ctx.transaction      # The Wallets::Transaction record
+  #   ctx.amount           # Amount involved (a reservation's, on hold events)
+  #   ctx.previous_balance # Available balance before the operation
+  #   ctx.new_balance      # Available balance after the operation
+  #   ctx.transaction      # The Wallets::Transaction record (a capture's debit
+  #                        # on hold_released)
   #   ctx.transfer         # The Wallets::Transfer record
-  #   ctx.category         # Transaction category
+  #   ctx.hold             # The Wallets::Hold record (hold events)
+  #   ctx.category         # Transaction category (the hold's on hold events)
   #   ctx.threshold        # Low balance threshold
-  #   ctx.metadata         # Additional event-specific context
+  #   ctx.metadata         # Additional event-specific context (a hold's
+  #                        # creation metadata, or its release metadata)
   #   ctx.to_h             # Hash representation without nil values
   #
   # IMPORTANT: Keep callbacks fast. Use background jobs for email,
@@ -84,4 +110,20 @@ Wallets.configure do |config|
   # config.on_insufficient_balance do |ctx|
   #   Rails.logger.info "[Wallets] #{ctx.owner.class}##{ctx.owner.id} needs #{ctx.amount}, has #{ctx.metadata[:available]}"
   # end
+  #
+  # config.on_hold_created do |ctx|
+  #   Rails.logger.info "[Wallets] #{ctx.category} hold on #{ctx.owner.class}##{ctx.owner.id}, available #{ctx.new_balance}"
+  # end
+  #
+  # on_hold_released carries the hold's category, its amount (reservations
+  # only) and the release metadata. On a capture, ctx.transaction is the
+  # debit the capture posted, which carries the capture's metadata.
+  #
+  # config.on_hold_released do |ctx|
+  #   if ctx.transaction
+  #     Rails.logger.info "[Wallets] #{ctx.category} reservation captured as transaction #{ctx.transaction.id}"
+  #   else
+  #     Rails.logger.info "[Wallets] #{ctx.category} hold released: #{ctx.hold.release_reason}"
+  #   end
+  # end
 end

data/lib/generators/wallets/upgrade_generator.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Wallets
+  module Generators
+    # Brings an existing installation's schema up to date. Today that is one
+    # migration: the holds table that 0.4 adds to 0.1, 0.2 and 0.3 installs.
+    class UpgradeGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      # Idempotent on purpose: a second run (even after a Rails upgrade has
+      # changed the rendered migration version) points at the migration it
+      # already wrote instead of adding a duplicate, and an app whose 0.4
+      # schema is already complete (a fresh 0.4 install: the holds table and
+      # the wallets' ledger revision) gets no migration at all, so it can
+      # never hold a rollback that would drop them.
+      def create_holds_migration
+        existing_migration = self.class.migration_exists?(File.expand_path(db_migrate_path, destination_root), "add_wallets_holds")
+
+        if existing_migration
+          say_status :exist, relative_to_original_destination_root(existing_migration), :blue
+        elsif upgraded_schema?
+          @skipped = true
+          say_status :skip, "#{holds_table} already exists: there is nothing to migrate", :yellow
+        else
+          migration_template "add_wallets_holds.rb.erb", File.join(db_migrate_path, "add_wallets_holds.rb")
+        end
+      end
+
+      def display_post_upgrade_message
+        if @skipped
+          say "\n✅ This app already has the `wallets` 0.4 holds table: nothing to migrate.", :green
+          say "\nRead the 0.4.0 CHANGELOG: `balance` is now the AVAILABLE balance, and held value is excluded from it."
+          return
+        end
+
+        say "\n🎉 The `wallets` upgrade migration is ready.", :green
+        say "\nTo complete the upgrade:"
+        say "  1. Run 'rails db:migrate' to add the holds table (a no-op if it already exists)."
+        say "  2. Read the 0.4.0 CHANGELOG: `balance` is now the AVAILABLE balance, and held value is excluded from it."
+      end
+
+      private
+
+      # Asks the database when it can. One that does not exist yet, or cannot
+      # be reached, gets the migration anyway: its `up` checks again.
+      def upgraded_schema?
+        ActiveRecord::Base.with_connection do |connection|
+          connection.table_exists?(holds_table) && connection.column_exists?(wallets_table, :ledger_revision)
+        end
+      rescue ActiveRecord::ActiveRecordError
+        false
+      end
+
+      def holds_table
+        "#{Wallets.configuration.table_prefix}holds"
+      end
+
+      def wallets_table
+        "#{Wallets.configuration.table_prefix}wallets"
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/wallets/callback_context.rb

@@ -15,6 +15,7 @@ module Wallets
     :category,
     :transaction,
     :metadata,
+    :hold,
     keyword_init: true
   ) do
     def owner

data/lib/wallets/callback_dispatcher.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Wallets
+  # Shared callback execution plumbing for wallets and embedding gems.
+  # Extenders provide callback_configuration, callback_context_class, and
+  # callback_log_prefix; arity handling, freezing, and error isolation live in
+  # one place.
+  module CallbackDispatcher
+    def dispatch(event, **context_data)
+      reader = :"on_#{event}_callback"
+      config = callback_configuration
+      return unless config.respond_to?(reader)
+
+      callback = config.public_send(reader)
+      return unless callback.is_a?(Proc)
+
+      context = callback_context_class.new(event: event, **context_data).freeze
+      execute_safely(callback, context)
+    end
+
+    def execute_safely(callback, context)
+      case callback.arity
+      when 1, -1, -2
+        callback.call(context)
+      when 0
+        callback.call
+      else
+        log_warn "#{callback_log_prefix} Callback has unexpected arity (#{callback.arity}). Expected 0 or 1."
+      end
+    rescue => e
+      log_error "#{callback_log_prefix} Callback error for #{context.event}: #{e.class}: #{e.message}"
+      log_debug Array(e.backtrace).join("\n")
+    end
+
+    def log_error(message)
+      rails_logger ? rails_logger.error(message) : warn(message)
+    end
+
+    def log_warn(message)
+      rails_logger ? rails_logger.warn(message) : warn(message)
+    end
+
+    def log_debug(message)
+      rails_logger.debug(message) if rails_logger&.debug?
+    end
+
+    def rails_logger
+      Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+    end
+  end
+end

data/lib/wallets/callbacks.rb

@@ -1,53 +1,22 @@
 # frozen_string_literal: true
 
 module Wallets
-  # Centralized callback dispatcher with error isolation.
-  # Callback failures should never break the ledger write that triggered them.
+  # Wallet-specific adapter for the shared callback dispatcher.
   module Callbacks
-    module_function
-
-    def dispatch(event, **context_data)
-      callback = Wallets.configuration.public_send(:"on_#{event}_callback")
-      return unless callback.is_a?(Proc)
-
-      context = CallbackContext.new(event: event, **context_data)
-      execute_safely(callback, context)
-    end
+    extend Wallets::CallbackDispatcher
 
-    def execute_safely(callback, context)
-      case callback.arity
-      when 1, -1, -2
-        callback.call(context)
-      when 0
-        callback.call
-      else
-        log_warn "[Wallets] Callback has unexpected arity (#{callback.arity}). Expected 0 or 1."
-      end
-    rescue StandardError => e
-      log_error "[Wallets] Callback error for #{context.event}: #{e.class}: #{e.message}"
-      log_debug e.backtrace.join("\n")
-    end
+    module_function
 
-    def log_error(message)
-      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-        Rails.logger.error(message)
-      else
-        warn message
-      end
+    def callback_configuration
+      Wallets.configuration
     end
 
-    def log_warn(message)
-      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-        Rails.logger.warn(message)
-      else
-        warn message
-      end
+    def callback_context_class
+      Wallets::CallbackContext
     end
 
-    def log_debug(message)
-      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger&.debug?
-        Rails.logger.debug(message)
-      end
+    def callback_log_prefix
+      "[Wallets]"
     end
   end
 end

data/lib/wallets/configuration.rb

@@ -18,11 +18,13 @@ module Wallets
     # =========================================
 
     attr_reader :on_balance_credited_callback,
-                :on_balance_debited_callback,
-                :on_transfer_completed_callback,
-                :on_low_balance_reached_callback,
-                :on_balance_depleted_callback,
-                :on_insufficient_balance_callback
+      :on_balance_debited_callback,
+      :on_transfer_completed_callback,
+      :on_low_balance_reached_callback,
+      :on_balance_depleted_callback,
+      :on_insufficient_balance_callback,
+      :on_hold_created_callback,
+      :on_hold_released_callback
 
     def initialize
       # Keep the out-of-the-box default close to the most common "main wallet"
@@ -42,10 +44,12 @@ module Wallets
       @on_low_balance_reached_callback = nil
       @on_balance_depleted_callback = nil
       @on_insufficient_balance_callback = nil
+      @on_hold_created_callback = nil
+      @on_hold_released_callback = nil
     end
 
     def default_asset=(value)
-      value = normalize_asset_code(value)
+      value = Wallets.normalize_asset_code(value)
       raise ArgumentError, "Default asset can't be blank" if value.blank?
 
       @default_asset = value.to_sym
@@ -59,7 +63,7 @@ module Wallets
 
     def low_balance_threshold=(value)
       if value
-        value = Integer(value)
+        value = Wallets::WholeNumber.parse(value, name: "Low balance threshold", allow_string: true)
         raise ArgumentError, "Low balance threshold must be greater than or equal to zero" if value.negative?
       end
 
@@ -77,7 +81,7 @@ module Wallets
       normalized_value = value.to_s.strip.downcase.to_sym
       allowed_values = %i[preserve none]
 
-      raise ArgumentError, "Transfer expiration policy must be one of: #{allowed_values.join(', ')}" unless allowed_values.include?(normalized_value)
+      raise ArgumentError, "Transfer expiration policy must be one of: #{allowed_values.join(", ")}" unless allowed_values.include?(normalized_value)
 
       @transfer_expiration_policy = normalized_value
     end
@@ -106,12 +110,16 @@ module Wallets
       @on_insufficient_balance_callback = block
     end
 
-    private
+    def on_hold_created(&block)
+      @on_hold_created_callback = block
+    end
 
-    def normalize_asset_code(value)
-      value.to_s.strip.downcase
+    def on_hold_released(&block)
+      @on_hold_released_callback = block
     end
 
+    private
+
     def normalize_category(value)
       value.to_s.strip
     end

data/lib/wallets/engine.rb

@@ -4,15 +4,11 @@ module Wallets
   class Engine < ::Rails::Engine
     isolate_namespace Wallets
 
-    # Load wallet models early so host apps can reference them during boot.
-    config.autoload_paths << File.expand_path("models", __dir__)
-    config.autoload_paths << File.expand_path("models/concerns", __dir__)
-
-    initializer "wallets.autoload", before: :set_autoload_paths do |app|
-      app.config.autoload_paths << root.join("lib")
-      app.config.autoload_paths << root.join("lib/wallets/models")
-      app.config.autoload_paths << root.join("lib/wallets/models/concerns")
-    end
+    # All gem code is required eagerly by lib/wallets.rb, so nothing here is
+    # added to the host app's autoload paths. Registering lib/wallets/models
+    # with Zeitwerk would claim top-level constants like ::Wallet and
+    # ::Transaction and shadow (break) host apps that define models with
+    # those very common names.
 
     initializer "wallets.active_record" do
       ActiveSupport.on_load(:active_record) do