6. Delta Events and Event-Carried State Transfer Coexist

Why core services publish both business (delta) events and state-transfer (ECST) events, and how players should use them.
  • Status: accepted
  • Date: 2025-12-05
  • Deciders: Jannik Alexander, Stefan Bente, Daniel Köllgen (governance board)

Context

Core services publish two kinds of events for their aggregates:

  • Delta events (business events, bl.* topics): what happened, e.g. robot.moved or credits-deposited.
  • Event-carried state transfer (ECST, db.*.ecst.* topics): the full current state of an entity after a change, e.g. robot.state-transfer.

After a discussion on Discord, the board had to decide whether both should exist side by side. Players need reliable state (where robots are, how many credits they have) as well as triggers to react to. Core services need a simple way to replicate each other’s data (e.g. Robot keeps a copy of the map). And the design must be explainable to students.

Decision

  • Core services SHOULD publish delta events on bl.<aggregate>.events.v<n> and ECST events on db.<aggregate>.ecst.v<n> (see ADR-0005).
  • Consumers SHOULD NOT mix both kinds for the same entity: state for an entity is built from one kind only.

Alternatives

  • Delta events only — rejected because consumers must apply every delta in order to know the current state, and cannot easily recover from a missed event.
  • ECST events only — rejected because the reason for a change is lost; consumers must diff states to detect what happened.

Consequences

  • Good: players can build a consistent local view from ECST without interpreting every delta.
  • Good: delta events keep the meaning of a change visible, which reactive player logic needs.
  • Good: core services replicate other services’ data by consuming ECST topics.
  • Bad: producers publish two events per change and must keep them consistent (both through the same outbox transaction, see ADR-0008).
  • Bad: beginners must understand two event styles before choosing; mixing them wrongly causes subtle inconsistencies.
Last modified October 22, 2026: Update documentation (f481966)