ADR-0031: Clients Access Boundary Storage Only Through BSFG Service

Context

BSFG is defined as a boundary appliance with a narrow explicit contract:

AppendFact
FetchFacts
ConfirmReceipt
PutObject

Underneath that contract sit the zone-local durable substrates:

• JetStream fact streams
• Object Store artifact buckets

A design question follows:

• should application clients interact directly with JetStream streams and object buckets?
• or should all boundary storage access be mediated by the BSFG service?

This decision determines whether the boundary contract stays explicit and enforceable, or whether storage internals become the de facto public API.

Options Considered

• fewer application hops
• clients can use native storage features directly

|

• storage internals become the real public contract
• idempotency and confirmation semantics fragment across clients
• security and policy enforcement become inconsistent

| | Mixed mode | Some clients use the BSFG service while others access JetStream or Object Store directly. |

• migration can feel incremental
• specialized clients can bypass service limits

|

• two competing contracts emerge
• audit and ops behavior become inconsistent
• architectural discipline erodes over time

| | BSFG service as the only boundary-facing storage contract (Selected) | All application access to fact logs and artifact storage goes through the BSFG service contract. |

• one explicit boundary API
• uniform idempotency, confirmation, and auth behavior
• storage implementation can evolve behind the service
• audit posture remains coherent

|

• service implementation must cover all supported access paths
• some native storage convenience features remain intentionally hidden

| | Storage-side policy wrappers only | Expose JetStream and Object Store directly, but rely on ACLs and conventions to approximate BSFG semantics. |

• lower service-layer complexity
• heavy reuse of substrate primitives

|

• semantics are implied rather than contractual
• client behavior becomes harder to standardize
• boundary model weakens into infrastructure convention

|

Decision

Application clients do not access JetStream streams or object buckets directly as part of the boundary contract.

All boundary-facing storage interaction is mediated by the BSFG service:

client
  -> BSFG service
      -> JetStream
      -> Object Store

Therefore:

• AppendFact is the only supported path for boundary fact append
• FetchFacts is the canonical path for retained fact retrieval
• ConfirmReceipt is the canonical path for durable confirmation
• PutObject is the canonical path for large artifact storage

JetStream and Object Store are implementation substrates, not the public boundary protocol.

Consequences

Benefits:

• the architecture retains a single explicit contract
• security, authorization, idempotency, and observability remain centralized
• storage internals can change without breaking clients
• boundary semantics stay aligned with ADRs rather than with substrate-specific usage patterns

Tradeoffs:

• the BSFG service must be implemented carefully enough that direct substrate access is not tempting
• operators may still use substrate-native tooling for diagnosis, but that tooling is not part of the client contract
• some advanced substrate capabilities remain intentionally outside the public model