feat(cpf): add MA overflow to SA/RA when BHS cap reached by jcleow · Pull Request #181 · jcleow/wealthproject

jcleow · 2026-01-18T04:20:22Z

Summary

When MA contributions would exceed the Basic Healthcare Sum (BHS), excess now automatically overflows to SA (age <55) or RA (age ≥55)
NEW: MA interest also overflows when MA is at/above BHS
Interest is now calculated on opening balance (before contributions) per CPF policy
Uses projected BHS with 4% annual growth via GetBHS(year)

Flow Diagram

flowchart TD
    subgraph Monthly["ProcessMonth Order"]
        A[Start of Month] --> B[1. YTD Reset if new year]
        B --> C[2. RA Formation at age 55]
        C --> D[3. Apply Interest on Opening Balance]
        D --> E[4. Apply Contributions]
        E --> F[5. CPF LIFE Payout]
    end

    subgraph Interest["Step 3: Interest Calculation"]
        D --> I1{MA >= BHS?}
        I1 -->|Yes| I2{Age >= 55?}
        I1 -->|No| I3[Add MA interest to MA]
        I2 -->|Yes| I4[MA interest → RA]
        I2 -->|No| I5[MA interest → SA]
    end

    subgraph Contrib["Step 4: MA Contribution"]
        E --> C1{MA >= BHS?}
        C1 -->|Yes, full overflow| C2{Age >= 55?}
        C1 -->|No| C3{MA + contrib > BHS?}
        C3 -->|Yes, partial overflow| C4[Fill MA to BHS]
        C3 -->|No| C5[Add to MA]
        C4 --> C2
        C2 -->|Yes| C6[Overflow → RA]
        C2 -->|No| C7[Overflow → SA]
    end

    style I4 fill:#4ade80
    style I5 fill:#4ade80
    style C6 fill:#4ade80
    style C7 fill:#4ade80

Changes

File	Description
`interest.go`	Add MA interest overflow to SA/RA when MA >= BHS
`lifecycle.go`	Reorder: interest before contributions; add overflow tracking
`retirement.go`	Add `ApplyMAContributionWithBHSCap` and helper functions
`ma_overflow_test.go`	Comprehensive tests for contribution and interest overflow

Test plan

Unit tests for RedirectMAOverflowFromBHS function (6 cases)
Integration tests for ProcessMonth with contributions (5 cases)
NEW: Tests for MA interest overflow (5 cases)
BHS growth projection tests across years (4 cases)
Edge case tests for nil inputs
All existing CPF tests pass
Pre-commit hooks pass

Closes #169

🤖 Generated with Claude Code

jcleow · 2026-01-18T04:31:23Z

backend/internal/cpf/engine/lifecycle.go

+				} else {
+					// Calculate room available in MA before hitting BHS
+					room := bhs.Sub(state.MA)
+					if maContrib.Cmp(room) <= 0 {


rename room to remainderToMACap

jcleow · 2026-01-18T04:34:29Z

backend/internal/cpf/engine/ma_overflow_test.go

+			}
+
+			// Check overflow amounts in result - this is the key test
+			if got := result.MAOverflowToSA.ToFloat64(); got != tt.wantMAOverflowSA {


what does "got" mean?

jcleow · 2026-01-18T04:35:33Z

backend/internal/cpf/engine/ma_overflow_test.go

+	testDate := time.Date(2026, 6, 1, 0, 0, 0, 0, time.UTC)
+
+	// Person born in 1991 (age 35 in 2026)
+	dobAge35 := time.Date(1991, 1, 1, 0, 0, 0, 0, time.UTC)


will these tests fail in a new year

Per CPF policy, when the MediSave Account (MA) balance reaches the Basic Healthcare Sum (BHS), additional MA contributions overflow to: - SA (Special Account) for members age < 55 - RA (Retirement Account) for members age >= 55 Changes: - Add MAOverflowToSA/MAOverflowToRA tracking fields to MonthlyResult - Add RedirectMAOverflowFromBHS function in retirement.go - Call overflow check in ProcessMonth after contributions - Add comprehensive unit tests for overflow scenarios Closes #169 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Rename 'room' to 'remainderToMACap' in lifecycle.go for clarity - Replace generic 'got' variable names with descriptive names: - actualOverflowToSA, actualOverflowToRA for overflow amounts - actualFinalMA, actualFinalSA, actualFinalRA for balance checks - actualOverflow for BHS growth tests - Use dynamic base year from assumptions instead of hardcoded 2026 to ensure tests work regardless of current year - Modernize Go syntax: use max() builtin and range-over-int Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Enhance TestProcessMonth_MAOverflow_BHSGrowthAcrossYears with: - Comprehensive header explaining BHS 4% annual growth projection - Detailed description field for each test case showing: - Year and projected BHS value with growth calculation - Initial MA, contribution, and expected overflow - Clear explanation of why overflow occurs/doesn't occur - Verbose logging showing actual BHS projection and growth percentage - wantOverflow boolean for explicit overflow expectation The tests now clearly demonstrate that monthly MA contributions are compared against the PROJECTED BHS for that year (e.g., $92,418 in 2030), not the base year BHS ($79,000 in 2026). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jcleow · 2026-01-18T05:00:36Z

backend/internal/cpf/engine/ma_overflow_test.go

+	// Example with base year 2026:
+	//   - 2026: BHS = $79,000 (base)
+	//   - 2028: BHS = $79,000 × 1.04² = $85,446.40
+	//   - 2030: BHS = $79,000 × 1.04⁴ = $92,436.89


should be 92,418.83

jcleow · 2026-01-18T05:02:27Z

backend/internal/cpf/engine/ma_overflow_test.go

+					t.Errorf("Expected overflow but got none. MA contribution should have exceeded projected BHS of $%.2f", projectedBHS)
+				}
+				// Check overflow amount matches expected (with $1 tolerance for rounding)
+				tolerance := 1.0


there should be no tolerance, answer must be exact

jcleow · 2026-01-18T05:03:02Z

backend/internal/cpf/engine/ma_overflow_test.go

+			// Verify MA is capped at projected BHS (if overflow occurred)
+			if tt.wantOverflow {
+				endMA := result.EndOfMonthState.MA.ToFloat64()
+				// MA should be near projected BHS (plus up to 0.5% monthly interest)


where is this 0.5% monthly interest coming from

- Move age-based overflow routing logic to package-level helper - Simplify ProcessMonth by removing inline closure - Use "calculate then check" pattern for overflow detection Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jcleow · 2026-01-18T05:05:18Z

backend/internal/cpf/engine/ma_overflow_test.go

+				tt.year, projectedBHS, baseBHS, tt.year-baseYear)
+
+			// Calculate expected overflow: (initialMA + contribution) - projectedBHS
+			totalMAAfterContribution := float64(tt.initialMA) + float64(tt.maContribution)


arithmetic operation using float64 is not allowed. use decimal

- Fix BHS calculation in comment: $92,436.89 → $92,418.83 - Remove arbitrary $1 tolerance, use exact cent comparison with rounding - Clarify that final MA includes interest earned after BHS cap applied - Use math.Round() to handle float precision when comparing cents Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jcleow · 2026-01-18T05:07:17Z

backend/internal/cpf/engine/lifecycle.go

+				bhs := opts.Assumptions.GetBHS(date.Year())
+				maContrib := contrib.Allocation.MA
+
+				if state.MA.Cmp(bhs) >= 0 {


we should encapsulate this further into a helper function for Redirecting MA overflows in general so its clearer and lower cognitive load for other readers

Address PR review comments: - Create ApplyMAContributionWithBHSCap helper in retirement.go for lower cognitive load when reading lifecycle.go (reduced from ~20 lines to 4) - Convert BHS growth test to use decimal arithmetic instead of float64 for exact comparisons without floating-point precision issues - Remove unused math import Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

When MA balance is at or above BHS, MA interest now overflows to: - SA for members age < 55 - RA for members age >= 55 Also reorders ProcessMonth to apply interest BEFORE contributions, since CPF calculates interest on the opening (lowest) balance during the month. Changes: - Add MAInterestOverflowToSA/RA fields to InterestResult - Check BHS in ApplyMonthlyInterest and redirect MA interest - Swap steps 3 and 4 in ProcessMonth (interest before contributions) - Update tests with correct expected values and add MA interest test Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jcleow · 2026-01-18T06:18:41Z

backend/internal/cpf/engine/ma_overflow_test.go

+			// Verify that overflow was correctly added to SA or RA
+			if tt.wantMAOverflowSA > 0 {
+				// SA should include the overflow (plus interest)
+				minExpectedSA := float64(tt.initialSA) + tt.wantMAOverflowSA


we shouldn't use float64

jcleow · 2026-01-18T06:19:14Z

backend/internal/cpf/engine/ma_overflow_test.go

+	baseBHS := assumptions.BHSBase
+
+	// Person under 55 (overflow goes to SA)
+	dob := time.Date(baseYear-35, 1, 1, 0, 0, 0, 0, time.UTC)


no magic numbers

jcleow · 2026-01-18T06:22:12Z

backend/internal/cpf/engine/interest.go

 	state.RA = state.RA.Add(raInterest)

+	// MA interest: if MA >= BHS, redirect interest to SA/RA instead of MA
+	if state.MA != nil && bhs != nil && state.MA.Cmp(bhs) >= 0 {


can we have helper methods like gt, lt, gte, lte to make it easy to understand the comparisons

jcleow · 2026-01-18T06:25:59Z

backend/internal/cpf/engine/lifecycle.go

 	}

-	// Step 3: Apply contributions (if any)
+	// Step 3: Apply interest (on opening balance, before contributions)


need to explicit that is this is an Assumption. CPF uses the lowest balance in the month so there is room for more granular implementation

Address PR review comments: - Add GT, GTE, LT, LTE, EQ helper methods to decimal package for readability - Replace all Cmp() calls with semantic helpers throughout CPF engine - Convert test struct fields from float64 to int64/*decimal.Decimal - Use decimal comparison methods instead of ToFloat64() in assertions - Replace magic number 35 with named constant testAge Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add explicit ASSUMPTION comment for interest calculation on opening balance - Replace tolerance-based checks with exact decimal comparisons - Use decimal arithmetic throughout tests (remove float64 operations) - Fix test name to show correct BHS value (~$92,419 not ~$92,437) - Use named constants for test ages (ageUnder55, ageAt55) - Use ToCents() for accurate int64 conversion from decimal - Replace remaining Cmp() calls with GT/GTE/LT/LTE/EQ helpers Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Run go mod tidy to properly categorize x/time as a direct dependency rather than indirect. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jcleow · 2026-01-18T06:46:20Z

backend/internal/cpf/engine/ma_overflow_test.go

+			if !tt.wantMAOverflowSA.IsZero() {
+				// SA should include the overflow (plus interest)
+				minExpectedSA := decimal.NewFromInt64(tt.initialSA, 0).Add(tt.wantMAOverflowSA)
+				if endState.SA.LT(minExpectedSA) {


why are we not testing for exact? same for other tests

The overflow amounts are already verified exactly via MAOverflowToSA/RA tracking fields. The "at least" balance checks were redundant and didn't test for exact values as requested. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jcleow · 2026-01-18T06:48:49Z

backend/internal/cpf/engine/ma_overflow_test.go

+
+			// KEY ASSERTION: Verify BHS is actually growing across years
+			if tt.year > baseYear {
+				if projectedBHS.LTE(baseBHS) {


this should be tetsted for exactness

- Remove remaining "at least" balance checks in interest overflow test - Update test names to show exact BHS values instead of approximate (~) - All assertions now use exact decimal comparisons via EQ() Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Replace LTE comparison with exact EQ comparison for verifying BHS growth across years. Now tests the exact calculated value. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jcleow force-pushed the feature/cpf-ma-bhs-overflow branch from a87dd8a to 1aae440 Compare January 18, 2026 04:29

jcleow commented Jan 18, 2026

View reviewed changes

jcleow force-pushed the feature/cpf-ma-bhs-overflow branch from 1aae440 to fbe414c Compare January 18, 2026 04:39

jcleow and others added 3 commits January 18, 2026 12:42

update AGENTS.md

187e19c

jcleow commented Jan 18, 2026

View reviewed changes

jcleow and others added 2 commits January 18, 2026 13:11

jcleow commented Jan 18, 2026

View reviewed changes

jcleow and others added 3 commits January 18, 2026 14:31

chore: move golang.org/x/time to direct dependency

4bb4c24

Run go mod tidy to properly categorize x/time as a direct dependency rather than indirect. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jcleow commented Jan 18, 2026

View reviewed changes

test(cpf): remove redundant SA/RA balance checks

6d0b14e

The overflow amounts are already verified exactly via MAOverflowToSA/RA tracking fields. The "at least" balance checks were redundant and didn't test for exact values as requested. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jcleow commented Jan 18, 2026

View reviewed changes

jcleow and others added 2 commits January 18, 2026 14:50

test(cpf): use exact comparison for BHS growth verification

e54b143

Replace LTE comparison with exact EQ comparison for verifying BHS growth across years. Now tests the exact calculated value. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jcleow merged commit 97178b8 into main Jan 18, 2026
1 check passed

Conversation

jcleow commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Flow Diagram

Changes

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jcleow commented Jan 18, 2026 •

edited

Loading