# Future Work

## Projections: future enhancements

- Configurable return cap per position (default: none; cap outliers like NVDA)
- Configurable MIN period selection (currently 3Y/5Y/10Y, exclude 1Y)
- "Not Retired Yet" mode: accumulation phase with contributions before retirement.
  Separate from life events — the simulation has two distinct phases: accumulation
  (base spending = 0, contributions applied) and distribution (searched-for withdrawal
  + spending model). Config: `retirement_age::60` or `retirement_in::10`, plus
  `annual_contribution::100000`. Safe withdrawal search only applies to the
  distribution phase. Chart shows portfolio growing during accumulation, peaking
  at retirement, then drawing down.
- Multiple spending models: flat (current), decreasing (1-2% real annual decrease,
  Blanchett "spending smile"). Late-life healthcare better modeled as a life event.
- Configurable benchmark symbols (currently hardcoded SPY + AGG)
- Unclassified position handling in allocation split (warn user)
- Historical projection comparison: re-run projections from any past snapshot date,
  overlay actual portfolio trajectory from subsequent snapshots onto the projected
  percentile bands. Shows how reality tracked against the model. Data is already
  available in history/*.srf snapshots — just need to load a historical portfolio
  value and re-run `computePercentileBands` with that starting point, then plot
  actual values from later snapshots as a line overlaid on the bands.

  `zfin projections --as-of <DATE>` already reruns the simulation
  against a past snapshot (the prerequisite for this overlay). What's
  missing is the overlay itself — loading multiple downstream snapshots
  and plotting their net-worth trajectory on the same chart.

  **Deferred to ~2027.** Needs a practical volume of real snapshots
  (currently building up; meaningful backtest requires 12+ months).
  Backfilling from git history is not viable — the lot-level state on
  portfolio.srf at a past commit is insufficient to reconstruct the
  full transaction+contribution picture. Revisit once there are 12+
  months of continuous snapshot data.

  Also consider: `metadata.srf` and `projections.srf` classifications /
  assumptions drift over time. For back-dated runs we currently use
  the current versions of both; historical git-tracked versions could
  be checked out and loaded instead. Edge case for now.

## Analysis account/asset-class total mismatch

The "By Account" and "By Tax Type" sections in the analysis command sum to slightly
more than "Asset Class" (~0.6% error). Likely a discrepancy between how the lot-level
account loop values cash, CDs, or options vs how the asset-class section computes them
via `portfolio.totalCash()` / `totalCdFaceValue()`. Low priority — the per-account
values themselves are correct after the price_ratio fix.

## Upgrade to 0.16.0

Pending dependencies:

* SRF: complete (use 0.15.2 tag if needed)
* VAxis: work seems to be in this PR: https://github.com/rockorager/libvaxis/pull/316
* z2d: 0.16.0 branch exists, but not sure if this is fully compatible with last commit in March

## CLI options command UX

The `options` command auto-expands only the nearest monthly expiration and
lists others collapsed. Reconsider the interaction model — e.g. allow
specifying an expiration date, showing all monthlies expanded by default,
or filtering by strategy (covered calls, spreads).

## Risk-free rate maintenance

T-bill rates are hardcoded in `src/analytics/risk.zig` as a year-by-year table
(source: FRED series DTB3). Each trailing period uses the average rate over its
date range. The table includes update instructions as doc comments.

**Action needed annually:** Update the current year's rate mid-year, finalize
the prior year's rate in January. See the curl commands in the `tbill_rates`
doc comment.

## CLI/TUI code review (lower priority)

No review has been done on these files. They are presentation-layer code
and not part of the reusable library API.

TUI:
- `src/tui.zig`
- `src/tui/chart.zig`
- `src/tui/keybinds.zig`
- `src/tui/theme.zig`

Commands:
- `src/commands/common.zig`
- `src/commands/analysis.zig`
- `src/commands/cache.zig`
- `src/commands/divs.zig`
- `src/commands/earnings.zig`
- `src/commands/enrich.zig`
- `src/commands/etf.zig`
- `src/commands/history.zig`
- `src/commands/lookup.zig`
- `src/commands/options.zig`
- `src/commands/perf.zig`
- `src/commands/portfolio.zig`
- `src/commands/quote.zig`
- `src/commands/splits.zig`

## TUI: toggle to last symbol keybind

Add a single-key toggle that flips between the current symbol and the
previously selected one (like `cd -` in bash or `Ctrl+^` in vim). Store
`last_symbol` on `App`; on symbol change, stash the previous. The toggle
key swaps current and last. Works on any tab — particularly useful for
eyeball-comparing performance/risk data between two symbols.

## Fix `enrich` command for international funds

`deriveMetadata` in `src/commands/enrich.zig` misclassifies international ETFs:

1. **`geo`** uses Alpha Vantage's `Country` field, which is the *fund issuer's*
   domicile (USA for all US-listed ETFs), not the fund's investment geography.
   Every US-domiciled international fund gets `geo::US`.

2. **`asset_class`** short-circuits to `"ETF"` when `asset_type == "ETF"`, or
   falls through to a US-market-cap heuristic that always produces
   `"US Large Cap"` / `"US Mid Cap"` / `"US Small Cap"`.

Known misclassified tickers (all came back as `geo::US, asset_class::US Large Cap`):
- **FRDM** — Freedom 100 Emerging Markets ETF → should be `geo::Emerging Markets, asset_class::Emerging Markets`
- **HFXI** — NYLI FTSE International Equity Currency Neutral ETF → should be `geo::International Developed, asset_class::International Developed`
- **IDMO** — Invesco S&P International Developed Momentum ETF → should be `geo::International Developed, asset_class::International Developed`
- **IVLU** — iShares MSCI International Developed Value Factor ETF → should be `geo::International Developed, asset_class::International Developed`

The Alpha Vantage OVERVIEW endpoint doesn't provide fund geography data.
Options: use the ETF_PROFILE holdings/country data to infer geography, parse
the fund name for keywords ("International", "Emerging", "ex-US"), or accept
that `enrich` is a scaffold and emit a `# TODO` comment for ETFs instead of
silently misclassifying.

## Market-aware cache TTL for daily candles

Daily candle TTL is currently 23h45m, but candle data only becomes meaningful
after the market close. Investigate keying the cache freshness to ~4:30 PM
Eastern rather than a rolling window. This would avoid unnecessary refetches
during the trading day and ensure a fetch shortly after close gets fresh data.
Probably alleviated by the cron job approach.

## On-demand server-side fetch for new symbols

Currently the server's SRF endpoints (`/candles`, `/dividends`, etc.) are pure
cache reads — they 404 if the data isn't already on disk. New symbols only get
populated when added to the portfolio and picked up by the next cron refresh.

Consider: on a cache miss, instead of blocking the HTTP response with a
multi-second provider fetch, kick off an async background fetch (or just
auto-add the symbol to the portfolio) and return 404 as usual. The next
request — or the next cron run — would then have the data. This gives
"instant-ish gratification" for new symbols without the downsides of
synchronous fetch-on-miss (latency, rate limit contention, unbounded cache
growth from arbitrary tickers).

Note that this process doesn't do anything to eliminate all the API keys
that are necessary for a fully functioning system. A more aggressive view
would be to treat ZFIN_SERVER as a 100% source of record, but that would
introduce some opacity to the process as we wait for candles (for example) to
populate. This could be solved on the server by spawning a thread to fetch the
data, then returning 202 Accepted, which could then be polled client side. Maybe
this is a better long term approach?

## Per-account covered call adjustment

`adjustForCoveredCalls` in `valuation.zig` operates on portfolio-wide aggregated
allocations. It matches sold calls against total underlying shares across all
accounts. This is wrong — calls in one account can only cover shares in that
same account. If NVDA calls are sold in Emil IRA, they shouldn't cap NVDA
shares held in Joint trust.

Fixing this means restructuring `portfolioSummary`, since `Allocation` is
currently account-agnostic. Approach: compute per-account reductions using
`positionsForAccount` + account-filtered option lots, then sum into
portfolio-wide reductions. Each account's reduction capped by that account's
shares, not the global total.

Low priority — naked calls are rare, and calls are typically in the same
account as the underlying.

## Covered call adjustment optimization

`adjustForCoveredCalls` has a nested loop — for each allocation, it iterates
all lots to find matching option contracts. O(N*M) is fine for personal
portfolios (<1000 lots). Pre-indexing options by underlying would help if
someone had a very large options-heavy portfolio.

## HTTP connection pooling

Parallel server sync in `loadAllPrices` spawns up to 8 threads, each with its
own HTTP connection. Could reuse connections to reduce TCP handshake overhead.
Only matters with very large portfolios (100+ symbols) hitting ZFIN_SERVER.
8 concurrent connections is fine for now.

## Streaming cache deserialization

Cache store reads entire files into memory (`readFileAlloc` with 50MB limit).
For portfolios with 10+ years of daily candles, this could use significant
memory. Keep current approach unless memory becomes a real problem.

## Audit: manual-check accounts mechanism (NYL, Kelly's ESPP, etc.)

Some accounts/positions can't be reconciled from broker CSVs and need a
human-in-the-loop reminder at the audit step. Examples:

- **NY Life** — no CSV export at all. Values only live in periodic
  statements.
- **Kelly's ESPP** — accrued payroll-deduction cash doesn't appear in the
  Fidelity positions CSV until the purchase date hits (typically every
  6 months). Between purchases the cash is a real contribution that
  `zfin audit` can't see.
- Future: treat as an open category.

The existing `update_cadence::weekly|monthly|quarterly|none` field already
sort-of covers this, but has two gaps:

1. It fires off the last *git-detected change*, not the last *human
   review*. For NYL, the value sometimes hasn't changed in months — so
   git never fires, cadence never trips.
2. ESPP needs weekly-ish attention while accumulating cash between
   purchases, but the accrued balance is invisible to the CSV audit.

### Options

A. **New `update_cadence::manual` variant** — always fires every audit
   run until silenced. Blunt but zero design work.

B. **`last_refreshed::YYYY-MM-DD` field on `accounts.srf`** — explicit
   human-review timestamp, decoupled from git-detected changes. Audit
   compares `today - last_refreshed` against the cadence. User bumps
   the field when they check the statement. Probably the most
   correct fit for NYL.

C. **Sticky TODO list** — a `todos.srf` or `todo::` field on accounts
   that audit always surfaces until cleared. General-purpose; also
   covers "remember to rebalance on 5/15".

### ESPP-specific follow-through

ESPP is also a contribution-attribution blind spot. If Kelly's paystub
deducts $X/week but the cash lot doesn't reach `portfolio.srf` until
the purchase date, the attribution math is under-counting contributions
and over-counting the purchase-week gain. Possible fixes are discussed
in the "Contributions diff" TODO below — option C there (per-account
`cash_is_contribution`) would make manually-entered ESPP
cash additions count correctly.

## Audit: tax-loss account persistent discrepancy (~-$897.59)

The tax-loss account consistently shows a small discrepancy (around
-$897.59 at time of writing) that requires manual tweaking in the
ratio-updates section — either adjusting shares or `price_ratio` each
week. The account is a weird one and requires careful hand-updating;
not something the runbook can safely automate.

Consider introducing an **"expected discrepancy tolerance"** field per
account so audit only flags deltas exceeding the known drift. Would
keep the audit output signal-to-noise high for this and any other
accounts with known-unfixable drift.

Careful: a tolerance should never silently swallow real discrepancies.
Probably render as muted (still visible, just not warning-colored)
until the delta exceeds the tolerance, rather than filtering entirely.

## Torn SRF files from server sync (recurring bug)

**Status:** First-layer fix done — 2026-05-02. `syncFromServer`
(`src/service.zig`) now validates responses via
`cache.Store.looksCompleteSrf` before `writeRaw`. Torn HTTP bodies
(empty, missing `#!srfv1` header, or no trailing newline) are
rejected with a warn-level log and NOT written to cache. Next fetch
will try the provider fallback.

**Remaining work (if it comes back):**

- HTTP-level Content-Length validation in `src/net/http.zig` to fail
  closer to the source rather than at the cache write.
- Read-path self-heal: on SRF parse failure during read, invalidate
  the cache entry so a subsequent refresh can repair without user
  intervention.