Bonuses, Commissions, other income sources

[kryptodrex]

• Ability to add estimated annual, quarterly, custom bonuses that are % of gross or fixed amounts that count as an income
• Ability to add estimated commissions or tips
• Add other income sources, such as rent, retirement plan withdrawals, etc.

[kryptodrex]

v0.5.0 Plan: Other Income Sources

Status keys:

• [ ] Planned
• [-] In Progress
• [x] Done

Parent item: in v0.5.0-list.md
Parent status: [x] Done

---

Goal

Add support for income sources beyond the base salary/hourly paycheck while keeping pay calculations, taxes, summaries, exports, search, and audit history understandable and deterministic.

Scope Decision for v0.5.0

• In scope: Fixed-amount other income entries with frequency, income type, notes, enable/disable, and taxability controls.
• In scope: Percentage-of-gross income rules for bonus-style income.
• In scope: Automated withholding presets by income type with manual override preserved.
• In scope: Clear income-impact treatment so entries can affect gross pay, taxable income only, or net pay only depending on the income source.
• In scope: Inclusion of other income impacts in annual, monthly, and per-paycheck summary views.
• In scope: History/audit coverage, search integration, save/load/migration support, and demo-data/new-plan compatibility.
• Out of scope for v0.5.0 unless explicitly approved later: Country-specific tax engines for all jurisdictions tied to other-income type.
• Out of scope for v0.5.0 unless explicitly approved later: Fully date-effective payout schedules beyond simple frequency/month-window controls.

---

Product Model

Supported Income Types

• Add built-in income types for Bonus, Commission, Rental Income, Retirement Withdrawal, Disability, Reimbursement/Allowance, Investment Income, and Other.
• Allow a custom label when incomeType = 'other' or when users want a payroll-source-specific name. (The name field supports this for every entry.)

Income Impact Modes

• Add a required income-impact field, such as payTreatment: 'gross' | 'taxable' | 'net'.
• Define gross treatment for payroll-like income that should increase gross pay first, then flow through taxable income and taxes.
• Define taxable treatment for supplemental income that should affect withholding/taxable wages but remain visually separate from base paycheck gross.
• Define net treatment for after-tax income that should increase take-home totals without affecting taxable income or withholding.
• Document which built-in income types default to each treatment and allow manual override when needed.

Withholding Behavior

• Add per-entry withholding mode, such as manual | auto | none, with sane defaults by income type and treatment. (Field and UI exist; auto is saved but not yet computed — see Workstream C.)
• Ensure auto mode can propose withholding deltas without overwriting the user's existing manual tax lines.
• Ensure none mode is available for net-only and user-managed tax scenarios.

Calculation Principles

• Keep calculations deterministic and explainable across mixed base pay + other income scenarios.
• Preserve the current bias toward conservative/over-estimated withholding instead of under-estimated take-home.
• Keep manual user edits authoritative whenever automated logic would otherwise conflict.

---

Workstream A: Core Other-Income Model and Data Layer

Data Model

• Add a new OtherIncome type with fields for id, name, incomeType, amountMode, amount, percentOfGross, frequency, enabled, notes, isTaxable, payTreatment, withholdingMode, and optional withholdingProfileId.
• Add optional scheduling controls for expanded scope, such as activeMonths?: number[]. (Field exists in type and normalized in fileStorage; no form UI yet — see Defaulting/Validation.)
• Add optional guardrails for percent-based entries, such as cap/floor fields if needed. (Guardrail shipped: percent-of-gross must be > 0 and <= 100.)
• Add otherIncome?: OtherIncome[] to BudgetData.
• Add migration defaults so existing plans load with otherIncome: [].
• Update runtime validation/type guards to safely load and validate the new structure. (Type guards and normalizers for all 6 enum fields in fileStorage.ts.)
• Add migration and backwards-compatibility tests.

Tab view

• Add a new tab labeled as "Other Income" with structure similar to other tabs
  • Use the 'BanknoteArrowUp' icon
• This tab should be structured appropriately for these new income sources, using the similar SectionCardItem components from other views
• The tab by default should be hidden as it won't be the most common to use, and user can choose to 'show' it from the Manage Tabs modal.

Defaulting and Validation Rules

• Require non-negative values for fixed amounts, percent rules, and optional caps/floors.
• Restrict percent-of-gross entries to sensible ranges and document the final guardrails. (Shipped guardrail: percent-of-gross must be > 0 and <= 100.)
• Require explicit frequency for every other-income entry.
• Require explicit payTreatment so each entry's effect on calculations is unambiguous.
• Validate that active-month schedules are unique, in-range, and compatible with the selected frequency.

---

Workstream B: Calculation Engine and Income Placement Rules

Frequency and Annualization

• Add shared utilities to convert other-income entries into annual, monthly, and per-paycheck equivalents. (src/utils/otherIncome.ts)
• Support deterministic handling for annual, quarterly, monthly, and per-paycheck income frequencies.
• Document rounding strategy for line-level and aggregate calculations. (Policy settled: intermediate per-paycheck amounts are not rounded; rounding only at final display/annual presentation boundaries.)

Fixed-Amount Entries

• Integrate fixed-amount other income into the pay calculation pipeline.
• Ensure gross entries increase gross pay before pre-tax deductions and taxes.
• Ensure taxable entries increase taxable income and withholding calculations while remaining distinct from base paycheck gross in presentation.
• Ensure net entries increase take-home amounts only and do not affect taxable income or tax calculations.

Percentage-of-Gross Rules

• Add amountMode: 'fixed' | 'percent-of-gross'.
• Resolve the percent base from the base paycheck gross before other-income additions unless a future basis override is explicitly approved.
• Compute percent-based entries in a deterministic order that prevents circular references.
• Add preview helpers so the UI can show computed per-paycheck/month/year amounts before save.
• Add focused tests for mixed fixed + percent income stacks.

Tax and Withholding Interaction

• Define how taxable other income contributes to the existing tax-estimation and tax-line model.
• For gross and taxable entries, compute withholding deltas separately from base paycheck taxes so the source of withholding remains explainable.
• Keep current manual tax lines authoritative unless a dedicated auto-withholding path is enabled.
• Make sure auto-withholding suggestions add deltas predictably rather than silently mutating unrelated tax lines.
• Ensure net entries never inflate gross/taxable displays or withholding totals.

---

Workstream C: Automated Withholding Presets

Preset Model

• Add default withholding profiles by income type, such as supplemental bonus behavior, retirement-withdrawal withholding, or no-withholding defaults for non-payroll income.
• Add optional withholdingProfileId to other-income entries. (Field exists on type; always undefined in practice until profiles are defined.)
• Keep profile mapping internal/testable so the UI only consumes structured profile metadata.

Calculation Behavior

• Add withholdingMode: 'manual' | 'auto' | 'none' per entry or equivalent plan-safe design. (Field, type guard, normalizer, and UI mode selector all present. auto behavior is saved but not yet computed.)
• In auto mode, generate withholding suggestions from the selected/default profile.
• In manual mode, let the user enter or leave withholding impact fully under their control.
• In none mode, record the income without any automatic withholding impact.
• Ensure auto-generated withholding is visible as a distinct source in breakdowns and explain views.

Explainability and Safety

• Add a trace/explain structure: income source, treatment mode, withholding source, taxable base, applied rate, and estimated withheld amount.
• Preserve a one-click fallback to manual control if the user dislikes or distrusts auto behavior. (Withholding mode selector allows switching to manual at any time.)
• Add regression tests ensuring manual tax lines are not overwritten unexpectedly.

---

Workstream D: UI and UX

Other Income Management UI

• Add an OtherIncomeManager tab view using existing manager patterns.
• Add create/edit/delete/enable-disable flows for other-income entries.
• Add validation UI for required fields, non-negative values, and schedule conflicts.
• Show treatment clearly in the form so users understand whether an income source affects gross, taxable income, or net pay.

Entry Form Behavior

• Add toggle between fixed amount and % of gross for eligible entries.
• Add frequency selector and optional active-month selector for irregular income.
• Add treatment selector with helper text for Gross, Taxable Only, and Net Only.
• Add withholding mode selector and profile selector where relevant.
• Show real-time previews for per-paycheck, monthly, and annual impact.
• Warn when the chosen frequency/month-window combination creates sparse or irregular payouts.

Summary and Breakdown Presentation

• Show other-income contributions in key summary views without obscuring base pay.
• Make sure taxable-only income is displayed distinctly enough that gross-pay reconciliation still makes sense. (Separate 'Taxable additions' section in Pay Breakdown.)
• Add breakdown rows or grouped sections so users can understand how each income source affects totals. (Pay Breakdown shows per-entry line items in gross/taxable/net sections.)
• Ensure tax views can show which tax impacts come from other income vs base paycheck where practical. (Pay Breakdown and tax rows now include distinct Other Income auto-withholding source rows.)

---

Workstream E: Integration, Search, Export, and History

Integration

• Wire tab visibility defaults and tab management support.
• Ensure exports and PDFs include other-income impacts where relevant.
• Ensure demo/new plan initialization includes a realistic empty/default otherIncome field.
• Ensure encryption/save/load paths include the new field.

Search and Navigation

• Add search integration entries and deep-link actions for Other Income. (src/utils/searchModules/otherIncomeSearchModule.ts — per-entry results with toggle/edit/delete/add actions.)
• Support search terms for income type, treatment, withholding mode, and manager actions where appropriate.

Audit and History

• Add history/audit integration for create/update/delete/enable-disable actions.
• Ensure audit entries summarize whether a change affected gross, taxable-only, or net-only income behavior.

---

Testing Plan

Unit Tests

• Unit tests for frequency conversion and annualization logic.
• Unit tests for fixed vs percent-of-gross amount calculation.
• Unit tests for month-window behavior.
• Unit tests for gross vs taxable-only vs net-only treatment.
• Unit tests for withholding profile behavior and mode selection.

Integration and Regression Tests

• Regression tests for mixed base pay + other income + tax scenarios.
• Regression tests ensuring taxable-only entries affect taxes without corrupting base gross displays.
• Regression tests ensuring net-only entries bypass tax logic entirely.
• Regression tests verifying existing plans still load without data loss.
• Regression tests ensuring manual tax lines are not overwritten unexpectedly.

UI and Workflow Tests

• Component tests for add/edit/delete/toggle flows. (Minimal — add entry and render entry covered.)
• Component tests for amount-mode toggles, previews, and treatment selection.
• Search/action tests for opening and focusing the correct UI targets.
• Explainability tests for withholding preview/output if an explain panel is added. (Covered via auto-withholding calculation and manager/profile-output tests.)

---

Risks

• Risk: Adding taxable-only income can create confusing gross vs taxable reconciliations.
• Mitigation: Present base gross and supplemental taxable income separately in summaries and breakdowns.
• Risk: Auto-withholding may reduce user trust if it silently changes take-home pay.
• Mitigation: Keep manual override explicit, show previews, and expose the withholding source/rate/base.
• Risk: Percent-of-gross rules can introduce circular or order-dependent math.
• Mitigation: Lock the percent base to base paycheck gross and test deterministic ordering.
• Risk: Scope expansion may create regressions in core paycheck calculations.
• Mitigation: Add focused regression coverage for mixed income/tax scenarios before release cut.

Dependencies

• Depends on stable budget migration and validation paths in file storage.
• Depends on calculation services that can support additional income inputs without destabilizing existing paycheck flows.
• Depends on tab/search registration updates for discoverability.
• Depends on export and audit layers being able to surface the new income impacts clearly.

---

Acceptance Criteria

• Users can add, edit, pause, and delete other income entries and view their history.
• Users can choose whether an entry affects gross pay, taxable income only, or net pay only.
• Users can configure fixed-amount and % of gross income rules with clear previews.
• Automated withholding presets are available where relevant, transparent, and manually overridable.
• Other income appears in relevant annual, monthly, and per-paycheck totals without obscuring base-pay behavior.
• Other income entries are tracked in the audit log.
• Existing plans open normally with no migration issues.
• Tests cover core math, UI interactions, tax interaction behavior, and migration paths.

Done Definition

• Other-income management is available and stable in v0.5.0.
• Fixed-amount, % of gross, and withholding-preset workflows are complete or explicitly deferred before release cut.
• Gross/taxable-only/net-only treatment behavior is documented, implemented, and covered by tests.
• All planned tests for this item pass.
• Release notes include a user-facing outcome summary.