Market State

MarketSnapshot is the normalized language of AtlantisV2 market state.

It is not a venue payload. It is not an option chain row. It is not a database table. It is the as-of view that features and patterns consume.

Snapshot Shape

The current MarketSnapshot carries:

• snapshot_id
• cycle
• underlying
• primary_instrument
• capabilities
• session_context
• freshness
• quality
• source_lineage
• events

The snapshot is intentionally capability-based. Feature definitions ask for capabilities, not instrument classes.

Capability Blocks

Implemented capability names include:

• price
• volume
• open interest
• funding
• volatility
• options surface
• liquidity
• microstructure
• execution cost
• regime

Implemented block types currently include:

• PriceCapability
• VolumeCapability
• OpenInterestCapability
• GreeksCapability

The registry is typed:

CAPABILITY_TYPES = {
    CapabilityName.PRICE: PriceCapability,
    CapabilityName.VOLUME: VolumeCapability,
    CapabilityName.OPEN_INTEREST: OpenInterestCapability,
    CapabilityName.GREEKS: GreeksCapability,
}

Wrong-typed capability entries raise instead of degrading silently.

Availability States

Capability availability is explicit:

• PRESENT
• MISSING
• STALE
• INVALID
• WITHHELD

This is one of the most important framework rules. Missing data must not become 0.0. Stale data must not look present. Invalid data must not look missing.

SnapshotBuilder

SnapshotBuilder currently builds a snapshot from EventEnvelope[].

It owns:

• event deduplication
• future event filtering
• stable event ordering
• event-to-market-event normalization
• invalid payload quality flags
• price capability construction
• volume capability construction
• open-interest capability construction
• freshness flags
• source lineage map

Adapters should not duplicate those responsibilities.

Price Capability

PriceCapability supports:

• present price with last price, event timestamp, and source
• missing price with reason
• stale price with last observed price and reason

PriceCapability.present(
    last_price=65000.0,
    event_ts=event_ts,
    source="event_envelope",
)

Move Intelligence Capabilities

The first Move Intelligence Core Pack extends market state beyond price-only snapshots.

VolumeCapability can carry:

• latest volume
• event timestamp
• source
• volume z-score
• velocity and acceleration placeholders

OpenInterestCapability can carry:

• latest open interest
• event timestamp
• source
• OI velocity percentage
• OI acceleration placeholder

GreeksCapability can carry:

• delta
• gamma
• theta
• vega
• IV
• IV velocity

These are typed capability shells. They make the old Atlantis feature vocabulary portable without making Core depend on option-chain rows, perp venue payloads, or database schemas.

Quality Flags

Snapshot quality currently records flags such as:

• future_event_ignored
• duplicate_event_ignored
• invalid_price_payload
• invalid_volume_payload
• invalid_open_interest_payload
• missing_price
• stale_price

These flags are later visible to scoring and permission logic, where data quality can reduce confidence or reject an intent.

Instrument References

UnderlyingRef and InstrumentRef keep identity separate:

• underlying: BTC, NIFTY, BANKNIFTY
• instrument: BTC-PERP, NIFTY option contract, spot symbol, synthetic index

Core can reason about a BTC thesis without assuming the final expression is a perp, spot position, or option.

What Comes Next

The next market-state expansions should continue as capability blocks, not hardcoded snapshot fields:

• funding capability
• volatility capability
• options surface capability
• liquidity and execution cost capability

Each should include availability, event timestamp, source, and typed value fields.