All research Research note 02

Exactly-once effects for agents

Fibric ResearchEffects6 min read

Distributed systems have spent decades getting "exactly once" right. Almost all of that work assumes the effects live inside systems you control, where a mistake can be rolled back. An agent's effects land in the physical world, where a sent message stays sent and an opened door stays open. This is how we extend the idea past the edge of the screen.

The comfortable version of the problem

Engineers who have built payment systems or message queues know the shape of exactly-once delivery well. A producer sends a message. The network may drop the acknowledgement. The producer retries. Without care, the consumer processes the message twice. The standard cure is a deduplication key plus idempotent processing: the consumer remembers which keys it has seen and refuses to process the same one twice. Done right, the effect happens exactly once even though the message may arrive many times.

There is an important honesty in the literature here: true end-to-end "exactly-once delivery" is, strictly, impossible in an asynchronous network with failures. What systems actually achieve is exactly-once processing or exactly-once effect, built from at-least-once delivery plus idempotent, deduplicated handling. The retry still happens. The duplicate still arrives. The effect happens once. That distinction is the whole game, and it is the version that matters for agents.

You cannot guarantee a message is delivered exactly once. You can guarantee its effect happens exactly once. For an agent acting on the world, the effect is the only thing that matters.

Why the agent case is harder

The comfortable version assumes the deduplicated effect is something inside your own systems: a row written, a balance updated, a record marked processed. If something goes wrong, you can usually compensate, reverse the row, refund the balance, because you own both ends.

An agent breaks that assumption. Its effects are actions on the real world, and the real world does not have a rollback. Consider the ladder of reversibility an agent's actions actually live on:

The effect

What "undo" means in the real world

Write a status row

Fully reversible. Delete or correct the row.

Place an order on hold

Reversible, but the hold may have already changed someone's plan.

Send a customer a message

Not reversible. They have read it. A correction is a second message, not an undo.

Unlock a door

Not reversible. The moment of access already happened.

Once an effect is irreversible, "we will compensate if it goes wrong" stops being a safety net. The only acceptable guarantee is that the effect never happens more than intended in the first place. Prevention is the entire strategy, because there is no cure.

How Fibric extends idempotency to the edge

Fibric treats every real-world action as an effect that must happen exactly once, and builds the guarantee from the same two primitives the distributed-systems world proved out, pushed all the way down into the executor that performs the action.

An idempotency key on every effect. The key is derived from what the action is: this notification, for this order, about this event. Not from when it ran. The first time the key is seen, the effect is performed and the result recorded. Every subsequent time, the recorded result is returned and the effect is not repeated.
Single-flight per entity. At most one action against a given entity is in flight at a time. The retries that drive duplication in the first place cannot fan out into parallel effects against the same thing.

Together these give the agent permission to be naive about failure. It can retry as aggressively as a flaky network demands, because the retry cannot turn into a second real action. The deduplication and the serialization are not the connector's responsibility and not the operator's; they are the kernel's, below every action, so no integration can forget them.

The boundary, and the receipt

There is a clean line in Fibric between proposal and effect. The model proposes a plan; a deterministic executor disposes. The idempotency key is assigned at that boundary, on the deterministic side, where the same proposed action always resolves to the same key. This is what makes "exactly once" hold even across a crash: if the executor restarts mid-action, the resumed attempt carries the same key, finds the effect already settled, and does not repeat it.

And because every effect is keyed and recorded, the prevention is visible. When a duplicate is caught, that is itself logged. The receipt does not just show what happened; it shows what was stopped from happening twice. For an irreversible action, that record is the difference between a system you can audit and a system you have to trust.

What we are still working on

The hard frontier is keys for effects whose identity is fuzzy. "Notify the customer about a delay" is easy to key. "Adjust the setpoint to keep the room comfortable" is a continuous intent, not a discrete event, and reasonable people can disagree about when two adjustments are "the same" effect. We model these as single-flight intents per entity rather than keyed one-shot effects, but getting the boundary right, between a fresh decision and a duplicate of an old one, is open work, and we would rather be conservative and re-decide than risk a repeat.

Grounding

Exactly-once semantics in distributed messaging: at-least-once delivery plus idempotent, deduplicated processing yields exactly-once effects.
The impossibility of true exactly-once delivery in asynchronous networks, and why "exactly-once effect" is the achievable, useful target.
Idempotency keys in payment and API design: deriving a stable key from the action's identity so retries are safe.
Single-flight / request coalescing: collapsing concurrent duplicate work against the same entity into one.

Get early access → All research