#IndexBus v1 production profile: scope, blessed paths, stability

This document defines the v1 production profile for IndexBus as shipped in this repository:

• what is considered stable vs experimental
• the blessed paths (recommended integration combinations)
• a stability tier matrix so users know what to build on

“Production profile” is intentionally conservative: it names the supported contract and avoids a combinatorial surface area.

Related docs:

• Architecture overview: ../architecture/overview.md
• Ops triage: ../ops/v1-triage.md
• Performance & tuning: ../ops/performance-tuning.md
• v1 conformance tests guide: ../guides/v1-conformance-tests.md

#1) What the v1 production profile means

The v1 production profile means:

• Bounded-by-design: hot-path data structures have explicit, fixed capacities.
• Explicit failure semantics: “full”, “empty”, “too large”, and validation failures are surfaced as typed errors.
• Hardened region validation for cross-process use: shared mappings are validated before use.
• Compatibility rules are explicit: ABI v1 layouts are append-only and capability-gated.

#Supported vs experimental (high level)

IndexBus is currently 0.x. Many crates still label themselves Experimental in their crate READMEs; treat this section as the recommended/supported surface area for building on this repo today (not a promise of long-term SemVer stability).

Supported / recommended (v1 production profile):

• ABI layout contract in indexbus-abi (v1 append-only policy; capability bits; header contract).
• Core primitives in indexbus-core: events (SPSC/MPSC), fanout router handles, state stream, wait strategy.

Supported / recommended (v1 production profile, lane-specific):

• Sequencer control plane in indexbus-seq (cursor + gating sequences; polling waits; optional wake-backed blocking).
• Envelope/header parsing in indexbus-msg.
• Core codec traits in indexbus-codec and small reference codecs.
• Canonical router loop orchestration in indexbus-route.
• Local + SHM transports intended for production IPC: indexbus-transport-local, indexbus-transport-shm.

Experimental / best-effort (v1.x):

• UDP transport adapter indexbus-transport-udp is best-effort framing (not a complete flow-control/reliability stack).
• Async/runtime integrations in indexbus-adapters are optional and may evolve.
• Journal/log (indexbus-log) is experimental (framing and semantics may evolve).
• Ops/UI surfaces (some CLI flags, output formats) may evolve as the operational story hardens.

#2) Blessed paths (avoid combinatorial API)

These are the recommended “happy paths” for users.

#Fanout router loop (default production story): single-writer + batching

Use this when you want pub/sub or work distribution with predictable performance.

• Cross-process (recommended): indexbus-transport-shm + indexbus-core + indexbus-route
  • create/open a fanout region with indexbus-transport-shm
  • run a single router loop (thread/process) via indexbus-route
  • producers publish into the producer queue; consumers read their consumer queues
• In-process / embedded: indexbus-transport-local + indexbus-core

Typed messaging (recommended layering):

• Use indexbus-msg v1 envelope (schema/type/version + payload length).
• Use indexbus-typed to glue a codec to a transport handle.
• Choose a codec crate (indexbus-codec-raw, indexbus-codec-sbe, …).

#Router-enforced credits (default overload-control story)

Router-enforced credits are the v1 overload-control story.

• Credits are enforced in the router loop (indexbus-route) and reflected in counters.
• v1 credit model is depth-based (per-consumer queue depth vs credit_max).
• Core data structures (indexbus-core) remain policy-free.

Operational surface:

• indexbus-router exposes --credit-max, --credit-policy (drop|detach|park), and --detach-after-ms.

#Sequencer + gating sequences (default for single-process staged DAGs)

The sequencer is intended for single-process (or tightly coordinated) staged systems where deterministic gating is important.

Blessed approach:

• define the region layout in indexbus-abi (cursor + gating sequences)
• keep the public API surface minimal in indexbus-core
• provide orchestration and examples as tools/adapters

#Journal / segment log (experimental): replay/inspection

The journal is intended for log-like streams with replay/inspection and overrun semantics.

Blessed approach:

• define a journal region layout in indexbus-abi
• use indexbus-log primitives for append/read/poll (currently experimental)
• use indexbus-inspect --journal-dump/--journal-watch for inspection/triage

#3) Stability tier matrix

These tiers are the “support contract” for the v1 production profile.

#Tier A — ABI layout contract (indexbus-abi)

Stable guarantees:

• #[repr(C)] layout structs are the source of truth for the shared-memory ABI.
• ABI v1 is append-only; compatibility is checked using LayoutHeader + layout_bytes + capability bits.

#Tier B — Core primitives (indexbus-core, indexbus-msg, indexbus-codec)

Stable guarantees:

• bounded, nonblocking primitives
• clear typed errors for full/empty/too-large/validation failures
• no implicit global configuration

#Tier C — Transports and adapters

Stable-ish / integration surface:

• indexbus-transport-local: caller-owned memory regions (embedded/no_std-friendly)
• indexbus-transport-shm: file-backed shared memory mappings (std-only)

Experimental / best-effort:

• indexbus-transport-udp: best-effort framing adapter, not a full network stack
• indexbus-adapters, indexbus-blocking, indexbus-wake: optional runtime/OS integration crates

#Tier D — Tools and binaries

• indexbus-route router loop + reference CLI (indexbus-router)
• inspection tooling (e.g. indexbus-inspect)
• ops runbook-style triage: ops triage (v1)

#4) Supported goals vs explicit non-goals

Supported goals:

• bounded memory and predictable overload behavior via explicit policies (drop/block/park at the edges)
• cross-process IPC via SHM mappings with hardened validation
• at-most-once queues/fanout (with optional router-enforced credits) and state-style overwrite-latest (state)
• ops visibility via inspection + counters + clear failure contracts

Explicit non-goals:

• exactly-once / transactional delivery semantics
• durable storage, replication, broker rebalancing (Kafka/Pulsar-class features)
• “Aeron-grade” cross-host networking completeness (driver, full flow control, pacing)
• hard real-time scheduling guarantees (this is OS/application-level)