Stax Digital Garden

QTM-1003 - Deterministic FIFO Lot Tracking for Multi-Currency Balances

2 min read

Living Document Notice
Published 2026-09-17. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Deterministic FIFO Lot Tracking for Multi-Currency Balances

Deterministic FIFO Lot Tracking for Multi-Currency Balances: Dual-trace Phosphor P1 high-persistence green and P4 paper white vector CRT macro showing deterministic FIFO currency lot queues, cost basis depletion curves, and multi-currency exchange rate axes

Tracking foreign currencies, equities, and digital assets requires strict inventory lot accounting. When selling an asset, the system must determine which purchase lot was liquidated to calculate capital gains or losses deterministically. Quartermaster enforces First-In, First-Out (FIFO) lot allocation directly in plain text.

FIFO Lot Inventory Queue

Each acquisition posting registers a discrete lot specifying purchase date, unit quantity, and cost basis:

2024-03-15 * "Brokerage Purchase"
  Assets:Investments:VT       100 VT {85.00 USD}
  Assets:Cash:Checking     -8500.00 USD
 
2026-09-17 * "Brokerage Sale"
  Assets:Cash:Checking     10200.00 USD
  Assets:Investments:VT      -100 VT {85.00 USD} @ 102.00 USD
  Income:CapitalGains      -1700.00 USD

When liquidations occur without an explicit lot designation, the FIFO solver matches the earliest available lot in the queue:

pub struct AssetLot {
    pub date: String,
    pub quantity: f64,
    pub cost_basis: f64,
}
 
pub fn deplete_fifo_lots(lots: &mut Vec<AssetLot>, mut sell_qty: f64) -> f64 {
    let mut realized_gain = 0.0;
    while sell_qty > 0.0 && !lots.is_empty() {
        let lot = &mut lots[0];
        let take = lot.quantity.min(sell_qty);
        lot.quantity -= take;
        sell_qty -= take;
        if lot.quantity == 0.0 {
            lots.remove(0);
        }
    }
    realized_gain
}

This prevents ambiguous cost-basis calculations during annual tax audits.

  • Directus Target: quartermaster
  • Garden Source Reference: MOC - Personal Finance, Ledgers & Tax Manifests, MOC - Bosun PKM Tools
  • Garden Source Reference: [QTM-1003 - Deterministic FIFO Lot Tracking for Multi-Currency Balances](QTM-1003 - Deterministic FIFO Lot Tracking for Multi-Currency Balances)

Graph View