Glossary

Terms and concepts used across lib and the wider Virtufin platform. Each entry links to where it's authoritatively defined. A shorter, newcomer-facing version of this glossary — domain concepts and org vocabulary only, no implementation detail — lives at docs.virtufin.com/glossary.

Core domain concepts

Term	Definition
Market	The exogenous price universe the system observes; nothing inside the system influences it. See the pubsub-topics spec's Market Data Events.
Portfolio	The collection of all positions (holdings per symbol, including cash), modeled as Map Symbol PositionState.
Strategy	The pair of functions — decide and execute — that decide what to do and execute it. Not itself a stream. See the Behavior Layer.
Scenario	A named, registered configuration tying together a market data source, an initial portfolio, and a strategy, with a stable identity for routing, attribution, and audit. See the scenarios spec.
Event	An immutable fact that occurred at a specific eventTime. See the pubsub-topics spec's CloudEvents Envelope.
Log	An append-only, ordered history of events — a free monoid Event*.
Stream	A time-indexed sequence of events observed at runtime; formally a functor 𝕋 → Set Event.
Signal	A continuously derivable value computed from a log; never transported on the wire (e.g. PortfolioState(t), unrealizedPnL(t)), computed on demand instead. See the Behavior Layer.
Indicator	A self-folding Signal — one that also knows how to incorporate a new sample and produce an updated instance (IIndicator<TSelf, TSample, TValue>, see below), e.g. a moving average. See the Behavior Layer.
Position	The holding of a specific symbol at a point in time: symbol, qty, avgEntry, unrealizedPnL, eventTime. See the pubsub-topics spec's Position Lifecycle Events.
Cash	A degenerate position in the settlement currency — avgEntry is always 1.0, unrealizedPnL always 0.
equity	Σ PositionState(s,t).qty × marketPrice(s,t) across all symbols.
unrealizedPnL	(marketPrice − avgEntry) × qty, recomputed on every tick, never stored.
realizedPnL	The fold over closing fills of accrued P&L — the change in USDT quantity since scenario start.
watermark	A threshold beyond which late-arriving events (by eventTime) are dropped or routed to a correction stream.
Monotonicity invariant	Event streams must be monotonically ordered by eventTime — the invariant the whole fold-based state model depends on for deterministic replay.
Clock morphism (φ)	An order-preserving map 𝕋_wall → 𝕋_synth translating wall time to replay time. Switching a component between act and hyp is a change of clock interpretation, not a change of behavior.
Variant	The cross-cutting discriminated-union type (Virtufin.Data) — the platform's wire "lingua franca," byte-identically deserializable across C#/Python/TypeScript via FlatBuffers.
EAV (Entity-Attribute-Value)	The data model underlying every business concept in the platform — orders, positions, scenarios, contracts, accounts. Every "thing" is an entity with named attributes whose values come from pluggable value providers (IEntity, IAttribute, IValueProvider, Registry).

The act/hyp dimension

Term	Definition
act	The "actual" leg of a scenario component — a live data source or a real account, running on 𝕋_wall.
hyp	The "hypothetical" leg — replay/synthetic data or a simulated account, running on 𝕋_synth. Always requires a named world; bare hyp with no name is never valid.
world	One of two triplet-leg values, "act" or "hyp.<name>", identifying which reality — actual, or a specific named hypothetical — a market/portfolio/strategy leg runs against.
universe	The data-universe name for market data (e.g. EQ_EUROPE, ALL, BTC_202101_202206); present for both act and hyp.<name>. Travels in the marketuniverse envelope extension, never as a topic segment.
Named Hypothetical World	A hyp.<name> value identifying one specific hypothetical reality, independent of universe and scenarioId — e.g. hyp.STRESS.
Scenario triplet	The three legs that fully define a scenario: market { world, universe }, portfolio { world }, strategy { world }.
Lane	The C# enum { Act, Hyp } backing the market/portfolio/strategy act/hyp designator (Virtufin.Core.Events.Lane).

Coalgebra/algebra abstractions

The "Behavior layer" (coalgebras — processes that evolve) and "Derivation layer" (algebras — values folded from a log); see Behavior Layer for the full treatment.

Term	Definition
Coalgebra	The category-theoretic shape for a stateful process that evolves (a strategy, an execution engine) — dual to an algebra.
F-algebra	(S, α) where α : F(S) → S is the fold/reduce; models how a Signal is derived from a log.
IProcess<TState, TInput, TOutput>	The generic coalgebra: (State, Input) → (State, Output), with the hidden state exposed explicitly rather than captured in a closure.
IDecide<TState, TMarket, TPortfolio, TAction>	Specializes IProcess<TState, (TMarket, TPortfolio), TAction[]> — the decide strategy trait.
IExecutor<TState, TAction, TEvent>	The coalgebra (TState, TAction) → (TState, TEvent) — the execute half of the trading loop.
IAlgebra<TEvent, TState>	The F-algebra shape: Apply(state, event) : TState, folds an event log into state; has an Initial state.
ISignal<T>	T Value { get; } — a continuously derivable value.
IIndicator<TSelf, TSample, TValue>	A self-folding, immutable ISignal<TValue> with TSelf Add(TSample sample); Add returns a new instance rather than mutating.
Corecursive	Describes the trading loop: fills feed back into Stream PositionEvent, making the loop a greatest fixed point rather than a finite pure pipeline.
Greatest fixed point	The trading loop's formal characterization — the maximal solution to its corecursive behavioral equations, arising from the fill→position feedback edge.
ProcessExtensions.Run	Drives an IProcess over an IObservable input stream via the scan combinator, folding from process.Initial or an explicit checkpoint. The coalgebra itself stays pure/pull-based; this is the opt-in reactive layer.
SignalExtensions.Map/Combine	Pure, lazy map/zip combinators over ISignal<T> — no folding of their own.
IndicatorExtensions.Map/Combine	The foldable counterparts over IIndicator<...>, returning small wrapper types (MappedIndicator, CombinedIndicator) that thread Add into the wrapped indicator(s).

Event domains and ADTs

Each domain has a marker interface, a sealed abstract record, and a Rich* companion ADT adding derived/attributed data under the same marker.

Term	Definition
MarketEvent	Sealed ADT implementing IMarketEvent; cases TickReceived, OrderBookReceived.
RichMarketEvent	Companion ADT adding derived signals CandleClosed, VWAPComputed, VolatilityEstimate, plus a Base(MarketEvent) pass-through.
PositionEvent	Sealed ADT implementing IPositionEvent; cases Opened, Updated, Closed, Flipped — the single unified stream driving all holdings changes, including cash.
RichPositionEvent	Companion ADT adding OpenedWithParty, UpdatedAttributed, plus Base.
TradeEvent	ADT TradeEvent : ITradeEvent<RichTradeAction>, 13 cases from OrderPlaced to InterestMatched, each carrying its originating action for correlation.
RichTradeEvent	Companion ADT adding FillAttributed, TransferAttributed, plus Base.
RiskEvent	Sealed ADT implementing IRiskEvent; cases PnLUpdated, PnLRealized, DrawdownUpdated, LimitBreached, LimitRestored, MarginWarned, MarginCalled, ExposureBreached.
RichRiskEvent	Companion ADT adding PnLAttributed, DrawdownWithMetadata, LimitBreachedWithThreshold, plus Base.
TradeAction	Sealed ADT implementing ITradeAction; cases BuyOrder, SellOrder, CancelOrder, TransferAction, InterestAction, WithdrawInterestAction — strategy intent, as opposed to TradeEvent's outcome.
RichTradeAction	Wraps each TradeAction case with strategy attribution, latency budget, and routing venue.
ITradeEvent<A>	Marker interface for trade events, parameterized by action type A : ITradeAction — statically forbids an executor from emitting events for the wrong action universe.

CloudEvents / envelope vocabulary

Events are transported as a real CloudNative.CloudEvents.CloudEvent (CloudEvents v1.0). Standard attributes carry id, source, type, subject, time, data; Virtufin's own vocabulary rides as extension attributes — the ratified pubsub-topics spec's Common Envelope Extensions. Built as fluent With* extension methods on the real CloudEvent in workmanager's Virtufin.Worker.DevKit (WorkerBase.cs, class CloudEventExtensions) — there is no separate lib-side envelope type or round-trip conversion.

Term	Definition
CloudEvent	The real CloudNative.CloudEvents.CloudEvent, CloudEvents v1.0, transport-agnostic.
ce-type	The CloudEvent type field — names the event (e.g. com.virtufin.trading.order.filled).
ce-subject	Set to <entity_type>/<entity_id> for events about a specific entity, enabling per-entity routing on a consolidated topic.
correlationid	UUID extension tying a fill back to its originating order. Copied input→output via WithCorrelationId.
scenarioid	Opaque-ID extension resolving to the full scenario configuration in the registry (LIVE for production).
runid	UUID extension disambiguating concurrent runs of the same scenario.
exchange	String extension naming the exchange (binance, …) — distinct from ce-source.
clocktype	wall | historical extension — how to interpret eventtime.
eventtime	RFC3339 extension, the logical event time (spec-defined as = ce-time), historical for replays — drives all domain logic (state folds, P&L).
walltime	RFC3339 extension, always the real wall clock at publish time — used only for audit trails, tracing, and late-arrival detection.
marketworld / marketuniverse	The world/universe legs for market.
portfolioworld	The world leg for portfolio.
strategyworld	The world leg for strategy.
replytopic	Extension attribute letting a request override the reply's ce-type.
publishtopic	Extension attribute letting a response publish to a topic other than its own ce-type; stripped before publish.
WorkerBase.BuildResponse	Constructs the standard CloudEvent fields (Id, Source, correlation, timestamp) that the With* extension methods then chain onto.

Topic naming scheme

Term	Definition
Tier 0 (infrastructure)	Scenario-agnostic topics matching <service>.<category> (e.g. workmanager.lifecycle). MAY carry only correlationid.
Tier 1	Every event requiring the full Common Envelope Extensions set — market-data-world and scenario-world events.
Market-data-world topic	Pattern act.exchange.<venue>.<entity>.<event>[.<id>] or hyp.<name>.exchange.<venue>... — data-universe-bound, shared across scenarios.
Scenario-world topic	Pattern sc.<scenarioId>.<domain>.<entity>.<event>[.<id>] — triplet-bound.
Cardinality Rule	Services SHALL prefer consolidated topics (per-entity routing via ce-subject) over one topic per entity, except where broker-level per-entity subscription is genuinely needed.
Delete-on-Deploy	Topic/state-key renames carry no deprecation window — old names are removed in the same commit as the new ones.

Execution / order vocabulary

Term	Definition
BuyOrSell	Enum { Buy, Sell } — side of a trade. Lives in Virtufin.Base.Orders.
Side	The standardized property name for a BuyOrSell-typed field (SimpleOrder.Side, IOrderLine.Side, InterestAction.Side).
LimitOrMarketOrder	Enum { LimitOrder, MarketOrder } — order-type discriminator. Lives in Virtufin.Core.Position.
SimpleOrder<U>	readonly record struct(Side, LimitOrMarket, Quantity: DecimalQuantity<U>) — a simple order combining side, execution type, and quantity. Lives in Virtufin.Base.Orders.
DeterministicExecutorBase	Abstract executor base with S = DeterministicState.Instance; pure, no IO effect.
SlippageExecutorBase	Abstract executor base with S = StochasticState(seed); models exchange behavior (e.g. slippage) via a seeded PRNG — reproducible given a fixed seed.
LiveExecutorBase	Abstract executor base with S = live API client state; makes real exchange API calls, not reproducible.
ObserveOnlyExecutor	Decorator wrapping another IExecutor; records outcomes (for SHADOW_* scenarios) without changing the inner executor's behavior.
IStochasticModel	Models one aspect of exchange behavior (slippage, latency, partial fills, queue position); composable into a pipeline, e.g. SlippageExecutor → LatencyExecutor → PartialFillExecutor.

Scenario configuration

Term	Definition
ScenarioId	Opaque readonly record struct ID (e.g. LIVE, S7F3A9B); LIVE is reserved for production.
IScenarioConfiguration	{ id, name, market: (Lane, selector?), portfolio: Lane, strategy: Lane } — a configuration of behavioral interpreters.
IScenarioRegistry	Get(ScenarioId), Register(config) — resolves scenario IDs to full configuration.
InMemoryScenarioRegistry	Registry implementation backed by Dictionary<ScenarioId, IScenarioConfiguration>.
StandardScenarios	Factory class with Live (pre-registered) plus PaperLive, Backtest, Shadow factory methods.
LIVE	Standard scenario: market=act, portfolio=act, strategy=act — production trading.
PAPER_LIVE	Standard scenario: market=act, portfolio=hyp, strategy=hyp — validates a strategy on live prices without real capital.
BACKTEST_*	Standard scenario family: market=hyp, portfolio=hyp, strategy=hyp — historical replay.
SHADOW_*	Standard scenario family: market=act, portfolio=act, strategy=hyp — observes a new strategy against a real portfolio without placing real orders.

Org / repo vocabulary

Term	Definition
API Gateway (api)	The only service permitted to talk to Dapr pub/sub and state directly on behalf of other services; pure infrastructure, no domain logic.
WorkManager (workmanager)	Event-driven, polyglot worker execution/management service; workers subscribe to Dapr pub/sub topics and process CloudEvents.
Virtufin.Worker.DevKit	The devkit package (published from workmanager) providing WorkerBase and the CloudEvent With* fluent extensions every worker-authoring devkit depends on. See the Worker DevKit.
DotNetDllEngine	WorkManager's default in-process worker execution engine for pre-compiled .NET DLLs — embeds CoreCLR via hostfxr, loads each worker into its own collectible AssemblyLoadContext.
NativeDllEngine	WorkManager's in-process engine for native workers, over a stable C ABI.
WebSocketManager (websocketmanager)	Service managing outbound WebSocket connections to exchanges; publishes connection lifecycle events. Pure infrastructure, no business logic.
virtufin-tui	Textual-based Python operator dashboard — a pure gRPC consumer of the API gateway; the kubectl of the Virtufin control plane.
Gitea	The org's self-hosted git/package registry (PyPI, npm, NuGet packages published here via CI).
Harbor	The Docker image registry used by the reusable Docker build workflow.
LIBRARY_VERSION / API_VERSION	The central version identifiers, defined once in each repo's versions.env, propagated to all downstream packages, Docker images, and docs by the shared CI tooling.