Context
BSFG is a narrow boundary appliance, not a general integration platform. Its RPC surface should expose only the operations required to:
- append durable facts
- retrieve bounded batches of retained facts
- confirm durable receipt
- store large artifacts out-of-band
The contract must remain stable, auditable, and easy to implement across zones without turning the boundary protocol into a large application API.
Options Considered
| Option | Description | Benefits | Drawbacks |
|---|---|---|---|
| Large generic CRUD-style API | Expose many endpoints for querying, mutating, validating, deleting, and inspecting boundary data. |
- high flexibility
- fewer external helper tools needed
|
- bloated appliance surface
- transport leaks into application semantics
- higher governance and security burden
|
| Single generic command endpoint | Use one RPC such as Execute or Command with operation details embedded in the payload. |
- very small transport surface
- easy versioning at first glance
|
- weak explicitness
- poorer tooling and observability
- operation semantics become opaque
| | Transport-only replication stream | Expose only a fetch/replicate primitive and push append semantics elsewhere. |
- very narrow protocol
- close to raw log replication
|
- poor producer ergonomics
- append semantics become indirect
- artifact handling remains unresolved
|
| Four explicit RPC operations (Selected) | Expose exactly AppendFact, FetchFacts, ConfirmReceipt, and PutObject. |
- minimal but explicit
- maps directly to the architecture
- easy to secure and observe
- keeps transport semantics narrow
|
- some convenience operations are intentionally absent
- higher-level workflows must be built outside the boundary contract
|
Decision
BSFG exposes exactly four canonical RPC operations:
AppendFact
FetchFacts
ConfirmReceipt
PutObject
Their roles are:
AppendFact: append an idempotent fact to the local durable logFetchFacts: retrieve a bounded batch of retained facts using unary paged pullConfirmReceipt: acknowledge durable commit in the target zone logPutObject: store large artifacts in zone-local object storage
The contract deliberately omits CRUD-style mutation, delete, search, and business-specific commands. Those belong outside the boundary substrate.
Consequences
Benefits:
- small, explicit, and teachable API surface
- tight alignment between contract and architecture
- simpler security policy and operational monitoring
- clear separation between boundary substrate and higher-level application logic
Tradeoffs:
- clients needing richer behavior must compose it themselves
- indexing, search, and domain validation remain downstream concerns
- some teams may initially want convenience endpoints that the architecture intentionally refuses