Derivative Identity And Proxy Mapping Contract

This document defines the preparatory contract for derivative-equivalent identity and proxy mapping. It is the planning artifact for ENG-5238.

It does not create database tables, backend code, or UI behavior yet. It defines the model that those later changes should implement after Gordon reviews the sponsor-facing strategy.

Core Problem

The dashboard cannot attach marks, smile data, term-structure context, liquidity, or P&L to a trade until it knows what derivative-equivalent instrument the trade represents.

Gordon described several examples that are the same identity problem:

SMA trades that are not exchange-listed but can be represented by a derivative-equivalent ticker
OTC-like trades with custom strikes
OTC-like trades with custom expiries
expiries traded before they appear formally on the board
adjusted contracts such as 2MSTR or 2COIN
MSTR/COIN proxy trades whose opportunity context is BTC-linked but whose execution marks must be MSTR/COIN option marks

The identity layer must keep these concepts separate:

market/regime proxy != traded contract identity != valuation source

For example, an ICOI COIN option trade can use BTC-linked regime context for opportunity alignment while still requiring exact COIN option quotes for execution quality and forward outcome marks.

Identity Statuses

Status	Meaning	Decision-grade use
`exact_listed`	The source trade maps to a listed contract recognized by the approved market-data provider.	Allowed for sourced execution marks, liquidity, forward marks, and smile data if source coverage exists.
`adjusted_authoritative`	The trade maps to an adjusted contract with approved deliverable, multiplier, root, and provider symbol.	Allowed once authority source is recorded.
`standard_root_fallback`	An adjusted or ambiguous source trade is temporarily looked up using a standard root such as `MSTR` instead of `2MSTR`.	Exploratory only unless business approves the fallback for a specific metric family. Must be visibly caveated.
`derivative_equivalent`	An SMA, OTC-like, or custom trade maps to an approved equivalent contract representation.	Allowed only for the approved context and metric families.
`proxy_context_only`	The trade uses a market proxy for opportunity/regime context but not for exact contract marks.	Allowed for opportunity context only. Not allowed for execution marks or P&L.
`custom_pending_listing`	The trade references a strike/expiry expected to appear later but not currently listed.	Needs review until listed equivalent or approved proxy is available.
`unmapped`	The system cannot resolve a derivative-equivalent identity.	Withhold decision-grade analytics.
`unsupported`	The instrument or structure is outside current provider/system capability.	Withhold decision-grade analytics and show unsupported reason.
`needs_review`	The mapping is plausible but ambiguous or missing authority.	Withhold decision-grade analytics until reviewed.

Required Identity Fields

The eventual persisted or deterministic identity representation should carry these fields.

Field	Meaning
`trade_source`	Source system such as `alpha_sync`, SMA feed, manual scenario, or future OMS/PMS source.
`source_trade_id`	Source-system trade identifier.
`source_portfolio`	Portfolio such as `ICOI`, `IMST`, or future SMA portfolio.
`source_symbol`	Raw symbol from the source system.
`source_instrument`	Human-readable source instrument label.
`source_underlying`	Raw underlying from source, such as `MSTR`, `COIN`, `BTC`, `ETH`, or custom source value.
`source_expiry`	Expiry supplied by the source.
`source_strike`	Strike supplied by the source.
`source_option_type`	`call` or `put` from source.
`source_multiplier`	Source-provided contract multiplier.
`canonical_underlying`	Normalized underlying for the traded contract.
`canonical_option_type`	Normalized call/put value.
`canonical_expiry`	Normalized expiry date.
`canonical_strike`	Normalized strike.
`canonical_multiplier`	Multiplier used for analytics after mapping.
`deliverable`	Contract deliverable for adjusted or non-standard contracts.
`provider_name`	Market-data provider or authority source used for lookup.
`provider_symbol`	Provider-recognized contract symbol.
`provider_symbol_format`	Format such as OCC/OPRA, Deribit, Amberdata-native, or source-native.
`market_proxy`	Market/regime context key such as `BTC`; null when not used.
`market_proxy_method`	Reason for market proxy, such as `crypto_equity_proxy` or `direct_market_symbol`.
`identity_status`	One of the statuses above.
`mapping_method`	How the identity was produced: exact parse, provider lookup, manual map, approved proxy, standard-root fallback, or unsupported.
`mapping_confidence`	Numeric or labelled confidence in the identity mapping.
`authority_source`	Source that validates the mapping, such as Alpha, broker/OMS, OCC/OPRA, OptionMetrics, Amberdata, Deribit convention, or manual approval.
`authority_status`	`approved`, `pending`, `rejected`, `expired`, or `not_required`.
`caveat`	Human-readable limitation, especially for fallback or proxy mappings.
`missing_fields`	Required fields that prevented exact mapping.
`review_owner`	Person/team expected to approve or reject ambiguous mappings.
`review_status`	`not_needed`, `pending`, `approved`, or `rejected`.
`valid_from` / `valid_to`	Optional date range for mappings that change over time.

Mapping Layers

The system should evaluate mapping in layers rather than jumping directly from raw source trade to analytics.

Layer	Question	Example output
Source parse	What did the source system say the trade was?	Alpha row: COIN May call, strike, expiry, multiplier.
Canonical identity	What is the normalized traded contract?	COIN option, call, expiry, strike, multiplier.
Provider identity	What symbol does the approved data provider require?	Provider-native option symbol or OCC/OPRA format.
Derivative-equivalent identity	If source trade is SMA/OTC/custom, what listed or model-equivalent contract should represent it?	Deribit-style BTC expiry/strike/call-put equivalent.
Market proxy	What market/regime context should explain opportunity backdrop?	`MSTR -> BTC`, `COIN -> BTC`, or direct `BTC -> BTC`.
Authority gate	Is this mapping allowed for the metric being displayed?	Exact mark allowed; proxy context allowed only for opportunity; fallback excluded from sourced aggregates.

Mapping Policy By Case

Case	Mapping policy	Output state
Standard listed MSTR/COIN option	Parse source fields and validate with provider lookup.	`exact_listed` when provider recognizes the contract.
Adjusted `2MSTR` / `2COIN` option	Require authoritative adjusted root, deliverable, multiplier, and provider symbol before decision-grade analytics.	`adjusted_authoritative` when approved; otherwise `needs_review` or `standard_root_fallback`.
Standard-root adjusted fallback	Use only as explicitly labelled exploratory fallback when enabled.	`standard_root_fallback`; excluded from decision-grade aggregates unless approved for a metric family.
BTC/ETH/SOL listed crypto option	Use direct exchange/provider instrument identity when source fields match provider convention.	`exact_listed`.
SMA option trade with derivative-equivalent listed representation	Store the source trade plus approved equivalent ticker and authority source.	`derivative_equivalent`.
OTC-like custom strike	Map to exact equivalent only if provider/listing exists; otherwise keep custom mapping pending review.	`derivative_equivalent`, `custom_pending_listing`, or `needs_review`.
OTC-like custom expiry	Same as custom strike; if expiry is expected to list later, do not assume listed identity before it appears.	`custom_pending_listing` or `needs_review`.
Proxy ticker used before listed equivalent exists	Record proxy ticker, reason, expected listed equivalent, and review state.	`proxy_context_only` or `custom_pending_listing` depending on use.
Unknown underlying or incomplete option terms	Do not infer BTC or another proxy silently.	`unmapped`.
Provider cannot support the instrument	Keep explicit unsupported state.	`unsupported`.

Current Known Mappings

These are current planning positions, not a complete production mapping table.

Source trade scope	Traded contract identity	Market/regime proxy	Execution/outcome source requirement
`ICOI` COIN options	COIN listed or adjusted option identity.	BTC context for opportunity backdrop.	COIN option market data for execution and forward marks.
`IMST` MSTR options	MSTR listed or adjusted option identity.	BTC context for opportunity backdrop.	MSTR option market data for execution and forward marks.
Future SMA BTC/ETH options	TBD derivative-equivalent identity.	Direct BTC/ETH if equivalent is crypto option exposure.	Equivalent contract or approved valuation source.
Future SMA OTC/custom structures	TBD derivative-equivalent identity or unsupported.	Depends on approved mapping.	Requires approved equivalent, mark source, and caveat.

Separation From Source Authority

Identity answers:

What instrument is this?

Source authority answers:

Can this source and quality state support the metric being displayed?

The Source Authority Register controls whether exact, proxy, fallback, estimated, stale, pending, unavailable, unsupported, and not-entitled states can feed decision-grade outputs.

Examples:

exact_listed identity plus fresh provider quote can support execution quality.
proxy_context_only can support opportunity context but not fill-vs-mid.
standard_root_fallback can support exploratory diagnostics but should not be mistaken for authoritative adjusted-contract mapping.
derivative_equivalent can support SMA analytics only for the metric families approved by Gordon/team.

Business Decisions Needed

Decision	Proposed owner	Why it matters
Which SMA portfolios enter first after ICOI/IMST?	Gordon / Jamil / trading	Defines the next source scope and expected mapping universe.
Who owns derivative-equivalent mapping approvals?	Gordon / trading / operations	Prevents engineering from silently approving economic equivalence.
What source validates adjusted `2MSTR` / `2COIN` deliverables and multipliers?	Operations / broker/OMS / OCC/OPRA / approved vendor	Needed before adjusted rows become decision-grade.
Which provider symbol format is canonical for MSTR/COIN options?	Engineering / market-data owner	Prevents provider-specific parsing errors and empty responses.
How should proxy tickers be retired once the listed equivalent appears?	Trading / operations	Prevents stale proxy mappings from remaining active.
Where is standard-root fallback acceptable?	Gordon / trading	May differ across diagnostics, execution marks, forward marks, liquidity, and P&L.
Can SMA/OTC derivative-equivalent mappings be manually approved?	Gordon / trading / operations	Determines whether a manual review workflow is required.
What is the minimum evidence needed before a custom strike/expiry is analyzable?	Gordon / trading	Controls whether custom structures are supported, proxy-only, or unsupported.

Preparatory Implementation Notes

Future implementation should preserve these principles:

no silent default from unknown symbol to BTC
no silent upgrade from standard_root_fallback to adjusted_authoritative
no use of market proxy as traded-contract execution liquidity
no valuation or P&L output without both identity and source authority
every unmapped or unsupported row should carry a reason code
provider symbols should be validated against live/provider responses, not assumed from docs alone
mappings should support multiple portfolios, underlyings, providers, and date ranges from the start

Recommended future API shape:

contract_identity = {
  trade_source,
  source_trade_id,
  source_portfolio,
  source_symbol,
  source_underlying,
  canonical_underlying,
  canonical_expiry,
  canonical_strike,
  canonical_option_type,
  canonical_multiplier,
  deliverable,
  provider_name,
  provider_symbol,
  provider_symbol_format,
  market_proxy,
  market_proxy_method,
  identity_status,
  mapping_method,
  mapping_confidence,
  authority_source,
  authority_status,
  caveat,
  missing_fields,
  review_owner,
  review_status
}

Open Implementation Boundary

This document is preparatory. The following remain deferred until Gordon reviews the strategy and the team agrees on source authority:

database schema or migration for persisted contract identity
backend mapping service changes
SMA ingestion
provider lookup behavior changes
UI display of identity states
execution/forward/P&L logic that relies on new identity states