Documentation Layers: Editorial Ontology

Audience: All readers. Use: Understand how BSFG documentation is organized and what guarantees each layer provides.

The Three-Layer Documentation Model

BSFG documentation is organized into three distinct layers, each with different scope and vocabulary rules. This model ensures that architectural principles remain clear and that implementation choices do not become confused with architecture.

Layer 1: Principle Layer

Defines what BSFG is.

This layer describes the invariants, guarantees, and exclusions that define BSFG's essence:

• Four-buffer decomposition (ISB, IFB, ESB, EFB as logical roles)
• Key guarantees: Producer non-blocking, effectively-once boundary, mechanism agnosticism, fast swappability
• Explicit exclusions: Not shared database, not synchronous RPC, not distributed transactions, etc.
• Operational modes: Normal (gate open), Autonomous (gate closed), Reconciliation (reconnecting)
• Core protocol concepts: cursor/frontier, handoff, contiguous acknowledgment, idempotency keys
• Architectural invariants: zone isolation, no durable middleware at boundary, asynchronous replay only

Vocabulary rules:

• No NATS, JetStream, Redis, Kafka, etcd, S3, or other substrate-specific terms
• No references to infrastructure internals
• Use abstract terms: "durable store", "durable fact log", "idempotent append", "zone-local storage"
• Architectural roles and interfaces, never implementation details

Key document: Architecture Specification is the authoritative principle-layer reference.

Documents in this layer:

• docs/overview/executive-brief.md — Executive summary
• docs/overview/architecture.md — Normative specification (authoritative)
• docs/concepts/boundary-roles.md — Four roles and invariants
• docs/concepts/message-model.md — Envelope and fact structure
• docs/concepts/replay-model.md — Handoff protocol and operational modes
• docs/concepts/hexagonal.md — Port/adapter architectural pattern
• docs/concepts/artifact-handling.md — Out-of-band storage semantics
• docs/concepts/security-model.md — Trust boundaries and security principles

Layer 2: Logical System Layer

Defines how BSFG operates as a system.

This layer explains the abstract protocol semantics, interfaces, and operational contracts that bind producers and consumers:

• RPC contract: AppendFact, FetchFacts, ConfirmReceipt, PutObject operations and their semantics
• Peer replication protocol: Six-step pull-driven handoff between zones
• Cursor advancement and frontier semantics: How zones track confirmation state
• Idempotency rules: Strategies for deriving idempotency keys, retry safety
• Delivery guarantees: At-least-once transport + idempotent append at boundary
• Integration obligations: Producer and consumer contracts

Vocabulary rules:

• No substrate-specific implementation terms
• Abstract over implementation choices (e.g., "durable cursor storage" not "JetStream consumer offset")
• Operations are named as RPC verbs, not storage API calls
• Interface specifications are substrate-neutral

Documents in this layer:

• docs/concepts/peer-replication.md — Zone-to-zone replication protocol
• docs/integration/integration-contract.md — Producer and consumer obligations
• docs/integration/producer-guide.md — How to emit facts (abstract)
• docs/integration/consumer-guide.md — How to consume facts (abstract)

Layer 3: Substrate Layer

Describes how BSFG can be implemented.

This layer documents concrete implementations and the mapping between principle/logical-system layers and infrastructure:

• NATS/JetStream reference implementation: How JetStream streams, durable consumers, object store, accounts, and authorizations realize the BSFG model
• Backend adapters: How Kafka, PostgreSQL, S3, Redis, etcd, and other systems can implement the StoreBuffer, ForwardBuffer, and CursorTracker ports
• Deployment topologies: HA configurations, networking, certificate management
• Operational procedures: Patching, monitoring, alerts, incident response

Vocabulary rules:

• NATS, JetStream, accounts, streams, buckets, durable consumers, etc. are used explicitly
• Implementation-specific configuration and operational details are permitted
• Every substrate doc must be clearly labeled "Reference Implementation" or "Deployment"
• Substrate docs must include explicit framing: "This describes one possible implementation of BSFG. The architecture itself is substrate-neutral."

Documents in this layer:

• docs/deployment/nats-jetstream.md — NATS/JetStream reference implementation (badge: Reference Implementation)
• docs/deployment/nats-naming.md — NATS/JetStream naming conventions (badge: Reference Implementation)
• docs/deployment/identity-model.md — Zone identity, mTLS, and authentication
• docs/deployment/network-policy.md — Firewall rules and network topology
• docs/deployment/observability-and-operations.md — Monitoring, metrics, and operations
• docs/deployment/operations-runbook.md — Operational procedures and incident response

Architecture Decision Records (ADRs)

ADRs retain their full historical context, including the rationale and implementation details that led to each decision. However:

• ADRs may reference JetStream, NATS, and other substrate details in the Context and Decision sections (documenting the actual decision basis)
• When substrate-specific language appears in an ADR, it is framed with a note clarifying that this was the reference implementation at the time of the decision, not an architectural requirement
• Where possible, ADRs reference the three-layer model to avoid readers conflating implementation history with architecture

Framed ADRs:

• docs/adr/adr-0012.md — Append idempotency and confirmation semantics (notes that JetStream's properties were the implementation basis)
• docs/adr/adr-0031.md — Client access mediation through BSFG service (notes that JetStream/Object Store are reference implementation substrates)

Editorial Rules

For Writers

1. Identify your layer. Determine whether your doc belongs in principle, logical-system, or substrate layer.
2. Use the vocabulary of your layer. Avoid terms from other layers.
3. Cross-reference between layers. Principle docs should reference logical-system docs for detailed operation. Logical-system docs should reference substrate docs for implementation.
4. When describing implementation, always use a substrate badge and include an explicit framing statement: "This document describes one possible implementation of BSFG..."
5. When extracting implementation details from principle docs, move the entire section to a substrate doc and replace with a cross-reference.

For Readers

• If you want to understand BSFG architecture, start with the Architecture Specification (principle layer)
• If you want to understand how BSFG operates at the protocol level, read the Concepts and Integration sections (logical system layer)
• If you want to implement BSFG on a specific stack (e.g., NATS/JetStream), read the Reference Implementation and deployment guides (substrate layer)
• If you need to understand why a decision was made, read the relevant ADR in the ADR index

Examples

Example 1: ISB Buffer (Three-Layer Contrast)

Principle Layer (boundary-roles.md):

The Ingress Store Buffer (ISB) is a durable write-ahead log at the external zone perimeter. It accepts incoming facts and confirms durability.

Logical System Layer (architecture.md):

The ISB interface is append(payload: Bytes, metadata: Headers) → Promise<Offset>, guaranteeing a durable append-only log with monotonic offsets.

Substrate Layer (nats-jetstream.md):

The ISB is implemented as a JetStream stream (facts.operational.*) in the external zone. Producers append to the stream via the AppendFact RPC, which internally calls stream.publish(). Durability is confirmed once the message is replicated to the configured replication factor.

Example 2: Naming (Three-Layer Contrast)

Principle Layer (naming-conventions.md):

Identifiers follow lowercase ASCII naming conventions. Predicates use verb_object format (e.g., order_created). Zone names must be stable, unique, and DNS-friendly.

Logical System Layer (integration-contract.md):

Producers must generate stable, deterministic message_id values derived from business logic. Zone identities are transmitted in the envelope's from_zone and to_zone fields.

Substrate Layer (nats-naming.md):

JetStream streams follow the naming format facts.<category>[.<prefix>]. NATS accounts are named <zone>_account due to NATS naming conventions. The relationship between abstract naming grammar and NATS specifics is documented in detail here.

Authoritativeness

The Architecture Specification is the single authoritative source for what BSFG is. If you find a contradiction between the Architecture Specification and another document, the Architecture Specification is correct, and the other document should be updated.

For ADRs: If an ADR contradicts the current Architecture Specification, the Architecture Specification takes precedence. The ADR remains a historical record of the decision, but the current normative specification is authoritative.

Cross-Links

• Architecture Specification — The authoritative principle-layer reference
• Boundary Roles — Key roles and invariants
• NATS/JetStream Reference — Reference implementation details
• ADR Index — All architectural decisions