This document defines Muninn's core domain vocabulary. Every term here has a precise meaning. When in doubt, refer back to this document; do not re-define terms locally.
classDiagram
class MarketEvent {
<<sealed interface>>
+UUID eventId
+Instant eventTime
+Instant ingestTime
+String source
+Instrument instrument
+long sequenceNumber
+int schemaVersion
+String topicName()
}
class TradeEvent {
+BigDecimal price
+BigDecimal size
+Side side
+String exchangeTradeId
}
class CandleEvent {
+BigDecimal open
+BigDecimal high
+BigDecimal low
+BigDecimal close
+BigDecimal volume
+Instant windowStart
+Instant windowEnd
+Duration windowDuration
}
class OrderBookSnapshotEvent {
+List~PriceLevel~ bids
+List~PriceLevel~ asks
+int depth
}
class FeatureComputedEvent {
+String featureName
+String featureVersion
+BigDecimal value
+Instant windowStart
+Instant windowEnd
+List~UUID~ inputEventIds
+String codeVersion
}
class Instrument {
+String symbol
+String baseAsset
+String quoteAsset
+Exchange exchange
}
class Exchange {
+String id
+String displayName
+ZoneId timezone
}
class ReplayJob {
+UUID jobId
+Instant from
+Instant to
+List~String~ topics
+String featureVersion
+String outputSink
+Status status
}
class FeatureWindow {
+String featureName
+Instant windowStart
+Instant windowEnd
+WindowType windowType
+Duration size
+Duration slide
}
class Checkpoint {
+UUID checkpointId
+Instant watermark
+String engineVersion
+String stateSnapshotUri
}
MarketEvent <|-- TradeEvent
MarketEvent <|-- CandleEvent
MarketEvent <|-- OrderBookSnapshotEvent
MarketEvent --> Instrument
Instrument --> Exchange
FeatureComputedEvent ..> MarketEvent : derived from N
FeatureComputedEvent --> FeatureWindow : computed over
ReplayJob --> Checkpoint : may resume from
ReplayJob ..> MarketEvent : replays
ReplayJob ..> FeatureComputedEvent : produces
The Mermaid block above renders inline on GitHub. The remainder of this document is the textual specification — it is authoritative if the diagram and the text disagree.
All events are immutable records. They carry an eventId (UUIDv7, sortable by creation time), an eventTime (when the fact occurred in the world), and a source identifying their origin.
The supertype of all market-data events. Carries:
eventId: UUIDeventTime: Instant— exchange-reported timestampingestTime: Instant— when Muninn observed itsource: String— adapter id (e.g.,coinbase.spot.v1)instrument: InstrumentsequenceNumber: long— monotonic per (source, instrument)
A single executed trade reported by an exchange.
- price:
BigDecimal - size:
BigDecimal - side:
Side(BUY | SELL | UNKNOWN) - exchangeTradeId:
String
A time-bucketed OHLCV summary. Produced either by the exchange (preferred) or by the feature engine. When produced internally, it is itself reproducible from TradeEvents.
- open, high, low, close:
BigDecimal - volume:
BigDecimal - windowStart, windowEnd:
Instant - windowDuration:
Duration
A point-in-time order-book state, capped to a configured depth.
- bids:
List<PriceLevel> - asks:
List<PriceLevel> - depth:
int - sequenceNumber:
long
PriceLevel = (price, size).
The output of the feature engine. It is itself an event so that downstream consumers can subscribe to derived signals using the same machinery as raw events.
- featureName:
String - featureVersion:
String - value:
BigDecimal | Map<String, BigDecimal> - windowStart, windowEnd:
Instant - inputEventIds:
List<UUID>— provenance - codeVersion:
String— git SHA of the feature engine that produced this
A trade-able instrument on an exchange.
- symbol:
String(e.g.,BTC-USD) - baseAsset:
String - quoteAsset:
String - exchange:
Exchange
A data source.
- id:
String(e.g.,coinbase) - displayName:
String - timezone:
ZoneId
The time the fact occurred in the world, as reported by the source. This is the primary time used for windowing, ordering, and feature computation. It can arrive out-of-order.
The time the system observed or processed the event. Used for SLAs, lag metrics, and operational dashboards. Never used inside feature computation.
A monotonic estimate of "we have seen all events with eventTime ≤ W." A window closes when its end is below the current watermark. Late events arriving after their window's watermark are routed to a configured policy (drop, side-output, or revise).
A scheduled or ad-hoc replay of a portion of the event log through the feature engine.
- jobId:
UUID - from, to:
Instant— event-time range - topics:
List<String> - featureVersion:
String - outputSink:
String(e.g.,parquet://muninn-warehouse/replay/{jobId}) - status:
PENDING | RUNNING | COMPLETED | FAILED - checkpoints:
List<Checkpoint>
The bounded time range over which a feature is computed.
- featureName:
String - windowStart, windowEnd:
Instant - windowType:
TUMBLING | SLIDING | SESSION - size, slide:
Duration
A durable snapshot of feature-engine state, indexed by watermark. Replay can resume from a checkpoint rather than re-reading from the beginning.
- checkpointId:
UUID - watermark:
Instant - engineVersion:
String - stateSnapshotUri:
String
- All
UUIDfields are UUIDv7 (time-ordered). featureVersionandcodeVersionare git SHAs or semantic version strings; they are recorded on everyFeatureComputedEventso that consumers can detect logic changes.- Schema evolution is tracked separately in EVENT_SCHEMA_STRATEGY.md.