amortizy 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1bf3cd11455f5c2c301066d64f911a15e696dd1b033c2b865a5d7ddaff93e05
-  data.tar.gz: 34482d2f3553108c4ad04d3dd238ff486e3c72aa266fd4f19582607720df98ff
+  metadata.gz: 00f0ccad91127633326557a81254c429737b526a834bb18de2235b842390f7ef
+  data.tar.gz: fcf4c2b4d999c1c276446fb36ea85984c7d380b4819b9592f55afcdb405985d2
 SHA512:
-  metadata.gz: e1d49aaa154f7dbce6a7f5e9fddf77c04a4f6ea90af9662b4cfa1c6ed787a70672277cd6a8425346277067fef6af76ac2d3ec32ddfd2f7b3d972f049cdd43846
-  data.tar.gz: 94aaf0a040ba624cedc10ea49db5a873712b8682a6f6191439088eb02df8f74d27bb86c14cb9288607a51217d9f091ab643b3d4108fb83b3e04dcf8e28a11dd3
+  metadata.gz: 73e33d2c4a0ee6f0ab15d9618d4aa53df5bbbe16608630f125dac377e674e82bf8c576362e492257692c928b6ec0328781cd91c752a57b8d55c36946154fb804
+  data.tar.gz: 0c9e25aabdceee720c8fb6fcf2367b101fbce214642e4be84022f0ea2ca166478ea2bbeb190018bca41c03fe63b5e87963e5c79f1fc23b4b333cea71d72d8314

data/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-04-20
+
+### Added
+
+#### Commercial Financing Disclosure Module
+- **`Amortizy::Disclosure`** - new class that computes disclosure data elements for
+  closed-end commercial loan transactions per California SB 1235 (Title 10, Chapter 3)
+- **APR calculation** using the actuarial method per Appendix J of Regulation Z
+  (12 CFR Part 1026, section 940) with Newton-Raphson solver and bisection fallback
+- **Finance charge** - total dollar cost of financing including interest and all fees (section 943)
+- **Amount financed** - principal adjusted for prepaid finance charges (section 900(a)(1)(B))
+- **Recipient funds** - net amount disbursed to borrower after third-party payoffs (section 900(a)(26))
+- **Term display** - formatted per regulation: days for terms <= 1 year,
+  years/months for longer terms (section 901(a)(4))
+- **Average monthly cost** - automatically computed for non-monthly payment frequencies (section 910(a)(12))
+- **Prepayment information** - structured data for prepayment penalty disclosures (section 910(a)(8-10))
+- **`#to_h`** - flat hash of all computed values
+- **`#to_labeled_h`** - hash with regulation-correct labels from section 910
+
+#### Design Notes
+- Disclosure class wraps an existing `AmortizationSchedule` — no changes to the engine API
+- Values are jurisdiction-agnostic: computed per the most stringent methodology (California),
+  usable for any state's commercial financing disclosure requirements
+- Origination fee is treated as a prepaid finance charge by default
+- APR rounded to nearest 10 basis points per section 901(a)(5)
+- APR accuracy within 1/8 of 1 percentage point tolerance per section 955
+
 ## [2.0.0] - 2026-04-19
 
 ### Added
@@ -127,7 +154,6 @@ bundle update amortizy
 
 Potential features for future releases:
 
-- Additional payment frequencies (monthly, bi-weekly)
 - More interest calculation methods
 - Support for additional holiday calendars (state, international)
 - Balloon payment support

data/README.md

@@ -19,7 +19,8 @@ Perfect for financial applications, lending platforms, and loan calculators.
 - **Bank day calculations**: Automatically skip weekends and US Federal Reserve holidays
 - **Multiple output formats**: Console display or CSV export
 - **Public API**: Programmatic access to schedule data, summaries, and totals
-- **Testing**: 70 RSpec tests
+- **Commercial financing disclosures**: APR (Reg Z actuarial method), finance charge, amount financed, and more
+- **Testing**: 120 RSpec tests
 
 ## Installation
 
@@ -325,6 +326,107 @@ schedule = Amortizy::AmortizationSchedule.new(
 schedule.generate(output: :csv, csv_path: "commercial_loan.csv")
 ```
 
+## Commercial Financing Disclosures
+
+Amortizy includes a disclosure module for computing data elements required by California SB 1235 and similar state commercial financing disclosure laws (New York, Georgia, etc.). Values are jurisdiction-agnostic — computed per the most stringent methodology, usable for any state.
+
+The `Disclosure` class wraps an existing `AmortizationSchedule` and computes nine disclosure elements. The gem computes the numbers — your application handles document formatting.
+
+**Key assumption:** The origination fee is treated as a prepaid finance charge (deducted from amount financed, included in finance charge). This is the standard treatment for commercial lending.
+
+### Basic Usage
+
+```ruby
+schedule = Amortizy::AmortizationSchedule.new(
+  start_date: "2026-01-15",
+  principal: 50_000,
+  annual_rate: 12.0,
+  frequency: :monthly,
+  term_months: 36,
+  origination_fee: 500,
+  additional_fee: 250,
+  additional_fee_treatment: :distributed
+)
+
+disclosure = Amortizy::Disclosure.new(schedule)
+
+disclosure.apr                   # => 12.3 (Reg Z actuarial method, 10 bps precision)
+disclosure.finance_charge        # => 11119.65
+disclosure.amount_financed       # => 49500.0
+disclosure.total_payment_amount  # => 60619.65
+disclosure.recipient_funds       # => 49500.0
+disclosure.term_display          # => "3 years, 0.20 months"
+disclosure.average_monthly_cost  # => nil (monthly frequency)
+disclosure.prepayment            # => { has_non_interest_charges: false, ... }
+```
+
+### With Third-Party Payments and Prepayment Info
+
+```ruby
+disclosure = Amortizy::Disclosure.new(
+  schedule,
+  third_party_payments: 10_000,
+  prepayment_penalty_max: 1_200,
+  additional_prepayment_fees: [
+    { amount: 250.0, description: "Early termination fee" }
+  ]
+)
+
+disclosure.recipient_funds  # => 39500.0 (amount_financed - third_party_payments)
+disclosure.prepayment
+# => {
+#   has_non_interest_charges: true,
+#   max_non_interest_finance_charge: 1200.0,
+#   has_additional_fees: true,
+#   additional_fees: [{ amount: 250.0, description: "Early termination fee" }]
+# }
+```
+
+### Output Formats
+
+```ruby
+# Raw values
+disclosure.to_h
+# => { amount_financed: 49500.0, apr: 12.3, finance_charge: 11119.65, ... }
+
+# With regulation-correct labels (per CA SB 1235 section 910)
+disclosure.to_labeled_h
+# => {
+#   amount_financed: { label: "Funding Provided", value: 49500.0 },
+#   apr: { label: "Annual Percentage Rate (APR)", value: 12.3 },
+#   finance_charge: { label: "Finance Charge", value: 11119.65 },
+#   ...
+# }
+```
+
+### Disclosure Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `third_party_payments` | Float | 0 | Amounts paid to third parties from the financing |
+| `prepayment_penalty_max` | Float | 0 | Maximum non-interest charge on early payoff |
+| `additional_prepayment_fees` | Array | [] | Array of `{ amount:, description: }` hashes |
+
+### Disclosure Elements
+
+| Element | Method | Description | Regulatory Reference |
+|---------|--------|-------------|---------------------|
+| Funding Provided | `#amount_financed` | Principal adjusted for prepaid finance charges | §900(a)(1)(B) |
+| APR | `#apr` | Annual percentage rate (Reg Z actuarial method) | §940 |
+| Finance Charge | `#finance_charge` | Total dollar cost (derived from Reg Z identity) | §943 |
+| Total Payment Amount | `#total_payment_amount` | Sum of all borrower payments | §910(a)(5) |
+| Payment | `#payment_amount` | Regular periodic payment | §910(a)(6) |
+| Term | `#term_display` | Days (<=1yr) or years/months (>1yr) | §901(a)(4) |
+| Average Monthly Cost | `#average_monthly_cost` | For non-monthly frequencies only | §910(a)(12) |
+| Recipient Funds | `#recipient_funds` | Net amount to borrower | §900(a)(26) |
+| Prepayment | `#prepayment` | Prepayment penalty details | §910(a)(8-10) |
+
+### Technical Notes
+
+- **APR calculation** uses the actuarial method per Appendix J of Regulation Z (12 CFR Part 1026). Newton-Raphson solver with bisection fallback. APR rounded to nearest 10 basis points per §901(a)(5). Accuracy within 1/8 of 1 percentage point per §955.
+- **Finance charge** is derived from the Reg Z identity: `total_payment_amount - amount_financed`. This guarantees the three core disclosure values are always internally consistent.
+- **Floating-point arithmetic** is used for all calculations. This is adequate for typical commercial loans. For extremely large principals or very long terms (1000+ payments), consider validating against a reference APR calculator.
+
 ## Command Line Interface
 
 Amortizy includes an interactive CLI tool:
@@ -363,7 +465,7 @@ bin/console
 
 ## Testing
 
-The test suite includes 70 RSpec examples covering:
+The test suite includes 120 RSpec examples covering:
 
 - Initialization and validation
 - Payment calculations for all four frequencies
@@ -379,6 +481,9 @@ The test suite includes 70 RSpec examples covering:
 - Public API (schedule, summary, convenience methods)
 - Deep freeze immutability
 - Edge cases (year boundaries, month-end clamping, input validation)
+- Commercial financing disclosures (APR, finance charge, amount financed, all nine elements)
+- Reg Z identity verification across all fee treatment modes
+- APR solver convergence (grace periods, interest-only, short-term, zero-rate loans)
 
 Run the test suite:
 

data/lib/amortizy/disclosure.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+# Commercial Financing Disclosure Calculator
+#
+# Computes disclosure data elements for closed-end commercial loan transactions
+# per California SB 1235 (Title 10, Chapter 3, Subchapter 3). Values are
+# jurisdiction-agnostic — the gem computes numbers, not documents.
+#
+# APR is calculated using the actuarial method per Appendix J of Regulation Z
+# (12 CFR Part 1026), as required by section 940 of the regulation.
+#
+# Key assumption: the origination fee is treated as a prepaid finance charge
+# (deducted from amount financed, included in finance charge).
+#
+# Regulatory references:
+#   - Section 910: Closed-end transaction disclosure contents
+#   - Section 940: APR calculation method
+#   - Section 943: Finance charge definition
+#   - Section 900(a)(1)(B): Amount financed for closed-end transactions
+#   - Section 900(a)(26): Recipient funds
+#   - Section 901(a)(4): Term display formatting
+#   - Section 901(a)(5): APR rounding (nearest 10 basis points)
+#   - Section 955: APR tolerance (1/8 of 1 percentage point)
+
+module Amortizy
+  class Disclosure
+    APR_MAX_ITERATIONS = 100
+    APR_CONVERGENCE_TOLERANCE = 1e-8
+    APR_REG_Z_TOLERANCE = 0.00125 # 1/8 of 1 percentage point
+
+    def initialize(schedule, third_party_payments: 0, prepayment_penalty_max: 0,
+                   additional_prepayment_fees: [])
+      raise ArgumentError, 'First argument must be an Amortizy::AmortizationSchedule' unless schedule.is_a?(Amortizy::AmortizationSchedule)
+
+      @schedule = schedule
+      @third_party_payments = third_party_payments.to_f
+      @prepayment_penalty_max = prepayment_penalty_max.to_f
+      @additional_prepayment_fees = additional_prepayment_fees
+    end
+
+    # --- Finance Charge (§943) ---
+    # Total dollar cost of the financing. Derived from the Reg Z identity:
+    #   Finance Charge = Total Payment Amount - Amount Financed
+    # This ensures the three core disclosure values are always consistent.
+
+    def finance_charge
+      @finance_charge ||= total_payment_amount - amount_financed
+    end
+
+    # --- Amount Financed (§900(a)(1)(B)) ---
+    # Principal + financed amounts - prepaid finance charges (origination fee).
+
+    def amount_financed
+      @amount_financed ||= begin
+        base = principal - origination_fee
+        base += additional_fee if fee_treatment == :add_to_principal
+        base
+      end
+    end
+
+    # --- Total Payment Amount (§910(a)(5)) ---
+
+    def total_payment_amount
+      @schedule.total_paid
+    end
+
+    # --- Payment Amount ---
+
+    def payment_amount
+      @schedule.payment_amount
+    end
+
+    # --- Payment Frequency ---
+
+    def payment_frequency
+      @schedule.frequency
+    end
+
+    # --- Recipient Funds (§900(a)(26)) ---
+    # Net amount given directly to the borrower.
+
+    def recipient_funds
+      amount_financed - @third_party_payments
+    end
+
+    # --- Term (§901(a)(4)) ---
+
+    def term_days
+      @term_days ||= (@schedule.end_date - disbursement_date).to_i
+    end
+
+    def term_display
+      if term_days <= 365
+        "#{term_days} days"
+      else
+        years = term_days / 365
+        remaining_days = term_days % 365
+        months = (remaining_days / 30.4).round(2)
+        year_label = years == 1 ? 'year' : 'years'
+        month_label = (months - 1.0).abs < 0.005 ? 'month' : 'months'
+        format('%d %s, %.2f %s', years, year_label, months, month_label)
+      end
+    end
+
+    # --- Average Monthly Cost (§910(a)(12)) ---
+    # Only for non-monthly payment frequencies.
+
+    def average_monthly_cost
+      return nil if @schedule.frequency == :monthly
+      return nil if term_days <= 0
+
+      total_payment_amount / (term_days / 30.4)
+    end
+
+    # --- APR (§940) ---
+    # Actuarial method per Appendix J, Regulation Z (12 CFR Part 1026).
+    # Rounded to nearest 10 basis points per §901(a)(5).
+
+    def apr
+      @apr ||= begin
+        raw_apr = calculate_apr
+        round_to_ten_basis_points(raw_apr)
+      end
+    end
+
+    # --- Prepayment (§910(a)(8-10)) ---
+
+    def prepayment
+      @prepayment ||= {
+        has_non_interest_charges: @prepayment_penalty_max.positive?,
+        max_non_interest_finance_charge: @prepayment_penalty_max.positive? ? @prepayment_penalty_max : nil,
+        has_additional_fees: @additional_prepayment_fees.any?,
+        additional_fees: @additional_prepayment_fees
+      }
+    end
+
+    # --- Output Methods ---
+
+    def to_h
+      {
+        amount_financed: amount_financed.round(2),
+        apr: apr,
+        finance_charge: finance_charge.round(2),
+        total_payment_amount: total_payment_amount.round(2),
+        payment_amount: payment_amount.round(2),
+        payment_frequency: payment_frequency,
+        term_days: term_days,
+        term_display: term_display,
+        average_monthly_cost: average_monthly_cost&.round(2),
+        recipient_funds: recipient_funds.round(2),
+        prepayment: prepayment
+      }
+    end
+
+    def to_labeled_h
+      {
+        amount_financed: { label: 'Funding Provided', value: amount_financed.round(2) },
+        apr: { label: 'Annual Percentage Rate (APR)', value: apr },
+        finance_charge: { label: 'Finance Charge', value: finance_charge.round(2) },
+        total_payment_amount: { label: 'Total Payment Amount', value: total_payment_amount.round(2) },
+        payment_amount: { label: 'Payment', value: payment_amount.round(2) },
+        payment_frequency: { label: 'Payment Frequency', value: payment_frequency },
+        term_days: { label: 'Term', value: term_display },
+        average_monthly_cost: { label: 'Average Monthly Cost', value: average_monthly_cost&.round(2) },
+        recipient_funds: { label: 'Recipient Funds', value: recipient_funds.round(2) },
+        prepayment: prepayment
+      }
+    end
+
+    private
+
+    def disbursement_date
+      @schedule.start_date
+    end
+
+    def principal
+      @schedule.principal
+    end
+
+    def origination_fee
+      @schedule.origination_fee
+    end
+
+    def additional_fee
+      @schedule.additional_fee
+    end
+
+    def fee_treatment
+      @schedule.additional_fee_treatment
+    end
+
+    # --- APR Calculation ---
+    #
+    # Solves for the annual rate i such that:
+    #   Amount Financed = Σ (Payment_k / (1 + i/365)^(days_k))
+    #
+    # where days_k is the number of days from disbursement to payment k.
+    #
+    # Uses Newton-Raphson with bisection fallback.
+
+    def calculate_apr
+      cash_flows = extract_cash_flows
+      return 0.0 if cash_flows.empty?
+      return 0.0 if amount_financed <= 0
+      return 0.0 if cash_flows.length > 10_000
+
+      # Initial guess: use the nominal annual rate as starting point
+      guess = @schedule.annual_rate
+      guess = 0.10 if guess.zero?
+
+      apr_newton_raphson(cash_flows, guess) || apr_bisection(cash_flows)
+    end
+
+    def extract_cash_flows
+      flows = []
+      start = disbursement_date
+
+      @schedule.schedule.each do |row|
+        payment = row[:total_payment]
+        next if payment.nil? || payment <= 0
+
+        days_from_start = (row[:date] - start).to_i
+        next if days_from_start <= 0
+
+        flows << { days: days_from_start, amount: payment }
+      end
+
+      flows
+    end
+
+    # Present value of all payments at annual rate r, minus amount financed.
+    # When this equals zero, r is the APR.
+    def pv_function(cash_flows, annual_rate)
+      daily_rate = annual_rate / 365.0
+      pv = cash_flows.sum do |cf|
+        cf[:amount] / ((1.0 + daily_rate)**cf[:days])
+      end
+      pv - amount_financed
+    end
+
+    # Derivative of the PV function with respect to annual_rate.
+    def pv_derivative(cash_flows, annual_rate)
+      daily_rate = annual_rate / 365.0
+      cash_flows.sum do |cf|
+        -cf[:days] * cf[:amount] / (365.0 * ((1.0 + daily_rate)**(cf[:days] + 1)))
+      end
+    end
+
+    def apr_newton_raphson(cash_flows, initial_guess)
+      rate = initial_guess
+
+      APR_MAX_ITERATIONS.times do
+        f = pv_function(cash_flows, rate)
+        f_prime = pv_derivative(cash_flows, rate)
+
+        return rate * 100.0 if f.abs < APR_CONVERGENCE_TOLERANCE
+        return nil if f_prime.abs < 1e-15 # derivative too small, switch to bisection
+
+        step = f / f_prime
+        rate -= step
+
+        # Guard against negative rates or runaway
+        return nil if rate <= -1.0 / 365.0
+        return nil if rate > 10.0 # 1000% APR cap — something went wrong
+      end
+
+      nil # didn't converge
+    end
+
+    def apr_bisection(cash_flows)
+      low = -0.001
+      high = 10.0
+
+      # Ensure the interval brackets the root
+      f_low = pv_function(cash_flows, low)
+      f_high = pv_function(cash_flows, high)
+
+      # If both same sign, try expanding
+      if (f_low * f_high).positive?
+        high = 50.0
+        f_high = pv_function(cash_flows, high)
+        return 0.0 if (f_low * f_high).positive?
+      end
+
+      (APR_MAX_ITERATIONS * 5).times do
+        mid = (low + high) / 2.0
+        f_mid = pv_function(cash_flows, mid)
+
+        return mid * 100.0 if f_mid.abs < APR_CONVERGENCE_TOLERANCE
+
+        if (f_low * f_mid).negative?
+          high = mid
+        else
+          low = mid
+          f_low = f_mid
+        end
+      end
+
+      ((low + high) / 2.0) * 100.0
+    end
+
+    def round_to_ten_basis_points(apr_percent)
+      (apr_percent * 10).round / 10.0
+    end
+  end
+end

data/lib/amortizy/engine.rb

@@ -16,7 +16,8 @@ require 'holidays'
 
 module Amortizy
   class AmortizationSchedule
-    attr_reader :start_date, :principal, :term_months, :annual_rate, :frequency, :additional_fee_label
+    attr_reader :start_date, :principal, :term_months, :annual_rate, :frequency, :additional_fee_label,
+                :origination_fee, :additional_fee, :additional_fee_treatment
 
     def initialize(start_date:, principal:, annual_rate:, frequency:, term_months: nil, num_payments: nil,
                    origination_fee: 0, additional_fee: 0, additional_fee_label: 'Additional Fee',

data/lib/amortizy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Amortizy
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

data/lib/amortizy.rb

@@ -4,6 +4,7 @@ require_relative 'amortizy/version'
 require_relative 'amortizy/engine'
 require_relative 'amortizy/console_formatter'
 require_relative 'amortizy/csv_formatter'
+require_relative 'amortizy/disclosure'
 
 module Amortizy
   class Error < StandardError; end

data/tasks/todo.md

@@ -1,74 +1,203 @@
-# Amortizy v2.0 — Dynamic Payment Model
+# Amortizy v2.1 — Commercial Financing Disclosure Module
 
 ## Goal
 
-Replace the hardcoded term/payment lookup table with a dynamic calculation engine.
-Support two entry points: `term_months` (calculate payment count) or `num_payments`
-(calculate end date). Add monthly and bi-weekly frequencies.
+Add a `Disclosure` class that computes California SB 1235 disclosure data elements
+for closed-end commercial loan transactions. The gem exposes jurisdiction-agnostic
+numbers — APR (Reg Z actuarial method), finance charge, amount financed, recipient
+funds, term, average monthly cost, and prepayment info — queryable via a clean API.
+
+**Design decisions:**
+- `Amortizy::Disclosure` is a separate class that wraps an `AmortizationSchedule`
+- Origination fee is treated as a prepaid finance charge by default (deducted from
+  amount financed, included in finance charge) — must be documented
+- No state/jurisdiction parameters — data elements are universal
+- No document formatting — the gem computes numbers, not PDFs
+- Scoped to closed-end transactions only (no MCA, factoring, leases, open-end)
+
+**Regulatory references:**
+- Section 910: Closed-end transaction disclosure contents
+- Section 940: APR calculation (Appendix J, 12 CFR Part 1026 — actuarial method)
+- Section 943: Finance charge definition
+- Section 900(a)(1)(B): Amount financed for closed-end transactions
+- Section 900(a)(26): Recipient funds
+- Section 955: APR tolerance (1/8 of 1 percentage point)
 
 ---
 
-## Phase 1: Dynamic Payment Engine
-
-### 1.1 Dual input model
-- [ ] Accept `term_months` OR `num_payments` — one required, not both
-- [ ] Validate: raise `ArgumentError` if both provided, or neither
-- [ ] When `term_months` given: calculate `num_payments` from frequency
-  - monthly: `term_months`
-  - bi-weekly: `term_months * 2` (approx 26/year)
-  - weekly: `term_months * 52 / 12` (rounded)
-  - daily: calculate actual business/calendar days in the term
-- [ ] When `num_payments` given: calculate end date by walking the payment schedule forward
-- [ ] Remove the hardcoded `calculate_total_payments` lookup table
-- [ ] Remove `validate_term_months!` (any positive integer is now valid)
-
-### 1.2 New frequencies
-- [ ] Add `:monthly` frequency — payment on same day each month (or last business day)
-- [ ] Add `:biweekly` frequency — every 14 days
-- [ ] Update `validate_frequency!` to accept all four
-- [ ] Handle month-end edge cases for monthly (e.g., start Jan 31 — Feb payment is Feb 28)
-
-### 1.3 Dynamic day calculation
-- [ ] Replace static payment counts with actual date walking
-- [ ] For daily + `bank_days_only`: count actual business days in the term
-- [ ] For weekly/biweekly: walk forward by 7/14 days, skip to next bank day if needed
-- [ ] For monthly: advance by calendar month, adjust for bank days
-
-## Phase 2: Public API Cleanup
-
-### 2.1 Expose schedule data
-- [ ] Make `generate_schedule_data` public, rename to `schedule` or `to_a`
-- [ ] Return frozen array of payment hashes
-- [ ] Add `summary` method — returns hash with totals, dates, payment count
-- [ ] Remove `send(:generate_schedule_data)` from README examples
-
-### 2.2 Convenience methods
-- [ ] `#end_date` — last payment date
-- [ ] `#total_interest` — sum of all interest payments
-- [ ] `#total_paid` — sum of all payments
-- [ ] `#payment_amount` — make public (currently private)
-
-## Phase 3: Extract Formatters
-
-- [ ] Extract `ConsoleFormatter` — takes schedule data, renders table
-- [ ] Extract `CsvFormatter` — takes schedule data, writes CSV
-- [ ] `generate(output:)` delegates to formatter
-- [ ] Engine class focuses on math only
-
-## Phase 4: Polish
-
-- [ ] Fix README broken markdown in Development section
-- [ ] Update README examples for new API
-- [ ] Update gemspec description
-- [ ] Add CHANGELOG entry for v2.0
-- [ ] Bump version
-- [ ] Update Ruby requirement to >= 3.0
-- [ ] Run full spec suite, update/add specs for new features
+## Phase 1: Disclosure Class Skeleton
+
+### 1.1 Create `lib/amortizy/disclosure.rb`
+- [ ] Define `Amortizy::Disclosure` class
+- [ ] Accept `AmortizationSchedule` as first argument
+- [ ] Accept keyword args: `third_party_payments: 0`, `prepayment_penalty_max: 0`,
+      `additional_prepayment_fees: []`
+- [ ] Validate that schedule argument is an `AmortizationSchedule`
+- [ ] Store schedule reference and disclosure-specific params
+
+### 1.2 Wire into gem
+- [ ] Add `require_relative 'amortizy/disclosure'` to `lib/amortizy.rb`
+- [ ] Create `spec/disclosure_spec.rb` with basic instantiation tests
+
+---
+
+## Phase 2: Simple Computed Properties
+
+These derive directly from existing schedule data with minimal new logic.
+
+### 2.1 Finance Charge (§943)
+- [ ] `#finance_charge` — total dollar cost of financing
+- [ ] Calculation: `total_interest + origination_fee + additional_fee`
+- [ ] All charges that would be included under 12 CFR 1026.4 if this were consumer credit
+- [ ] Spec: verify against known loan (e.g., $50K, 12%, 36mo, $500 orig fee, $250 addl fee)
+
+### 2.2 Amount Financed (§900(a)(1)(B))
+- [ ] `#amount_financed` — principal + financed amounts - prepaid finance charges
+- [ ] For closed-end: `principal + additional_fee (if add_to_principal) - origination_fee`
+- [ ] Origination fee treated as prepaid finance charge (deducted)
+- [ ] Additional fee treatment depends on `additional_fee_treatment` setting:
+  - `:distributed` or `:separate_payment` → not added to amount financed
+  - `:add_to_principal` → added to amount financed
+- [ ] Spec: test all three fee treatment scenarios
+
+### 2.3 Total Payment Amount (§910(a)(5))
+- [ ] `#total_payment_amount` — delegates to `schedule.total_paid`
+- [ ] Spec: verify matches schedule total
+
+### 2.4 Recipient Funds (§900(a)(26))
+- [ ] `#recipient_funds` — net amount given directly to the borrower
+- [ ] Calculation: `amount_financed - third_party_payments`
+- [ ] Spec: with and without third-party payments
+
+### 2.5 Term Display (§901(a)(4))
+- [ ] `#term_days` — total days from start to last payment
+- [ ] `#term_display` — formatted per regulation:
+  - Term <= 1 year: display in days (e.g., "270 days")
+  - Term > 1 year: display in years and months, remainder as decimal
+    (e.g., "2 years, 3.15 months")
+- [ ] Spec: test boundary at exactly 365 days, and multi-year terms
+
+### 2.6 Average Monthly Cost (§910(a)(12))
+- [ ] `#average_monthly_cost` — total payments / (term_days / 30.4)
+- [ ] Returns `nil` for monthly frequency (only required for non-monthly)
+- [ ] Spec: weekly and biweekly loans, verify nil for monthly
+
+---
+
+## Phase 3: APR Calculation (§940)
+
+The core engineering work. APR per Appendix J of Regulation Z (12 CFR Part 1026).
+
+### 3.1 Actuarial method solver
+- [ ] Implement APR calculation using the actuarial method
+- [ ] The APR is the rate `i` that satisfies:
+      `Amount Financed = Σ (Payment_k / (1 + i)^(t_k / 365))`
+      where `t_k` is the number of days from disbursement to payment k
+- [ ] Use Newton-Raphson iteration to solve for `i`
+- [ ] Convergence tolerance: 1/8 of 1 percentage point (0.00125) per §955
+- [ ] Maximum iterations: 100 (with fallback to bisection if Newton diverges)
+- [ ] Cash flows: amount financed is the initial advance (positive);
+      each scheduled payment is an outflow (negative)
+- [ ] Include all finance charge components in the payment stream
+
+### 3.2 Cash flow extraction
+- [ ] Extract payment dates and amounts from the schedule
+- [ ] Include separate_payment additional fees in the stream
+- [ ] Include grace period payments if any
+- [ ] Disbursement date = schedule start_date
+- [ ] Each payment: { date:, amount: } from schedule rows
+
+### 3.3 APR formatting
+- [ ] `#apr` — returns APR as a percentage rounded to nearest 10 basis points (§901(a)(5))
+      e.g., 14.8, 14.85, not 14.8532
+- [ ] Spec: verify against known Reg Z examples
+- [ ] Spec: tolerance check — result within 1/8 percentage point of exact
+
+### 3.4 Edge cases
+- [ ] Zero-interest loans (APR should reflect fees only)
+- [ ] Loans with grace periods (disbursement date vs first payment date gap)
+- [ ] Interest-only periods followed by amortizing payments
+- [ ] Precomputed interest method
+- [ ] Very short terms (< 30 days)
+- [ ] Very long terms (> 10 years)
+
+---
+
+## Phase 4: Prepayment Information (§910(a)(8-10))
+
+### 4.1 Prepayment hash
+- [ ] `#prepayment` — returns hash:
+      ```ruby
+      {
+        has_non_interest_charges: true/false,
+        max_non_interest_finance_charge: Float or nil,
+        has_additional_fees: true/false,
+        additional_fees: [] # array of { amount:, description: } hashes
+      }
+      ```
+- [ ] Derived from `prepayment_penalty_max` and `additional_prepayment_fees` inputs
+- [ ] Spec: all four combinations (charges/no charges x fees/no fees)
 
 ---
 
-## Breaking changes (v2.0)
+## Phase 5: Output Methods
+
+### 5.1 `#to_h`
+- [ ] Returns flat hash of all computed values:
+      ```ruby
+      {
+        amount_financed:, apr:, finance_charge:, total_payment_amount:,
+        payment_amount:, payment_frequency:, term_days:, term_display:,
+        average_monthly_cost:, recipient_funds:, prepayment:
+      }
+      ```
+- [ ] All monetary values as Float, rounded to 2 decimal places
+- [ ] Spec: verify all keys present, types correct
+
+### 5.2 `#to_labeled_h`
+- [ ] Returns hash with regulation-correct labels:
+      ```ruby
+      {
+        amount_financed: { label: "Funding Provided", value: 50_250.00 },
+        apr: { label: "Annual Percentage Rate (APR)", value: 14.85 },
+        finance_charge: { label: "Finance Charge", value: 10_432.50 },
+        ...
+      }
+      ```
+- [ ] Labels follow §910 column 1 text for fixed-rate closed-end transactions
+- [ ] Spec: verify exact label strings match regulation text
+
+---
+
+## Phase 6: Documentation & Polish
+
+### 6.1 README updates
+- [ ] Add Disclosure section to README with usage examples
+- [ ] Document the origination fee = prepaid finance charge assumption
+- [ ] Document regulatory references (CA SB 1235, sections 910/940/943)
+- [ ] Note that labels follow California regulation but values are jurisdiction-agnostic
+
+### 6.2 CHANGELOG
+- [ ] Add v2.1.0 entry documenting the disclosure module
+
+### 6.3 Version bump
+- [ ] Bump version to 2.1.0 in `version.rb`
+
+### 6.4 Final spec run
+- [ ] Full suite green — existing specs unaffected
+- [ ] Disclosure specs comprehensive — all nine data elements tested
+- [ ] APR accuracy verified against at least 3 known Reg Z examples
+
+---
 
-- `term_months` no longer restricted to [6, 9, 12, 15, 18]
-- `generate_schedule_data` renamed to public method
-- New frequencies may change default behavior for existing users (unlikely — additive)
+## Out of Scope
+
+- MCA / sales-based financing disclosures (§914)
+- Factoring disclosures (§912, §913)
+- Open-end credit plan disclosures (§911)
+- Lease financing disclosures (§915)
+- Asset-based lending disclosures (§916)
+- Disclosure document generation (PDF/HTML formatting)
+- Jurisdiction detection or state-specific logic
+- Adjustable rate APR estimation (amortizy only does fixed-rate)
+- Retrospective APR auditing (§931)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amortizy
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Rich Zapata
@@ -40,6 +40,7 @@ files:
 - lib/amortizy.rb
 - lib/amortizy/console_formatter.rb
 - lib/amortizy/csv_formatter.rb
+- lib/amortizy/disclosure.rb
 - lib/amortizy/engine.rb
 - lib/amortizy/version.rb
 - sig/amortizy.rbs