BSFG Boundary Roles

Overview

The four-buffer model is the architectural heart of BSFG. It defines four logical boundary roles: ISB, IFB, ESB, and EFB.

These roles are not services or concrete components — they are principles that describe what each part of the boundary does, independent of how it is implemented. A BSFG node may implement one or more of these roles using any conforming zone-local durability substrate.

Role Definitions

Each boundary role has a specific responsibility in the ingress-to-egress path. The table below maps each role to its direction, responsibility, and durability characteristics:

Ingress vs Egress Flows

The boundary operates in two directions. Here is a simplified flow showing how the four roles work together:

flowchart TD
  subgraph IN["INGRESS FLOW (Inbound to Internal Zone)"]
    EZ1["External Zone"] --> ISB["ISB (store)"]
    ISB --> H1["Handoff (async replay)"]
    H1 --> IFB["IFB (forward)"]
    IFB --> IZ1["Internal Zone"]
  end

  subgraph OUT["EGRESS FLOW (Outbound to External Zone)"]
    IZ2["Internal Zone"] --> ESB["ESB (store)"]
    ESB --> H2["Handoff (async replay)"]
    H2 --> EFB["EFB (forward)"]
    EFB --> EZ2["External Zone"]
  end

  G["Gate controls flow"]
  ISB -.-> G -.-> IFB
  ESB -.-> G -.-> EFB

Three-Layer Ontology

To avoid confusion between roles and implementations, BSFG distinguishes three layers:

• Principle Layer: ISB, IFB, ESB, EFB are logical boundary roles. They describe the what — what each part of the boundary must do.
• Logical System Layer: A BSFG node orchestrates these roles via the RPC contract (AppendFact, FetchFacts, ConfirmReceipt, PutObject) and implements the replay handoff protocol, cursor advancement, and confirmation semantics.
• Substrate Layer: Zone-local durability is provided by any conforming durable store and transport adapter. The substrate implements the roles but is decoupled from the topology principles.

For one reference implementation of these roles, see NATS/JetStream Reference.

Key Invariants

The four-buffer topology enforces several architectural invariants:

• Zone-Local Durability: Each zone owns its own ISB/ESB (store buffers) and IFB/EFB (forward buffers). No zone writes directly into another zone's durable log.
• No Durable Middleware at Boundary: The boundary network carries only connectivity infrastructure (routers, firewalls, TLS terminators). Durable state is zone-owned.
• Asynchronous Replay Only: Zones communicate via async handoff, never via synchronous RPC. A zone can operate autonomously when the boundary is sealed.
• Idempotent Append at Forward Buffers: The forward buffers (IFB, EFB) use atomic putIfAbsent to deduplicate. This eliminates the need for background reconciliation workers.
• Contiguous Frontier: Safe truncation at store buffers depends on contiguous confirmation at forward buffers. Gaps break truncation safety.

Terminology

Gate

A logical circuit breaker. When open (normal operation), synchronous paths work. When closed (network partition), producers and consumers continue via local buffers; the handoff freezes.

Cursor / Frontier

The position in the store buffer up to which facts have been durably confirmed at the forward buffer. Also called highest_contiguous_committed_offset.

Handoff

The asynchronous transfer of facts from store buffer to forward buffer. Driven by cursor advancement and replay.