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