Idempotency & Deduplication

Retries are inevitable on a distributed control plane; idempotency keys make a repeated write or command harmless.

The retry problem

Networks partition, processes restart, and producers time out and retry. Without protection, a retried write duplicates a breeder magnetics sample or, catastrophically, re-issues a burner neutral-beam command. Layer 4 makes every producer and every command handler idempotent: applying the same operation twice yields the same state as applying it once.

Idempotency keys

Each event carries an idempotency_key derived from the semantic identity of the operation, not from wall-clock time. The backbone and each stateful consumer keep a bounded dedup window keyed on it. A duplicate is silently absorbed.

def handle(cmd):
    # dedup on semantic identity, not arrival time
    if store.seen(cmd.idempotency_key):
        return store.result_of(cmd.idempotency_key)   # same answer, no re-apply
    result = apply(cmd)
    store.record(cmd.idempotency_key, result, ttl=DEDUP_WINDOW)
    return result

# breeder coil setpoint: key encodes what, not when
# key = f"coil:{coil_id}:shot:{shot_id}:step:{step}:setpoint:{value_hash}"

Commands vs measurements

• Measurements: dedup prevents double-counting in twin inputs and diagnostics.
• Commands: dedup prevents double-actuation, the safety-critical case on both machines.
• Compensations (see sagas): must themselves be idempotent so a retried rollback does not overshoot.

Window sizing

The dedup window must exceed the maximum retry horizon plus the maximum consumer lag, or a late duplicate slips through. It is bounded so state does not grow without limit. Keys older than the window are safe to forget because the backbone's offset commits guarantee they will not be re-delivered from before that point.

Idempotency is the precondition for the stronger delivery-semantics guarantees: at-least-once delivery plus idempotent handling is how the stack achieves effectively-once processing without a distributed transaction on the hot path.