feat(tax): add prior losses handling

Author: SkeLLLa

docs/HOW-IT-WORKS.md

@@ -470,13 +470,15 @@ poz29 = max(poz27 − poz26, 0)              // Loss (strata)
 #### Section D — Tax Calculation
 
 ```
-poz30 = min(priorYearLoss, poz28)            // Prior year loss deduction (capped at gain)
+poz30 = applyLossCarryForward(priorLosses, poz28).deductedPln  // Prior-year loss deduction
 poz31 = roundToFullPln(max(poz28 − poz30, 0))  // Tax base (podstawa obliczenia podatku)
 poz33 = poz31 × 0.19                        // Tax amount (podatek)
 poz34 = 0                                    // Foreign tax on capital gains (not applicable)
 poz35 = roundToFullPln(max(poz33 − poz34, 0))  // Tax due (podatek należny)
 ```
 
+`applyLossCarryForward` enforces the 5-year window and 50%-per-year cap per loss entry — see Section 9.
+
 #### Sections E & F — Crypto (placeholders, all zeros)
 
 Not yet implemented. Fields poz36–poz45 are set to 0.
@@ -534,19 +536,34 @@ Results are sorted alphabetically by country code.
 
 ### 9. Prior Year Losses (Carry-Over)
 
-**Legal basis:** [Art. 9 ust. 3 ustawy o PIT](https://lexlege.pl/ustawa-o-podatku-dochodowym-od-osob-fizycznych/art-9/) — losses from a given income source can be carried forward for up to 5 consecutive tax years, with two alternative methods:
+**Implementation:** `src/core/tax/loss-carry-forward.ts`
+
+**Legal basis:** [Art. 9 ust. 3 ustawy o PIT](https://lexlege.pl/ustawa-o-podatku-dochodowym-od-osob-fizycznych/art-9/) — losses from a given income source can be carried forward for up to **5 consecutive tax years** following the year in which they were incurred, with a cap of **50% of the original loss per year** (art. 9 ust. 3 pkt 1).
 
-**Option 1 (gradual):** Deduct up to **50% of the loss per year** across 5 years ([art. 9 ust. 3 pkt 1](https://lexlege.pl/ustawa-o-podatku-dochodowym-od-osob-fizycznych/art-9/)).
+> _Option 2_ (one-shot deduction up to 5,000,000 PLN, art. 9 ust. 3 pkt 2) is **not** supported by the calculator. Users who qualify can still enter an equivalent gradual deduction schedule manually.
 
-**Option 2 (one-time):** Deduct the entire loss in a single year, up to **5,000,000 PLN** ([art. 9 ust. 3 pkt 2](https://lexlege.pl/ustawa-o-podatku-dochodowym-od-osob-fizycznych/art-9/)). Any remainder above 5M PLN follows the 50% rule for subsequent years.
+**Data model:** Each loss is recorded as a `PriorYearLoss { year, totalLossPln, alreadyDeductedPln }` in the `priorLosses` Dexie table, scoped per session. The `/prior-losses` page provides CRUD for these rows; `alreadyDeductedPln` tracks the residual consumed across prior tax years.
 
-**Implementation detail:** The user manually enters the deduction amount (`priorYearLoss`). The code caps it at the current year's gain:
+**Algorithm (`applyLossCarryForward`):**
 
 ```
-deductible = min(priorYearLoss, capitalGain)
+For each priorLoss (oldest year first):
+    ageInYears = currentYear − loss.year
+    expired    = ageInYears > 5 || ageInYears <= 0
+    cap        = expired ? 0 : min(0.5 × loss.totalLossPln,
+                                    loss.totalLossPln − loss.alreadyDeductedPln)
+    deducted   = min(cap, remainingGain)
+    remainingGain −= deducted
+    loss.alreadyDeductedPln += deducted  // returned in updatedLosses
+
+poz30 = sum of deducted across all priorLosses
 ```
 
-The 50% limit and 5-year carry-forward tracking are **not enforced by the calculator** — the user is responsible for computing the correct deduction amount. This is by design for flexibility (supports both option 1 and option 2).
+**Guarantees:**
+
+- Losses older than 5 years or newer than the tax session are silently skipped (a warning is attached for residuals lost to expiration).
+- The 50%-per-year cap is enforced per loss year — a user entering 100% of a loss as "already deducted" previously still has their residual constrained by `0.5 × totalLossPln`.
+- The per-year breakdown (`perYear`) is persisted on the `taxSummary.lossDeduction` record and rendered in Section D of the PIT-38 form.
 
 ---
 
@@ -671,7 +688,7 @@ The app supports **three languages:**
    - Compute raw (unrounded) tax amounts for dashboard display
 6. **PIT-38** (`buildPit38`):
    - Map summary values to form fields with proper rounding
-   - Apply prior-year loss deduction (capped at gain amount)
+   - Apply prior-year loss deduction via `applyLossCarryForward` (5-year window, 50%-per-year cap, FIFO across loss years)
    - Round tax base and tax due to full PLN ([art. 63 § 1](https://lexlege.pl/ordynacja-podatkowa/art-63/))
    - Round dividend tax to full groszy up ([art. 63 § 1a](https://lexlege.pl/ordynacja-podatkowa/art-63/))
 7. **PIT/ZG** (`buildPitZg`):

messages/en.json

@@ -192,13 +192,28 @@
   "nav_docs_more": "More coming soon...",
   "nav_faq": "FAQ",
   "nav_home": "Home",
+  "nav_prior_losses": "Prior-year losses",
   "nav_rates": "Exchange Rates",
   "nav_support": "Support",
   "nav_tax_form": "Tax Form",
   "noscript": "kloPIT requires JavaScript to run.",
   "page_about": "About",
   "page_dashboard": "Dashboard",
   "page_data": "Data",
+  "page_prior_losses": "Prior-year losses",
+  "prior_losses_add": "Add loss year",
+  "prior_losses_already_deducted": "Already deducted (PLN)",
+  "prior_losses_already_deducted_help": "Cumulative amount deducted in earlier tax years.",
+  "prior_losses_cap_explainer": "Each loss can be deducted across the next 5 tax years, with at most 50% of the original loss in any single year (art. 9 ust. 3 updof).",
+  "prior_losses_empty": "No prior-year losses recorded for this session.",
+  "prior_losses_intro": "Prior-year capital losses available to offset gains in {year}. Older than 5 years are excluded automatically.",
+  "prior_losses_no_session": "Select or create a session on the Data page first.",
+  "prior_losses_remaining": "Remaining (PLN)",
+  "prior_losses_title": "Prior-year losses (PIT-38 poz. 30)",
+  "prior_losses_total_loss": "Total loss reported (PLN)",
+  "prior_losses_warn_expired": "Loss from {year} expired (older than 5 years) — {amount} PLN no longer deductible.",
+  "prior_losses_warn_fully_deducted": "Loss from {year} is already fully deducted.",
+  "prior_losses_year": "Loss year",
   "page_docs": "Documentation",
   "page_docs_desc_faq": "Answers to common questions about PIT-38 filing, tax calculations, and using kloPIT.",
   "page_docs_desc_ib": "Step-by-step guide to exporting your activity statement from Interactive Brokers.",
@@ -252,6 +267,12 @@
   "tax_c_total_proceeds": "Total income",
   "tax_calculating": "Fetching exchange rates and calculating...",
   "tax_d_foreign_tax": "Tax paid abroad",
+  "tax_d_loss_breakdown_cap": "Cap (PLN)",
+  "tax_d_loss_breakdown_deducted": "Deducted (PLN)",
+  "tax_d_loss_breakdown_residual": "Remaining after (PLN)",
+  "tax_d_loss_breakdown_title": "Per-year loss breakdown",
+  "tax_d_loss_breakdown_year": "Loss year",
+  "tax_d_loss_warning_expired": "Loss from {year} expired unused ({amount} PLN lost — carry-forward window is 5 years).",
   "tax_d_prior_loss": "Losses from previous years",
   "tax_d_tax_amount": "Tax",
   "tax_d_tax_base": "Tax base (rounded to full PLN)",

messages/pl.json

@@ -187,12 +187,27 @@
   "nav_docs_more": "Więcej wkrótce...",
   "nav_faq": "FAQ",
   "nav_home": "Start",
+  "nav_prior_losses": "Straty z lat ubiegłych",
   "nav_rates": "Kursy walut",
   "nav_support": "Wsparcie",
   "nav_tax_form": "Formularz PIT",
   "page_about": "O aplikacji",
   "page_dashboard": "Panel",
   "page_data": "Dane",
+  "page_prior_losses": "Straty z lat ubiegłych",
+  "prior_losses_add": "Dodaj rok ze stratą",
+  "prior_losses_already_deducted": "Już odliczone (PLN)",
+  "prior_losses_already_deducted_help": "Łączna kwota odliczona w poprzednich latach podatkowych.",
+  "prior_losses_cap_explainer": "Stratę można odliczać przez 5 kolejnych lat podatkowych, w jednym roku najwyżej 50% jej pierwotnej kwoty (art. 9 ust. 3 updof).",
+  "prior_losses_empty": "Brak strat z lat ubiegłych dla tej sesji.",
+  "prior_losses_intro": "Straty kapitałowe z poprzednich lat dostępne do odliczenia od dochodu w {year}. Straty starsze niż 5 lat są pomijane automatycznie.",
+  "prior_losses_no_session": "Najpierw wybierz lub utwórz sesję na stronie Dane.",
+  "prior_losses_remaining": "Pozostało (PLN)",
+  "prior_losses_title": "Straty z lat ubiegłych (PIT-38 poz. 30)",
+  "prior_losses_total_loss": "Wykazana strata (PLN)",
+  "prior_losses_warn_expired": "Strata z {year} przedawniona (starsza niż 5 lat) — {amount} PLN nie podlega już odliczeniu.",
+  "prior_losses_warn_fully_deducted": "Strata z {year} została już w pełni odliczona.",
+  "prior_losses_year": "Rok poniesienia straty",
   "page_docs": "Dokumentacja",
   "page_docs_desc_faq": "Odpowiedzi na najczęstsze pytania dotyczące PIT-38, obliczeń podatkowych i korzystania z kloPIT.",
   "page_docs_desc_ib": "Instrukcja krok po kroku eksportu wyciągu z Interactive Brokers.",
@@ -246,6 +261,12 @@
   "tax_c_total_proceeds": "Razem przychody",
   "tax_calculating": "Pobieranie kursów walut i obliczanie...",
   "tax_d_foreign_tax": "Podatek zapłacony za granicą",
+  "tax_d_loss_breakdown_cap": "Limit (PLN)",
+  "tax_d_loss_breakdown_deducted": "Odliczono (PLN)",
+  "tax_d_loss_breakdown_residual": "Pozostało po (PLN)",
+  "tax_d_loss_breakdown_title": "Odliczenie straty per rok",
+  "tax_d_loss_breakdown_year": "Rok straty",
+  "tax_d_loss_warning_expired": "Strata z {year} przepadła niewykorzystana ({amount} PLN — okres rozliczenia to 5 lat).",
   "tax_d_prior_loss": "Straty z lat ubiegłych",
   "tax_d_tax_amount": "Podatek",
   "tax_d_tax_base": "Podstawa obliczenia podatku (po zaokrągleniu do pełnych zł)",

messages/uk.json

@@ -187,12 +187,27 @@
   "nav_docs_more": "Більше незабаром...",
   "nav_faq": "FAQ",
   "nav_home": "Головна",
+  "nav_prior_losses": "Збитки минулих років",
   "nav_rates": "Курси валют",
   "nav_support": "Підтримка",
   "nav_tax_form": "Форма PIT",
   "page_about": "Про додаток",
   "page_dashboard": "Панель",
   "page_data": "Дані",
+  "page_prior_losses": "Збитки минулих років",
+  "prior_losses_add": "Додати рік збитку",
+  "prior_losses_already_deducted": "Уже відраховано (PLN)",
+  "prior_losses_already_deducted_help": "Сума, відрахована в попередніх податкових роках.",
+  "prior_losses_cap_explainer": "Збиток можна відраховувати протягом 5 наступних податкових років, але не більше 50% початкової суми за один рік (ст. 9 п. 3 УПДОФ).",
+  "prior_losses_empty": "Для цієї сесії немає збитків минулих років.",
+  "prior_losses_intro": "Капітальні збитки минулих років, доступні для зменшення прибутку у {year}. Збитки старші за 5 років виключаються автоматично.",
+  "prior_losses_no_session": "Спочатку оберіть або створіть сесію на сторінці Дані.",
+  "prior_losses_remaining": "Залишилось (PLN)",
+  "prior_losses_title": "Збитки минулих років (PIT-38 поз. 30)",
+  "prior_losses_total_loss": "Заявлений збиток (PLN)",
+  "prior_losses_warn_expired": "Збиток за {year} прострочено (понад 5 років) — {amount} PLN більше не підлягає відрахуванню.",
+  "prior_losses_warn_fully_deducted": "Збиток за {year} вже повністю відраховано.",
+  "prior_losses_year": "Рік збитку",
   "page_docs": "Документація",
   "page_docs_desc_faq": "Відповіді на поширені питання про PIT-38, податкові розрахунки та використання kloPIT.",
   "page_docs_desc_ib": "Покрокова інструкція з експорту виписки з Interactive Brokers.",
@@ -246,6 +261,12 @@
   "tax_c_total_proceeds": "Всього доходи",
   "tax_calculating": "Отримання курсів валют та розрахунок...",
   "tax_d_foreign_tax": "Податок сплачений за кордоном",
+  "tax_d_loss_breakdown_cap": "Ліміт (PLN)",
+  "tax_d_loss_breakdown_deducted": "Відраховано (PLN)",
+  "tax_d_loss_breakdown_residual": "Залишилось після (PLN)",
+  "tax_d_loss_breakdown_title": "Відрахування збитку за роками",
+  "tax_d_loss_breakdown_year": "Рік збитку",
+  "tax_d_loss_warning_expired": "Збиток за {year} згорів невикористаним ({amount} PLN — вікно перенесення складає 5 років).",
   "tax_d_prior_loss": "Збитки попередніх років",
   "tax_d_tax_amount": "Податок",
   "tax_d_tax_base": "База оподаткування (округлено до повних злотих)",

src/core/tax/calculator.ts

@@ -8,12 +8,17 @@ import {
   type EnrichedWithholdingTax,
   type Pit38Fields,
   type PitZgFields,
+  type PriorYearLoss,
   type TaxPeriod,
   type TaxSummary,
   type TradeResult,
 } from '../types.js';
 import { calculateCapitalGains } from './capital-gains.js';
 import { calculateDividends } from './dividends.js';
+import {
+  applyLossCarryForward,
+  type ApplyLossCarryForwardResult,
+} from './loss-carry-forward.js';
 import { buildPitZg } from './pit-zg.js';
 import { buildPit38 } from './pit38.js';
 import { getDividendCreditCapRate } from './treaty-rates.js';
@@ -24,7 +29,12 @@ export interface CalculateTaxesArgs {
   withholdingTaxes: EnrichedWithholdingTax[];
   corporateActions: EnrichedCorporateAction[];
   carryInPositions: CarryInPosition[];
-  priorYearLoss?: number;
+  /**
+   * Prior-year capital losses (art. 9 ust. 3 updof). Replaces the legacy
+   * single-number `priorYearLoss` field — each year carries its own
+   * residual and 50%-per-year cap.
+   */
+  priorLosses?: PriorYearLoss[];
   taxPeriod: TaxPeriod;
   symbolCountryMap?: Map<string, string>;
 }
@@ -35,6 +45,8 @@ export interface TaxCalculationResult {
   summary: TaxSummary;
   pit38: Pit38Fields;
   pitZg: PitZgFields[];
+  /** Per-year breakdown of how prior-year losses were applied. */
+  lossDeduction: ApplyLossCarryForwardResult;
 }
 
 /** Orchestrate full tax calculation pipeline */
@@ -45,7 +57,7 @@ export function calculateTaxes(args: CalculateTaxesArgs): TaxCalculationResult {
     withholdingTaxes,
     corporateActions,
     carryInPositions,
-    priorYearLoss,
+    priorLosses,
     taxPeriod,
   } = args;
 
@@ -72,7 +84,16 @@ export function calculateTaxes(args: CalculateTaxesArgs): TaxCalculationResult {
     year: taxPeriod.year,
   });
 
-  const pit38 = buildPit38({ summary, priorYearLoss });
+  // Compute the loss-carry-forward breakdown once so the UI and PIT-38
+  // builder agree on the deduction amount.
+  const gainPln = Math.max(summary.totalProceedsPln - summary.totalCostPln, 0);
+  const lossDeduction = applyLossCarryForward({
+    gainPln,
+    priorLosses: priorLosses ?? [],
+    currentYear: taxPeriod.year,
+  });
+
+  const pit38 = buildPit38({ summary, priorLosses });
   const pitZg = buildPitZg({
     trades: tradeResults,
     dividends: dividendResults,
@@ -84,6 +105,7 @@ export function calculateTaxes(args: CalculateTaxesArgs): TaxCalculationResult {
     summary,
     pit38,
     pitZg,
+    lossDeduction,
   };
 }