FIFO/LIFO tax lot tracking

1 · Principles check

Verify this design respects every principle in v0.1.0. Any violation requires either a principles amendment or a deliberate exception logged below.

Load-bearing principles only. Platform-wide conformance across all twenty principles is tracked in the umbrella design (001); this table records where this slice carries weight of its own.

2 · Technical context

Language(s)

Java 21 (Temurin 21.0.9).

Frameworks

Quarkus 3.37.3, Maven; extensions quarkus-rest, quarkus-rest-jackson, quarkus-arc, quarkus-micrometer-registry-prometheus, quarkus-smallrye-openapi.

Architecture

Vertical slice inside a modular monolith — a tax module under io.spectastic.portfolio that folds the umbrella's event stream; no new service boundary.

Storage

In-memory event-sourced projection over the TradeLedger log; snapshot = deep copy, restore-then-replay-tail equals full replay. No database.

Testing

JUnit5 unit tests plus one @QuarkusTest with rest-assured; the SC-001 worked example is the headline relief test.

Coverage

Jacoco, diff-aware: a patch target on changed lines and the rule that a change never lowers coverage of the code it touches — no single universal %.

Perf targets

Relief p99 < 40 µs at ≤ 1000 open lots (NFR-001); daily P&L reconcile bit-matches replay 99.999% (NFR-002); open lots ≤ open buys, 0 when flat (NFR-003).

Constraints

No floating point on the money path — exact integer fixed-point at scale 1e-4 (PRICE_SCALE = 10_000), whole-long quantities.

3 · Grounding & evidence

Every design-bearing fact this design rests on, and how it was confirmed — read this before the approach: it separates what the design knows from what it assumes (per REQ-LIFECYCLE-006). Status is verified (opened the source this turn), spike (decidable only by a time-boxed investigation — run it, record the finding), or assumed (taken as true without verification). A must-tier decision may not rest on an assumed/unresolved-spike fact unless accepted as a <spec-risk> (see §8).

4 · Approach

A TaxLotBook (one per (account, instrument)) folds the ledger's event stream. A buy pushes a Lot — quantity, integer basis-per-unit, acquisition timestamp, open sequence — onto the tail of an acquisition-ordered ArrayDeque<Lot>. A sell reads the account's elected policy, relieves lots from the head under FIFO or the tail under LIFO, and when the sell is smaller than the boundary lot it reduces that lot's qtyOpen in place — a split that leaves an open remainder carrying the original basis and acquisition time. Each relief computes realized gain as qtyRelieved·(sellPrice − lotBasis) in long arithmetic and emits an immutable RealizedGainRecord; cumulative realized gain is the sum of the records. Price ticks fold into per-lot unrealized gain. A sell exceeding all open long lots closes them and opens a SHORT lot for the residual, with symmetric relief on a later buy-to-cover.

Worked example (spec SC-001). Buy 100 @ 10, then 100 @ 12, then sell 150. Under FIFO the relieved basis is 100·10 + 50·12 = 1600, leaving a 50-share lot @ 12; under LIFO it is 100·12 + 50·10 = 1700, leaving 50 @ 10. Prices are scaled ×10 000 internally, so both figures are exact longs and both reconcile to a full replay to the cent.

5 · Alternatives considered

Acquisition order is the one order both policies need — FIFO reads it from the head, LIFO from the tail — so a single deque serves both with O(1) ends and an in-place split, where priority queues duplicate state and re-deriving from replay cannot meet the relief latency envelope.

6 · Decisions

7 · Project structure

Only the new or changed paths, grouped by the tax module boundary the §6 decisions draw.

src/main/java/io/spectastic/portfolio/
  tax/
    TaxLotBook.java          fold ledger → ordered lots, relieve by policy
    Lot.java                 { account, instrument, openSeq, acquiredTs, qtyOpen, basisPerUnit, side }
    ReliefPolicy.java        FIFO | LIFO | HIFO
    RealizedGainRecord.java  immutable audit record per relieved lot
src/test/java/io/spectastic/portfolio/
    TaxLotBookTest.java       acquisition order, FIFO/LIFO relief, split, reconcile-to-replay

8 · Risks & mitigations

9 · Complexity tracking

Anywhere this design introduces complexity not strictly required by the spec, justify it here. A reviewer should be able to point at any non-trivial choice and find its rationale in this section.

10 · Open questions

11 · Change log