Add Salary Advance Zero-Interest Modeling Module

[Thorium]

Summary

Introduces zero-interest Salary Advance / Earned Wage Access modeling under:
FSharp.Finance.Personal.SalaryAdvance

Focus: construct repayment schedules, handle fee treatments, expose provider-perspective cashflows.

---

Module Overview

src/SalaryAdvance.fs

Types:

• RepaymentMode = LumpOnFirstPayroll | EvenlyProrated | Custom of int64<Cent> list
• Fee = NoFee | Flat of int64<Cent> | Percentage of decimal (0 < p < 1)
• FeeTreatment = NettedFromProceeds | AddedOnTop
• BuildConfig
• SalaryAdvanceResult

Primary function:

• build : BuildConfig -> SalaryAdvanceResult

Helper:

• borrowerCashflows (sign inversion for borrower perspective analysis)

---

Fee & Principal Logic

FeeTreatment	Net Disbursed	Total Repayable	Principal Stored
NettedFromProceeds	Advance - Fee	Advance	Advance
AddedOnTop	Advance	Advance + Fee	Advance + Fee

Principal equals the sum of scheduled repayments so amortisation alignment is preserved.
Fee rounding: percentage fee → multiply advance amount, round up fractional cent.

---

Validations

• Payroll dates: non-empty, strictly increasing, all > AdvanceDate
• Percentage fee: 0 < p < 1
• Custom list length = payroll dates length AND sums to total repayable
• AdvanceAmount > 0

---

Repayment Allocation

• Lump: single payment on first payroll date
• EvenlyProrated: integer division across all dates; final repayment absorbs remainder
• Custom: explicit amounts—must match total & count

---

Cashflow Convention

Provider perspective:

• (AdvanceDate, -netDisbursed)
• Each payroll date: positive repayment

Borrower-facing analytics: use borrowerCashflows to invert signs.

---

APR Handling

Reuses Apr.CalculationMethod.UnitedKingdom 2 placeholder (no interest).
Potential future addition: AprMethod.Disabled for clarity on zero-interest products.

---

Tests

Planned / to be ensured:

• Test_Lump_Netted_NoFee
• Test_Prorated_PercentageFee_AddedOnTop
• Test_CustomMismatch_ShouldFail

All validate principal, fee handling, sum consistency, and failure modes.

---

Documentation

docs/exampleSalaryAdvance.fsx:

• Demonstrates both fee treatments
• Prints cashflows & totals
• Notes that XIRR analytics reside in separate B2B PR
• Serves as a user onboarding example for fee semantics

---

Checklist

• Module scaffold
• Tests added & green
• README bullet added (verify after push)
• Build verification
• Coordinate version bump after B2B PR merges

---

Open Questions

1. Introduce Apr.CalculationMethod.Disabled later?
2. Unify fee abstraction with future factoring / trade credit?
3. Add early/partial repayment support?

---

Non-Goals (This PR)

• Interest accrual mechanics
• Multi-advance aggregation
• XIRR calculation
• Regulatory or compliance classification

---

Disclaimer

Analytical only; validate independently for production, compliance, or disclosure usage.