Idempotent Message Identity

• NATS: `Nats-Msg-Id`, duplicate window.
• The pattern language: Idempotent Receiver.

At-least-once delivery means a message can arrive twice: a durable consumer redelivers an unacknowledged message, and a publisher retries an unacknowledged send. Both are correct behaviour that the receiver must survive.

How does a receiver do the work once when the same message may reach it two or more times?

• The transport guarantees at-least-once, never exactly-once.
• The work is often a write, which is not naturally repeatable.
• The receiver may see the repeat minutes later, on another replica.
• A server-side deduplication window is bounded in time; the receiver cannot rely on it alone.

Give the message a stable identity derived from the work, and make the write idempotent on it. Two mechanisms are available and they compose:

// 1. The identity the server can dedupe on: Nats-Msg-Id on a JS publish.
std::unordered_map<std::string, std::string> hdrs{
    {"Nats-Msg-Id", std::string(step_id)}};
nats.js_publish(subject, payload, hdrs);

// 2. The receiver's own guard, which outlives the server's window.
if (store.has_completed(step_id))
    return;                       // already done: discard the duplicate
store.record_completion(step_id, result);

Three rules:

• The identity comes from the work, not the send. A fresh id per attempt defeats the pattern.
• The receiver's own guard is authoritative. `Nats-Msg-Id` and the server's duplicate window help, but the window is finite and a redelivery may fall outside it, so the receiver must be able to recognise a repeat itself.
• The guard is checked in the same transaction as the write. A check followed by a separate write is a race between two replicas.

• An identity generated at send time. Each retry looks like new work.
• Relying on the server's duplicate window alone. A repeat outside the window is applied twice.
• A check and a write in separate transactions. Two replicas both pass the check.
• Treating a duplicate as an error. It inflates the error rate for correct transport behaviour and hides the real failures.

Benefits

At-least-once delivery becomes effectively-once processing without the transport pretending to guarantee it.

Liabilities

The receiver must store the identity of completed work, which is durable state it would not otherwise need.

Both mechanisms are in use, on the messages that have an identity of their own.

The publisher side. `ores::nats::headers::with_publish_identity()` adds the `Nats-Msg-Id` header, and does nothing when handed an empty identity, so a message with no identity of its own is published without one rather than under a shared value. It is set from the work's own identifier:

A market tick and a liveness notice carry none: two ticks are genuinely two messages, and deduplicating them would discard real data.

The receiver side. Each durable consumer already holds its own guard, which is the authoritative one because the stream's window is finite:

• IAM's provisioning step reads the step's recorded outcome before doing the work and replays it rather than repeating it.
• The engine's step-completed handler treats an event for a step that is no longer in progress as a duplicate and keeps the state it recorded.
• The engine's start handler recognises a start for a run that already exists and leaves the run alone.

One limit is worth stating: a guard that reads and then writes is not atomic against two deliveries running at once on different replicas, so a redelivery that overlaps the original is still possible. Closing that needs a claim in the store rather than a header, and the step's own record is the natural place.

• Commit Through the Stream — the send that may be retried.
• Acknowledge What Was Handled — the redelivery this pattern absorbs.

• NATS documentation, Advanced publishing — `Nats-Msg-Id` and the duplicate window.
• Gregor Hohpe and Bobby Woolf, Enterprise Integration Patterns, Addison-Wesley, 2003, Idempotent Receiver.

• NATS service patterns — the structure note that orders this pattern language, and where to read this page in it.