Event Ordering & Partitioning

Ordering is guaranteed only within a partition, so partition keys are chosen to keep causally-related machine events on one ordered stream.

Ordering is a per-partition guarantee

The event log guarantees total order within a partition, not across partitions. Choosing the partition key is therefore a correctness decision: any two events whose relative order must be preserved must share a key. Get this wrong and a consumer may see a coil setpoint applied before the measurement that justified it.

Key selection on the machines

• Breeder magnetics: key by coil-set, so each coil's setpoint and current history is totally ordered.
• Breeder equilibrium and shot events: key by shot_id, so a shot's timeline is one ordered stream.
• Burner plug/throat: key by mirror-cell, so a cell's field history is ordered.
• Commands: key by actuator_id with single-writer, so an actuator's command sequence is unambiguous.

Cross-partition ordering needs event time

When a consumer must merge streams from different partitions (for example, correlate breeder magnetics with plasma density during a disruption), it cannot rely on arrival order. It orders by the event-time field in the envelope and uses watermarks to know when it has seen enough to emit a correct merged result.

same key      -> same partition -> total order (safe to assume causality)
different key -> different partition -> merge by occurred_at + watermark
rule: if order matters for correctness, co-locate on one key

Partition count and parallelism

Partition count sets the maximum consumer parallelism. Too few and a burst on one key becomes a bottleneck (see backpressure); too many and cross-partition merges get harder. The count is sized to the peak per-key event rate during a breeder disruption or burner transient, the worst case.

Rebalancing safely

When consumers are added or removed, partitions rebalance. Handlers are idempotent (see idempotency) and commit offsets atomically so a partition reassigned mid-processing does not double-apply an event. Ordering within each partition is preserved across the rebalance.