Negative-balance correctness: fix transfer_to + :balance_depleted, audit + pin documented behavior

[rameerez]

Summary

Wallets.configuration.allow_negative_balance was half-applied: direct wallet.debit honored it via apply_debit, but the canonical wallet.transfer_to had its own balance pre-check that always rejected transfers below zero — regardless of the flag. Apps using the flag for a "convenience overdraft" (ride-fare apps where passengers briefly go negative until rewards land, family wallets with shared spend, telecom plans with bridging credit) got inconsistent behavior and had to monkey-patch the gem.

This PR fixes that, and follows up with a full audit of every code path that touches balance under allow_negative_balance = true. The audit found one more real bug (:balance_depleted callback was missing positive→negative crossings) and several documented subtleties that needed explicit test coverage so future changes can't quietly regress them.

Bug fixes

Wallet#transfer_to honors allow_negative_balance

lib/wallets/models/wallet.rb:

• The insufficient-balance pre-check is now gated on !allow_negative_balance?, matching apply_debit's long-standing semantics. When the flag is on, the transfer goes through; the source wallet records the deficit as an unbacked negative transaction (the same shape wallet.debit already produced).
• When a transfer drives the source below zero AND the caller is using the default :preserve expiration policy, the policy automatically falls back to :none for that transfer. There are no positive source buckets to inherit expirations from for the deficit portion, so build_preserved_transfer_inbound_credit_specs would otherwise raise InvalidTransfer on the count mismatch. The receiver gets a single evergreen credit — the only honest representation of "value created without a source bucket".
• Explicit :fixed (with expires_at:) and explicit :none are honored unchanged — those policies don't depend on source-bucket walking.
• The :insufficient_balance callback no longer fires for successful overdraft transfers. It still fires (and the transfer still raises Wallets::InsufficientBalance) when the flag is off and the transfer is rejected.

:balance_depleted callback fires on positive→non-positive crossings

Previously fired only on exact zero. With allow_negative_balance = true, a single debit can take a wallet from e.g. +100 to -50, skipping zero entirely, and the callback was silently missing. Widened the condition from balance.zero? to !balance.positive?. With the flag off, balances can't go below zero, so the new condition collapses to "exactly zero" and existing callers see no behavior change.

Documented behavior, now pinned by tests

These were correct already but easy to break — the audit pass added explicit coverage and inline comments so they stay correct:

• Compounding debits accumulate unbacked_amount per row; the gem doesn't spread debt across debits.
• A credit on a negative-balance wallet does NOT auto-allocate against existing unbacked debits. Both ledger entries persist; balance reconciles them on the fly. FIFO consumption on the next debit pulls from the new credit, not the old debt.
• has_enough_balance? keeps strict semantics under the flag: it answers "do you have it on hand?", not "would the gem accept this debit?". Overdraft is a deliberate caller choice.
• balance_before / balance_after snapshots correctly record signed integers across the positive→negative boundary.
• Flipping allow_negative_balance OFF while wallets are below zero leaves them un-saveable until the flag is flipped back on. The model's balance >= 0 validation is gated on the flag, and refresh_cached_balance! calls save! on every credit/debit. The flag is meant to be a stable config decision, not a runtime toggle. Test pins both the lockup and the recovery path.
• :low_balance_reached is one-shot per crossing — going from -50 to -80 doesn't re-fire because the wallet was already low; coming back up to +200 then dipping low again does fire.
• Concurrent overdraft debits on the same wallet serialize through with_lock (FOR UPDATE) and accumulate cleanly without double-counting previous_balance. Concurrent transfers serialize through lock_wallet_pair!.

Tests

22 new tests across transfer_test.rb, wallet_test.rb, wallet_callbacks_test.rb. Existing tests covering the old "transfers always reject below zero" and "depleted = exactly zero" semantics are amended to reflect the new contracts.

Run	Result
bundle exec rake test	92 / 338 assertions, all green
gemfiles/rails_7.2.gemfile	92 / 338 assertions, all green
gemfiles/rails_8.1.gemfile	92 / 338 assertions, all green

Compatibility

• allow_negative_balance defaults to false, so apps that haven't opted in see no behavior change.
• :balance_depleted semantic widening is a no-op under default config (balance can't go below zero).
• Apps that previously caught Wallets::InsufficientBalance from transfer_to after flipping the flag on (i.e. were aware of the half-applied behavior and relied on it as a guardrail) need to know transfers will now go through. The README gains a "Negative balances and overdraft" section calling this out and the recommended pattern of layering an app-level floor policy in front.

Documentation

• README gains a "Negative balances and overdraft" section covering: the unified wallet.debit / wallet.transfer_to contract, the floor-is-yours-to-enforce model, the :preserve→:none fallback, :balance_depleted semantics, :low_balance one-shot behavior, credit-doesn't-settle-prior-debt, the flag-flip lockup, concurrency guarantees, and the system-reversal use case.
• CHANGELOG.md updated for 0.2.0.
• Initializer template comment on allow_negative_balance warns against runtime-toggling; on_balance_depleted docstring updated to reflect the crossing-into-non-positive semantic.

Bumps version to 0.2.0.

🤖 Generated with Claude Code