One action per entity, even on a bad day
Retry storms, webhook replays and racing workers are normal distributed-systems failure modes. Single-flight can serialize work for an entity inside a governed runtime. It does not collapse distinct intents, external writers, or an ambiguous downstream outcome into one provable effect.
Every operational system eventually has a bad day. A partner API times out and its client retries. A webhook provider replays an hour of events after an outage. Two operators, each reasoning correctly from slightly stale state, both decide the same order needs a refund. None of these are bugs in anyone’s code. They are what distributed systems do under stress, and any platform that acts on the real world has to decide, in advance, what happens when three well-formed requests to do the same thing arrive at once.
The reference kernel uses single-flight per entity to serialize governed work for an entity inside one runtime. A matching concurrent attempt may join an existing flight, while a distinct intent waits for revalidation. External writers and processes outside the lock boundary are not covered.
What “collapse” means, concretely
The word we use internally is collapse. Duplicates do not get rejected with errors that callers then retry into a storm; they converge. Here is the shape of a bad five minutes, as the kernel sees it:
Operator proposes a refund on order 4471 after a failed shipment signal.
The webhook that triggered it replays ninety seconds later. Same entity, same proposal.
A second operator, reading state cached before the first flight resolved, proposes the same refund.
Matching attempts converge before dispatch; a distinct intent waits for revalidation. The external refund outcome still depends on the payment system.
Centralizing the lock reduces duplicated concurrency logic. The payment connector still owns downstream semantics, idempotency support, reconciliation, and ambiguous-result handling.
An order, a door, a thermostat
Single-flight matters differently depending on what the entity is, which is exactly why it has to live below the connectors rather than inside any one of them.
For an order, the failure mode is financial. BearScope is live on governed CX and commerce data, but its current BFF does not route through the generalized kernel described here. Any refund path must be verified separately against downstream idempotency and reconciliation behavior.
For a door, the failure mode is physical and stateful. A governed lock can serialize Fibric attempts, but independent access-control commands, device state, and read-back still determine the actual outcome. Life-safety and access systems must remain authoritative.
For a thermostat, the failure mode is oscillation. The hotel example is illustrative; a real BACnet deployment would need bounded authority, read-back, commissioning evidence, and control-system safeguards in addition to single-flight.
Why the kernel, not the connector
Making single-flight a kernel primitive gives governed connectors a common concurrency control. Combined with a stable idempotency key, it can suppress matching attempts within the boundary. It does not merge distinct intents, cover external writers, or prove an unknown downstream effect.
The bounded promise is narrower: matching governed attempts should not dispatch concurrently, and settled duplicate keys should return the recorded result. Connector-specific evidence decides what can be said about the world beyond that boundary.
Keep reading: Idempotency is a kernel primitive · The executor doesn't reason