Merge pull request #6 from Error404IsFound/tharun

docs(tax): specify FIFO capital gains
4 weeks ago · dcc54954de
1 changed files with 757 additions and 0 deletions
--- a/project-docs/iteration-1/tax/fifo-capital-gains-spec.md
+++ b/project-docs/iteration-1/tax/fifo-capital-gains-spec.md
@ -0,0 +1,757 @@
 # Tax Metrics — FIFO Capital-Gains Calculation Specification
 **Owner:** Tharun Swaminathan
 **Iteration:** 1 — Design & Data Modelling
 **Date:** September 17, 2026
 ## Objective
 This document specifies the FIFO (First-In, First-Out) capital-gains method for the Ghostfolio tax extension. The goal is to define deterministic, traceable calculation behavior for Iteration 2 without changing production code during Iteration 1.
 The FIFO engine calculates realized gains from BUY and SELL activities and keeps each sale traceable to the acquisition lots it consumes.
 This is tax analytics software, not personal tax advice. The design does not introduce jurisdiction-specific tax rates, wash-sale rules, holding-period rules, or similar country-specific treatment.
 ## Repository Findings
 ### Activity ordering
 `ActivitiesService.getActivities()` already retrieves activities by `date` ascending and adds `id` as a secondary sort key. The FIFO engine should reuse that deterministic ordering:
 1. exact activity `date` ascending
 2. activity `id` ascending when dates are equal
 ### Existing performance calculation is not FIFO
 Ghostfolio's current portfolio calculator uses an average investment basis for SELL activities. It reduces investment proportionally and calculates sell performance against an average price.
 The tax FIFO engine should therefore be a separate tax-domain calculation. It should not replace or modify the existing ROAI performance behavior.
 ### Use enriched Activity records
 The enriched `Activity` object contains source identifiers and transaction values such as:
 - `feeInAssetProfileCurrency`
 - `feeInBaseCurrency`
 - `unitPriceInAssetProfileCurrency`
 - `value`
 - `valueInBaseCurrency`
 The portfolio calculator later converts activities into a smaller `PortfolioOrder` representation that does not retain the activity `id` or full source timestamp. FIFO should therefore operate on enriched `Activity` records before that conversion.
 ### Stock-split handling
 Ghostfolio already adjusts investment activities for stock splits. Activities before a split have quantity multiplied by the split ratio and unit price divided by the same ratio, preserving total value.
 FIFO should reuse this existing normalization instead of implementing a second split formula.
 ### Currency conversion
 `ActivitiesService` already calculates transaction-date values in the asset-profile currency and the user's base currency. FIFO should reuse those values where practical.
 ## Scope
 The FIFO algorithm operates on one **lot-matching scope** at a time. Activities from different assets must never be matched together.
 The caller is responsible for grouping activities into the correct lot-matching scope before running FIFO.
 Whether lots are pooled across accounts is intentionally not decided here because that can depend on later tax-lot requirements and jurisdiction-specific assumptions. The final scope key belongs to the Sep 21 tax-lot design.
 ## Eligible Activities
 Only:
 - `BUY`
 - `SELL`
 participate in FIFO lot matching.
 The following do not create or consume acquisition lots:
 - `DIVIDEND`
 - `FEE`
 - `INTEREST`
 - `LIABILITY`
 A fee attached directly to a BUY or SELL can be allocated during the calculation. A standalone `FEE` activity is not automatically attached to a trade because the current data model does not identify which trade it belongs to.
 ## Filtering
 The initial FIFO implementation should follow Ghostfolio's existing default filtering:
 - exclude draft activities
 - exclude activities explicitly excluded from analysis
 - exclude activities in excluded accounts
 - include only BUY and SELL
 - do not include synthetic cash activities
 The Sep 23 tax-relevant flag/filter can add another layer later without changing the core FIFO algorithm.
 ## Required Inputs
 Each FIFO activity should retain:
 - activity `id`
 - exact activity `date`
 - activity `type`
 - asset identity
 - `quantity`
 - transaction currency
 - `unitPriceInAssetProfileCurrency`
 - `feeInAssetProfileCurrency`
 - `valueInBaseCurrency`
 - `feeInBaseCurrency`
 Original transaction currency and unit price should also remain available for audit/export use.
 ## Deterministic Ordering
 Process activities by:
 1. exact `date` ascending
 2. `id` ascending for equal timestamps
 Do not rely on database return order or array insertion order.
 Example:
 ```text
 2026-01-10T10:00:00Z  BUY   id=0001
 2026-01-10T10:00:00Z  BUY   id=0002
 2026-01-10T12:00:00Z  SELL  id=0003
 ```
 The SELL consumes lot `0001` before lot `0002`.
 ## Numeric Precision
 Convert relevant numeric inputs to `Big` values at the tax-engine boundary.
 Do not round intermediate calculations. Fractional quantities must remain supported because stock splits and some assets can produce non-integer quantities.
 Display/export rounding belongs to the Sep 24 export specification.
 ## Working Acquisition Lot
 Each BUY creates one working FIFO lot containing at least:
 ```text
 sourceActivityId
 acquiredAt
 initialQuantity
 remainingQuantity
 unitCostAssetCurrency
 grossAcquisitionValueAssetCurrency
 buyFeeAssetCurrency
 grossAcquisitionValueBaseCurrency
 buyFeeBaseCurrency
 currency
 ```
 `sourceActivityId` points to the original Ghostfolio BUY.
 `remainingQuantity` begins equal to `initialQuantity` and decreases as SELL activities consume the lot.
 This is an in-memory FIFO structure. Permanent tax-lot persistence is a separate Sep 21 task.
 ## BUY Processing
 For a BUY:
 1. validate the activity
 2. create a new acquisition lot
 3. append it to the end of the open-lot queue
 4. do not calculate realized gain
 A BUY never consumes an older BUY lot.
 ## SELL Processing
 For a SELL:
 ```text
 quantityToMatch = sell.quantity
 ```
 While `quantityToMatch > 0`:
 1. take the oldest open lot
 2. compute `matchedQuantity = min(quantityToMatch, lot.remainingQuantity)`
 3. create a FIFO match record
 4. subtract the matched quantity from the lot
 5. subtract the matched quantity from the sale
 6. remove the lot when its remaining quantity reaches zero
 7. continue with the next oldest lot if needed
 Stop when the full sale is matched or no open lots remain.
 ## Partial-Lot Consumption
 Example:
 ```text
 BUY 10
 SELL 4
 ```
 The lot remains open with:
 ```text
 remainingQuantity = 6
 ```
 A later SELL consumes those 6 before any newer lot.
 ## Sale Across Multiple Lots
 Example:
 ```text
 BUY 100
 BUY 50
 SELL 120
 ```
 FIFO matches:
 ```text
 100 from BUY #1
 20 from BUY #2
 ```
 BUY #2 remains open with 30.
 Each consumption must be returned as a separate trace record.
 ## FIFO Match Output
 Each matched BUY/SELL slice should expose data similar to:
 ```text
 buyActivityId
 sellActivityId
 buyDate
 sellDate
 matchedQuantity
 grossAcquisitionValueAssetCurrency
 grossProceedsAssetCurrency
 buyFeeAllocatedAssetCurrency
 sellFeeAllocatedAssetCurrency
 grossRealizedGainAssetCurrency
 realizedGainAfterActivityFeesAssetCurrency
 grossAcquisitionValueBaseCurrency
 grossProceedsBaseCurrency
 buyFeeAllocatedBaseCurrency
 sellFeeAllocatedBaseCurrency
 grossRealizedGainBaseCurrency
 realizedGainAfterActivityFeesBaseCurrency
 ```
 This is calculation output, not necessarily a persisted Prisma model.
 ## Gross Cost Basis
 For one matched slice:
 ```text
 grossAcquisitionValue = matchedQuantity × buyUnitPrice
 ```
 For a SELL spanning multiple lots:
 ```text
 grossCostBasis = sum(grossAcquisitionValue of each match)
 ```
 ## Gross Sale Proceeds
 For one matched slice:
 ```text
 grossProceeds = matchedQuantity × sellUnitPrice
 ```
 For a fully matched sale:
 ```text
 grossSaleProceeds = sellQuantity × sellUnitPrice
 ```
 ## Gross Realized Gain
 For each match:
 ```text
 grossRealizedGain = grossProceeds - grossAcquisitionValue
 ```
 For the complete sale:
 ```text
 grossRealizedGainForSale = sum(match.grossRealizedGain)
 ```
 A negative value is a realized loss.
 This is an analytics value and should not be labeled as universally "taxable gain."
 ## Activity-Fee Treatment
 Fees should remain visible separately from gross basis/proceeds while also allowing a fee-adjusted analytics result.
 ### BUY fee allocation
 ```text
 buyFeeAllocated =
    buyFee × matchedQuantity / originalBuyQuantity
 ```
 When the final remaining portion of a BUY lot is consumed, assign any tiny remaining fee-allocation balance to that final match so allocations sum exactly to the original fee.
 ### SELL fee allocation
 ```text
 sellFeeAllocated =
    sellFee × matchedQuantity / sellQuantity
 ```
 Assign any tiny residual to the final match so allocated SELL fees sum exactly to the original SELL fee.
 ### Fee-adjusted gain
 ```text
 realizedGainAfterActivityFees =
    (grossProceeds - sellFeeAllocated)
    - (grossAcquisitionValue + buyFeeAllocated)
 ```
 Keep this separate from `grossRealizedGain`.
 ### Standalone FEE activities
 Do not automatically allocate standalone `FEE` activities because the existing model does not link them to a specific trade.
 ## Currency Behavior
 ### Asset-profile currency
 Primary lot calculations should use:
 - `unitPriceInAssetProfileCurrency`
 - `feeInAssetProfileCurrency`
 This gives a common currency for matching acquisition and sale values for the same asset.
 ### User base currency
 Reuse historical transaction-date values already calculated by Ghostfolio.
 For a matched BUY portion:
 ```text
 acquisitionValueBase =
    buy.valueInBaseCurrency
    × matchedQuantity
    / buy.quantity
 ```
 For a matched SELL portion:
 ```text
 proceedsBase =
    sell.valueInBaseCurrency
    × matchedQuantity
    / sell.quantity
 ```
 Fees can be allocated from `feeInBaseCurrency` using the same matched-quantity proportions.
 This keeps BUY values tied to the BUY-date exchange rate and SELL values tied to the SELL-date exchange rate.
 ### Missing FX data
 If historical base-currency conversion is unavailable, do not silently assume FX = 1 for tax analytics.
 Return the asset-currency result, leave the affected base-currency value unavailable, and return a traceable warning/error for the affected transaction.
 ## Stock Splits
 Reuse Ghostfolio's existing split normalization:
 ```text
 adjustedQuantity =
    originalQuantity × numerator / denominator
 adjustedUnitPrice =
    originalUnitPrice × denominator / numerator
 ```
 Total activity value remains unchanged.
 Pre-split BUY lots and post-split SELL quantities can then be matched using comparable adjusted quantities.
 Do not adjust provider market data a second time.
 Always retain the original activity ID for traceability.
 ## Example 1 — Sale Across Two Lots
 ```text
 BUY #1: 100 @ 10.00, fee 2.00
 BUY #2:  50 @ 12.00, fee 1.00
 SELL #3: 120 @ 15.00, fee 3.00
 ```
 FIFO consumption:
 ```text
 100 from BUY #1
 20 from BUY #2
 ```
 Gross basis:
 ```text
 100 × 10.00 = 1000.00
 20 × 12.00 =  240.00
 grossCostBasis = 1240.00
 ```
 Gross proceeds:
 ```text
 120 × 15.00 = 1800.00
 ```
 Gross realized gain:
 ```text
 1800.00 - 1240.00 = 560.00
 ```
 Allocated BUY fees:
 ```text
 BUY #1 = 2.00
 BUY #2 = 1.00 × 20 / 50 = 0.40
 total = 2.40
 ```
 Allocated SELL fee:
 ```text
 3.00
 ```
 Fee-adjusted gain:
 ```text
 (1800.00 - 3.00) - (1240.00 + 2.40)
 = 554.60
 ```
 Remaining lot:
 ```text
 BUY #2 remaining quantity = 30
 remaining unallocated BUY fee = 0.60
 ```
 ## Example 2 — Partial Lot
 ```text
 BUY: 10 @ 100.00, fee 5.00
 SELL: 4 @ 130.00, fee 2.00
 ```
 Results:
 ```text
 gross acquisition value = 400.00
 gross proceeds = 520.00
 gross realized gain = 120.00
 allocated BUY fee = 5.00 × 4 / 10 = 2.00
 allocated SELL fee = 2.00
 fee-adjusted gain =
    (520.00 - 2.00) - (400.00 + 2.00)
    = 116.00
 remaining lot quantity = 6
 remaining unallocated BUY fee = 3.00
 ```
 ## Example 3 — Stock Split
 Original BUY:
 ```text
 10 shares @ 100.00
 fee = 5.00
 ```
 After a 2:1 split:
 ```text
 20 shares @ 50.00
 ```
 Later SELL:
 ```text
 5 shares @ 60.00
 fee = 1.00
 ```
 FIFO result:
 ```text
 gross acquisition value = 5 × 50.00 = 250.00
 gross proceeds = 5 × 60.00 = 300.00
 gross realized gain = 50.00
 allocated BUY fee = 5.00 × 5 / 20 = 1.25
 allocated SELL fee = 1.00
 fee-adjusted gain =
    (300.00 - 1.00) - (250.00 + 1.25)
    = 47.75
 remaining adjusted shares = 15
 ```
 ## Closed Position and New Cycle
 When every open lot in the current scope reaches zero, the long position is fully closed.
 A later BUY starts a new FIFO cycle. Fully consumed lots remain available in history/output for traceability but cannot be consumed again.
 ## Invalid and Unsupported Conditions
 ### Non-positive quantity
 A BUY or SELL with quantity <= 0 is invalid FIFO input and must not create or consume a lot.
 ### Negative unit price or fee
 Negative price or fee values are invalid for this engine. The DTO layer already prevents these in normal input, but the engine should validate defensively.
 ### SELL with insufficient open lots
 If a SELL exceeds available open BUY quantity, do not create a negative lot.
 Match the valid portion if desired, but record:
 ```text
 unmatchedQuantity
 error = INSUFFICIENT_OPEN_LOTS
 ```
 Do not include the unmatched portion as a valid FIFO realized gain.
 ### SELL before any BUY
 Treat as the same insufficient-lot condition.
 Ghostfolio's existing performance calculator can represent short positions, but short-sale tax treatment is outside this long-lot FIFO specification.
 ### Missing base-currency conversion
 If asset-currency inputs are valid but historical FX is missing:
 - continue asset-currency FIFO
 - leave affected base-currency values unavailable
 - return a traceable conversion warning/error
 ## Reconciliation Rules
 For a valid long-only scope:
 ```text
 total adjusted BUY quantity
 - total successfully matched SELL quantity
 = total remaining open-lot quantity
 ```
 For each fully matched SELL:
 ```text
 sum(match.matchedQuantity) = sell.quantity
 ```
 For each fully consumed BUY:
 ```text
 sum(allocated BUY fees) = original BUY fee
 ```
 For each fully matched SELL:
 ```text
 sum(allocated SELL fees) = original SELL fee
 ```
 These invariants should be unit-tested.
 ## Proposed Sale-Level Result
 In addition to lot-level matches, one aggregate result per SELL should contain:
 ```text
 sellActivityId
 sellDate
 currency
 sellQuantity
 matchedQuantity
 unmatchedQuantity
 grossProceeds
 grossCostBasis
 grossRealizedGain
 allocatedBuyFees
 sellFee
 realizedGainAfterActivityFees
 matches[]
 errors[]
 ```
 Add base-currency equivalents when conversion data is available.
 ## Realized vs Unrealized
 This FIFO engine calculates realized gain only when a SELL consumes a BUY lot.
 Open lots are returned for future matching and traceability. This Sep 17 specification does not calculate unrealized gain.
 ## Planned Iteration 2 Tests
 Use exact expected numeric results for:
 - one BUY and one full SELL
 - one BUY and a partial SELL
 - multiple BUY lots and one SELL spanning lots
 - multiple sequential SELL activities
 - closed position followed by a new BUY cycle
 - zero fees
 - non-zero BUY and SELL fees
 - fractional quantities
 - same timestamp with deterministic ID ordering
 - normal stock split
 - reverse split
 - multiple stock splits
 - missing base-currency conversion
 - SELL greater than available lots
 - SELL before any BUY
 - separate assets never matching
 - separate lot-matching scopes never matching
 Tests must verify numeric results and source-activity traceability, not only successful execution.
 ## Implementation Boundary — Iteration 2
 FIFO should be tax-domain business logic, not a modification of the existing ROAI portfolio calculator.
 The ROAI path currently uses average-price behavior and is shared with performance functionality. Changing it to FIFO could alter Arthur's performance-chart behavior.
 The Iteration 2 FIFO implementation should instead:
 1. obtain enriched activities from existing Ghostfolio services
 2. apply existing stock-split normalization
 3. filter/group eligible BUY and SELL activities
 4. run the FIFO engine
 5. return realized-gain matches, aggregate sale results, and remaining lots
 A candidate future location is:
 `apps/api/src/app/tax/`
 This is a recommendation, not a fixed shared-architecture decision. Raniya owns architecture/integration, so the final tax service boundary and shared contract location should be coordinated with her before implementation.
 ## Likely Relevant Files in Iteration 2
 - `apps/api/src/app/activities/activities.service.ts`
 - `apps/api/src/services/asset-profile-split/asset-profile-split.helper.ts`
 - `apps/api/src/services/exchange-rate-data/exchange-rate-data.service.ts`
 - `libs/common/src/lib/interfaces/activities.interface.ts`
 New tax-specific service, interface, and test files will also be needed.
 No change to the existing ROAI performance formulas is required for FIFO tax calculation.
 ## Acceptance Criteria
 The FIFO specification is complete when:
 - only eligible BUY/SELL activities participate
 - deterministic ordering uses full activity date then activity ID
 - each BUY creates one acquisition lot
 - each SELL consumes the oldest available lot first
 - partial lots keep the correct remainder
 - one SELL can consume multiple lots
 - every match references its BUY and SELL source activities
 - gross cost basis and gross proceeds are defined
 - gross realized gain is defined
 - attached BUY/SELL fees are allocated deterministically
 - fee-adjusted gain remains separate from gross gain
 - asset-profile and base-currency behavior are defined
 - missing FX behavior is defined
 - stock splits reuse Ghostfolio's existing normalization
 - insufficient holdings are reported instead of creating negative lots
 - short-sale tax handling is outside the current scope
 - open lots remain distinct from realized results
 - reconciliation invariants are defined
 - Iteration 2 numeric tests are identified
 - no jurisdiction-specific tax rules are invented
 - existing portfolio-performance logic remains unchanged
 ## Open Questions for Later Iteration 1 Tasks
 ### Sep 21 — Tax-lot data model
 Decide:
 - permanent lot schema
 - final account/lot pooling scope
 - which results are stored versus recalculated
 - open/closed lot lifecycle fields
 - relationships among source activities, lots, and sale matches
 ### Sep 22 — Yearly summary
 Define how realized FIFO results are grouped by year.
 ### Sep 23 — Tax-relevant filtering
 Define the explicit tax-relevant flag and its interaction with existing draft/excluded filters.
 ### Sep 24 — Export
 Define output precision, display/export rounding, and FIFO trace fields for CSV/PDF.
 ## Out of Scope
 - average-cost method
 - permanent tax-lot persistence
 - yearly tax-summary schema
 - tax-relevant flag implementation
 - React/UI work
 - jurisdiction-specific tax rates
 - holding-period classifications
 - wash-sale/superficial-loss rules
 - short-sale tax matching
 - undefined account pooling rules
 - corporate actions beyond Ghostfolio's existing stock-split support
 ## Next Task
 The next scheduled tax task is September 18:
 **Specify the capital-gains average-cost method.**
 That specification should reuse the same filtering, precision, currency, split, validation, and traceability principles where applicable while replacing FIFO lot consumption with a pooled average-cost basis.