Skip to content

Pub/Sub Topics

Purpose

Canonical naming scheme for Dapr pub/sub topics and state keys across all Virtufin services: the naming library and its fragments, the routing taxonomy, the CloudEvents envelope contract, the state-key taxonomy, and the scenario axis.

Related specs: - Scenarios — scenario registry, triplet definition, LIVE bootstrap. - Cross-cutting — API-mediated pub/sub (envelope contract travels through the API gRPC). - Worker Management and WebSocket Feed — worker lifecycle events (sys.workmanager.worker.lifecycle), which also carry a WebSocketFeed's connection status, and the relayed venue frames. - Naming reference — every published naming fragment, composed and rendered.

Architecture

Two orthogonal routing axes plus a scenario-agnostic infrastructure axis:

Axis Pattern Scope Example
Market data world act.exchange.<venue>.<entity>.<event>[.<identity>] or hyp.<WORLD>.exchange.<venue>.<entity>.<event>[.<identity>] data-universe-bound; shared across scenarios act.exchange.binance.orderbook.update.BTC_USDT
Portfolio world act.portfolio.<venue>.<entity>.<event>.<account> or hyp.<WORLD>.portfolio.<venue>.<entity>.<event>.<account> one venue account; shared across scenarios act.portfolio.binance.balance.changed.main
Scenario world sc.<scenarioId>.<domain>.<entity>.<event>[.<identity>] triplet-bound (market + portfolio + strategy) sc.LIVE.trading.order.filled
Tier 0 / infrastructure sys.<service>.<entity>.<event> scenario-agnostic sys.workmanager.worker.lifecycle, sys.api.state.saved

Workers, request-reply and dead letters have their own scopes (wrk, rpc, dlq; Topic Patterns requirement); registry keys use cfg.

Rationale: - Market data is world-scoped because it depends on the data universe (live vs hypothetical replay) and is shareable across scenarios. Two paper runs sharing the same Binance feed do not double-publish ticks. - The venue-side portfolio is world-scoped for the same reason: an account's balances, holdings and ledger as the venue reports them are one fact, shared by every scenario whose portfolio leg uses that account. Portfolio workers observe only; the executors change the portfolio. - Trading / position / risk / pnl are scenario-scoped because each depends on the full triplet. P&L in particular is meaningless without knowing all three legs. - Tier 0 is scenario-agnostic because infra lifecycle (workers up, connections reconnecting) is a deployment concern, not a trading concern.

act and hyp.<WORLD> are both top-level world markers. act is the single actual reality (act.exchange.*); a hypothetical world carries a <WORLD> segment identifying which hypothetical reality is in play (hyp.BACKTEST.exchange.*). Bare hyp (no name) is never a valid topic segment — it denotes the category of all hypothetical worlds, not a specific one (see Scenarios spec §Named Hypothetical Worlds). The data universe (ALL, EQ_EUROPE, EQ_2008_2009, …) is not encoded in the topic — it travels in the marketuniverse CloudEvent envelope extension (see below) and on the producing WebSocketFeed worker's universe tag. The scenario triplet (market + portfolio + strategy legs) lives in the scenario registry.

Requirements

Requirement: Names Are Built by the Naming Library

Every pubsub topic, state key and CloudEvent type, subject and source SHALL be produced by the naming library: Virtufin.Naming (C#), virtufin-naming (Python) or @virtufin/naming (TypeScript), all published from lib. Code SHALL NOT assemble a name from string fragments. The three ports SHALL behave identically, which the shared conformance vectors (lib/naming/conformance/vectors.yaml) verify in each port's CI.

The library SHALL validate its arguments in the caller's process. This does not relax the "No Topic or Scenario-State Validation Anywhere" requirement: infrastructure (virtufin-api, WorkManager, Dapr) SHALL keep passing names through unchanged.

Scenario: Producer builds a topic

  • WHEN a worker publishes an order-book change for BTC_USDT on Binance
  • THEN it SHALL obtain the topic from the entity (book.Topic("changed", World.Act, pair)), not from string interpolation
  • AND the result SHALL be act.exchange.binance.orderbook.changed.BTC_USDT

Scenario: Invalid argument fails in the caller

  • WHEN a caller builds a name with an invalid value (a lowercase or unseparated pair, a missing world, an unknown event)
  • THEN the library SHALL throw NamingException (C#) or NamingError (Python, TypeScript) before anything is published or stored

Scenario: Infrastructure passes names through

  • WHEN virtufin-api receives a publish or state request
  • THEN it SHALL NOT parse or validate the topic or key against the naming library

Scenario: Ports agree

  • WHEN a naming change is made
  • THEN it SHALL land in all three ports and in the conformance vectors in the same lib release

Requirement: Segment Classes

Names SHALL be sequences of segments joined with .. Every segment SHALL belong to exactly one class, and the letter case SHALL identify the class: vocabulary is lowercase, identifiers are uppercase.

Class Alphabet Used for
vocab [a-z][a-z0-9-]* scope, domain, entity, event, venue, service, worker type, indicator instance
identifier [A-Z0-9_]{1,32} with at least one letter scenario, world, universe, strategy and world registry names
pair BASE_QUOTE, uppercase currency pair
guid lowercase canonical GUID worker, order, connection id
interval 1s 1m 3m 5m 15m 30m 1h 2h 4h 6h 8h 12h 1d 3d 1w 1mo candle interval
token [a-z0-9][a-z0-9-]* opaque lowercase id, e.g. a run id
any [A-Za-z0-9_-]+ experimental (x.) names only

A segment SHALL be at most 64 characters and a whole name at most 249 characters.

Scenario: Pair format

  • WHEN a currency pair appears in a topic, key or subject
  • THEN it SHALL be written BASE_QUOTE in uppercase (BTC_USDT), never in the venue's own form (BTCUSDT, BTC/USD, btcusdt)

Scenario: Reserved lowercase words cannot collide with identities

  • WHEN an entity has an index key <stem>.index
  • THEN its identity class SHALL NOT admit index; because identities are uppercase or GUIDs, an index key never collides with an instance key

Scenario: Multi-word vocabulary

  • WHEN an event, entity or worker type needs more than one word
  • THEN the words SHALL be joined with - (load-failed), never _ or a further .

Requirement: Name Derivation

Names SHALL be derived from an entity: a scope (the leading segments that are not part of the CloudEvent type), a path (vocabulary naming the entity), an identity (the segments identifying one instance), an entity type, and a set of events, each partitioned or not. Topic, key, subject and type of one entity SHALL therefore never disagree.

Name Rule
topic scope.path.event[.identity]; the identity only if the event is partitioned
state key scope.path.identity; all events of the entity share it
index key scope.path.index
ce-subject entity_type/identity
ce-type com.virtufin.path.event
ce-source urn:com.virtufin:<service>[:<instance>]; workers urn:com.virtufin:worker:<type>[:<worker_id>]
dead letter dlq.<topic>; dlq.pubsub is reserved (Dapr's Redis pub/sub has no dead-letter topic)
experimental x.<segments>, outside the contract

Identity segments SHALL be last: nothing follows them in a topic or key.

Scenario: Partitioned event

  • WHEN an order book for BTC_USDT changes on Binance in the actual world
  • THEN the topic SHALL be act.exchange.binance.orderbook.changed.BTC_USDT, the key act.exchange.binance.orderbook.BTC_USDT, the subject currency_pair/BTC_USDT and the type com.virtufin.exchange.binance.orderbook.changed

Scenario: Unpartitioned event

  • WHEN an order is filled in scenario LIVE
  • THEN the topic SHALL be sc.LIVE.trading.order.filled, the subject order/<order_id> and the key sc.LIVE.trading.order.<order_id>

Scenario: Pure event family

  • WHEN an entity declares no state (state: false), e.g. worker commands
  • THEN it SHALL have topics but no state key

Requirement: Naming Fragments

Names SHALL be defined in YAML fragments that live in the repo owning them (<repo>/naming/<fragment-id>.yaml) and ship with its packages: embedded under naming/ and packed under naming/ for NuGet, as package data under an entry point in the group virtufin.naming for Python. A fragment declares an id, the fragments it imports, and its patterns, entities, bindings (bind), venues and worker types, all written as combinator expressions (literals, typed segments, ref, optional, oneOf). There SHALL be no central list of names: the global catalog SHALL be generated from the published fragments.

Fragment Owner Defines
virtufin.core lib segment classes; the sys, wrk, rpc, cfg, dlq, x scopes; worker and reply families
virtufin.worlds domain-devkit the act/hyp.<WORLD> and sc.<SCENARIO> scopes; scenario, world and strategy registries
virtufin.market market-data-devkit venue-generic order book, candle, trade, instrument
virtufin.indicator indicator-devkit indicator values
virtufin.portfolio portfolio-devkit the venue-side account: snapshot, balances, holdings, ledger, open orders
virtufin.trading strategy-devkit (Trading.Contracts) a scenario's orders and trades
virtufin.positions portfolio-devkit a scenario's positions, P&L and risk; the P&L book key sc.<S>.pnl.book
virtufin.venue.<venue> market-data-devkit the venue, its symbol mapping, the market families bound to it, and the worker types of that venue's workers (in any repo)
virtufin.worker.<type> the worker's repo its worker type, for a worker not tied to a venue
virtufin.service.<service> the service's repo the service's sys.* and cfg.* names

worker-devkit is generic and SHALL own no fragment that names a business entity (nor any domain envelope attribute; see Common Envelope Extensions).

Scenario: Adding a venue

  • WHEN an order-book worker for a new venue (e.g. Alpaca) is added
  • THEN market-data-devkit SHALL add one fragment that declares the venue, binds virtufin.market/orderbook to it and declares the worker's type
  • AND the worker's repo SHALL NOT carry a copy of that fragment, and no central file SHALL change

Scenario: One owner, one copy

  • WHEN a repo needs a fragment another repo owns
  • THEN it SHALL load the fragment from the package that ships it and SHALL NOT keep a copy
  • AND it SHALL compose it so that a registry already holding an identical copy is accepted

Scenario: Conflicting fragments

  • WHEN two fragments could produce the same topic or key, and neither is a bind specialisation of the other, or two fragments declare the same venue or worker type
  • THEN composition SHALL fail and name both fragments
  • AND the specs site build, which composes every published fragment, SHALL fail with it

Scenario: Reference without import

  • WHEN a fragment references another fragment's pattern or entity without importing it
  • THEN composition SHALL fail

Scenario: Docs tables

  • WHEN a repo with a naming/ folder publishes its docs
  • THEN the docs workflow SHALL render the repo's families, keys, worker types and venues as tables (virtufin-naming render)

Requirement: Venue Symbols

Each venue fragment SHALL declare how the venue spells a pair (symbol: "{BASE}{QUOTE}", "{BASE}/{QUOTE}", optionally lowercase) and how it names intervals that differ from the canonical set (Binance 1M → 1mo). Workers SHALL accept configuration in the canonical forms only and convert at the venue boundary.

Scenario: Outgoing venue call

  • WHEN a worker configured with BTC_USDT subscribes to Binance
  • THEN it SHALL use the venue symbol BTCUSDT from the venue declaration

Scenario: Incoming venue message

  • WHEN a venue message carries BTCUSDT
  • THEN the worker SHALL map it to the canonical pair by looking it up among its configured pairs, because an unseparated venue symbol cannot be split on its own

Requirement: Topic Patterns

Services SHALL publish to and subscribe from topics produced by the naming library (Names Are Built by the Naming Library requirement). Every topic SHALL start with one of these scopes:

Scope Template Owner fragment
act act.<path>.<event>[.<identity>] virtufin.worlds
hyp hyp.<WORLD>.<path>.<event>[.<identity>] virtufin.worlds
sc sc.<SCENARIO>.<path>.<event>[.<identity>] virtufin.worlds
sys sys.<service>.<entity>.<event> virtufin.core, each service
wrk wrk.<worker_type>.<event>[.<worker_id>] virtufin.core, each worker
rpc rpc.<caller>.reply.<run_id> virtufin.core
dlq dlq.<topic> virtufin.core
x x.<segments> none (experimental)

cfg is a scope for keys only. This is not an enforced contract at the infrastructure: no service validates or rejects topics before publish -- see cross-cutting spec for why no enforcement point owns this check.

Scenario: Tier 0 / infrastructure topic

  • WHEN a service publishes a lifecycle or infrastructure event
  • THEN the topic SHALL match sys.<service>.<entity>.<event> (e.g. sys.workmanager.worker.lifecycle, sys.api.state.saved)
  • AND <event> SHALL name a kind of event (lifecycle, heartbeat, changed), not a state; the state travels in the payload

Scenario: Market data topic (real)

  • WHEN a service publishes real (live) market data
  • THEN the topic SHALL match act.exchange.<venue>.<entity>.<event>[.<identity>]
  • AND the data universe SHALL be carried in the marketuniverse envelope extension (ALL for unrestricted, EQ_EUROPE for a live subset) — it is not a topic segment

Scenario: Market data topic (hypothetical)

  • WHEN a service publishes hypothetical (replay / backtest) market data
  • THEN the topic SHALL match hyp.<WORLD>.exchange.<venue>.<entity>.<event>[.<identity>]
  • AND <WORLD> SHALL identify the specific hypothetical world (see Scenarios spec §Named Hypothetical Worlds) — bare hyp (no name) SHALL NOT appear in a topic
  • AND the data universe SHALL be carried in the marketuniverse envelope extension, independent of <WORLD> — the same universe MAY appear under different hypothetical worlds and vice versa

Scenario: Trading topic

  • WHEN a service publishes a trading-domain event (order lifecycle, trade lifecycle)
  • THEN the topic SHALL match sc.<scenarioId>.trading.<order|trade>.<event> (unpartitioned; per-order/per-trade routing via ce-subject -- see the Cardinality Rule requirement for why the entity ID does not appear in the topic)
  • AND <scenarioId> SHALL be either the reserved LIVE or a registered opaque scenario ID
  • AND ce-subject SHALL be set to order/<order_id> or trade/<trade_id> per the Common Envelope Extensions requirement

Scenario: Position topic

  • WHEN a service publishes a position-domain event
  • THEN the topic SHALL match sc.<scenarioId>.position.<event> (unpartitioned; per-pair and portfolio-aggregate routing via ce-subject)
  • AND ce-subject SHALL be set to position/<PAIR> for a per-pair event or position/portfolio for the aggregate snapshot

Scenario: Risk topic

  • WHEN a service publishes a risk-domain event
  • THEN the topic SHALL match sc.<scenarioId>.risk.<metric>.<event> (unpartitioned; per-pair routing via subject)

Scenario: P&L topic

  • WHEN a service publishes a P&L-domain event
  • THEN the topic SHALL match sc.<scenarioId>.pnl.<metric>.<event> (unpartitioned; per-pair routing via subject)

Requirement: No Topic or Scenario-State Validation Anywhere

No service — publisher, subscriber, virtufin-api's publish handlers, or any shared helper — SHALL validate a topic's shape against the patterns in this spec, or a scenario ID's registration/lifecycle status, before publish. Topic shape (universes, scenario IDs, venues, lifecycle status) is Virtufin domain vocabulary, and the infrastructure services (API, WorkManager) are pure infrastructure with no domain logic. The naming library validates the arguments of the caller that builds a name (Names Are Built by the Naming Library requirement); nothing downstream re-checks the result.

Scenario: Malformed or unregistered topic is published anyway

  • WHEN a service publishes to a topic that matches no pattern in this spec, or to an sc.<scenarioId>.* topic whose scenarioId is not registered (or is paused/archived/deleted)
  • THEN the publish SHALL proceed; the Dapr pub/sub component (pubsub.redis) is the only enforcement point, accepting whatever it considers a legal topic string
  • AND detecting and correcting a bad topic or stale scenario reference is a monitoring/observability concern (dead-letter, consumer-side logging), not a publish-time rejection

Requirement: CloudEvents Envelope

Every event SHALL be a CloudEvents v1.0 envelope. The CE base attributes (id, source, type, time, subject when applicable, specversion, datacontenttype) SHALL be carried as ce- prefixed metadata; data SHALL be the JSON payload. type, subject and source SHALL be derived by the naming library (Name Derivation requirement).

Scenario: ce-type format

  • WHEN a service publishes an event
  • THEN ce-type SHALL be com.virtufin.<path>.<event>: the topic without its scope and identity segments. Examples:
  • Tier 0: com.virtufin.workmanager.worker.lifecycle, com.virtufin.api.state.saved
  • Market data: com.virtufin.exchange.binance.orderbook.changed, com.virtufin.exchange.binance.candle.closed
  • Trading: com.virtufin.trading.order.filled
  • Position: com.virtufin.position.flipped
  • Risk: com.virtufin.risk.exposure.update
  • P&L: com.virtufin.pnl.realized.update
  • Indicator: com.virtufin.indicator.sma-20.changed
  • Worker: com.virtufin.httpget.response
  • AND a multi-word event SHALL hyphenate (load-failed), never use _

Scenario: ce-source format

  • WHEN a service publishes an event
  • THEN ce-source SHALL be urn:com.virtufin:<service> (e.g. urn:com.virtufin:workmanager, urn:com.virtufin:api)
  • AND a per-instance publisher MAY append the instance as a further segment (urn:com.virtufin:<service>:<instance>)
  • AND a worker SHALL use urn:com.virtufin:worker:<worker_type>[:<worker_id>]
  • AND the namespace and service SHALL be colon-separated, not dot-separated: urn:<NID>:<NSS> is the URN shape

Scenario: subject attribute (per-entity events)

  • WHEN a service publishes an event referring to a specific entity (order, trade, position, currency pair)
  • THEN ce-subject SHALL be <entity_type>/<identity> (e.g. order/<order_id>, position/BTC_USDT, currency_pair/BTC_USDT) — partitioned topics carry the same identity in both the topic and the subject
  • AND unpartitioned topics (trading, position, risk, pnl) SHALL use subject to enable per-entity routing without topic proliferation

Requirement: Common Envelope Extensions

Every Tier 1 event SHALL carry the following CloudEvents extensions, scoped by the event's axis. Tier 0 events MAY carry correlationid only. The generic legs (correlationid, eventtime, walltime, ingesttime) are provided by worker-devkit; the domain legs (scenarioid, runid, exchange, clocktype, marketworld, marketuniverse, portfolioworld, strategyworld) by domain-devkit (DomainEnvelope.Stamp on a derived event).

The scenario-bound extensions -- scenarioid, runid, portfolioworld, strategyworld -- apply to scenario-scoped Tier 1 events (sc.<scenarioId>.*) only. World-scoped market-data events (act|hyp.<WORLD>.exchange.<venue>.*) SHALL NOT carry them: market data is shared across scenarios (see Architecture), so no single scenario, run, portfolio or strategy owns it, and any value would be wrong for every other consumer.

Extension Type Required Notes
correlationid UUID Tier 1 yes; Tier 0 no Ties fills back to originating order across services
scenarioid string Scenario-scoped yes; market data no Opaque registry key; LIVE for production
runid UUID Scenario-scoped yes when parallel backtests; market data no Disambiguates concurrent runs sharing a scenario
exchange string Tier 1 yes (when applicable) Exchange name (binance, coinbase, …); distinct from ce-source
clocktype wall | historical Tier 1 yes wall for prod + paper; historical for backtest replay
eventtime RFC3339 Tier 1 yes (= ce-time) Logical event time matching clocktype; for derived events, inherited from the triggering event (see below)
walltime RFC3339 Tier 1 yes Always real clock at publish — for tracing / logging
marketworld act | hyp.<WORLD> Tier 1 yes Triplet leg (world) for market
marketuniverse string Tier 1 yes Triplet leg (universe) for market; present for both act and hyp.<WORLD> (use "ALL" for unrestricted)
portfolioworld act | hyp.<WORLD> Scenario-scoped yes; market data no Triplet leg for portfolio
strategyworld act | hyp.<WORLD> Scenario-scoped yes; market data no Triplet leg for strategy

CloudEvents extension attribute names are restricted to lowercase alphanumerics — no dots, no underscores. These four are deliberately concatenated (marketworld, not market.world or market_world) to satisfy that constraint, matching every other extension in this table.

Scenario: Envelope on a production fill event

  • WHEN a service publishes sc.LIVE.trading.order.filled (ce-subject = order/<order_id>)
  • THEN the CloudEvent extensions SHALL include scenarioid=LIVE, runid=<uuid>, correlationid=<uuid>, exchange=binance, clocktype=wall, eventtime=<rfc3339>, walltime=<rfc3339>, marketworld=act, marketuniverse=ALL, portfolioworld=act, strategyworld=act

Scenario: Envelope on a backtest fill event

  • WHEN a backtest engine publishes sc.S7F3A9B.trading.order.filled (ce-subject = order/<order_id>)
  • THEN the envelope SHALL include scenarioid=S7F3A9B, clocktype=historical, eventtime=<historical rfc3339> (the replayed tick's timestamp), walltime=<real rfc3339> (now), marketworld=hyp.BACKTEST, marketuniverse=EQ_2008_2009, portfolioworld=hyp.BACKTEST, strategyworld=hyp.BACKTEST
  • AND runid SHALL differ for concurrent backtests against the same scenario

Scenario: clocktype rationale

  • WHEN a strategy computes a time-series indicator (e.g. 20-period moving average) from a backtest stream
  • THEN it SHALL use eventtime (which is historical for backtests) to maintain correct indicator semantics
  • AND it SHALL use walltime only for tracing, logging, and alerting

Scenario: Envelope on a derived event

  • WHEN a worker publishes an event derived from a triggering event (an indicator value from a candle, an order from a market event, a trade event from an order)
  • THEN its eventtime SHALL be the triggering event's eventtime, else the triggering event's ce-time, else the current time, regardless of clocktype
  • AND its ce-time SHALL equal that eventtime, its walltime SHALL be the current time, and its clocktype SHALL be the triggering event's, defaulting to wall
  • AND it SHALL carry the triggering event's other common envelope extensions (correlationid, scenarioid, runid, exchange, the world and universe legs) unless the deriving worker sets them explicitly

Scenario: Envelope on a market data event

  • WHEN a service publishes a world-scoped market-data event, e.g. act.exchange.binance.orderbook.changed.BTC_USDT
  • THEN the CloudEvent extensions SHALL include exchange=binance, clocktype=wall, eventtime=<rfc3339> (the exchange's own event time, = ce-time), walltime=<rfc3339>, marketworld=act, marketuniverse=ALL
  • AND they SHALL NOT include scenarioid, runid, portfolioworld or strategyworld

Scenario: Envelope on a portfolio event

  • WHEN a service publishes a world-scoped portfolio event, e.g. act.portfolio.binance.balance.changed.main
  • THEN the CloudEvent extensions SHALL include exchange=binance, portfolioworld=act, clocktype=wall, eventtime=<rfc3339> (the venue's own time, = ce-time), walltime=<rfc3339>
  • AND they SHALL NOT include scenarioid, runid, strategyworld, marketworld or marketuniverse: an account is shared across scenarios and is not market data

Requirement: Trade Lifecycle Events

The trading domain SHALL model the lifecycle: submitted → accepted → (partially_filled →)* filled → cleared → settled. For Binance CEX, cleared and settled collapse to near-instantaneous but the events remain distinct for future DeFi / TradFi integration. Every event below publishes to a consolidated per-scenario topic (no <order_id>/<trade_id> topic segment); ce-subject carries the entity reference per the Common Envelope Extensions and Cardinality Rule requirements.

Scenario: Order submitted

  • WHEN a service submits an order to an exchange
  • THEN it SHALL publish sc.<scenarioId>.trading.order.submitted with ce-type = com.virtufin.trading.order.submitted and ce-subject = order/<order_id>
  • AND the data payload SHALL include order_id, symbol, side (buy|sell), type (market|limit), qty, price?, venue, submitted_at

Scenario: Order accepted

  • WHEN the venue acknowledges the order
  • THEN the service SHALL publish sc.<scenarioId>.trading.order.accepted with ce-subject = order/<order_id> and data venue_order_id, accepted_at

Scenario: Order rejected

  • WHEN an order is rejected by pre-trade risk or the venue
  • THEN the service SHALL publish sc.<scenarioId>.trading.order.rejected with ce-subject = order/<order_id> and data reject_reason, reject_source (risk|venue), rejected_at
  • AND an order that cannot be sent because it fails a venue's filters (it rounds to nothing, or falls below the minimum quantity or notional) SHALL be rejected this way with source risk, never dropped

Scenario: Order amended (mutation, not transition)

  • WHEN an order's price or quantity is changed in-place
  • THEN the service SHALL publish sc.<scenarioId>.trading.order.amended with ce-subject = order/<order_id> and data new_price?, new_qty?, amended_at
  • AND the order's status SHALL remain unchanged (pending or partially_filled)

Scenario: Order cancelled

  • WHEN an order is canceled by the user or system
  • THEN the service SHALL publish sc.<scenarioId>.trading.order.canceled with ce-subject = order/<order_id> and data canceled_at, canceled_by (user|system|venue)
  • AND an order that executed part of its quantity before it was canceled SHALL carry the cumulative qty_filled, the fill_id and the fees of its order.filled in this event too, because the two events travel on two topics and a consumer's inputs are ordered only within a topic; a consumer folds the quantity and its fees from whichever arrives first, once per fill_id

Scenario: Order expired

  • WHEN an order's time-in-force is reached without a fill
  • THEN the service SHALL publish sc.<scenarioId>.trading.order.expired with ce-subject = order/<order_id> and data expired_at
  • AND an order that executed part of its quantity before it expired SHALL carry qty_filled, fill_id and fees as an order that was canceled does

Scenario: Order filled (workhorse event)

  • WHEN a partial or full fill is received from the venue (Binance WebSocket fill callback)
  • THEN the service SHALL publish sc.<scenarioId>.trading.order.filled with ce-subject = order/<order_id> and data fill_id, qty_filled, price, fees, liquidity (maker|taker), remaining_qty, filled_at, realized_pnl? (optional, included if computed at fill time)
  • AND for partial fills, remaining_qty SHALL be the post-fill remaining quantity (decreasing across events)
  • AND fees SHALL state what the venue charged for this fill per asset, an object from asset to amount ({"BNB":0.02,"BTC":0.0005}): {} when nothing was charged, null only when the fee is unknown (a trade was missed, the source failed); assets charged nothing are left out, so one order may pay in several assets and every producer of a fill states the same object
  • AND a consumer folding holdings SHALL subtract the part of fees in the instrument's base asset once per fill_id, leave fees in any other asset alone unless it tracks that asset, and report an unknown fee rather than treat it as zero
  • AND when remaining_qty == 0, nothing more of the order will fill: it is implicitly fully filled (no separate order.completed event), or, when an order.canceled/order.expired follows, it ended with qty_filled as its final executed quantity

Scenario: Trade cleared

  • WHEN an order is fully filled and counterparty obligations are netted
  • THEN the service SHALL publish sc.<scenarioId>.trading.trade.cleared with ce-subject = trade/<trade_id> and data trade_id, order_id, cleared_at
  • AND this event SHALL fire exactly once per trade (not per fill)

Scenario: Trade settled

  • WHEN asset transfer for a trade is final
  • THEN the service SHALL publish sc.<scenarioId>.trading.trade.settled with ce-subject = trade/<trade_id> and data trade_id, order_id, settled_at, tx_hash? (null for CEX, populated for on-chain settlement)
  • AND for Binance CEX, cleared and settled SHALL be emitted back-to-back by the publisher
  • AND for DeFi / TradFi integration, the gap between cleared and settled may span minutes to days

Requirement: Position Lifecycle Events

Position state SHALL be derived from signed size plus a liquidation sub-state. position.flipped SHALL be a first-class atomic event because the risk engine needs direction-change awareness without a flat interval. Every event below publishes to a consolidated per-scenario topic (no <PAIR> topic segment); ce-subject carries the entity reference. Multi-word events hyphenate (liquidation-warning), so every position topic is sc.<scenarioId>.position.<event>.

Scenario: Who publishes position events

  • WHEN a strategy folds its own fills into its holdings (behaviour spec, Derived Portfolio State)
  • THEN no platform service SHALL be required to publish position events for a strategy to hold its positions
  • AND an absolute event is how a strategy leaves degraded (position or fee unknown) without being recreated: an operator MAY publish one as an external correction, and a reconciliation worker SHALL publish one only under Automatic Position Recovery (behaviour spec); BinancePositionReconciler (portfolio-workers) is the one worker that publishes position events

Scenario: Recovery event

  • WHEN a reconciliation worker recovers a strategy from a read of the venue
  • THEN it SHALL publish sc.<scenarioId>.position.opened for a holding above zero and sc.<scenarioId>.position.closed at zero, with source = External, avgEntry = 0 and realizedPnL = 0 (a spot balance has no cost basis, so these are no prices), the read's time as the event's time and in the asof extension (RFC 3339)
  • AND an event carrying asof is a recovery event, which a strategy treats per Automatic Position Recovery; an event without it is folded as before

Scenario: Position opened

  • WHEN a position is established (absolute: sets the holding)
  • THEN the publisher SHALL publish sc.<scenarioId>.position.opened with ce-subject = position/<PAIR> and data symbol, quantity, avgEntry, source, openedAt

Scenario: Position updated

  • WHEN a position grows or shrinks on the same side (absolute: newQuantity sets the holding)
  • THEN the publisher SHALL publish sc.<scenarioId>.position.updated with ce-subject = position/<PAIR> and data symbol, deltaQuantity, newQuantity, newAvgEntry, source, updatedAt

Scenario: Position updated, attributed

  • WHEN one fill's change is attributed to a strategy (delta: applied once per fillId)
  • THEN the publisher SHALL publish sc.<scenarioId>.position.updated-attributed with ce-subject = position/<PAIR> and data symbol, deltaQuantity, strategyId, fillId, updatedAt

Scenario: Position flipped (atomic direction change)

  • WHEN a position changes from long to short or vice versa in a single fill sequence (absolute)
  • THEN the publisher SHALL publish sc.<scenarioId>.position.flipped with ce-subject = position/<PAIR> and data symbol, newQuantity, oldDirection, newDirection, flippedAt
  • AND this event SHALL be atomic — no intermediate position.closed + position.opened sequence

Scenario: Position closed

  • WHEN a position returns to flat (absolute: zeroes the holding)
  • THEN the publisher SHALL publish sc.<scenarioId>.position.closed with ce-subject = position/<PAIR> and data symbol, closedAt, realizedPnL

Scenario: Reserved position events

  • WHEN a publisher considers increased, decreased, or an event below (liquidated, liquidation-warning, adjustment, snapshot)
  • THEN it SHALL NOT publish it to a strategy: these names are reserved, no strategy consumes them yet, and a strategy SHALL treat any position event it does not know as an error

Scenario: Position liquidated (forced)

  • WHEN a position is force-closed by the venue
  • THEN the service SHALL publish sc.<scenarioId>.position.liquidated with ce-subject = position/<PAIR> and data liquidation_price, realized_pnl, liquidated_at

Scenario: Liquidation warning (signal, not transition)

  • WHEN margin ratio crosses a warning threshold
  • THEN the service SHALL publish sc.<scenarioId>.position.liquidation-warning with ce-subject = position/<PAIR> and data margin_ratio, threshold
  • AND the position's primary state SHALL NOT change; only the liquidation_status sub-state becomes warning

Scenario: Position adjustment (corporate action)

  • WHEN a corporate action (split, dividend, symbol change) mutates a position's size or avg_price
  • THEN the service SHALL publish sc.<scenarioId>.position.adjustment with ce-subject = position/<PAIR> and data adjustment_type (split|dividend|symbol_change), new_qty, new_avg_price, corporate_action_id

Scenario: Portfolio snapshot

  • WHEN a full portfolio snapshot is published (consolidated)
  • THEN the service SHALL publish sc.<scenarioId>.position.snapshot with ce-subject = position/portfolio and data total_value, total_pnl, position_count

Requirement: Market Data Events

Market data events SHALL live under the world-scoped scopes (act.exchange.<venue>.* or hyp.<WORLD>.exchange.<venue>.*), as the entities of the virtufin.market fragment (market-data-devkit) bound to a venue by that venue's fragment (e.g. virtufin.venue.binance in market-data-workers). hyp carries one more segment than act (the <WORLD> slot); neither carries the data universe, which travels in the marketuniverse envelope extension. Every order-book event, trade.executed, candle.closed and instrument.snapshot SHALL be partitioned by pair, and so SHALL the raw feeds a WebSocketFeed worker serves: orderbook.update and trade.update per pair, candle.update per pair and interval (market-data-devkit 0.19.0; they were one topic for every pair), so a topic is the whole dependency of the worker that reads it (worker-management, Topic Dependencies). ticker.update, funding.rate and mark.price are reserved in the fragment and not produced yet.

Scenario: Order book snapshot

  • WHEN the venue publishes a full order book snapshot
  • THEN it SHALL be relayed on act\|hyp.<WORLD>.exchange.<venue>.orderbook.snapshot.<PAIR> (act omits <WORLD>), carrying the venue's own frame

Scenario: Order book update (delta)

  • WHEN the venue publishes an order book delta
  • THEN it SHALL be relayed on act\|hyp.<WORLD>.exchange.<venue>.orderbook.update.<PAIR> (act omits <WORLD>), carrying the venue's own frame; the WebSocketFeed worker serving the topic routes each frame to it (websocket-feed, Served Topics, Frame Publishing)

Scenario: Order book change

  • WHEN a service applies a snapshot or update-delta to a maintained per-pair local order book (see the State Keys requirement's "Order book state key" scenario)
  • THEN it SHALL publish act\|hyp.<WORLD>.exchange.<venue>.orderbook.changed.<PAIR> (act omits <WORLD>) with ce-type com.virtufin.exchange.<venue>.orderbook.changed and ce-subject currency_pair/<PAIR>, for every applied update
  • AND the data SHALL be the whole book as of that update as an order book image: FlatBuffers table OrderBook (market-data-devkit schemas/orderbook.fbs, identifier VFOB) with pair, last_update_id, event_time_unix_ns (the exchange's time of the last applied delta, 0 when unknown), price_precision, size_precision, and bids/asks with every level, best first, each level the DecimalAmount cardinals of price and size (value = cardinal / 10^precision)
  • AND datacontenttype SHALL be application/x-virtufin-orderbook+flatbuffers and dataschema urn:virtufin:marketdata:orderbook:v1
  • AND this event is the source of truth for the book at that update: a consumer acts on it alone; the order book state key holds a snapshot of the book for display and startup, written in the background and possibly older than the latest event

Scenario: Order book gap detected

  • WHEN a service maintaining a local order book detects a sequence gap (an update-delta's first update id doesn't bracket the book's current last_update_id) that it cannot resolve without a fresh snapshot
  • THEN it SHALL publish act\|hyp.<WORLD>.exchange.<venue>.orderbook.gap.<PAIR> (act omits <WORLD>) with ce-type com.virtufin.exchange.<venue>.orderbook.gap, ce-subject currency_pair/<PAIR>, and payload action (gap), reason (gap), pair, expected (the update id the book needed), got (the update id actually received), and event_time when known
  • AND it SHALL NOT overwrite the order book state key's cached value until a fresh snapshot resolves the gap -- a consumer that needs to know whether the cached book is currently fresh or stale SHALL subscribe to this topic rather than assume the state key alone reflects freshness

Scenario: Order book snapshot request

  • WHEN a pair's local order book is not live: it has no book yet (reason bootstrap, expected 0), a gap was detected (reason gap), or the book is still not live once the last request's backoff is over (reason retry: the request was lost, the fetch failed, or the snapshot did not bracket the buffered deltas)
  • THEN the gap event SHALL be the pair's snapshot request: the pair's snapshot fetcher (an HttpGet worker deployed with the venue's depth URL and replay=off) subscribes to the pair's gap topic and answers with an orderbook.snapshot; no timer polls snapshots
  • AND at most one request per pair SHALL be open: the next waits for a backoff that starts at 5 s and doubles up to 60 s while the pair stays out of sync, reset once the book is live, so a live book requests nothing and an out-of-sync pair at most one snapshot per minute
  • AND a restarted service SHALL restore a pair's instrument metadata from the instrument state key it saved, since instrument.snapshot is published once per run

Scenario: Raw trade and candle frames

  • WHEN a WebSocketFeed worker serves a pair's raw trades or a pair's candles at an interval
  • THEN it SHALL relay the venue's frames on act\|hyp.<WORLD>.exchange.<venue>.trade.update.<PAIR> and act\|hyp.<WORLD>.exchange.<venue>.candle.update.<PAIR>.<interval> (act omits <WORLD>)

Scenario: Public trade tape

  • WHEN a public trade occurs on the venue
  • THEN the service SHALL publish act\|hyp.<WORLD>.exchange.<venue>.trade.executed.<PAIR> (act omits <WORLD>) with ce-type com.virtufin.exchange.<venue>.trade.executed, subject currency_pair/<PAIR>, and payload trade_id, price, qty, side (buy/sell, the aggressor), trade_time

Scenario: Ticker update

  • WHEN a venue worker publishes 24h rolling stats (reserved: no worker produces them yet)
  • THEN it SHALL publish act\|hyp.<WORLD>.exchange.<venue>.ticker.update.<PAIR> (act omits <WORLD>) with last_price, volume_24h, change_24h_pct, and its venue fragment SHALL bind the reserved ticker entity

Scenario: Funding rate

  • WHEN a venue worker publishes a perpetual funding rate tick (reserved)
  • THEN it SHALL publish act\|hyp.<WORLD>.exchange.<venue>.funding.rate.<PAIR> (act omits <WORLD>) with funding_rate, next_funding_time

Scenario: Mark price

  • WHEN a venue worker publishes a mark price update (derivatives; reserved)
  • THEN it SHALL publish act\|hyp.<WORLD>.exchange.<venue>.mark.price.<PAIR> (act omits <WORLD>) with mark_price, index_price

Scenario: OHLCV candle

  • WHEN a candle interval closes
  • THEN the service SHALL publish act\|hyp.<WORLD>.exchange.<venue>.candle.closed.<PAIR>.<interval> (act omits <WORLD>) with ce-type com.virtufin.exchange.<venue>.candle.closed and ce-subject currency_pair/<PAIR>
  • AND the payload SHALL be JSON { symbol, interval, open, high, low, close, volume, windowStart, windowEnd }: symbol the canonical pair, prices and volume as JSON numbers, windowStart/windowEnd as RFC3339 (windowEnd is the candle's close time)
  • AND <interval> SHALL be the canonical interval (Segment Classes requirement), identical in the topic segment and the interval field; a venue's own interval name is mapped by its venue fragment (Binance 1M → 1mo)
  • AND the envelope SHALL be the world-scoped market-data envelope (Common Envelope Extensions requirement), with eventtime = ce-time = windowEnd
  • AND only closed candles SHALL be published: a still-open candle is not a fact yet

Scenario: Candle intervals are market data

  • WHEN a candle is aggregated over a standard venue interval
  • THEN it SHALL be published as market data under this requirement, whatever the interval (a 1d candle and a 1s candle are equally market data)
  • AND an aggregation over a non-standard, strategy-chosen window SHALL instead be an indicator (Indicator Events requirement)

Scenario: Instrument info

  • WHEN instrument metadata changes (lot size, tick size, status)
  • THEN it SHALL be published on act\|hyp.<WORLD>.exchange.<venue>.instrument.snapshot.<PAIR> (act omits <WORLD>)

Requirement: Portfolio Events

The venue-side view of a user account -- what the venue reports the account holds, not what the executors derived from their fills -- SHALL live under the world-scoped portfolio scopes (act.portfolio.<venue>.* or hyp.<WORLD>.portfolio.<venue>.*), as the entities of the virtufin.portfolio fragment (portfolio-devkit). <WORLD> is the portfolio world: act for a live account, hyp.<NAME> for a venue-backed paper or testnet account (e.g. hyp.PAPER for an Alpaca paper account). Every portfolio event SHALL be partitioned by the logical account name (lowercase vocabulary, e.g. main, paper), which is the last topic segment; ce-subject SHALL be account/<account>; the ce-type SHALL be com.virtufin.portfolio.<venue>.<entity>.<event>, the same for every account. The asset, symbol, ledger entry or order SHALL travel in the payload. Payloads SHALL be JSON with snake_case fields, decimals as JSON numbers and RFC3339 UTC times.

A portfolio worker SHALL observe only: it SHALL NOT place, amend or cancel orders. Order lifecycle (Trade Lifecycle Events) and the positions derived from fills (Position Lifecycle Events) remain scenario-scoped and owned by the executors. Reconciling the two views is a consumer's concern; the one consumer that publishes from it is a reconciliation worker, which holds no venue credential (behaviour spec, Automatic Position Recovery).

Scenario: Raw account frames

  • WHEN a WebSocketFeed worker relays a frame of an account's push stream (Binance user data stream, Alpaca trading stream)
  • THEN it SHALL be relayed on act\|hyp.<WORLD>.portfolio.<venue>.account.update.<account> (act omits <WORLD>), carrying the venue's own frame

Scenario: Account snapshot

  • WHEN a portfolio worker pulls the account from the venue (on start, after a reconnect, on a periodic trigger)
  • THEN it SHALL publish act\|hyp.<WORLD>.portfolio.<venue>.account.snapshot.<account> with ce-type com.virtufin.portfolio.<venue>.account.snapshot and payload { account, time, balances, holdings, open_orders }, each list holding the entries below; time SHALL be when the read began, the open orders SHALL be read before the balances, and balances SHALL hold every asset the venue lists, zero ones included (a zero proves an asset flat, a missing asset proves nothing)
  • AND it SHALL then publish only the changes since its previous snapshot (an asset gone as a zero balance, a holding gone as quantity zero, an order gone with status closed), never a replay of unchanged state

Scenario: Balance changed

  • WHEN an asset balance of the account changes
  • THEN the service SHALL publish act\|hyp.<WORLD>.portfolio.<venue>.balance.changed.<account> with payload { asset, free, locked, total } (total = free + locked)

Scenario: Holding changed

  • WHEN a holding (a position with the venue's cost basis and value) of the account changes
  • THEN the service SHALL publish act\|hyp.<WORLD>.portfolio.<venue>.holding.changed.<account> with payload { symbol, qty, avg_price?, market_value?, unrealized_pnl?, currency? }; a venue that reports balances only publishes none

Scenario: Ledger entry posted

  • WHEN the venue reports a movement of an asset on the account (deposit, withdrawal, transfer, fill, fee, dust conversion, dividend, interest)
  • THEN the service SHALL publish act\|hyp.<WORLD>.portfolio.<venue>.ledger.posted.<account> with payload { entry_id, kind, asset, delta, time, reference? }, kind one of deposit, withdrawal, transfer, fill, fee, dust, dividend, interest, other, and each entry published once

Scenario: Open order changed

  • WHEN the venue reports a change of an order on the account, whoever placed it
  • THEN the service SHALL publish act\|hyp.<WORLD>.portfolio.<venue>.openorder.changed.<account> with payload { order_id, symbol, side, type, qty, filled_qty, status, time, price?, client_order_id? }, status one of new, partially_filled, filled, canceled, expired, rejected, closed
  • AND this event SHALL NOT replace the executors' order.* events: it is the venue's view, for reconciliation and for orders placed outside Virtufin

Scenario: Portfolio state keys

  • WHEN a portfolio worker keeps the account's current state
  • THEN it SHALL use the keys act\|hyp.<WORLD>.portfolio.<venue>.<entity>.<account> for account (the latest snapshot), balance, holding and openorder; ledger entries have no state key, their history lives in the portfolio database

Requirement: Risk Events

Risk events SHALL be consolidated (one topic per metric). Per-symbol routing SHALL use ce-subject.

Scenario: Exposure update

  • WHEN risk greeks (delta / gamma / vega / theta) are recomputed
  • THEN the service SHALL publish sc.<scenarioId>.risk.exposure.update with greeks: { delta, gamma, vega, theta }, underlyings[]

Scenario: Spot exposure update

  • WHEN spot exposure is recomputed (a fill, or a new mark)
  • THEN the service SHALL publish sc.<scenarioId>.risk.exposure.update with ce-subject = position/portfolio and data by_symbol: { <PAIR>: { qty, mark, notional, share } }, gross_notional, net_notional, quote, where share = the symbol's notional / gross_notional
  • AND when the scenario's registry entry has limits (scenarios spec), each symbol SHALL carry limit and breached (true when its notional is above max_notional_per_symbol) and the payload gross_limit and gross_breached (max_gross_notional); a limit that becomes breached SHALL be published once as sc.<scenarioId>.risk.limit.breach (limit_name the limit's name, severity warning, subject pair/<PAIR> for a symbol's limit, position/portfolio for the gross one)

Scenario: Margin update

  • WHEN margin used or available changes
  • THEN the service SHALL publish sc.<scenarioId>.risk.margin.update with margin_used, margin_available, margin_ratio

Scenario: Drawdown alert

  • WHEN drawdown crosses a configured threshold
  • THEN the service SHALL publish sc.<scenarioId>.risk.drawdown.alert with drawdown_pct, threshold_pct, peak_value, current_value

Scenario: Limit breach

  • WHEN a configured risk limit is breached
  • THEN the service SHALL publish sc.<scenarioId>.risk.limit.breach with limit_name, limit_value, actual_value, severity

Scenario: Scenario P&L (stress test)

  • WHEN a stress / scenario P&L computation completes
  • THEN the service SHALL publish sc.<scenarioId>.risk.scenario.pnl with scenario_name, pnl, scenario_inputs

Requirement: P&L Events

P&L events SHALL be consolidated. The full triplet context is carried in the envelope (not the topic) because P&L is meaningless without it.

Scenario: Realized P&L update

  • WHEN realized P&L is recomputed (e.g. on fill or position close)
  • THEN the service SHALL publish sc.<scenarioId>.pnl.realized.update with realized_pnl, by_symbol: { <PAIR>: <pnl> }, period (daily|session|cumulative)

Scenario: Unrealized P&L update

  • WHEN unrealized P&L is recomputed (mark-to-market)
  • THEN the service SHALL publish sc.<scenarioId>.pnl.unrealized.update with unrealized_pnl, by_symbol: { <PAIR>: <pnl> }, mark_prices: { <PAIR>: <price> }

Scenario: P&L book

  • WHEN a P&L producer keeps a scenario's per-symbol book
  • THEN it SHALL save it at the state key sc.<scenarioId>.pnl.book (entity pnl_book, virtufin.positions) as { time, quote, symbols: { <PAIR>: { qty, avg_cost, mark?, realized_pnl, unrealized_pnl?, notional?, fees: { <asset>: <amount> }, fee_unknown } }, realized_pnl, unrealized_pnl, fills_folded }, decimals as JSON numbers, time RFC 3339 UTC

Requirement: P&L Worker

A generic P&L worker (portfolio-workers, no venue code) SHALL compute each configured scenario's P&L and spot exposure from the scenario's own trading events and the market world's order books.

  • Inputs: sc.<S>.trading.order.submitted (symbol, side, of each order_id) and sc.<S>.trading.order.filled; a fill SHALL be joined to its order by ce-subject order/<order_id>, and a fill whose order is unknown SHALL be held until the order arrives. The quantity of a canceled or expired order that executed part of it SHALL be folded from its order.filled, which carries the price. Marks: the order book changed events of the scenario's market world (<marketworld>.exchange.<venue>.orderbook.changed.<PAIR>) for the symbols it holds.
  • Fold per symbol: quantity (buys add, sells subtract), average cost (the quantity-weighted fill price of the open quantity, reset when the quantity crosses zero), realized P&L (on a reducing fill: reduced quantity × (fill price − average cost), sign by side), fees (in the quote asset when charged in it; a fee in another asset SHALL be kept per asset and not converted). Each fill SHALL be folded once (by fill_id).
  • Mark to market: the mark of a symbol SHALL be its book's mid; unrealized P&L = quantity × (mark − average cost); notional = |quantity| × mark.
  • Publish: on an input, at most once per publishintervalms (default 1000) and only when a fill or a held symbol's mark changed: sc.<S>.pnl.realized.update, sc.<S>.pnl.unrealized.update and sc.<S>.risk.exposure.update (P&L Events, Risk Events).
  • State: it SHALL save the book (P&L Events, P&L book) at sc.<S>.pnl.book with each publish, and what a restart needs (symbols, marks, orders, the fill ids folded, the fills held) in worker state, from which it SHALL continue on start; input replay across moves (worker management) SHALL NOT fold a fill twice.
  • Limits: it SHALL read the scenario's limits (scenarios, Scenario Limits) from cfg.scenario.<S> at start and again on each sys.api.state.saved of that key.

Scenario: A round trip

  • WHEN a scenario buys 2 BTC_USDT at 100, buys 2 at 110 and sells 3 at 120, with the book mid at 125
  • THEN the book SHALL hold quantity 1, average cost 105, realized P&L 45 and unrealized P&L 20

Scenario: Restart

  • WHEN the worker restarts
  • THEN it SHALL continue from sc.<S>.pnl.book and fold only fills not in it

Requirement: Tier 0 / Infrastructure Events

Tier 0 events SHALL be scenario-agnostic and SHALL use the sys scope: sys.<service>.<entity>.<event>. Each service SHALL define its Tier 0 entities in its own fragment (virtufin.service.<service>). The state of a lifecycle event SHALL travel in the payload, not in the topic or the ce-type.

Scenario: Worker lifecycle event

  • WHEN a worker changes state (registered, starting, online, degraded, stopping, stopped, failed, loaded, load-failed), is deleted (deleted), or its tags or code change (updated)
  • THEN the WorkManager SHALL publish to sys.workmanager.worker.lifecycle with ce-type = com.virtufin.workmanager.worker.lifecycle and ce-subject = worker/<worker_id>
  • AND the event SHALL carry state, worker_id, topic, and state-specific fields (error_type, error_message on a failure; libraries on loaded; changed and tags or codeurl on updated)

Scenario: New topics announced

  • WHEN the gateway's topic catalog gains topics
  • THEN the gateway SHALL publish com.virtufin.api.topic.catalog.added on sys.api.topic.catalog.added with {topics: [...]}, once per topic cluster-wide, best effort

Scenario: Trigger change events

  • WHEN ScheduleTrigger or DeleteTrigger succeeds
  • THEN the gateway SHALL publish com.virtufin.api.trigger.scheduled on sys.api.trigger.scheduled with the trigger's definition (name, schedule, duetime, repeats, ttl, targettopic, ownerworkerid), or com.virtufin.api.trigger.deleted on sys.api.trigger.deleted with name
  • AND like the state-change events these SHALL be best effort: a failed publish SHALL NOT fail the call
  • AND a trigger's firing SHALL stay on its target topic (com.virtufin.api.trigger.fired), never on these topics

Scenario: Worker metrics event

  • WHEN a worker pushes its counters (worker-devkit WorkerMetrics)
  • THEN it SHALL publish com.virtufin.<worker_type>.metrics on wrk.<worker_type>.metrics with ce-subject = worker/<worker_id> and data {workerid, counters: {name: integer}, at}, at most once per metricsseconds and only when the counters changed

Scenario: Connection lifecycle event

  • WHEN a WebSocketFeed worker's connection changes state (connecting, connected, reconnecting, disconnected, degraded, released)
  • THEN it SHALL be reported as a worker lifecycle event on sys.workmanager.worker.lifecycle with state = status, status = the connection state and detail (worker-management, Worker Lifecycle Events); there SHALL be no connection lifecycle topic

Scenario: Infra events (connection / worker detail)

  • WHEN a service publishes a finer-grained heartbeat for one of its entities
  • THEN it SHALL publish to sys.<service>.<entity>.heartbeat (the virtufin.service.workmanager fragment declares sys.workmanager.worker.heartbeat; it is not published today, and a connection, being a worker, has no heartbeat of its own)

Requirement: Cardinality Rule

Services SHALL prefer consolidated topics (one topic, per-entity routing via ce-subject) over per-entity topics (.<entity_id> segment). Per-entity topics SHALL be used only when a subscriber chooses one specific, known entity at subscribe time and the deployed pub/sub backend supports an exact-topic subscription for it. Per-entity topics SHALL NOT be used when a subscriber needs an unbounded or dynamically-appearing set of entities (e.g. every order in a scenario, every symbol in a portfolio) — that access pattern requires either a consolidated topic or genuine broker-level wildcard/pattern subscription support, and the currently-deployed Dapr pubsub component (pubsub.redis, Redis Streams) provides neither: its Subscribe/Publish implementation matches the topic string against a Redis Stream key exactly, with no pattern matching (confirmed by reading components-contrib/pubsub/redis/redis.go — XGROUP CREATE MKSTREAM <topic> and XAdd(ctx, req.Topic, ...) both treat <topic> as a literal key).

Scenario: Per-entity topic justified

  • WHEN a subscriber knows the specific entity ahead of time and subscribes to exactly that entity's topic (e.g., order book updates for one specific, chosen currency pair)
  • THEN the topic SHALL carry the entity ID segment (act.exchange.binance.orderbook.changed.<PAIR>)

Scenario: Consolidated topic preferred

  • WHEN a subscriber needs events for an unbounded or dynamically-appearing set of entities it cannot enumerate ahead of subscribing (e.g., all orders in a scenario, all symbols in a portfolio)
  • THEN the topic SHALL be consolidated (risk.exposure.update, sc.<scenarioId>.trading.order.filled, sc.<scenarioId>.position.opened) and ce-subject SHALL carry the entity reference (subject=position/BTC_USDT, subject=order/<order_id>)
  • AND this SHALL NOT be worked around with a broker-level wildcard subscription (e.g. sc.<scenarioId>.>) unless the deployed pub/sub backend is confirmed to support wildcard/pattern subscriptions -- it does not today (see the requirement description above)

Scenario: act and hyp carry no universe segment

  • WHEN a topic uses the act.exchange.<venue>.* or hyp.<WORLD>.exchange.<venue>.* pattern
  • THEN the hyp form SHALL have exactly one more segment than the act form (the <WORLD> slot)
  • AND the data universe SHALL NOT appear in either topic — it travels in the marketuniverse envelope extension, not as a topic segment
  • AND brokers and wildcard subscriptions SHALL NOT assume segment-count parity between the two forms — subscribe to act.exchange.* and hyp.*.exchange.* as two separate patterns rather than one shared positional pattern

Requirement: State Keys

State keys SHALL be derived like topics (Name Derivation requirement): scope.path.identity. The physical key is api||<key> because every write goes through virtufin-api's State service.

Owner Pattern Example
Service sys.<service>.<entity>[.<id>] sys.workmanager.worker.<worker_id>, sys.workmanager-runtime.worker.<worker_id>, sys.api.publication.fence.<worker_id>, sys.api.topic.catalog
Market data cache act\|hyp.<WORLD>.exchange.<venue>.<entity>.<identity> act.exchange.binance.orderbook.BTC_USDT
Scenario state sc.<scenarioId>.<path>.<identity> sc.LIVE.trading.order.<order_id>
Registry cfg.<registry>.<ID>, cfg.<registry>.index cfg.scenario.LIVE, cfg.scenario.index

Scenario: Order state key

  • WHEN a service writes order state
  • THEN the key SHALL be sc.<scenarioId>.trading.order.<order_id>
  • AND the value SHALL be JSON { status, side, type, qty, remaining_qty, avg_price, venue, created_at, updated_at }

Scenario: Trade state key

  • WHEN a service writes trade state
  • THEN the key SHALL be sc.<scenarioId>.trading.trade.<trade_id>
  • AND the value SHALL be JSON { status, order_id, cleared_at?, settled_at?, tx_hash? }

Scenario: Position state key

  • WHEN a service writes position state
  • THEN the key SHALL be sc.<scenarioId>.position.<PAIR>
  • AND the value SHALL be JSON { size, avg_price, realized_pnl, liquidation_status, updated_at }

Scenario: Portfolio state key

  • WHEN a service writes portfolio state
  • THEN the key SHALL be sc.<scenarioId>.position.portfolio (a lowercase literal, so it can never collide with a <PAIR> position key)
  • AND the value SHALL be JSON { total_value, total_pnl, position_count, updated_at }

Scenario: Indicator state key

  • WHEN a service persists a deployed indicator's current value (e.g. IndicatorWorkerBase in indicator-devkit)
  • THEN the key SHALL be sc.<scenarioId>.indicator.<name>.<PAIR> (e.g. sc.LIVE.indicator.sma-10.BTC_USDT)
  • AND the value SHALL be JSON { value, updated_at } (the indicator's own encoding of its current value, plus a write timestamp)
  • AND this key is scenario-scoped rather than market-data-cache-scoped (contrast the "Order book state key" scenario below): an indicator fed by scenario-specific replayed/synthetic data under hyp.* needs run disambiguation two concurrent backtests of the same pair would otherwise collide on — an order book has no such need, since it's a genuinely singular venue-level fact regardless of observer

Scenario: Trading halt key

  • WHEN a scenario's trading is halted or resumed (the kill switch)
  • THEN the key SHALL be sc.<scenarioId>.trading.halt (the virtufin.trading/halt entity)
  • AND the value SHALL be JSON { halted, reason, by, at } (Trading Halt)

Scenario: Worker state key

  • WHEN the WorkManager writes worker state
  • THEN the key SHALL be sys.workmanager.worker.<worker_id>, with the list of workers at sys.workmanager.worker.index
  • AND the value SHALL be the JSON worker record (id, code source, MIME type, topics, config, secret references, tags, status, code history)
  • AND the Runtime SHALL keep its own execution copy of the worker under sys.workmanager-runtime.worker.<worker_id>

Scenario: Connection state key

  • WHEN a worker writes its own state through its context (context.State), e.g. a WebSocketFeed worker its connection session
  • THEN the key SHALL be sys.workmanager.worker.<worker_id>.state.<key>, deleted with the worker
  • AND a WebSocketFeed worker SHALL keep its session there (sys.workmanager.worker.<worker_id>.state.session: publish topic, routing, replayed frames, attachments; never a credential)

Scenario: Order book state key

  • WHEN a service maintains a per-pair local order book (e.g. a WorkManager worker consuming the venue's update-delta and snapshot feeds -- not the WebSocketFeed worker that relays them, which is a generic, exchange-agnostic relay with no order-book logic of its own)
  • THEN the key SHALL be act\|hyp.<WORLD>.exchange.<venue>.orderbook.<PAIR> (act omits <WORLD>)
  • AND the value SHALL be JSON { bids, asks, last_update_id, updated_at }: a consolidated snapshot per venue + pair, for display and startup (updated_at is an RFC3339 timestamp of the last applied snapshot/update). It is not the source of truth for a live book -- the changed event is, written at most once per saveintervalms, so the key can trail the latest event
  • AND on a detected sequence gap the value SHALL NOT be overwritten until a fresh snapshot resolves it (see the Market Data Events requirement's "Order book gap detected" scenario) -- the key keeps serving the last known-good book rather than being cleared

Scenario: Scenario registry key

  • WHEN a service writes scenario metadata
  • THEN the key SHALL be cfg.scenario.<scenarioId>, with the registered scenarios listed at cfg.scenario.index
  • AND the value SHALL be the scenario triplet definition (see Scenarios spec)

Requirement: Source-of-Truth Rule

Each piece of derived or owned state SHALL have exactly one writer.

Scenario: Single publisher per status field

  • WHEN two publishers attempt to write the same status field on the same entity (e.g. both writing order.status)
  • THEN this SHALL be treated as a design bug — the entity has exactly one owner for status transitions
  • AND consumers SHALL treat the status field as monotonically advancing through the state machine

Scenario: Single owner per derived metric

  • WHEN multiple services could compute the same derived metric (e.g. portfolio total value)
  • THEN exactly one aggregator SHALL own the write; other services SHALL subscribe to the topic for read access

Requirement: Delete-on-Deploy (No Deprecation)

Topic and state-key renames SHALL NOT carry a deprecation window. Old names SHALL be deleted on the same commit that introduces new names.

Scenario: Rename lifecycle

  • WHEN a topic or state-key name is changed
  • THEN the change SHALL be a single commit per affected repo
  • AND old names SHALL be removed in the same commit (no parallel publishing under both names)
  • AND the change proposal that renames them SHALL list the old → new mappings

Requirement: Multi-Publisher Tier 2

Subscribers of Tier 2 (scenario-scoped) topics SHALL NOT assume single-source. A scenario topic MAY have multiple publishers (e.g., aggregator + per-leg publisher).

Scenario: Multiple publishers on same topic

  • WHEN two services publish to the same scenario topic (e.g., a strategy publishes order.filled and a replayer also publishes the same event during replay)
  • THEN consumers SHALL handle events from either source
  • AND ce-source SHALL identify the publishing service for filtering / dedup

Requirement: Run-ID in Envelope, Not Topic

Backtest replay and parallel scenarios SHALL NOT introduce run-id segments into topics. Run isolation SHALL be achieved via the runid envelope extension.

Scenario: Parallel backtests share topic

  • WHEN two backtests run concurrently against the same scenario (sc.S7F3A9B)
  • THEN both SHALL publish to sc.S7F3A9B.trading.*
  • AND each event SHALL carry a distinct runid extension
  • AND consumers that want a single backtest's events SHALL filter by runid

Scenario: Run-id dropped from topic

  • WHEN a service migrates from binance-depth.<run_id> to the new scheme
  • THEN the topic SHALL become act.exchange.binance.orderbook.update.<PAIR> (no run-id segment)
  • AND the run-id SHALL travel in the runid envelope extension (or be omitted for production traffic)

Requirement: Subscription Implementation Pattern

Dapr-based subscribe handlers in any Virtufin service SHALL open one Dapr subscription per topic per service process and fan out the resulting event stream in-process to every interested consumer within that process. Per-call Dapr subscriptions (one per gRPC call or one per caller) are PROHIBITED because they cause the same event to be silently load-balanced across callers instead of broadcast to each.

Scenario: Multiple callers on one topic

  • WHEN two gRPC clients subscribe to the same topic in the same API process
  • THEN each caller SHALL receive every message on that topic (true 1:many broadcast within the process)
  • AND the Dapr sidecar SHALL see exactly one subscription per topic per process

Scenario: Every replica receives every message

  • WHEN a topic is subscribed in several processes, e.g. two API replicas each serving a caller
  • THEN each process SHALL receive every message on the topic: the pub/sub component SHALL give every sidecar its own consumer group (consumerID: {podName} with Dapr's Redis pub/sub), not one group shared by an app's replicas
  • AND there SHALL be no competing-consumer layer: Dapr has no first-class broadcast (dapr/dapr#3332), so this per-sidecar group is how broadcast is achieved, and fan-out within a process stays the process's job

Scenario: New caller arrives

  • WHEN a third gRPC client subscribes to a topic that already has two subscribers in the same process
  • THEN the existing Dapr subscription SHALL be reused; the new caller's in-process handler SHALL be added to the fan-out list; no new Dapr subscription SHALL be opened

Scenario: Last caller leaves

  • WHEN the last gRPC client unsubscribes from a topic
  • THEN the in-process fan-out registration SHALL be removed and the Dapr subscription SHALL be kept for a linger (api PubsubSubscriptionLingerSeconds, default 10 s; 0 disposes it at once)
  • AND a caller that subscribes to the topic during the linger SHALL join that Dapr subscription, so a quick resubscribe never closes and reopens one (with Dapr's Redis pub/sub a closed subscription's leftover reader would take the topic's next message, common#28)
  • AND once the topic has had no caller for a whole linger, the Dapr subscription SHALL be disposed; subsequent callers SHALL open a new Dapr subscription on demand
  • AND messages published while the topic has no caller SHALL NOT be delivered to a later caller (no catch-up)

Scenario: New subscription starts at the stream tail

  • WHEN a service process opens a new Dapr subscription for a topic (no in-process subscription for that topic exists)
  • THEN it SHALL receive only messages published after the subscription opened -- no replay of entries still in the stream, and no redelivery of entries left pending by an earlier subscription
  • AND there is no catch-up: messages published while the process held no subscription for the topic SHALL NOT be delivered to it, including during the brief gap of a consumer reload; consumers that need continuity SHALL reconcile from state (e.g. an order book resyncs from its next snapshot)
  • AND with Dapr's Redis pub/sub (one consumer group per sidecar, consumerID: {podName}) the process SHALL move its own consumer group to the stream tail (the id of the stream's last entry, read first; 0-0 for an empty stream) and ack the group's entries pending up to that id before subscribing, because Dapr resumes an existing group at its last-delivered-id, creates a missing one at the stream start ("0"), and streamTTL trims only on publish
  • AND if the group cannot be positioned the subscribe SHALL fail rather than fall back to replay

Scenario: A closed subscription's reader takes a live message

  • WHEN a closed subscription's leftover sidecar reader (daprd leaves it blocked in XREADGROUP, common#28) takes a message published after the topic's current subscription opened, and abandons it unacked
  • THEN the process SHALL deliver that message to the current subscription within seconds (late and possibly out of order) and ack it, rather than drop it
  • AND an abandoned entry published before the current subscription opened SHALL still be acked without delivery (no catch-up)

Scenario: Subscription with replay_since

  • WHEN a caller subscribes with replay_since (a time) on the Redis backend
  • THEN the gateway SHALL first deliver every entry each topic's stream still retains from that time on (the stream's own clock), oldest first, read without moving any consumer group, and then the live messages, skipping a live message the replay already delivered (matched by CloudEvent id)
  • AND it SHALL refuse the subscription before sending its response headers with FAILED_PRECONDITION when the backend cannot read a stream's history and with OUT_OF_RANGE when a topic retains more than 1000 entries since then; replay is for low-rate topics (a worker's command topic), never for market data

Scenario: In-process exception on a subscriber

  • WHEN an in-process subscriber's handler throws an exception while processing a fanned-out message
  • THEN the broker SHALL continue delivering to the remaining subscribers (per-subscriber fault isolation)
  • AND the failed subscriber SHALL be logged but SHALL NOT cause the message to be re-delivered to the surviving subscribers

Requirement: Dead-Letter Policy on Subscribe Exceptions

Services that consume pub/sub messages SHALL NOT silently lose a message on an uncaught processing exception, and SHALL NOT retry it either: a message the handler fails on SHALL be dead-lettered once and the consumer SHALL go on with the next message. Where this is enforced depends on the consumption model:

  • A consumer of the streaming Pubsub.Subscribe gRPC API (see the "Subscription Implementation Pattern" requirement above) is one of potentially several in-process fan-out consumers per Dapr subscription; the Gateway acks Dapr's broker before any consumer processes the message, so broker-level redelivery is not available to it, and redelivering would double-process the other consumers. Such a consumer SHALL publish the original message, unchanged except for failure extensions, exactly once to dlq.<topic> (Name Derivation requirement) and SHALL NOT retry the processing or the dead-letter publish. The WorkManager Runtime does this for every worker (worker-management spec, "Worker Dead Letters").
  • The Gateway's own Dapr subscription is governed by the pub/sub component for messages its handler answers Retry on: with Dapr's Redis pub/sub the entry stays pending and is redelivered once pending processingTimeout, checked every redeliverInterval (helm pubsub.redis.*), with no retry limit and no dead-letter topic; the component SHALL set only keys its type reads. Drop SHALL be reserved for explicit business-logic skips (e.g., "no local worker registered for this topic"); it SHALL NOT be used to silently discard a message on an uncaught exception.

Scenario: Streaming-API consumer throws on a message

  • WHEN a consumer of the streaming Pubsub.Subscribe API throws processing a message on topic T
  • THEN the consumer SHALL publish the original message once to dlq.T, with no retry
  • AND the consumer's process SHALL NOT terminate and SHALL continue processing subsequent messages

Scenario: Dead-letter publish fails

  • WHEN publishing a dead letter fails
  • THEN the consumer SHALL log it at error level and continue; it SHALL NOT retry the publish or block the subscription

Scenario: Explicit business-logic skip

  • WHEN a handler determines the message is not relevant (e.g., no local worker on the topic) and explicitly chooses to skip it
  • THEN the handler MAY return TopicResponseAction.Drop and the message SHALL be acked with no redelivery and no dead letter

Scenario: Handler times out

  • WHEN a handler does not return within MessageHandlingPolicy timeout (default 30 s)
  • THEN the call SHALL be treated as a failure of that message, and the handler's process SHALL remain responsive

Requirement: State Change Events

virtufin-api's State RPCs publish a change notification when the caller opts in. Which topic that notification belongs on SHALL follow the tier the state belongs to, not the service that wrote it.

Infrastructure state — records whose owner is a platform service and whose meaning is deployment-scoped (worker registrations, connection records, leader leases) — SHALL use the Tier 0 topics sys.api.state.saved and sys.api.state.deleted, one per action.

Domain state — records that are scenario- or universe-scoped (positions, portfolios, orders, risk and P&L artefacts) — SHALL NOT use those topics. Its change notifications SHALL be published as ordinary Tier 1 events on the market-data or scenario axes, carrying the full Tier 1 envelope. Which service performed the write is an implementation detail; subscribers route on the domain topic and MUST NOT be required to track it.

The gateway cannot synthesise a Tier 1 event from a state write: it knows the store, key and value, but not the scenario, the world markers, the clock type, or the writing service's identity. A caller publishing a domain state change SHALL therefore supply the complete CloudEvent and its target topic, and the gateway SHALL publish it only after the write has succeeded.

Scenario: Infra state change

  • WHEN a service writes infrastructure state with change notification enabled
  • THEN the event SHALL be published to sys.api.state.saved for a save or sys.api.state.deleted for a delete
  • AND ce-type SHALL be com.virtufin.api.state.saved or com.virtufin.api.state.deleted, so a subscriber can filter by action on either the topic or the type without parsing the payload
  • AND ce-source SHALL be urn:com.virtufin:api, the publishing service

Scenario: Domain state change

  • WHEN a service writes scenario- or universe-scoped domain state with change notification enabled
  • THEN the caller SHALL supply the CloudEvent and its topic, matching the Tier 1 patterns in the Topic Patterns requirement (e.g. sc.<scenarioId>.position.snapshot)
  • AND the event SHALL carry the extensions required of every Tier 1 event by the Common Envelope Extensions requirement
  • AND the gateway SHALL publish it only after the state write succeeds
  • AND the gateway SHALL NOT additionally publish that change to sys.api.state.saved / sys.api.state.deleted

Scenario: Domain state change without a caller-supplied event

  • WHEN a caller enables change notification for domain state but supplies no CloudEvent
  • THEN the gateway SHALL publish to sys.api.state.saved / sys.api.state.deleted as for infra state
  • AND the resulting event is Tier 0 and carries no scenario or world markers, so subscribers cannot route it by scenario — the caller has opted out of the domain taxonomy, not into a degraded form of it

Scenario: State-name topics are not a substitute

  • WHEN a design would give each state its own topic (sys.api.state.saved.<state_name>)
  • THEN it SHALL be rejected: a Tier 0 topic names an entity and a kind of event, not a state, and per-key topics contradict the Cardinality Rule
  • AND domain state SHALL use the Tier 1 taxonomy instead, which already provides the routing such a design is reaching for

Scenario: Change payload

  • WHEN the gateway publishes to sys.api.state.saved / sys.api.state.deleted
  • THEN the payload SHALL carry service, the key (or keys for a bulk delete), and action (save / delete)
  • AND it SHALL carry value only when the caller set the include-value flag

Scenario: Tier 0 events carry no version

  • WHEN the gateway publishes a sys.api.state.saved or sys.api.state.deleted event
  • THEN it SHALL NOT claim a version for the written value: Dapr's state API returns no etag from a write, so the gateway cannot label the event with the version it just produced
  • AND it SHALL NOT re-read the key to obtain one — a concurrent writer may have advanced the value in between, which would attribute a newer version to an older payload and corrupt exactly the ordering the version exists to establish

Scenario: Event-carried state transfer on the Tier 0 topic

  • WHEN a subscriber uses a Tier 0 state-change event's value instead of reading the state back
  • THEN it SHALL treat the value as advisory: with no version there is no way to detect out-of-order delivery, so two rapid writes to one key may arrive reversed under redelivery and silently regress the subscriber
  • AND it SHALL do so only where writes to that key are known to be serialized, and SHALL read state back where correctness depends on freshness
  • AND a subscriber needing a stronger guarantee SHALL use the Tier 1 path below, where the caller controls the envelope

Scenario: Ordering on the Tier 1 path

  • WHEN a caller supplies a CloudEvent for a domain state change and subscribers consume its payload without reading state back
  • THEN the caller SHALL carry a monotonic ordering token for the entity in the event (a domain version, sequence number, or eventtime where the clock is authoritative)
  • AND subscribers SHALL discard any event not newer than the last processed for that entity
  • AND the token is the caller's to supply because only the caller knows the entity's versioning; the gateway has the key and the bytes and nothing that orders them

Scenario: Delivery guarantee

  • WHEN the state write succeeds and the subsequent publish fails
  • THEN the change event is lost: publication is at-most-once and is not atomic with the write
  • AND subscribers SHALL be designed to reconcile from state rather than assuming every change produced an event
  • AND the gateway SHALL NOT report the write itself as failed on account of a failed publish, since the write did land and reporting failure invites a caller to repeat it

Requirement: Indicator Events

An indicator deployed as a worker SHALL publish each new value as a scenario-scoped event, because an indicator is a tuned analytic owned by a scenario (behaviour spec, Glossary requirement), not a world-scoped market fact.

Scenario: Indicator changed

  • WHEN a deployed indicator folds a sample and has a new value
  • THEN it SHALL publish sc.<scenarioId>.indicator.<name>.changed.<PAIR> with ce-type com.virtufin.indicator.<name>.changed and ce-subject currency_pair/<PAIR>
  • AND <name> SHALL be the deployment's configured indicator name, built as Indicator Names requires, so two parameterisations of one indicator (sma-7x1m, sma-30x1m) publish on distinct topics
  • AND the payload SHALL be the indicator's own JSON encoding of its value, { value } for a scalar
  • AND the envelope SHALL follow the derived-event rule (Common Envelope Extensions requirement): eventtime inherited from the triggering sample, and scenarioid set to <scenarioId>

Scenario: Indicator value persisted

  • WHEN an indicator publishes a changed event
  • THEN it SHALL have saved the same value under the indicator state key (State Keys requirement) first, so a consumer that receives the event can read the matching state

Scenario: Indicator names

  • WHEN an indicator is deployed
  • THEN its name SHALL be <kind>-<parameter>: <kind> the indicator's kind as its worker names it (sma, entropy, logreturn, absolutereturn, relativereturn, range, tradeflow, bookimbalance), <parameter> its window with the unit it counts in
  • AND a window of candles SHALL be written <n>x<interval> (sma-20x1m: 20 one-minute candles), because the topic carries no candle interval and sma-20 on 1 s and on 1 m candles would otherwise share one topic
  • AND a window of time SHALL be written in seconds, one spelling per window (tradeflow-60s, tradeflow-300s, never 5m)
  • AND an indicator without a window parameter SHALL be its kind alone (bookimbalance)
  • AND the name SHALL be built by indicator-devkit's IndicatorNames (C#, Python), never by hand

Requirement: Cross-Topic Delivery Ordering

Consumers SHALL NOT assume any ordering guarantee between messages published to different topics. Per the Subscription Implementation Pattern requirement, each topic is its own independent Dapr subscription with its own dispatch loop; two topics' streams interleave in whatever order messages happen to arrive from the broker, not by publish wall-clock order. Ordering guarantees (if any) apply only within a single topic and are broker-dependent.

Scenario: Strategy worker's market and position feeds

  • WHEN a strategy worker subscribes to both a market-data topic and a position topic (see the multi-topic worker support in worker-management)
  • THEN a market event and a related position update MAY arrive in either order
  • AND a strategy that needs the two consistent with each other (e.g. "this candle's decision must see the fill it depends on") SHALL NOT assume the position update arrives first -- it must handle the out-of-order case itself (e.g. by re-evaluating on the next event) or accept the resulting staleness window

Scenario: No cross-topic sequencing infrastructure exists

  • WHEN a service needs strict ordering between events on two different topics
  • THEN it SHALL implement that ordering itself (e.g. via a sequence number in the envelope, or by consolidating both event kinds onto one topic) -- the platform provides no built-in mechanism for it

Requirement: Ingest Time

A frame relayed from an exchange connection SHALL carry the CloudEvents extension ingesttime (RFC3339): the real clock when the frame was received off the connection, taken before any routing or queueing. A world-scoped market-data event derived from such a frame SHALL carry the triggering frame's ingesttime unchanged. ingesttime is optional for every other event.

Scenario: Relayed frame

  • WHEN a WebSocketFeed worker publishes a frame it received off its connection
  • THEN the event SHALL carry ingesttime = the receive time, and its ce-time SHALL remain the publish time

Scenario: Derived market-data event

  • WHEN a venue worker publishes an order-book changed event for a frame carrying ingesttime
  • THEN the event SHALL carry the same ingesttime, so that eventtime to ingesttime measures the exchange and the network, and ingesttime to walltime measures the pipeline from receiving the order-book diff to publishing the new book

Scenario: No ingest time

  • WHEN the input of a market-data event carries no ingesttime
  • THEN the event SHALL NOT carry one