finrb 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b167e3a39320ed5f8026b7451063d08f6eeb8e1047dc06f7688e4afc617434c2
-  data.tar.gz: 9407136f5589353ab3704f9bd7bb37b802191aa3aa51ca2bc3248cf359a276da
+  metadata.gz: 8474be54c480d3150125ba2a00e7b935fbfb10281ce857304889ebca48839bac
+  data.tar.gz: 571f0f38b0a662c749df453e314cb3f916efe27e2f466896e600719a9048aef1
 SHA512:
-  metadata.gz: 9ec1ff7159e4d1aadd5dde4fcb168a0f1a7679e20f59c50bb26a642ccbee1e6aa65b021e67906586382e64aca23a240e566625ea359dc48e9aa2987e24a9c433
-  data.tar.gz: 671ae01b065e636c0bf8ef60e851e53866b02e09238d3a233443150a11f09851af493a2462e891a305ce174c6cb57ba492f09f6cfef48ded3693a120e448c410
+  metadata.gz: 31edbc91ddfe6bfd433daaae2598be24b7fe22d604e40745b238a66c01ad8cd597d9a441b4643f9cd0a1adc5230cd2e3780fc1ba791e5799e921ffb0a6bc6e59
+  data.tar.gz: 59b760dfb7f1c27686d34362ad9da310b2bb20ccfc440b42f39e6c551fd14c1ac134dd3ed8795e0cf9d4274c264e085a95b59339bd71b5c11e6763f99f9b82a1

data/CHANGELOG.md

@@ -1,5 +1,55 @@
 # finrb changelog
 
+## 1.2.0
+
+### Validation and financial correctness
+
+- Apply the shared finite-decimal validation contract across yields, returns,
+  accounting, ratios, cashflows, rates, amortization, and TVM helpers.
+- Replace abbreviated validation errors with descriptive financial terms such
+  as period count, future value, face value, and compounding periods.
+- Add explicit denominator, rate, share-count, inventory, useful-life, and
+  residual-value domain checks while preserving valid decimal calculations and
+  return types.
+- Fix LIFO ending-inventory retention when a sale is satisfied by the second
+  purchase layer, preserving inventory cost conservation.
+- Reject invalid weighted-return vectors and replace the previous unsolicited
+  weighted-portfolio warning with an explicit validation error.
+
+### Development and project maintenance
+
+- Add deterministic `benchmark:run` scenarios using `benchmark-ips` for IRR,
+  XIRR, and amortization scaling, with known-root, equation-residual, solver
+  evaluation, and schedule-reconciliation preflight diagnostics.
+- Add contributor and security guidance, and link the project entry documents
+  from the README.
+- Include contributor and security documentation in packaged gem metadata.
+
+## 1.1.0
+
+### Investment returns and risk
+
+- Add compound annual growth rate (CAGR) with explicit value and period-domain validation.
+- Add modified internal rate of return (MIRR) with separate financing and reinvestment rates.
+- Add sample and population volatility, downside deviation, Sortino ratio, and maximum drawdown.
+- Add compound-return and square-root-of-time volatility annualization helpers.
+- Define the statistical conventions explicitly: volatility is sample-based by default, downside deviation includes all observations in its denominator, and maximum drawdown is returned as a non-negative loss fraction.
+
+### Loan schedules
+
+- Expose each amortization period as an immutable `Finrb::Amortization::Entry` containing its period, opening and closing balances, payment, interest, principal, additional principal, balloon settlement, and interest-only state.
+- Preserve the existing cashflow convention: payments are negative, while balances, interest, principal repaid, and additional principal are non-negative.
+- Add contractual balloon targets. Regular installments amortize toward the target and the final payment settles the residual, including cent-rounding reconciliation.
+- Add leading interest-only periods, including zero-rate periods and combinations with balloon loans. Remaining principal amortizes over the rest of the term.
+- Add upfront and financed origination fees with separate `principal`, `net_proceeds`, and `amount_financed` values. Financed fees enter the opening balance; upfront fees reduce borrower proceeds.
+- Correct schedule period numbering across rate segments and reused payment templates.
+
+### API and documentation
+
+- Add RBS declarations and API examples for all new return metrics and amortization features.
+- Refine README compatibility badges to identify tested MRI versions, x86-64/ARM64 architectures, and experimental JRuby/TruffleRuby coverage.
+- Remove redundant YARD `@api` annotations and make the internal amortization calculation methods genuinely private.
+
 ## 1.0.1
 
 ### Runtime compatibility

data/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to finrb
+
+finrb welcomes focused bug fixes, documentation improvements, tests, and
+financial calculations that fit the project's scope. Before starting a large
+feature or public API change, open an issue so its financial conventions and
+design can be agreed upon first.
+
+## Development setup
+
+finrb requires Ruby 3.3 or newer. MRI 3.3, 3.4, and 4.0 are supported; JRuby
+and TruffleRuby are tested as informational compatibility targets.
+
+```shell
+bundle install
+bundle exec rake quality
+bundle exec rubocop
+```
+
+`rake quality` runs the RSpec suite with coverage, verifies maintained API
+examples, and validates the packaged RBS declarations. Additional checks are
+available for changes that affect their domains:
+
+```shell
+bundle exec rake security:audit
+bundle exec rake package:verify
+bundle exec rake benchmark:run
+bundle exec rake solver:verify
+```
+
+The solver verification task requires the optional Python environment
+documented in [spec/fixtures/README.md](spec/fixtures/README.md). The Python
+packages are development references and are not gem dependencies.
+
+## Making changes
+
+- Preserve unrelated code and behavior. Keep pull requests small enough to
+  review their financial and numerical consequences directly.
+- Follow the local Ruby style and run RuboCop. Comments should explain a
+  non-obvious reason or convention, not restate the code.
+- Route public numeric inputs through `Finrb::Validation`. Use `ArgumentError`
+  for malformed inputs and namespaced finrb errors for financial or numerical
+  domains.
+- Preserve `Flt::DecNum` calculations and return types unless the change has a
+  documented compatibility reason.
+- Update RBS declarations and user documentation when a public contract
+  changes.
+- Do not add an unreleased changelog section for ordinary development work.
+  The maintainer prepares the changelog as part of an actual release.
+
+## Numerical and financial changes
+
+A formula compiling or producing a plausible number is not sufficient
+verification. Describe the convention being implemented and test the relevant
+invariants, boundaries, and failure modes.
+
+For a solver or precision-sensitive change, include as appropriate:
+
+- known-root or algebraically constructed cases;
+- normalized equation residuals;
+- zero, negative-rate, long-horizon, and scale-sensitive cases;
+- attributable fixtures from a reputable independent implementation under
+  matching financial conventions;
+- deterministic seeds for generated cases; and
+- benchmarks that compare the same scenario across revisions, runtimes, or
+  architectures rather than ranking unrelated calculations.
+
+Reference fixtures must record their source, version, conventions, generation
+method, and tolerance. Do not replace committed fixtures merely to make a
+changed implementation pass without explaining why the reference changed.
+
+## Pull requests
+
+Use the pull request template and include:
+
+- the financial or technical problem;
+- the intended contract and compatibility impact;
+- the evidence used to verify correctness; and
+- any checks skipped because an optional runtime or external reference was
+  unavailable.
+
+Commit subjects in this repository commonly use the form
+`domain [Category]: Imperative summary`, for example:
+
+```text
+cashflows [Fix]: Preserve negative-root selection
+```
+
+By contributing, you agree that your work is provided under the repository's
+LGPL-3.0-or-later license.

data/README.md

@@ -3,6 +3,9 @@
 [![CI](https://github.com/ncs1/finrb/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ncs1/finrb/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/ncs1/finrb/actions/workflows/codeql.yml/badge.svg)](https://github.com/ncs1/finrb/actions/workflows/codeql.yml)
 [![RuboCop](https://github.com/ncs1/finrb/actions/workflows/rubocop.yml/badge.svg)](https://github.com/ncs1/finrb/actions/workflows/rubocop.yml)
+[![MRI](https://img.shields.io/badge/MRI-3.3_%7C_3.4_%7C_4.0-CC342D?logo=ruby&logoColor=white)](https://github.com/ncs1/finrb/actions/workflows/ci.yml)
+[![Architectures](https://img.shields.io/badge/architectures-x86__64_%7C_arm64-4169E1)](https://github.com/ncs1/finrb/actions/workflows/ci.yml)
+[![Experimental engines](https://img.shields.io/badge/experimental-JRuby_%7C_TruffleRuby-F0AD4E)](https://github.com/ncs1/finrb/actions/workflows/ci.yml)
 
 Precision-first financial mathematics for Ruby.
 
@@ -61,8 +64,8 @@ API explicitly returns another financial object, such as `Finrb::Rate`.
 | `Finrb::Ratios` | Liquidity, leverage, profitability, and per-share ratios |
 | `Finrb::Accounting` | Inventory costing and depreciation |
 
-The detailed [API and examples guide](docs/api.md) lists each calculation and
-its parameters. Packaged RBS declarations are available under `sig/`.
+The [API and examples guide](docs/api.md) documents each financial domain and
+its public calculations. Packaged RBS declarations are available under `sig/`.
 
 ## Cashflows
 
@@ -117,6 +120,15 @@ loan = Finrb::Amortization.new(250_000, rate)
 loan.payment      # => Flt::DecNum('-1229.85')
 loan.interest.sum # => Flt::DecNum('192745.98')
 loan.balance      # => Flt::DecNum('0.00')
+
+first = loan.schedule.first
+first.opening_balance
+first.interest
+first.principal
+first.payment
+first.balloon_payment
+first.interest_only?
+first.closing_balance
 ```
 
 Pass several duration-bearing rates for an adjustable-rate schedule. A block
@@ -130,6 +142,48 @@ end
 
 Payments and interest follow the sign convention used throughout finrb:
 money received is positive and money paid is negative.
+Schedule balances, interest, principal repaid, and additional principal are
+non-negative; the schedule's payment field is negative.
+
+Set a residual principal target to create a balloon loan. Regular installments
+amortize only the non-balloon portion, and the final payment settles the stated
+balloon:
+
+```ruby
+balloon_loan = Finrb::Amortization.new(250_000, rate, balloon: 100_000)
+balloon_loan.schedule.last.balloon_payment # => Flt::DecNum('100000')
+```
+
+`balloon` is the contractual residual target. Because regular postings are
+rounded to cents, the actual `balloon_payment` in the final schedule row can
+differ from that target by a few cents.
+
+Leading interest-only periods defer scheduled principal repayment and amortize
+the balance over the remaining term:
+
+```ruby
+interest_only = Finrb::Amortization.new(250_000, rate, interest_only_periods: 24)
+interest_only.schedule.first.interest_only? # => true
+interest_only.schedule.first.principal      # => Flt::DecNum('0')
+```
+
+Origination fees can either reduce the borrower's net proceeds or be added to
+the financed balance:
+
+```ruby
+cash_fee = Finrb::Amortization.new(250_000, rate, origination_fee: 2_500)
+cash_fee.net_proceeds    # => Flt::DecNum('247500')
+cash_fee.amount_financed # => Flt::DecNum('250000')
+
+financed_fee = Finrb::Amortization.new(
+  250_000,
+  rate,
+  origination_fee: 2_500,
+  finance_origination_fee: true
+)
+financed_fee.net_proceeds    # => Flt::DecNum('250000')
+financed_fee.amount_financed # => Flt::DecNum('252500')
+```
 
 ## Configuration
 
@@ -284,6 +338,8 @@ Docker, batching, and tolerance details.
 - [RubyGems](https://rubygems.org/gems/finrb)
 - [Source](https://github.com/ncs1/finrb)
 - [Issue tracker](https://github.com/ncs1/finrb/issues)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
 
 ## Acknowledgements
 

data/SECURITY.md

@@ -0,0 +1,41 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are made against the current released finrb line. Older
+versions may receive a fix when practical, but they are not guaranteed to be
+maintained. Users should reproduce an issue on the newest release before
+reporting it when possible.
+
+JRuby and TruffleRuby are informational compatibility targets. A
+runtime-specific vulnerability may also need to be reported to the relevant
+Ruby implementation or dependency maintainers.
+
+## Reporting a vulnerability
+
+Do not disclose a suspected vulnerability in a public issue, discussion, or
+pull request. Use GitHub's private vulnerability reporting for finrb:
+
+<https://github.com/ncs1/finrb/security/advisories/new>
+
+If private reporting is unavailable, contact the maintainer through the email
+listed in the gem metadata. Include only enough information in the initial
+message to establish a private channel.
+
+A useful report contains:
+
+- affected finrb and Ruby versions;
+- the affected API or packaged artifact;
+- minimal reproduction steps;
+- the expected and observed impact; and
+- any known mitigations or disclosure constraints.
+
+Please avoid including production credentials, private financial data, access
+tokens, or other secrets. There is no guaranteed response or remediation
+timeline; this project is maintained by one person. Reports will be evaluated
+according to reproducibility, impact, and available maintainer capacity.
+
+Numerical disagreement alone is normally a correctness bug rather than a
+security vulnerability. Treat it as security-sensitive when it can cross a
+trust boundary, bypass validation, enable denial of service, corrupt packaged
+artifacts, or predictably cause unsafe downstream financial decisions.

data/lib/finrb/accounting.rb

@@ -2,6 +2,7 @@
 
 require_relative 'decimal'
 require_relative 'errors'
+require_relative 'validation'
 
 module Finrb
   # Inventory costing and depreciation calculations.
@@ -34,74 +35,32 @@ module Finrb
     # @example
     #   Finrb::Accounting.cogs(uinv=2,pinv=2,units=[3,5],price=[3,5],sinv=7,method="WAC")
     def self.cogs(uinv:, pinv:, units:, price:, sinv:, method: 'FIFO')
-      uinv = Flt::DecNum(uinv.to_s)
-      pinv = Flt::DecNum(pinv.to_s)
-      units = wrap_array(units).map { |value| Flt::DecNum(value.to_s) }
-      price = wrap_array(price).map { |value| Flt::DecNum(value.to_s) }
-      sinv = Flt::DecNum(sinv.to_s)
-      method = method.to_s
+      uinv, pinv, units, price, sinv, method = inventory_inputs(uinv:, pinv:, units:, price:, sinv:, method:)
 
       n = units.size
-      m = price.size
-      cost_of_goods = 0
-      ending_inventory = 0
-      if m == n
-        case method
-        when 'FIFO'
-          if sinv <= uinv
-            cost_of_goods = sinv * pinv
-            ending_inventory = (uinv - sinv) * pinv
-            (0...n).each do |i|
-              ending_inventory += (units[i] * price[i])
-            end
-          else
-            cost_of_goods = uinv * pinv
-            sinv -= uinv
-            (0...n).each do |i|
-              if sinv <= units[i]
-                cost_of_goods += (sinv * price[i])
-                ending_inventory = (units[i] - sinv) * price[i]
-                if i < n
-                  temp = i + 1
-                  (temp...n).each do |j|
-                    ending_inventory += (units[j] * price[j])
-                  end
-                end
-                sinv = 0
-                break
-              else
-                cost_of_goods += (units[i] * price[i])
-                sinv -= units[i]
-              end
-            end
-            raise(Error, "Inventory is not enough to sell\n") if sinv.positive?
-          end
-        when 'WAC'
-          ending_inventory = uinv * pinv
-          tu = uinv
+      cost_of_goods = Flt::DecNum(0)
+      ending_inventory = Flt::DecNum(0)
+      case method
+      when 'FIFO'
+        if sinv <= uinv
+          cost_of_goods = sinv * pinv
+          ending_inventory = (uinv - sinv) * pinv
           (0...n).each do |i|
             ending_inventory += (units[i] * price[i])
-            tu += units[i]
-          end
-          if tu >= sinv
-            cost_of_goods = ending_inventory / tu * sinv
-            ending_inventory = ending_inventory / tu * (tu - sinv)
-          else
-            raise(Error, "Inventory is not enough to sell\n")
           end
-
-        when 'LIFO'
-          (n - 1).downto(0).each do |i|
+        else
+          cost_of_goods = uinv * pinv
+          sinv -= uinv
+          (0...n).each do |i|
             if sinv <= units[i]
               cost_of_goods += (sinv * price[i])
               ending_inventory = (units[i] - sinv) * price[i]
-              if i > 1
-                temp = i - 1
-                temp.downto(0).each do |j|
+              if i < n
+                temp = i + 1
+                (temp...n).each do |j|
                   ending_inventory += (units[j] * price[j])
                 end
               end
-              ending_inventory += (uinv * pinv)
               sinv = 0
               break
             else
@@ -109,18 +68,52 @@ module Finrb
               sinv -= units[i]
             end
           end
-          if sinv.positive?
-            if sinv <= uinv
-              cost_of_goods += (sinv * pinv)
-              ending_inventory += ((uinv - sinv) * pinv)
-            else
-              raise(Error, "Inventory is not enough to sell\n")
+          raise(DomainError, 'Available inventory is insufficient for the requested sale.') if sinv.positive?
+        end
+      when 'WAC'
+        ending_inventory = uinv * pinv
+        tu = uinv
+        (0...n).each do |i|
+          ending_inventory += (units[i] * price[i])
+          tu += units[i]
+        end
+        if tu.zero? && sinv.zero?
+          cost_of_goods = Flt::DecNum(0)
+          ending_inventory = Flt::DecNum(0)
+        elsif tu >= sinv
+          cost_of_goods = ending_inventory / tu * sinv
+          ending_inventory = ending_inventory / tu * (tu - sinv)
+        else
+          raise(DomainError, 'Available inventory is insufficient for the requested sale.')
+        end
+
+      when 'LIFO'
+        (n - 1).downto(0).each do |i|
+          if sinv <= units[i]
+            cost_of_goods += (sinv * price[i])
+            ending_inventory = (units[i] - sinv) * price[i]
+            if i.positive?
+              temp = i - 1
+              temp.downto(0).each do |j|
+                ending_inventory += (units[j] * price[j])
+              end
             end
+            ending_inventory += (uinv * pinv)
+            sinv = 0
+            break
+          else
+            cost_of_goods += (units[i] * price[i])
+            sinv -= units[i]
+          end
+        end
+        if sinv.positive?
+          if sinv <= uinv
+            cost_of_goods += (sinv * pinv)
+            ending_inventory += ((uinv - sinv) * pinv)
+          else
+            raise(DomainError, 'Available inventory is insufficient for the requested sale.')
           end
         end
-
-      else
-        raise(Error, "length of units and price are not the same\n")
       end
 
       {
@@ -129,6 +122,20 @@ module Finrb
       }
     end
 
+    def self.inventory_inputs(uinv:, pinv:, units:, price:, sinv:, method:)
+      uinv = Validation.non_negative_decimal(uinv, name: 'beginning inventory units')
+      pinv = Validation.non_negative_decimal(pinv, name: 'beginning inventory unit cost')
+      units = inventory_values(units, name: 'purchase units')
+      price = inventory_values(price, name: 'purchase unit cost')
+      sinv = Validation.non_negative_decimal(sinv, name: 'units sold')
+      method = method.to_s
+      raise(ArgumentError, 'Inventory costing method must be FIFO, LIFO, or WAC.') unless %w[FIFO LIFO WAC].include?(method)
+      raise(ArgumentError, 'Purchase units and unit costs must have equal lengths.') unless units.size == price.size
+
+      [uinv, pinv, units, price, sinv, method]
+    end
+    private_class_method :inventory_inputs
+
     # Depreciation Expense Recognition -- double-declining balance (DDB), the most common declining balance method, which applies two times the straight-line rate to the declining balance.
     #
     # @param cost cost of long-lived assets
@@ -137,11 +144,10 @@ module Finrb
     # @example
     #   Finrb::Accounting.ddb(cost=1200,rv=200,t=5)
     def self.ddb(cost:, rv:, t:)
-      cost = Flt::DecNum(cost.to_s)
-      rv = Flt::DecNum(rv.to_s)
-      t = Flt::DecNum(t.to_s)
-
-      raise(Error, 't should be larger than 1') if t < 2
+      cost = Validation.non_negative_decimal(cost, name: 'asset cost')
+      rv = residual_value(rv, cost:)
+      t = Validation.positive_integer(t, name: 'useful life')
+      raise(DomainError, 'Useful life must be at least 2 periods for double-declining depreciation.') if t < 2
 
       ddb = [Flt::DecNum(0)] * t
       ddb[0] = cost * 2 / t
@@ -170,11 +176,24 @@ module Finrb
     # @example
     #   Finrb::Accounting.slde(cost=1200,rv=200,t=5)
     def self.slde(cost:, rv:, t:)
-      cost = Flt::DecNum(cost.to_s)
-      rv = Flt::DecNum(rv.to_s)
-      t = Flt::DecNum(t.to_s)
+      cost = Validation.non_negative_decimal(cost, name: 'asset cost')
+      rv = residual_value(rv, cost:)
+      t = Validation.positive_decimal(t, name: 'useful life', error: DomainError)
 
       ((cost - rv) / t)
     end
+
+    def self.inventory_values(values, name:)
+      wrap_array(values).map { |value| Validation.non_negative_decimal(value, name:) }
+    end
+    private_class_method :inventory_values
+
+    def self.residual_value(value, cost:)
+      value = Validation.non_negative_decimal(value, name: 'residual value')
+      raise(DomainError, 'Residual value must not exceed asset cost.') if value > cost
+
+      value
+    end
+    private_class_method :residual_value
   end
 end