ADR-0033: Boundary Delivery Semantics Are At-Least-Once with Idempotent Append

Context

BSFG operates across autonomous zones under retry, disconnect, restart, and partial-failure conditions. In that environment, the architecture must state clearly what delivery guarantee it actually offers.

Several prior decisions already constrain the answer:

• facts are append-only
• message_id is the idempotency key
• identical retries return the original durable sequence
• conflicting duplicates are rejected
• ConfirmReceipt means durable commit in the target zone log

The remaining question is whether BSFG should claim a stronger end-to-end delivery guarantee than these primitives actually justify.

Options Considered

• simple sounding promise
• appealing to application teams

|

• overstates what the boundary substrate can guarantee
• collapses transport, consumer, and business semantics into one claim
• difficult to verify honestly across autonomous systems

| | At-most-once delivery | Never retry once transmission ambiguity exists; prefer possible loss over duplicates. |

• no duplicate handling burden
• simpler consumer model

|

• unacceptable data-loss posture
• poor fit for compliance and auditability
• weak recovery semantics after partition

| | Unqualified “reliable delivery” | Use vague reliability language without stating the exact semantic model. |

• easy marketing language
• avoids precision in architecture docs

|

• ambiguous contracts
• operators and developers infer different meanings
• weak audit and incident analysis posture

| | At-least-once transfer with idempotent append (Selected) | Permit retry and redelivery at the transport level, while making append deterministic through idempotency. |

• honest failure model
• strong recovery semantics
• fits append-only history
• keeps duplicates from becoming ambiguous stored facts

|

• clients must understand retry vs duplicate-storage distinction
• exactly-once business processing is not implied

|

Decision

BSFG defines boundary delivery semantics as at-least-once transfer with idempotent append.

transport may retry
transport may redeliver
stored fact history remains deterministic via idempotency

Concretely:

• a sender may retry when delivery outcome is uncertain
• a receiver may observe the same attempted fact more than once
• the target zone stores that fact at most once under a given message_id and identical content
• if the same message_id arrives with different content, the append is rejected as conflicting_duplicate

Therefore BSFG does not claim:

• exactly-once business processing
• exactly-once consumer execution
• exactly-once projection updates

BSFG does claim:

• retry-safe transport
• deterministic stored fact history
• durable confirmation at the boundary log level

Consequences

Benefits:

• the architecture states a precise and defensible guarantee
• fact history remains clean even under retry-heavy conditions
• recovery after partial failure remains safe and operationally straightforward
• boundary semantics stay distinct from downstream business semantics

Tradeoffs:

• application teams must not misread idempotent append as exactly-once business execution
• downstream systems still need their own idempotency or acceptance modeling where appropriate
• documentation and operator training must reinforce the distinction clearly