Consolidated Equipment Finance Domain added: Loans, Leases, US MACRS, UK Capital Allowances

[Thorium]

Summary

Single coherent Equipment Finance feature set:

• Loans (fixed-rate, balloon support, recurring fee support)
• Leases (simplified rental schedule analytics)
• Depreciation (US MACRS simplified; UK Capital Allowances simplified)
• Shared depreciation abstractions
• Documentation for both regimes and high-level overview
• Baseline + edge test coverage
• Consistent monetary + rounding approach (int64<Cent>, MidpointRounding.AwayFromZero)

No public API breaking changes to existing non‑equipment modules.

Modules Included

Namespace root: FSharp.Finance.Personal.EquipmentFinance

Depreciation:

• DepreciationCommon.fs (shared types/helpers)
• US_MACRS.fs (simplified MACRS Half-Year convention, limited classes)
• UK_CapitalAllowances.fs (AIA allocation + WDA diminishing balance 18% / 6%)

Financing:

• Loan.fs (EquipmentLoanTerms, schedule generator, balloon handling, fees)
• Lease.fs (EquipmentLeaseTerms, rental schedule generator, total cost helper)

Depreciation Simplifications

US MACRS (Simplified)

• Half-year convention only
• Implemented property classes: (list those present in file)
• Even intra-year allocation (monthly split or proportional annual as documented)
• No mid‑quarter convention
• No bonus depreciation (§168(k))
• No Section 179 expensing
• No luxury auto limits
• No short-year adjustments
• TODO markers for each omitted regime variant

UK Capital Allowances (Simplified)

• AIA (Annual Investment Allowance) applied first up to configured cap for Year 1
• Remaining pool allocated to main (18%) or special (6%) pools as indicated
• Single aggregated asset assumption (no multi-asset pooled acquisitions)
• No First Year Allowances / super-deduction
• No disposal / balancing adjustments
• Termination when pool ≈ 0 or max years reached
• Allowances rounded MidpointAwayFromZero
• TODO markers: FYA, partial periods, disposal events, short period adjustments, multi-asset pooling

Loan Scope

Implemented:

• Fixed nominal annual rate divided by payment frequency
• Balloon (residual) handling
• Recurring per-period fee
• Validation for positive principal, term, frequency
• Rounding via cent utilities

Not Implemented (TODO):

• Variable / floating rates
• Interest-only or stepped schedules
• Payment holidays
• Fee capitalization / amortized origination cost treatment
• Multi-currency

Lease Scope

Implemented:

• Level periodic rentals with optional per-period fees
• Residual value stored informationally
• Schedule generation + total cost aggregation

Not Implemented (TODO):

• IFRS 16 / ASC 842 right-of-use accounting
• Classification logic (finance vs operating)
• Variable/index-linked payments
• Residual value guarantees & purchase options
• Re-measurement events

Tests Added

• Simple Depreciation (straight-line and declining-balance)
• Loan:
  • Balloon residual near expected
  • Invalid parameter guards (negative principal/term/frequency, balloon > principal)
  • Principal portions + balloon ≈ original principal (rounding tolerance)
• Lease:
  • Schedule length correctness
  • Total cost aggregation
  • Residual value independence of rental math
• US MACRS:
  • Depreciation sum ≈ cost basis (tolerance)
  • Non-negative declining remaining basis
• UK Capital Allowances:
  • AIA total elimination case
  • Partial AIA then WDA year 2 diminishing balance
  • Final tiny residual clearance
• Rounding edge test (midpoint behavior)

Documentation Changes

Added / Updated:

• docs/equipmentFinanceOverview.md (Loans, Leases, US & UK depreciation)
• docs/equipmentFinanceUsMacrs.md (simplifications + TODO)
• docs/equipmentFinanceUk.md (simplifications + TODO)
• docs/BUSINESS_CASES_INDEX.md (marks Equipment Finance as implemented, notes “simplified”)
• README: concise Equipment Finance section linking these docs

All docs emphasize: analytical-only; not financial / tax / accounting advice.

Rounding & Monetary Consistency

• All monetary values: int64<Cent>
• Derived values use Cent.fromDecimalCent MidpointRounding.AwayFromZero
• Tests assert invariants within ≤ 1 cent tolerance where appropriate

Backwards Compatibility

• Additive only; no changes to existing non-equipment modules
• No version bump (per instructions). Merge conflicts (if any) resolved favoring retention of existing main content plus ordered new includes

Next Steps (Proposed Roadmap)

1. US MACRS: mid-quarter, bonus, Section 179, luxury auto limits
2. UK: FYA / super-deduction historic support, disposal adjustments
3. Multi-asset pooling & asset-level tracking
4. Lease accounting (IFRS 16 / ASC 842) with PV & remeasurement logic
5. Variable / floating loan rates & interest-only phases
6. IRR / XIRR integration for comparative analytics
7. After-tax scenario engine (depreciation + financing + salvage)
8. Multi-currency extension
9. Performance profiling & potential lazy schedules
10. Lease vs Buy integrated NPV comparer

Validation Checklist

• Clean dotnet build succeeds
• dotnet test passes

License / Disclaimer

Analytical-only computations. Not tax, legal, accounting, or financial advice. Users must verify applicability and compliance independently.

[Copilot]

Pull request overview

Adds a new FSharp.Finance.Personal.EquipmentFinance domain that bundles equipment loans, leases, and simplified US/UK depreciation models, along with docs and baseline tests.

Changes:

• Introduces new Equipment Finance modules: Loans, Leases, US MACRS, UK Capital Allowances, plus shared depreciation utilities.
• Adds new test suites for the new modules and wires them into the test project.
• Updates documentation/examples and adds minor DU-case argument naming improvements in existing core modules.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 17 comments.

Show a summary per file

File	Description
src/FSharp.Finance.Personal.fsproj	Adds Equipment Finance source files to compilation.
src/EquipmentFinance/Depreciation/DepreciationCommon.fs	Shared depreciation utilities (SL/DB schedules, rounding, validation, disclaimers).
src/EquipmentFinance/Depreciation/US_MACRS.fs	Simplified MACRS tables + schedule generation + examples.
src/EquipmentFinance/Depreciation/UK_CapitalAllowances.fs	Simplified UK AIA+WDA schedule generator + examples.
src/EquipmentFinance/Loan.fs	Equipment loan payment, schedule, and MACRS-linked analysis.
src/EquipmentFinance/Lease.fs	Equipment lease payment, PV, schedules, and lease-vs-buy analysis.
src/Scheduling.fs	Adds named fields to DU cases for clarity.
src/Interest.fs	Adds named fields to Rate DU cases.
src/Fee.fs	Adds named fields to FeeType DU cases.
src/Amortisation.fs	Removes an attribute from OffsetDayType module.
tests/FSharp.Finance.Personal.Tests.fsproj	Includes new Equipment Finance test files.
tests/DepreciationCommonTests.fs	Tests for shared depreciation utilities and rounding invariants.
tests/USMacrsTests.fs	Tests for MACRS recovery periods, tables, and schedules.
tests/UKCapitalAllowancesTests.fs	Tests for AIA/WDA schedules and default config.
tests/EquipmentLoanTests.fs	Tests for loan payment/details/schedule + depreciation integration.
tests/EquipmentLeaseTests.fs	Tests for lease payment/details/schedules + depreciation integration.
docs/EquipmentFinanceExamples.fsx	Usage examples script (mostly illustrative output).
docs/EquipmentFinance.md	High-level documentation for the new modules.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Convention includes MidQuarter, but the implementation uses only half-year tables and doesn't check asset.Convention. Since the module is documented as half-year only, consider rejecting MidQuarter explicitly (e.g., invalidArg) or removing it to avoid silently incorrect results.

Suggested change

	| HalfYear // half-year convention (most common)
	| MidQuarter // mid-quarter convention (when over 40% of assets placed in service in Q4)
	| HalfYear // only supported convention in this module