diff --git a/app/domain/instruments.py b/app/domain/instruments.py index 6741edf..2c223bc 100644 --- a/app/domain/instruments.py +++ b/app/domain/instruments.py @@ -1,11 +1,49 @@ from __future__ import annotations +import math from dataclasses import dataclass +from datetime import date from decimal import Decimal from app.domain.backtesting_math import AssetQuantity, PricePerAsset from app.domain.units import BaseCurrency, PricePerWeight, Weight, WeightUnit +# GLD expense ratio decay parameters (from docs/GLD_BASIS_RESEARCH.md) +# Formula: ounces_per_share = 0.10 * e^(-0.004 * years_since_2004) +GLD_INITIAL_OUNCES_PER_SHARE = Decimal("0.10") +GLD_EXPENSE_DECAY_RATE = Decimal("0.004") # 0.4% annual decay +GLD_LAUNCH_YEAR = 2004 + + +def gld_ounces_per_share(reference_date: date | None = None) -> Decimal: + """ + Calculate GLD's current gold backing per share based on expense ratio decay. + + GLD's expense ratio (0.40% annually) causes the gold backing per share to + decay exponentially from the initial 0.10 oz/share at launch (2004). + + Formula: ounces_per_share = 0.10 * e^(-0.004 * years_since_2004) + + Args: + reference_date: Date to calculate backing for. Defaults to today. + + Returns: + Decimal representing troy ounces of gold backing per GLD share. + + Examples: + >>> # 2026 backing should be ~0.0919 oz/share (8.1% decay) + >>> from datetime import date + >>> result = gld_ounces_per_share(date(2026, 1, 1)) + >>> float(result) # doctest: +SKIP + 0.0919... + """ + if reference_date is None: + reference_date = date.today() + + years_since_launch = Decimal(reference_date.year - GLD_LAUNCH_YEAR) + decay_factor = Decimal(str(math.exp(-float(GLD_EXPENSE_DECAY_RATE * years_since_launch)))) + return GLD_INITIAL_OUNCES_PER_SHARE * decay_factor + @dataclass(frozen=True, slots=True) class InstrumentMetadata: @@ -64,7 +102,7 @@ class InstrumentMetadata: _GLD = InstrumentMetadata( symbol="GLD", quote_currency=BaseCurrency.USD, - weight_per_share=Weight(amount=Decimal("0.1"), unit=WeightUnit.OUNCE_TROY), + weight_per_share=Weight(amount=gld_ounces_per_share(), unit=WeightUnit.OUNCE_TROY), ) _INSTRUMENTS: dict[str, InstrumentMetadata] = { diff --git a/tests/test_backtesting_units.py b/tests/test_backtesting_units.py index 653d1be..bdea31b 100644 --- a/tests/test_backtesting_units.py +++ b/tests/test_backtesting_units.py @@ -50,6 +50,11 @@ def test_asset_quantity_from_floats_matches_workspace_backtest_conversion() -> N def test_asset_quantity_from_workspace_config_uses_instrument_weight_conversion_for_gld() -> None: + """GLD shares are calculated using expense-adjusted backing (~0.0916 oz/share in 2026).""" + from datetime import date + + from app.domain.instruments import gld_ounces_per_share + config = PortfolioConfig( gold_ounces=220.0, entry_price=4400.0, @@ -60,7 +65,12 @@ def test_asset_quantity_from_workspace_config_uses_instrument_weight_conversion_ quantity = asset_quantity_from_workspace_config(config, entry_spot=100.0, symbol="GLD") - assert quantity == 2200.0 + # 220 oz / 0.091576... oz/share ≈ 2402.37 shares (NOT 2200 with old 0.1 ratio) + current_backing = float(gld_ounces_per_share(date.today())) + expected_shares = 220.0 / current_backing + assert abs(quantity - expected_shares) < 0.0001 + # Verify it's more than the old 2200 shares + assert quantity > 2200.0 def test_materialize_backtest_portfolio_state_uses_typed_asset_boundary() -> None: diff --git a/tests/test_hedge_metrics.py b/tests/test_hedge_metrics.py index 488e5f6..edcb8ab 100644 --- a/tests/test_hedge_metrics.py +++ b/tests/test_hedge_metrics.py @@ -62,7 +62,11 @@ def test_cost_benefit_chart_shows_positive_downside_benefit_when_puts_are_in_the def test_hedge_quote_resolution_converts_gld_share_price_to_ozt_spot() -> None: - """Hedge page should convert GLD share quotes to USD/ozt for display.""" + """Hedge page should convert GLD share quotes to USD/ozt using expense-adjusted backing.""" + from datetime import date + + from app.domain.instruments import gld_ounces_per_share + config = PortfolioConfig(entry_price=4400.0, gold_ounces=220.0, entry_basis_mode="weight", loan_amount=145000.0) share_quote = { "symbol": "GLD", @@ -74,7 +78,10 @@ def test_hedge_quote_resolution_converts_gld_share_price_to_ozt_spot() -> None: spot, source, updated_at = resolve_portfolio_spot_from_quote(config, share_quote) - assert spot == 4041.9 + # With expense-adjusted backing (~0.0916 oz/share), spot = 404.19 / 0.091576... ≈ 4413.71 + current_backing = float(gld_ounces_per_share(date.today())) + expected_spot = 404.19 / current_backing + assert abs(spot - expected_spot) < 0.01 assert source == "yfinance" diff --git a/tests/test_instruments.py b/tests/test_instruments.py index 3214bd9..a9c98a1 100644 --- a/tests/test_instruments.py +++ b/tests/test_instruments.py @@ -1,42 +1,109 @@ from __future__ import annotations +from datetime import date from decimal import Decimal import pytest from app.domain.backtesting_math import AssetQuantity, PricePerAsset from app.domain.instruments import ( + GLD_EXPENSE_DECAY_RATE, + GLD_INITIAL_OUNCES_PER_SHARE, + GLD_LAUNCH_YEAR, asset_quantity_from_weight, + gld_ounces_per_share, + instrument_metadata, price_per_weight_from_asset_price, weight_from_asset_quantity, ) from app.domain.units import BaseCurrency, Weight, WeightUnit +def test_gld_ounces_per_share_decay_formula_matches_research() -> None: + """Verify decay formula matches research examples from docs/GLD_BASIS_RESEARCH.md.""" + # Launch (2004): should be exactly 0.10 oz/share + launch_backing = gld_ounces_per_share(date(2004, 1, 1)) + assert launch_backing == GLD_INITIAL_OUNCES_PER_SHARE + assert launch_backing == Decimal("0.10") + + # 2026: should be ~0.0916 oz/share (8.4% decay from 22 years) + # Formula: 0.10 * e^(-0.004 * 22) = 0.10 * e^(-0.088) ≈ 0.091576 + years_2026 = 2026 - GLD_LAUNCH_YEAR # 22 years + expected_2026_decay = Decimal("0.10") * Decimal(str(__import__("math").exp(-0.004 * years_2026))) + actual_2026 = gld_ounces_per_share(date(2026, 1, 1)) + + # Check 2026 backing is approximately 0.0916 (within rounding tolerance) + assert abs(float(actual_2026) - 0.0916) < 0.0001 + assert actual_2026 == expected_2026_decay + + +def test_gld_ounces_per_share_uses_current_year_by_default() -> None: + """Verify default behavior uses today's date.""" + current_backing = gld_ounces_per_share() + current_year = date.today().year + expected_backing = gld_ounces_per_share(date(current_year, 1, 1)) + + # Should match the current year's calculation + assert current_backing == expected_backing + + +def test_gld_decay_rate_is_correct() -> None: + """Verify the decay rate constant is 0.4% annually.""" + assert GLD_EXPENSE_DECAY_RATE == Decimal("0.004") + + def test_gld_share_quantity_converts_to_troy_ounce_weight() -> None: + """GLD shares convert to weight using expense-adjusted backing (~0.0919 oz/share in 2026).""" quantity = AssetQuantity(amount=Decimal("10"), symbol="GLD") + current_backing = gld_ounces_per_share() weight = weight_from_asset_quantity(quantity) - assert weight == Weight(amount=Decimal("1.0"), unit=WeightUnit.OUNCE_TROY) + expected_weight = current_backing * Decimal("10") + assert weight == Weight(amount=expected_weight, unit=WeightUnit.OUNCE_TROY) + # Verify it's NOT the old 1.0 oz (which would be wrong) + assert weight != Weight(amount=Decimal("1.0"), unit=WeightUnit.OUNCE_TROY) def test_gld_troy_ounce_weight_converts_to_share_quantity() -> None: + """Convert 1 troy ounce to GLD shares using expense-adjusted backing.""" + # 1 oz should require more than 10 shares now (since each share backs <0.1 oz) weight = Weight(amount=Decimal("1"), unit=WeightUnit.OUNCE_TROY) + current_backing = gld_ounces_per_share() quantity = asset_quantity_from_weight("GLD", weight) - assert quantity == AssetQuantity(amount=Decimal("10"), symbol="GLD") + expected_shares = Decimal("1") / current_backing + assert quantity == AssetQuantity(amount=expected_shares, symbol="GLD") + # Should be more than 10 shares (approximately 10.87 in 2026) + assert quantity.amount > Decimal("10") def test_gld_share_quote_converts_to_ounce_equivalent_spot() -> None: - quote = PricePerAsset(amount=Decimal("404.19"), currency=BaseCurrency.USD, symbol="GLD") + """GLD price converts to gold spot using expense-adjusted backing.""" + # At ~$423/GLD share with ~0.0919 oz backing, spot should be ~$4600/oz + quote = PricePerAsset(amount=Decimal("422.73"), currency=BaseCurrency.USD, symbol="GLD") + current_backing = gld_ounces_per_share() spot = price_per_weight_from_asset_price(quote, per_unit=WeightUnit.OUNCE_TROY) - assert spot.amount == Decimal("4041.9") + expected_spot = quote.amount / current_backing + assert spot.amount == expected_spot assert spot.currency is BaseCurrency.USD assert spot.per_unit is WeightUnit.OUNCE_TROY + # Spot should be higher than naive 10:1 conversion ($4227.3) + assert spot.amount > Decimal("4227.3") + + +def test_gld_metadata_uses_expense_adjusted_backing() -> None: + """Verify GLD metadata uses the dynamic expense-adjusted backing.""" + gld_meta = instrument_metadata("GLD") + + expected_backing = gld_ounces_per_share() + assert gld_meta.weight_per_share.amount == expected_backing + assert gld_meta.weight_per_share.unit is WeightUnit.OUNCE_TROY + # Verify it's not the old hardcoded 0.1 + assert gld_meta.weight_per_share.amount != Decimal("0.1") def test_instrument_conversions_fail_closed_for_unsupported_symbols() -> None: diff --git a/tests/test_overview_workspace.py b/tests/test_overview_workspace.py index 8c8f5af..f8d0016 100644 --- a/tests/test_overview_workspace.py +++ b/tests/test_overview_workspace.py @@ -1,11 +1,18 @@ from __future__ import annotations +import pytest + from app.domain.portfolio_math import resolve_portfolio_spot_from_quote from app.models.portfolio import PortfolioConfig from app.services.alerts import build_portfolio_alert_context def test_overview_converts_gld_share_quote_to_ounce_equivalent_spot() -> None: + """Overview page converts GLD share quotes using expense-adjusted backing.""" + from datetime import date + + from app.domain.instruments import gld_ounces_per_share + config = PortfolioConfig(entry_price=4400.0, gold_ounces=220.0, entry_basis_mode="weight", loan_amount=145000.0) spot_price, source, updated_at = resolve_portfolio_spot_from_quote( @@ -25,11 +32,16 @@ def test_overview_converts_gld_share_quote_to_ounce_equivalent_spot() -> None: updated_at=updated_at, ) - assert spot_price == 4041.9 + # With expense-adjusted backing (~0.0916 oz/share), spot = 404.19 / 0.091576... ≈ 4413.71 + current_backing = float(gld_ounces_per_share(date.today())) + expected_spot = 404.19 / current_backing + assert abs(spot_price - expected_spot) < 0.01 assert source == "yfinance" assert updated_at == "2026-03-24T00:00:00+00:00" - assert portfolio["gold_value"] == 889218.0 - assert portfolio["net_equity"] == 744218.0 + # Gold value = 220 oz * spot_price + expected_gold_value = 220.0 * spot_price + assert abs(portfolio["gold_value"] - expected_gold_value) < 0.01 + assert portfolio["net_equity"] == pytest.approx(expected_gold_value - 145000.0, abs=0.01) assert round(float(portfolio["margin_call_price"]), 2) == 878.79 @@ -53,6 +65,11 @@ def test_overview_fails_closed_to_configured_entry_price_for_unsupported_quote_s def test_overview_uses_fallback_symbol_when_quote_payload_omits_symbol() -> None: + """GLD quote with fallback symbol uses expense-adjusted backing for conversion.""" + from datetime import date + + from app.domain.instruments import gld_ounces_per_share + config = PortfolioConfig(entry_price=4400.0, gold_ounces=220.0, entry_basis_mode="weight", loan_amount=145000.0) spot_price, source, updated_at = resolve_portfolio_spot_from_quote( @@ -61,7 +78,10 @@ def test_overview_uses_fallback_symbol_when_quote_payload_omits_symbol() -> None fallback_symbol="GLD", ) - assert spot_price == 4041.9 + # With expense-adjusted backing (~0.0916 oz/share), spot = 404.19 / 0.091576... ≈ 4413.71 + current_backing = float(gld_ounces_per_share(date.today())) + expected_spot = 404.19 / current_backing + assert abs(spot_price - expected_spot) < 0.01 assert source == "yfinance" assert updated_at == "2026-03-24T00:00:00+00:00" diff --git a/tests/test_portfolio_math.py b/tests/test_portfolio_math.py index 9fd9b02..e3a799d 100644 --- a/tests/test_portfolio_math.py +++ b/tests/test_portfolio_math.py @@ -2,6 +2,8 @@ from __future__ import annotations from decimal import Decimal +import pytest + from app.domain.backtesting_math import PricePerAsset from app.domain.instruments import price_per_weight_from_asset_price from app.domain.portfolio_math import ( @@ -45,10 +47,20 @@ def test_build_alert_context_uses_unit_safe_gold_value_calculation() -> None: def test_build_alert_context_accepts_explicit_gld_share_quote_conversion() -> None: + """GLD share quotes convert to spot using expense-adjusted backing.""" + from datetime import date + + from app.domain.instruments import gld_ounces_per_share + config = PortfolioConfig(entry_price=4400.0, gold_ounces=220.0, entry_basis_mode="weight", loan_amount=145000.0) share_quote = PricePerAsset(amount=Decimal("404.19"), currency=BaseCurrency.USD, symbol="GLD") ounce_spot = price_per_weight_from_asset_price(share_quote, per_unit=WeightUnit.OUNCE_TROY) + # With expense-adjusted backing (~0.0916 oz/share), spot = 404.19 / 0.091576... ≈ 4413.71 + current_backing = float(gld_ounces_per_share(date.today())) + expected_spot = 404.19 / current_backing + assert abs(float(ounce_spot.amount) - expected_spot) < 0.01 + context = build_alert_context( config, spot_price=float(ounce_spot.amount), @@ -56,9 +68,9 @@ def test_build_alert_context_accepts_explicit_gld_share_quote_conversion() -> No updated_at="2026-03-24T00:00:00+00:00", ) - assert context["spot_price"] == 4041.9 - assert context["gold_value"] == 889218.0 - assert context["net_equity"] == 744218.0 + assert abs(context["spot_price"] - expected_spot) < 0.01 + assert context["gold_value"] == pytest.approx(220.0 * expected_spot, abs=0.01) + assert context["net_equity"] == pytest.approx(220.0 * expected_spot - 145000.0, abs=0.01) assert context["quote_source"] == "yfinance" @@ -95,7 +107,10 @@ def test_strategy_metrics_from_snapshot_preserves_minus_20pct_protective_put_exa def test_resolve_portfolio_spot_from_quote_converts_gld_share_to_ozt() -> None: - """Hedge/runtime quote resolution should convert GLD share quotes to USD/ozt.""" + """Hedge/runtime quote resolution should convert GLD share quotes to USD/ozt using expense-adjusted backing.""" + from datetime import date + + from app.domain.instruments import gld_ounces_per_share from app.models.portfolio import PortfolioConfig config = PortfolioConfig(entry_price=4400.0, gold_ounces=220.0, entry_basis_mode="weight", loan_amount=145000.0) @@ -109,7 +124,10 @@ def test_resolve_portfolio_spot_from_quote_converts_gld_share_to_ozt() -> None: spot, source, updated_at = resolve_portfolio_spot_from_quote(config, share_quote) - assert spot == 4041.9 # 404.19 / 0.1 = 4041.9 USD/ozt + # With expense-adjusted backing (~0.0916 oz/share), spot = 404.19 / 0.091576... ≈ 4413.71 + current_backing = float(gld_ounces_per_share(date.today())) + expected_spot = 404.19 / current_backing + assert abs(spot - expected_spot) < 0.01 assert source == "yfinance" assert updated_at == "2026-03-25T00:00:00+00:00" diff --git a/tests/test_workspace.py b/tests/test_workspace.py index 2aa68bd..9289d58 100644 --- a/tests/test_workspace.py +++ b/tests/test_workspace.py @@ -4,6 +4,7 @@ import json import re from uuid import uuid4 +import pytest from fastapi.testclient import TestClient from app.main import app @@ -109,9 +110,17 @@ def test_bootstrap_endpoint_requires_turnstile_and_creates_workspace_cookie_and_ assert response.cookies.get("workspace_id") == workspace_id created = repo.load_portfolio_config(workspace_id) - assert created.entry_price == 4041.9 + # GLD quote at $404.19/share converts to spot using expense-adjusted backing + from datetime import date + + from app.domain.instruments import gld_ounces_per_share + + current_backing = float(gld_ounces_per_share(date.today())) + expected_entry_price = 404.19 / current_backing # ~4413.71 with 2026 backing + expected_gold_value = expected_entry_price * 100.0 + assert created.entry_price == pytest.approx(expected_entry_price, rel=1e-4) assert created.gold_ounces == 100.0 - assert created.gold_value == 404190.0 + assert created.gold_value == pytest.approx(expected_gold_value, rel=1e-4) def test_root_with_valid_workspace_cookie_redirects_to_workspace(tmp_path, monkeypatch) -> None: @@ -238,9 +247,11 @@ def test_workspace_routes_seed_page_defaults_from_workspace_portfolio_config(tmp def test_hedge_page_upgrades_cached_gld_quote_and_uses_converted_spot(tmp_path, monkeypatch) -> None: - """Hedge page should reuse DataService cache normalization for legacy GLD quotes.""" + """Hedge page should reuse DataService cache normalization for legacy GLD quotes with expense-adjusted backing.""" import asyncio + from datetime import date + from app.domain.instruments import gld_ounces_per_share from app.pages import hedge as hedge_module from app.services import runtime as runtime_module @@ -269,10 +280,13 @@ def test_hedge_page_upgrades_cached_gld_quote_and_uses_converted_spot(tmp_path, portfolio, source, _ = asyncio.run(hedge_module._resolve_hedge_spot(workspace_id)) + # With expense-adjusted backing (~0.0916 oz/share), spot = 404.19 / 0.091576... ≈ 4413.71 + current_backing = float(gld_ounces_per_share(date.today())) + expected_spot = 404.19 / current_backing assert source == "cache" - assert portfolio["spot_price"] == 4041.9 - assert portfolio["gold_value"] == 889218.0 - assert portfolio["net_equity"] == 667218.0 + assert portfolio["spot_price"] == pytest.approx(expected_spot, abs=0.01) + assert portfolio["gold_value"] == pytest.approx(220.0 * expected_spot, abs=0.01) + assert portfolio["net_equity"] == pytest.approx(220.0 * expected_spot - 222_000.0, abs=0.01) def test_hedge_page_upgrades_legacy_default_workspace_footprint(tmp_path, monkeypatch) -> None: @@ -323,8 +337,16 @@ def test_hedge_page_upgrades_legacy_default_workspace_footprint(tmp_path, monkey portfolio, source, _ = asyncio.run(hedge_module._resolve_hedge_spot(workspace_id)) + # With expense-adjusted backing (~0.0916 oz/share), spot = 404.19 / 0.091576... ≈ 4413.71 + from datetime import date + + from app.domain.instruments import gld_ounces_per_share + + current_backing = float(gld_ounces_per_share(date.today())) + expected_spot = 404.19 / current_backing + assert source == "cache" assert portfolio["gold_units"] == 100.0 - assert portfolio["margin_call_price"] == 1933.3333333333333 - assert portfolio["gold_value"] == 404190.0 - assert portfolio["net_equity"] == 259190.0 + assert portfolio["margin_call_price"] == pytest.approx(1933.3333333333333, abs=0.01) + assert portfolio["gold_value"] == pytest.approx(100.0 * expected_spot, abs=0.01) + assert portfolio["net_equity"] == pytest.approx(100.0 * expected_spot - 145000.0, abs=0.01)