finrb 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5331d4b4769cc183d279c1eb4d837d05137cb6b09dd69394addb7be0c6debfae
-  data.tar.gz: de97a959862d55711e7e6989dc8c47ffa277dcea32cc8184cc89f2158edad160
+  metadata.gz: 2a5f20ce5e17a03b0043df557ea5ea2207eb15e286e8f80664ef436dadc6cbce
+  data.tar.gz: de4773bdabd2131fcfcf4be29cc9befecf47fd92353e308d7cdae5569d7c914e
 SHA512:
-  metadata.gz: e57aeeac9a952790c895d367170596097d15fe5cbdb43bcab6a9943bfa80bff0a3a4d1e9d016e859d6f554b7a892a78ee2b3896f961b850f9ac1fafd7e064948
-  data.tar.gz: 84e26bbd5a9862c6733cbce98cebe4ebe1640751992c6fffe74d33ba31b39dc77f0f0ca5cf4ec8b6fd6bb6d0c62fa5bab1cbbacd3b0a8384d4d1eb1573b9528d
+  metadata.gz: e0afa3b1d816b589d23ea2a6cd16c3a274d4ce68bb2a2552caa7b5c398d214b66c3f287fc824c7b607c6288df40b2b7fe7541c84f190a8e3f282cd8ed47238a7
+  data.tar.gz: 22c1d7ace18c693faa7f7d28551a064a1e9390e61d9bb023724dc98afbc24c13ae8d80044496260e1c846a37ba7d0a3b70da58e318d04a56aae979f5ead7892b

data/CHANGELOG.md

@@ -1,5 +1,61 @@
 # finrb changelog
 
+## 1.3.0
+
+### Dated lending and calendars
+
+- Add opt-in dated amortization with monthly, quarterly, semiannual, and annual
+  payment frequencies, explicit short-final stubs, and Actual/365 Fixed or
+  Actual/360 interest accrual. Rate durations remain expressed in months.
+- Add `Amortization#cashflow_yield` to report the dated borrower's effective
+  annual cashflow-equivalent cost from net proceeds and scheduled payments.
+  This is not a jurisdiction-specific legal APR disclosure.
+- Add dependency-free US Federal Reserve payment-day and Israel TASE trading
+  calendars with business-day adjustment conventions. Supported ranges are
+  explicit: US 1950–2065 and TASE 2000–2050.
+- Extract immutable `Finrb::Schedule` payment periods for reuse by dated loans
+  and fixed-rate bonds.
+
+### Fixed income
+
+- Add `Finrb::FixedRateBond` for regular fixed-coupon bullet bonds, with
+  Actual/Actual ICMA coupon accrual, accrued interest, clean and dirty prices,
+  and yield-to-maturity.
+- Correct accrued-interest selection when settlement falls between an
+  unadjusted coupon boundary and its business-day-adjusted payment date.
+
+### Verification and development
+
+- Add pinned QuantLib reference fixtures and seeded randomized cross-validation
+  for dated amortization, calendar profiles, and fixed-rate bond valuations.
+- Add calendar and randomized bond oracle checks to CI, and organize scripts by
+  verification, fixture generation, packaging, documentation, and benchmarks.
+
+## 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

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
+```
+
+`rake quality` runs RuboCop and the RSpec suite with coverage, verifies
+maintained API examples, and validates the packaged RBS declarations. Run
+`bundle exec rake lint` alone for a focused full-repository lint check.
+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

@@ -58,14 +58,17 @@ API explicitly returns another financial object, such as `Finrb::Rate`.
 | `Finrb::Cashflow` | NPV, XNPV, IRR, and XIRR |
 | `Finrb::Rate` | Nominal APR, effective APY, and compounding conversions |
 | `Finrb::Amortization` | Fixed and adjustable-rate loan amortization |
+| `Finrb::Schedule` | Immutable dated payment periods with optional calendar adjustment |
+| `Finrb::FixedRateBond` | Fixed-coupon bullet bond cashflows, accrued interest, price, and yield |
+| `Finrb::Calendars` | US Federal Reserve and Israel TASE business calendars |
 | `Finrb::TVM` | Present value, future value, payments, periods, and perpetuities |
 | `Finrb::Returns` | Holding-period, time-weighted, portfolio, and risk-adjusted returns |
 | `Finrb::Yields` | Money-market, bond-equivalent, effective, and continuous yield conversions |
 | `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
 
@@ -131,6 +134,44 @@ first.interest_only?
 first.closing_balance
 ```
 
+Pass a Ruby `Date` as `start_date:` to opt into an actual/365 dated schedule.
+The start date is the accrual boundary; the first payment date is one month
+later. Month-end anchors stay at month end, while other day numbers are clamped
+to shorter months and recovered from the original anchor in the following
+month. Dated periods accrue simple nominal APR for their actual number of days
+(`APR * days / 365`); this is a specific convention, not a universal loan
+standard. Dates stay unadjusted by default. To opt in, supply a finrb market
+calendar and explicit business-day convention; the adjusted payment dates then
+drive the actual/365 accrual. finrb includes US Federal Reserve and Israel
+TASE full-day calendars, with no runtime holiday-data dependency.
+The profiles intentionally support US dates from 1950 through 2065 and TASE
+dates from 2000 through 2050; querying or configuring dates outside those
+windows raises `RangeError` rather than extrapolating silently.
+
+```ruby
+require 'date'
+
+dated = Finrb::Amortization.new(
+  100_000,
+  Finrb::Rate.new(0.05, :apr, duration: 3),
+  start_date: Date.new(2024, 1, 31)
+)
+dated.schedule.first.date # => #<Date: 2024-02-29 ...>
+
+bank_calendar = Finrb::Calendars::USFederalReserve.new
+calendar_adjusted = Finrb::Amortization.new(
+  100_000,
+  Finrb::Rate.new(0.05, :apr, duration: 3),
+  start_date: Date.new(2026, 1, 31),
+  calendar: bank_calendar,
+  business_day_convention: :modified_following
+)
+calendar_adjusted.schedule.first.date # => #<Date: 2026-02-27 ...>
+```
+
+See the [calendar API guide](docs/api.md#business-calendars) for market scope,
+holiday overrides, and supported date-adjustment conventions.
+
 Pass several duration-bearing rates for an adjustable-rate schedule. A block
 can modify each scheduled payment, for example to add a $150 principal payment:
 
@@ -185,6 +226,25 @@ financed_fee.net_proceeds    # => Flt::DecNum('250000')
 financed_fee.amount_financed # => Flt::DecNum('252500')
 ```
 
+For a dated schedule, `cashflow_yield` calculates the effective annual
+cashflow-equivalent cost to the borrower using net proceeds on the start date
+and each actual payment on its scheduled date. The final payment already
+includes any balloon settlement, so it is counted only once. The result is a
+`Finrb::Rate`; it is not a jurisdiction-specific legal APR and follows the
+current `Finrb::Cashflow.xirr` configuration.
+
+```ruby
+require 'date'
+
+dated_loan = Finrb::Amortization.new(
+  250_000,
+  rate,
+  start_date: Date.new(2025, 1, 15),
+  origination_fee: 2_500
+)
+dated_loan.cashflow_yield.apy # effective annual cost implied by proceeds and payments
+```
+
 ## Configuration
 
 Configure process-wide defaults during application startup:
@@ -261,14 +321,14 @@ Install the bundle and run the self-contained quality checks:
 ```shell
 bundle install
 bundle exec rake quality
-bundle exec rubocop
 bundle exec rake security:audit
 bundle exec rake package:verify
 ```
 
-The quality task runs the RSpec suite with line and branch coverage, generated
-IRR/XIRR properties, committed SciPy/QuantLib reference fixtures, and RBS
-validation.
+The quality task runs RuboCop, the RSpec suite with line and branch coverage,
+generated IRR/XIRR properties, committed SciPy/QuantLib reference fixtures,
+verified API examples, and RBS validation. Run `bundle exec rake lint` alone for
+a focused full-repository lint check.
 
 `security:audit` updates ruby-advisory-db and checks the locked dependencies.
 `package:verify` builds the gem, validates its contents and metadata, installs
@@ -321,23 +381,36 @@ only finrb's runtime dependencies and RSpec; MRI-only development tooling such
 as RBS, RuboCop, and coverage is deliberately excluded from engine
 compatibility runs.
 
-Maintainers with the optional Python environment can run the larger seeded
-solver verification campaign:
+Maintainers with the optional Python environment can run seeded randomized
+cross-validation campaigns for solvers and fixed-rate bonds:
 
 ```shell
-python3 -m pip install --requirement script/requirements-solver-verification.txt
+python3 -m pip install --requirement script/verification/requirements-solver.txt
 bundle exec rake solver:verify
 ```
 
+The bond campaign needs only QuantLib-Python 1.43:
+
+```shell
+python3 -m pip install --requirement script/verification/requirements-bonds.txt
+bundle exec rake bond:verify
+```
+
+The same bond campaign can run in the isolated Docker target with
+`bundle exec rake docker:verify_bond`.
+
 The Python packages are verification references, not gem dependencies. See
 [the fixture documentation](spec/fixtures/README.md) for reproducibility,
-Docker, batching, and tolerance details.
+Docker, batching, and tolerance details. Verification and maintainer utilities
+are grouped by purpose under `script/`.
 
 ## Project links
 
 - [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