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
| Option | Description | Benefits | Drawbacks |
|---|---|---|---|
| Treat ISB/IFB/ESB/EFB as concrete services | Name runtime components after the four buffers; blur the distinction between role and implementation. | 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 boundaryIFB= Ingress Forward Role: durable ingress-side forward buffer for outbound replayESB= Egress Store Role: durable egress-side buffer for facts arriving from peersEFB= 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