ADR-0042: Four-Buffer Entities Are Boundary Roles Implemented by BSFG Nodes

Context

BSFG documentation uses the terms ISB, IFB, ESB, and EFB in two distinct senses:

• as first-class architectural primitives in the principle and topology layer (the four-buffer model)
• as if they were specific runtime services or concrete implementation components

This dual usage creates ambiguity when mapping between:

• architecture (topology, roles, invariants)
• runtime (BSFG node, service, RPC contract)
• substrate (JetStream, object store, durable consumers, transport)

The result is confusion about whether the four-buffer model remains valid, has been superseded, or is merely historical. Clarifying this distinction is essential for coherent documentation and implementation.

Options Considered

• intuitive at first glance
• term overloading is familiar in many systems

|

• over-couples architecture to implementation
• makes swapping substrates and deployments confusing
• obscures the principle layer from the implementation layer
• early docs cannot coexist coherently with later service-oriented docs

| | Treat them as mere historical metaphors or earlier models | Downplay or remove the four-buffer model in favor of service/operation terminology. |

• simplifies newer, service-centric documentation
• reduces terminology overload

|

• destroys the principled topology model
• makes it impossible to justify architectural decisions
• future deployments cannot reason about tradeoffs systematically
• breaks continuity with ADRs 0001–0006 and related topology decisions

| | Treat them as logical boundary roles implemented by BSFG nodes (Selected) | Establish that ISB/IFB/ESB/EFB are architectural roles in the replay topology, and BSFG nodes implement these roles using zone-local substrates (JetStream, object store, etc.). |

• preserves the four-buffer topology as first-class and stable
• allows implementation to remain flexible and swappable
• reconciles early topology-centric and later service-oriented documentation
• aligns with hexagonal architecture principles (role vs. adapter)
• makes architectural invariants explicit and independent of substrate

|

• requires documentation discipline to distinguish role, service, and substrate
• readers must learn a three-layer model
• more verbose in some contexts

|

Decision

BSFG adopts a three-layer ontology for clear mapping between architecture, runtime, and substrate:

Principle / Topology Layer

ISB, IFB, ESB, and EFB are logical boundary roles.

• ISB = Ingress Store Role: durable ingress-side buffer for facts arriving at the boundary
• IFB = Ingress Forward Role: durable ingress-side forward buffer for outbound replay
• ESB = Egress Store Role: durable egress-side buffer for facts arriving from peers
• EFB = Egress Forward Role: durable egress-side forward buffer for zone-local delivery

Together, they form the four-buffer replay topology, which defines the minimal partition-tolerant boundary capable of: autonomous operation when connectivity seals, asynchronous replay when reconnected, and effectively-once delivery without shared state or distributed transactions.

Logical System Layer

A BSFG node or BSFG service implements one or more of these roles.

• Boundary RPC contract: AppendFact, FetchFacts, ConfirmReceipt, PutObject
• Replay orchestration logic (handoff protocol, cursor advancement, confirmation semantics)
• Role implementation logic (which buffers are local, which are remote, how they synchronize)

Substrate / Implementation Layer

Zone-local durability substrates that implement the mechanics behind the roles.

• JetStream streams (fact durability)
• Durable consumers (cursor tracking, confirmation)
• Object storage (large artifact persistence)
• Connect RPC + mTLS (boundary transport and identity)

Canonical statement

ISB, IFB, ESB, and EFB are logical boundary roles. A BSFG node may implement one or more of these roles using local durability substrates such as JetStream streams, durable consumers, and object storage.

Consequences

Benefits:

• the four-buffer topology remains a first-class, stable architectural primitive
• implementation substrate is decoupled from topology (swappable backends)
• early topology-focused and later service-centric documentation become coherent
• architectural invariants are explicit and independent of specific technologies
• new deployment patterns can be evaluated against the topology, not against ad hoc service layouts

Tradeoffs:

• documentation must consistently distinguish role (what) from service (how) from substrate (with what)
• readers new to BSFG must internalize a three-layer model before understanding full deployment topology
• writers must resist term overloading and maintain the distinction deliberately