Context
BSFG must tolerate retries, partitions, reconnects, and duplicated delivery attempts without producing ambiguous fact history. Producers need a retry-safe append contract. Consumers and operators need a precise definition of what confirmation means at the boundary layer.
JetStream supports publish acknowledgement once a message has been stored, and supports message deduplication using a message ID header within a dedupe window. Consumers separately track delivery acknowledgements. :contentReference[oaicite:0]{index=0}
BSFG must define a stronger, transport-local meaning for both idempotency and confirmation than “some downstream consumer eventually processed it.”
Options Considered
| Option | Description | Benefits | Drawbacks |
|---|---|---|---|
| Reject all duplicate IDs | Any repeated message_id is treated as an error. |
- simple rule
- no lookup of existing payload needed
|
- unsafe for producer retries
- network ambiguity becomes operational pain
- weak resilience under partition/reconnect
| | Allow duplicate appends | Every retry appends a new record; dedupe is pushed downstream. |
- simplest append path
- minimal broker-side logic
|
- ambiguous audit history
- consumer-side dedupe required everywhere
- weak compliance posture
| | Business-level confirmation | Confirmation means a consumer processed and accepted the fact semantically. |
- matches application meaning closely
- useful for workflow orchestration
|
- couples transport to domain logic
- confirmation becomes non-uniform
- not a boundary-layer invariant
|
| Idempotent append + durable commit confirmation (Selected) | Repeated message_id with identical content returns the original durable sequence; conflicting content is rejected; confirmation means durable log commit. |
- retry-safe
- deterministic fact history
- clear transport semantics
- strong audit interpretation
|
- requires dedupe lookup
- requires stable content hashing or equivalence check
- business acceptance must be modeled separately
|
Decision
BSFG append semantics are idempotent at the boundary layer.
if message_id already exists and payload is identical:
return existing stream sequence
if message_id already exists and payload differs:
reject as conflicting_duplicate
message_id is the idempotency key. Payload identity is evaluated over the semantic message content, including the canonical fact body and attachment references.
BSFG confirmation semantics are defined as:
ConfirmReceipt = durable commit in target zone log
Confirmation therefore means the fact has been accepted and durably stored in the target zone’s JetStream stream. It does not mean:
- a downstream consumer fetched it
- a downstream consumer acknowledged it
- a business workflow semantically accepted it
Consequences
Benefits:
- producer retries are safe and deterministic
- replay semantics remain stable
- audit history does not accumulate accidental duplicates
- boundary contract remains transport-local and uniform
Tradeoffs:
- append path must maintain or query dedupe state
- conflicting retries must be surfaced as explicit errors
- business-level acceptance requires separate downstream facts or workflows