Skip to content

event_model.md

Latest commit

 

History

History
62 lines (46 loc) · 1.67 KB

event_model.md

File metadata and controls

62 lines (46 loc) · 1.67 KB
Raw

Event Model

The canonical Apex event model is defined in rust/apex-core and mirrored by Python schemas for orchestration and reporting.

The Rust core currently provides:

  • events.rs: typed event structs, enums, envelopes, kind tags, and deterministic event IDs.
  • event_bus.rs: in-memory deterministic publish/subscribe delivery.
  • event_log.rs: append-only event log with monotonic sequence checks and JSON-lines serialization.
  • clock.rs: deterministic backtest clock that cannot move backwards.

Envelope

Every event is wrapped in an EventEnvelope:

schema_version
sequence
event_id
run_id
timestamp_ns
kind
event

event_id is deterministic for a given run and sequence:

{run_id}-{sequence:020}

Sequences are assigned monotonically by EventBus and EventLog::append_event.

schema_version starts at 1 and must be incremented only when envelope or event payload compatibility changes.

Implemented event types

  • MarketDataEvent
  • SignalEvent
  • PortfolioTargetEvent
  • RiskCheckEvent
  • RiskLimitBreachEvent
  • OrderEvent
  • FillEvent
  • PnLEvent
  • AlertEvent
  • RunStartedEvent
  • RunCompletedEvent
  • RunFailedEvent

Determinism rules

  • Prices and money are represented as integer micros.
  • Quantities are represented as signed integer quantities.
  • Timestamps are represented as nanoseconds.
  • Event replay preserves append order.
  • Event logs reject non-monotonic sequence numbers.
  • The backtest clock rejects backwards time movement.

Current limitations

The Rust event core is intentionally small and deterministic. Durable storage, remote streaming, and production event infrastructure remain out of scope for v1.