fix(kilo-pass): display actual issued bonus

[jeanduplessis]

Summary

Show the Kilo Pass bonus that was actually issued instead of using a formula projection as available credit.

Why this change is needed

Referral bonuses can differ from the normal Kilo Pass projection. Once a bonus has been issued, continuing to display the projected amount makes the usage total disagree with the customer’s real credit issuance and balance.

Actual and projected values must remain separate so estimates are not presented as account credit.

How this is addressed

• Add explicit current-period bonus state with separate actual and projected amounts.
• Read the issued bonus kind and amount from the latest issuance.
• Display issued referral bonuses as “Referral bonus” and other issued bonuses as “Free bonus.”
• Use actual issued credit in the current-period usage total, while retaining projections for bonuses that remain available to unlock.
• Clarify that next-period bonus credits are projected amounts using “up to” wording.
• Update the Kilo Pass specification while preserving the no-double-bonus rule.
• Cover referral amounts both below and above the normal projection.

Human Verification

• Targeted Kilo Pass router and active-card tests passed: 137 tests.
• React Doctor reported 100/100 with no issues.
• Confirmed the implementation matches the updated Kilo Pass projection and issuance rules.

Reviewer Notes

Human Reviewer Flags

• The Kilo Pass specification now requires current-period displays and available-credit totals to use the actual bonus-like issuance amount after issuance.
• The existing projection field remains unchanged for compatibility; a separate structured field carries issued state, kind, actual amount, and projected amount.

Code Reviewer Agent

Code Reviewer Notes

• The latest issuance query now returns the bonus-like item’s persisted kind and amount_usd.
• The UI resolves one display amount: actual when issued, projected only while available.
• Referral bonus regression coverage includes values lower and higher than the formula projection.
• Renewal projection behavior remains unchanged apart from copy that makes its unissued status explicit.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

Reviewed all 6 changed files for the Kilo Pass actual-issued-bonus display fix. The router correctly separates actual issuance amounts from formula projections via the new currentPeriodBonus field, the UI layer resolves the correct display amount and label for issued vs. available bonuses, and test coverage includes referral bonus amounts both above and below the normal projection. No bugs, security issues, or missing error handling found in the changed code.

Files Reviewed (6 files)

• .specs/kilo-pass.md — spec updated to require actual/projected separation, "up to" wording for next-period, and referral bonus labeling
• apps/web/src/routers/kilo-pass-router.ts — getLatestBonusLikeItemForSubscriptionId returns kind + amount; buildActiveKiloPassSubscriptionState populates structured currentPeriodBonus; buildEndedKiloPassSubscriptionState nulls it out correctly
• apps/web/src/routers/kilo-pass-router.test.ts — regression tests for referral bonus amounts lower and higher than projection
• apps/web/src/components/profile/kilo-pass/KiloPassActiveSubscriptionCard.logic.ts — computeCurrentPeriodBonusModel resolves actual vs. projected with correct labels and null-safety
• apps/web/src/components/profile/kilo-pass/KiloPassActiveSubscriptionCard.test.ts — thorough unit tests for the new model function including edge cases
• apps/web/src/components/profile/kilo-pass/KiloPassActiveSubscriptionCard.tsx — uses new model for usage progress; "up to" wording for renewal projections

---

_{Reviewed by kimi-k3 · Input: 10.5K · Output: 2.1K · Cached: 528.4K}

_{Review guidance: REVIEW.md from base branch main}