Start and end balance anchors for historical account balances (#2455)

* Add kind field to valuation

* Fix schema conflict

* Add kind to valuation

* Scaffold opening balance manager

* Opening balance manager implementation

* Update account import to use opening balance manager + tests

* Update account to use opening balance manager

* Fix test assertions, usage of current balance manager

* Lint fixes

* Add Opening Balance manager, add tests to forward calculator

* Add credit card to "all cash" designation

* Simplify valuation model

* Add current balance manager with tests

* Add current balance logic to reverse calculator and plaid sync

* Tweaks to initial calc logic

* Ledger testing helper, tweak assertions for reverse calculator

* Update test assertions

* Extract balance transformer, simplify calculators

* Algo simplifications

* Final tweaks to calculators

* Cleanup

* Fix error, propagate sync errors up to parent

* Update migration script, valuation naming

app/models/balance/base_calculator.rb

@@ -0,0 +1,82 @@
+class Balance::BaseCalculator
+  attr_reader :account
+
+  def initialize(account)
+    @account = account
+  end
+
+  def calculate
+    raise NotImplementedError, "Subclasses must implement this method"
+  end
+
+  private
+    def sync_cache
+      @sync_cache ||= Balance::SyncCache.new(account)
+    end
+
+    def holdings_value_for_date(date)
+      holdings = sync_cache.get_holdings(date)
+      holdings.sum(&:amount)
+    end
+
+    def derive_cash_balance_on_date_from_total(total_balance:, date:)
+      if balance_type == :investment
+        total_balance - holdings_value_for_date(date)
+      elsif balance_type == :cash
+        total_balance
+      else
+        0
+      end
+    end
+
+    def derive_cash_balance(cash_balance, date)
+      entries = sync_cache.get_entries(date)
+
+      if balance_type == :non_cash
+        0
+      else
+        cash_balance + signed_entry_flows(entries)
+      end
+    end
+
+    def derive_non_cash_balance(non_cash_balance, date, direction: :forward)
+      entries = sync_cache.get_entries(date)
+      # Loans are a special case (loan payment reducing principal, which is non-cash)
+      if balance_type == :non_cash && account.accountable_type == "Loan"
+        non_cash_balance + signed_entry_flows(entries)
+      elsif balance_type == :investment
+        # For reverse calculations, we need the previous day's holdings
+        target_date = direction == :forward ? date : date.prev_day
+        holdings_value_for_date(target_date)
+      else
+        non_cash_balance
+      end
+    end
+
+    def signed_entry_flows(entries)
+      raise NotImplementedError, "Directional calculators must implement this method"
+    end
+
+    def balance_type
+      case account.accountable_type
+      when "Depository", "CreditCard"
+        :cash
+      when "Property", "Vehicle", "OtherAsset", "Loan", "OtherLiability"
+        :non_cash
+      when "Investment", "Crypto"
+        :investment
+      else
+        raise "Unknown account type: #{account.accountable_type}"
+      end
+    end
+
+    def build_balance(date:, cash_balance:, non_cash_balance:)
+      Balance.new(
+        account_id: account.id,
+        date: date,
+        balance: non_cash_balance + cash_balance,
+        cash_balance: cash_balance,
+        currency: account.currency
+      )
+    end
+end

app/models/balance/forward_calculator.rb

@@ -1,61 +1,66 @@
-class Balance::ForwardCalculator
-  attr_reader :account
-
-  def initialize(account)
-    @account = account
-  end
-
+class Balance::ForwardCalculator < Balance::BaseCalculator
   def calculate
     Rails.logger.tagged("Balance::ForwardCalculator") do
-      calculate_balances
+      start_cash_balance = derive_cash_balance_on_date_from_total(
+        total_balance: account.opening_anchor_balance,
+        date: account.opening_anchor_date
+      )
+      start_non_cash_balance = account.opening_anchor_balance - start_cash_balance
+
+      calc_start_date.upto(calc_end_date).map do |date|
+        valuation = sync_cache.get_reconciliation_valuation(date)
+
+        if valuation
+          end_cash_balance = derive_cash_balance_on_date_from_total(
+            total_balance: valuation.amount,
+            date: date
+          )
+          end_non_cash_balance = valuation.amount - end_cash_balance
+        else
+          end_cash_balance = derive_end_cash_balance(start_cash_balance: start_cash_balance, date: date)
+          end_non_cash_balance = derive_end_non_cash_balance(start_non_cash_balance: start_non_cash_balance, date: date)
+        end
+
+        output_balance = build_balance(
+          date: date,
+          cash_balance: end_cash_balance,
+          non_cash_balance: end_non_cash_balance
+        )
+
+        # Set values for the next iteration
+        start_cash_balance = end_cash_balance
+        start_non_cash_balance = end_non_cash_balance
+
+        output_balance
+      end
     end
   end
 
   private
-    def calculate_balances
-      current_cash_balance = 0
-      next_cash_balance = nil
-
-      @balances = []
-
-      account.start_date.upto(Date.current).each do |date|
-        entries = sync_cache.get_entries(date)
-        holdings = sync_cache.get_holdings(date)
-        holdings_value = holdings.sum(&:amount)
-        valuation = sync_cache.get_valuation(date)
-
-        next_cash_balance = if valuation
-          valuation.amount - holdings_value
-        else
-          calculate_next_balance(current_cash_balance, entries, direction: :forward)
-        end
-
-        @balances << build_balance(date, next_cash_balance, holdings_value)
-
-        current_cash_balance = next_cash_balance
-      end
-
-      @balances
+    def calc_start_date
+      account.opening_anchor_date
     end
 
-    def sync_cache
-      @sync_cache ||= Balance::SyncCache.new(account)
+    def calc_end_date
+      [ account.entries.order(:date).last&.date, account.holdings.order(:date).last&.date ].compact.max || Date.current
     end
 
-    def build_balance(date, cash_balance, holdings_value)
-      Balance.new(
-        account_id: account.id,
-        date: date,
-        balance: holdings_value + cash_balance,
-        cash_balance: cash_balance,
-        currency: account.currency
-      )
+    # Negative entries amount on an "asset" account means, "account value has increased"
+    # Negative entries amount on a "liability" account means, "account debt has decreased"
+    # Positive entries amount on an "asset" account means, "account value has decreased"
+    # Positive entries amount on a "liability" account means, "account debt has increased"
+    def signed_entry_flows(entries)
+      entry_flows = entries.sum(&:amount)
+      account.asset? ? -entry_flows : entry_flows
     end
 
-    def calculate_next_balance(prior_balance, transactions, direction: :forward)
-      flows = transactions.sum(&:amount)
-      negated = direction == :forward ? account.asset? : account.liability?
-      flows *= -1 if negated
-      prior_balance + flows
+    # Derives cash balance, starting from the start-of-day, applying entries in forward to get the end-of-day balance
+    def derive_end_cash_balance(start_cash_balance:, date:)
+      derive_cash_balance(start_cash_balance, date)
+    end
+
+    # Derives non-cash balance, starting from the start-of-day, applying entries in forward to get the end-of-day balance
+    def derive_end_non_cash_balance(start_non_cash_balance:, date:)
+      derive_non_cash_balance(start_non_cash_balance, date, direction: :forward)
     end
 end

app/models/balance/reverse_calculator.rb

@@ -1,71 +1,79 @@
-class Balance::ReverseCalculator
-  attr_reader :account
-
-  def initialize(account)
-    @account = account
-  end
-
+class Balance::ReverseCalculator < Balance::BaseCalculator
   def calculate
     Rails.logger.tagged("Balance::ReverseCalculator") do
-      calculate_balances
+      # Since it's a reverse sync, we're starting with the "end of day" balance components and
+      # calculating backwards to derive the "start of day" balance components.
+      end_cash_balance = derive_cash_balance_on_date_from_total(
+        total_balance: account.current_anchor_balance,
+        date: account.current_anchor_date
+      )
+      end_non_cash_balance = account.current_anchor_balance - end_cash_balance
+
+      # Calculates in reverse-chronological order (End of day -> Start of day)
+      account.current_anchor_date.downto(account.opening_anchor_date).map do |date|
+        if use_opening_anchor_for_date?(date)
+          end_cash_balance = derive_cash_balance_on_date_from_total(
+            total_balance: account.opening_anchor_balance,
+            date: date
+          )
+          end_non_cash_balance = account.opening_anchor_balance - end_cash_balance
+
+          start_cash_balance = end_cash_balance
+          start_non_cash_balance = end_non_cash_balance
+
+          build_balance(
+            date: date,
+            cash_balance: end_cash_balance,
+            non_cash_balance: end_non_cash_balance
+          )
+        else
+          start_cash_balance = derive_start_cash_balance(end_cash_balance: end_cash_balance, date: date)
+          start_non_cash_balance = derive_start_non_cash_balance(end_non_cash_balance: end_non_cash_balance, date: date)
+
+          # Even though we've just calculated "start" balances, we set today equal to end of day, then use those
+          # in our next iteration (slightly confusing, but just the nature of a "reverse" sync)
+          output_balance = build_balance(
+            date: date,
+            cash_balance: end_cash_balance,
+            non_cash_balance: end_non_cash_balance
+          )
+
+          end_cash_balance = start_cash_balance
+          end_non_cash_balance = start_non_cash_balance
+
+          output_balance
+        end
+      end
     end
   end
 
   private
-    def calculate_balances
-      current_cash_balance = account.cash_balance
-      previous_cash_balance = nil
 
-      @balances = []
-
-      Date.current.downto(account.start_date).map do |date|
-        entries = sync_cache.get_entries(date)
-        holdings = sync_cache.get_holdings(date)
-        holdings_value = holdings.sum(&:amount)
-        valuation = sync_cache.get_valuation(date)
-
-        previous_cash_balance = if valuation
-          valuation.amount - holdings_value
-        else
-          calculate_next_balance(current_cash_balance, entries, direction: :reverse)
-        end
-
-        if valuation.present?
-          @balances << build_balance(date, previous_cash_balance, holdings_value)
-        else
-          # If date is today, we don't distinguish cash vs. total since provider's are inconsistent with treatment
-          # of the cash component.  Instead, just set the balance equal to the "total value" reported by the provider
-          if date == Date.current
-            @balances << build_balance(date, account.cash_balance, account.balance - account.cash_balance)
-          else
-            @balances << build_balance(date, current_cash_balance, holdings_value)
-          end
-        end
-
-        current_cash_balance = previous_cash_balance
-      end
-
-      @balances
+    # Negative entries amount on an "asset" account means, "account value has increased"
+    # Negative entries amount on a "liability" account means, "account debt has decreased"
+    # Positive entries amount on an "asset" account means, "account value has decreased"
+    # Positive entries amount on a "liability" account means, "account debt has increased"
+    def signed_entry_flows(entries)
+      entry_flows = entries.sum(&:amount)
+      account.asset? ? entry_flows : -entry_flows
     end
 
-    def sync_cache
-      @sync_cache ||= Balance::SyncCache.new(account)
+    # Reverse syncs are a bit different than forward syncs because we do not allow "reconciliation" valuations
+    # to be used at all. This is primarily to keep the code and the UI easy to understand. For a more detailed
+    # explanation, see the test suite.
+    def use_opening_anchor_for_date?(date)
+      account.has_opening_anchor? && date == account.opening_anchor_date
     end
 
-    def build_balance(date, cash_balance, holdings_value)
-      Balance.new(
-        account_id: account.id,
-        date: date,
-        balance: holdings_value + cash_balance,
-        cash_balance: cash_balance,
-        currency: account.currency
-      )
+    # Alias method, for algorithmic clarity
+    # Derives cash balance, starting from the end-of-day, applying entries in reverse to get the start-of-day balance
+    def derive_start_cash_balance(end_cash_balance:, date:)
+      derive_cash_balance(end_cash_balance, date)
     end
 
-    def calculate_next_balance(prior_balance, transactions, direction: :forward)
-      flows = transactions.sum(&:amount)
-      negated = direction == :forward ? account.asset? : account.liability?
-      flows *= -1 if negated
-      prior_balance + flows
+    # Alias method, for algorithmic clarity
+    # Derives non-cash balance, starting from the end-of-day, applying entries in reverse to get the start-of-day balance
+    def derive_start_non_cash_balance(end_non_cash_balance:, date:)
+      derive_non_cash_balance(end_non_cash_balance, date, direction: :reverse)
     end
 end

app/models/balance/sync_cache.rb

@@ -3,8 +3,8 @@ class Balance::SyncCache
     @account = account
   end
 
-  def get_valuation(date)
-    converted_entries.find { |e| e.date == date && e.valuation? }
+  def get_reconciliation_valuation(date)
+    converted_entries.find { |e| e.date == date && e.valuation? && e.valuation.reconciliation? }
   end
 
   def get_holdings(date)

app/models/balance/trend_calculator.rb

@@ -18,7 +18,7 @@ class Balance::TrendCalculator
     BalanceTrend.new(
       trend: Trend.new(
         current: Money.new(balance.balance, balance.currency),
-        previous: Money.new(prior_balance.balance, balance.currency),
+        previous: prior_balance.present? ? Money.new(prior_balance.balance, balance.currency) : nil,
         favorable_direction: balance.account.favorable_direction
       ),
       cash: Money.new(balance.cash_balance, balance.currency),