Trade Performance Analytics Metric Contract

Purpose

This contract defines what the Vol Dashboard means by trade performance. It also documents the current production boundary so users can distinguish sourced analytics from intentionally unavailable metrics.

The central decision question is:

Did we trade when the dashboard showed an opportunity, did we execute well, and did the trade get the expected outcome?

The answer must be separated into three families:

Do not collapse these into one score until each component has its own source, unit, and data-quality state. A trade can align with a signal and still execute poorly. A trade can execute well and still lose money. A trade can have no defensible outcome yet even if its entry context is complete.

Current Production Status

The current /performance screen is live and should be read as a source-quality-aware analytics view, not a complete P&L report.

Current known gaps for the next phase are remaining source coverage for execution-time MSTR/COIN option quotes, authoritative adjusted 2MSTR/2COIN contract mapping, trade-level MSTR/COIN option liquidity fields, source coverage for 1d/7d/30d post-trade marks, intentionally unsourced Alpha trade-level smile richness, and authoritative realized-P&L/lifecycle accounting.

As of the 2026-05-10 production API check for source=alpha_sync, lookback_days=365, and limit=1000, the default Performance population is:

Current Alpha Inputs

Production Alpha sync writes source rows into internal_trades with source='alpha_sync'.

Current production scope:

The proxy split is intentional. BTC-linked volatility, gamma, VRP, term-structure, and stationarity context define the opportunity backdrop for current proxy trades. BTC proxy liquidity is context/backdrop only and should not be used to judge whether a MSTR/COIN option trade was executable. BTC smile remains a market-surface read, not an Alpha trade-level proxy. Execution and outcome marks must use the actual traded option market, not BTC option quotes.

The preparatory contract for exact, adjusted, standard-root fallback, SMA/OTC derivative-equivalent, unsupported, and unmapped identity states is maintained in Derivative Identity And Proxy Mapping.

The next preparatory work is split across Data Ingestion Readiness Plan, Trade Copilot Evaluation Specification, and SMA Ingestion Requirements. These documents define the durable sourcing plan, accident-avoidance and restructuring evaluation contract, and future SMA field requirements without changing the current Performance production boundary.

Available Fields

Current Field Gaps

The current Alpha feed does not provide enough data for all performance analytics.

Blank or unavailable is the correct output when a required input is missing. Do not display zero for unavailable economics.

Data-Quality States

Every computed trade-performance metric must carry a quality state.

For the cross-document policy that defines which source and quality states may feed decision-grade marks, P&L, estimates, proxy outputs, and future copilot warnings, see the Source Authority Register.

Recommended common metadata fields:

Required Direction And Sign Conventions

Direction must be explicit because buy and sell fills have opposite economics.

If strategy intent is unknown, report both the raw component and the assumed interpretation. Do not infer that every option buy is a pure long-vol trade or that every option sell is a pure short-vol trade.

Metric Families

1. Execution Quality

Execution quality asks whether the fill was attractive relative to the actual traded instrument market at the time.

Execution benchmarks must use the traded instrument quote source. For current scope that means MSTR/COIN option data for execution marks, not BTC option data.

Minimum execution-quality API shape:

execution_quality = {
  trade_id,
  source_trade_id,
  fill_price,
  benchmark_bid,
  benchmark_ask,
  benchmark_mid,
  fill_vs_mid,
  fill_vs_mid_bps,
  spread_capture,
  fill_vs_surface_mark,
  entry_iv_edge,
  source_name,
  source_timestamp,
  time_delta_minutes,
  metric_quality,
  missing_fields
}

2. Opportunity Alignment

Opportunity alignment asks whether the trade was entered when dashboard signals indicated a coherent opportunity. It is a signal-consistency measure, not a P&L measure.

The current MSTR/COIN scope should use BTC-linked dashboard context for these metrics unless a later decision changes the proxy mapping.

Candidate alignment interpretation:

Because Alpha currently lacks strategy intent, the first implementation should store the assumption used to calculate alignment.

Minimum opportunity-alignment API shape:

opportunity_alignment = {
  trade_id,
  source_trade_id,
  market_proxy,
  mapping_method,
  mapping_confidence,
  assumed_trade_intent,
  alignment_score,
  alignment_label,
  drivers,
  detractors,
  confidence,
  context_timestamp,
  context_time_delta_minutes,
  metric_quality,
  missing_fields
}

3. Outcome Quality

Outcome quality asks what happened after the trade and whether outcomes cluster by regime or signal.

Outcome metrics should operate on both execution rows and lifecycle/position groups once lifecycle grouping exists. Per-trade outcome is useful, but position-level outcome is often the more defensible trading answer.

The backend persists sourced 1d/7d/30d marks in trade_forward_outcome_marks through /api/internal/trades/outcomes/backfill. Performance APIs read those persisted rows by default so user-facing P&L is repeatable and carries source quality.

Required horizons for first implementation:

Expiry outcomes must remain unavailable unless backed by sourced quote, close, settlement, Alpha realized outcome, or equivalent authoritative mark. A model-estimated intrinsic value can only be shown as model_estimated, not as realized P&L.

Outcome states:

Minimum outcome API shape:

outcome = {
  trade_id_or_position_id,
  source_trade_ids,
  horizon,
  entry_value_usd,
  mark_value_usd,
  pnl_usd,
  return_on_premium,
  realized_vol,
  realized_vol_capture,
  spot_move,
  regime_at_entry,
  signal_bucket_at_entry,
  mark_source,
  mark_timestamp,
  mark_time_delta_minutes,
  metric_quality,
  missing_fields
}

Position And Lifecycle Requirements

Raw Alpha rows are executions. Many performance questions need lifecycle grouping before they can be answered defensibly.

Minimum grouping key:

source_portfolio
underlying_symbol
instrument or option_symbol
option_type
strike
expiry
direction/sign

Required position/lifecycle metrics:

If a row cannot be confidently paired, label it ambiguous_lifecycle. Do not force ambiguous rows into realized P&L. Same-contract FIFO cashflow can be retained for research, but it must not be shown as user-facing realized P&L until reconciled to source accounting.

Aggregation Contract

Aggregates are only meaningful when they expose sample size and quality composition.

Required aggregate dimensions:

Every aggregate must include:

sample_count
available_count
unavailable_count
estimated_count
stale_count
proxy_mapped_count

Aggregates must not silently exclude bad data. If unavailable rows are excluded from a calculation, show the excluded count.

First-Screen Questions

The Trade Performance screen should answer these questions in order:

1. Is the selected Alpha scope loaded cleanly enough to interpret Performance?
2. Which trades have enough context to score opportunity alignment?
3. When trades were entered, were dashboard signals cheap/rich, stable/unstable, or confirming/conflicting?
4. Which context source groups are available, partial, or unavailable?
5. Were fills good versus the actual traded instrument market? Current answer: available only for rows with fresh sourced execution-time quotes; otherwise not benchmarked, stale, or unavailable.
6. What happened after entry at defensible horizons? Current answer: available only for rows with persisted fresh forward marks; pending for immature horizons and unavailable for matured horizons without sourced marks.
7. Is realized P&L sourced? Current answer: unavailable until authoritative accounting or validated lifecycle data exists.
8. Which regimes, signals, portfolios, or underlyings are associated with better or worse outcomes? Current answer: bucket counts are available; P&L and hit-rate aggregates are available only for rows with sourced forward marks.
9. Which results are unavailable because data is missing rather than because economics were zero?

Implementation Sequence Dependencies

This contract originally preceded implementation. It now remains the governing contract for the live Performance screen and the follow-on data-sourcing work.

Non-Goals For This Contract

• It does not treat missing TradFi quote coverage as zero slippage or zero P&L.
• It does not authorize displaying a metric without source and quality state.
• It does not authorize model-estimated expiry P&L as realized P&L.
• It does not infer strategy intent from direction alone.
• It does not change the Alpha sync or sync-completeness diagnostic workflow.

Review Checklist

• Each metric has a formula or deterministic definition.
• Each metric has a unit.
• Each metric names required inputs.
• Each metric defines no-data behavior.
• Proxy underlyings are separated from quote/outcome underlyings.
• Current Alpha field gaps are explicit.
• Aggregates expose sample count and data-quality composition.
• No missing input is represented as zero.