SMA Ingestion Requirements

This document defines preparatory requirements for adding SMA portfolios after ICOI and IMST. It supports ENG-5249 and should be reviewed before any SMA ingestion implementation.

It does not change the current Alpha ingestion scope.

Purpose

Gordon confirmed that ICOI and IMST are the right first OIF portfolios. He also said the later extension should include SMA portfolios, but only if the system can map SMA positions to derivative-equivalent instruments.

The core requirement is:

The system must know what derivative-equivalent contract an SMA trade represents
before it can attach market data, smile context, term structure, marks, or
copilot warnings.

Relationship To Existing Contracts

SMA ingestion depends on two other documents:

Derivative Identity And Proxy Mapping: defines identity statuses, proxy policy, and mapping fields.
Source Authority Register: defines whether source states can support marks, P&L, estimates, proxies, and warnings.

SMA ingestion should not bypass either gate.

Minimum Source Field Contract

The future SMA source should provide, or allow the system to derive with approval, the following fields.

Field	Required?	Meaning
`portfolio`	Yes	SMA portfolio/account identifier.
`source_trade_id`	Yes	Stable source ID for idempotent ingestion.
`source_position_id`	Preferred	Position or lot ID when available.
`trade_timestamp`	Yes	Execution timestamp with timezone.
`settlement_date`	Preferred	Settlement date if available.
`source_symbol`	Yes	Raw instrument symbol from source.
`underlying`	Yes	Raw underlying, such as BTC, ETH, MSTR, COIN, or source-specific value.
`instrument_type`	Yes	Option, future, perpetual, spot, structured/OTC, or other.
`option_type`	Required for options	Call or put.
`expiry`	Required for options	Expiry date/time.
`strike`	Required for options	Strike.
`side`	Yes	Buy/sell or long/short.
`quantity`	Yes	Filled quantity.
`quantity_unit`	Yes	Contracts, coin, shares, notional, or source-specific unit.
`price`	Yes	Execution price in source units.
`price_currency`	Yes	Currency of price.
`premium`	Preferred	Total premium in source currency.
`premium_usd`	Preferred	Source total USD premium.
`multiplier`	Yes for options	Contract multiplier.
`deliverable`	Required for adjusted/custom	Deliverable or contract adjustment terms.
`status`	Yes	Filled, pending, canceled, expired, amended, or source equivalent.
`broker`	Preferred	Broker or execution venue.
`venue`	Preferred	Exchange, OTC, broker, or source venue.
`created_at`	Preferred	Source created timestamp.
`updated_at`	Preferred	Source updated timestamp for cursor sync.
`strategy_intent`	Preferred	Long vol, short vol, hedge, roll, close, or source strategy tag.
`parent_order_id`	Preferred	Parent/group ID for lifecycle and spread reconstruction.

Derivative-Equivalent Mapping Fields

For every SMA row, the mapping process should produce:

Field	Meaning
`canonical_underlying`	Normalized traded underlying.
`canonical_expiry`	Normalized expiry.
`canonical_strike`	Normalized strike.
`canonical_option_type`	Normalized call/put.
`canonical_multiplier`	Multiplier used for analytics.
`provider_symbol`	Symbol needed by the approved data provider.
`provider_symbol_format`	Deribit, OCC/OPRA, Amberdata-native, source-native, or other.
`derivative_equivalent_symbol`	Approved equivalent contract representation when source trade is OTC/custom.
`identity_status`	Exact, derivative-equivalent, proxy-only, pending listing, unmapped, unsupported, or needs review.
`mapping_method`	Exact parse, provider lookup, manual map, approved proxy, fallback, unsupported.
`authority_source`	Who or what approved the mapping.
`authority_status`	Approved, pending, rejected, expired, or not required.
`caveat`	Human-readable limitation.

Deribit-Style Crypto Option Representation

Gordon noted that Deribit uses a standard option representation. SMA crypto option trades should be mappable to an equivalent representation when economically valid.

The mapping should preserve:

underlying currency
expiry
strike
call/put
quantity unit
multiplier or coin contract size
execution source
whether the trade was exchange-listed, OTC-like, or custom

The system should not assume that an OTC-like trade is listed simply because a similar Deribit instrument exists. It needs an approved mapping state.

TradFi And Proxy Cases

SMA trades may include structures that are not exact Deribit-style crypto options. They may also include MSTR/COIN or other proxy underlyings.

Case	Required treatment
Exact listed crypto option	Map to provider-recognized exchange instrument.
OTC-like crypto option	Require derivative-equivalent approval or unsupported state.
Custom strike	Map only when approved; otherwise needs review.
Custom expiry	If expected to list later, mark as pending listing until equivalent exists.
MSTR/COIN option	Use MSTR/COIN traded-contract identity for marks, with BTC market proxy only if approved for opportunity context.
Adjusted contract	Require deliverable, multiplier, and authority source.
Proxy ticker	Record proxy reason, valid metric families, and retirement policy.
Unknown or incomplete terms	Keep unmapped; do not infer BTC silently.

Source Quality States

SMA ingestion should report quality before analytics are trusted.

State	Meaning
`ready`	Required fields and approved identity mapping exist.
`needs_mapping`	Required source fields exist but derivative-equivalent mapping is pending.
`needs_source_field`	Source feed lacks required contract/economic fields.
`proxy_only`	Row can support market context but not exact marks or P&L.
`unsupported`	Instrument is outside current provider/model capability.
`not_entitled`	Provider access blocks required source lookup.
`invalid`	Source row is internally inconsistent.

Questions For Jamil / Alpha / Operations

Question	Why it matters
Which SMA portfolios should enter first after `ICOI` and `IMST`?	Defines scope and test data.
What system will provide SMA trades and positions?	Determines API/file contract and auth.
Is there a stable source trade ID and update timestamp?	Required for idempotent sync.
Are option terms provided as discrete fields or only in a symbol string?	Controls parsing and validation work.
Are custom strike/expiry trades flagged by source?	Prevents silent listed-equivalent assumptions.
Does the source provide derivative-equivalent ticker or must we derive it?	Determines mapping ownership.
Who approves derivative-equivalent mappings?	Prevents engineering from approving economic equivalence.
Are strategy intent, opening/closing flag, and parent order/group available?	Needed for copilot action taxonomy and lifecycle.
Are execution marks, broker marks, settlement, or realized P&L available from the same source?	Determines whether SMA analytics can become outcome-aware.
How are amendments, cancels, partial fills, and corporate actions represented?	Required for reliable lifecycle and P&L.

Decision Points

Decision	Why it matters	Can proceed now?
Which SMA portfolios enter first?	Defines source scope, test data, and mapping universe.	Document requirements now; production scope needs Gordon/Jamil.
Who owns derivative-equivalent mapping approval?	Engineering should not silently approve economic equivalence.	Define approval fields now; owner decision needed.
Which SMA source system is authoritative?	Determines sync mechanism, field names, and lifecycle semantics.	Collect sample rows now; ingestion waits for source decision.
Can mappings be manually approved?	Custom strikes, custom expiries, and OTC-like trades may need human review.	Define review states now; workflow decision needed.
Which proxy cases are allowed for opportunity context only?	Prevents market proxy from becoming valuation authority.	Preserve proxy states now; approved metric families need review.
Does the SMA source provide strategy intent and lifecycle links?	Copilot evaluation needs to distinguish opens, closes, rolls, hedges, and spreads.	Define optional fields now; source availability decision needed.
What source supplies SMA realized P&L or terminal outcomes?	Outcome reporting cannot be inferred from partial trade rows.	Keep unavailable by default; source decision needed.

Preparatory Implementation Boundary

Can proceed now:

document SMA field contract
collect sample source rows
classify rows by source-readiness state
define derivative-equivalent mapping fields
define questions for Jamil and operations

Should wait:

production ingestion of SMA portfolios
treating SMA derivative-equivalent rows as decision-grade
SMA realized P&L
strong SMA trade warnings or recommendations
automated proxy ticker retirement

Acceptance For Preparatory Stage

This document is complete when Gordon, Jamil, and engineering can review:

which fields the SMA source must provide
which fields can be derived only with approval
how Deribit-style and TradFi/proxy cases differ
what states block analytics
what questions must be answered before ingestion begins