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