#IndexBus Semantics

This page describes the normative v1 semantics for IndexBus lane operations. These semantics define the behavioral contract that all implementations must satisfy.

#Region Lifecycle

1. Create — allocate a shared-memory region with a defined layout
2. Open — attach to an existing region and validate headers
3. Operate — read and write through lane handles
4. Close — detach from the region

Regions are persistent shared-memory objects. They survive process restarts until explicitly removed.

#Lane Operations

#Write

A write operation appends data to a lane. The behavior when the lane is full depends on the on_full policy:

• Block — the writer waits until a reader advances, freeing space
• Drop — the oldest unread entry may be overwritten

Write operations are atomic at the entry level. Partial writes are never visible to readers.

#Read

A read operation consumes the next available entry from the reader's position. Each reader tracks its own position independently.

• Reads never block when data is available
• Reads return None (or equivalent) when no data is available
• Reader position advances only after a successful read

#Ordering Guarantees

Within a single lane:

• Entries are ordered by write sequence
• Readers see entries in write order
• No entry is skipped unless the Drop policy overwrites it before the reader reaches it

Across lanes, ordering is defined by the topology and lane kinds, not by IndexBus globally.

#Failure Lifecycle

IndexBus defines explicit failure states and transitions:

Transitions between states are defined and observable. Recovery from Failed requires explicit remediation, not automatic retry.

#Header Layout

Lane headers use repr(C) layouts with:

• Magic number for validation
• Version field for compatibility checking
• Capacity and entry size
• Write position (producer-owned)
• Read positions (per-reader)
• Lane-kind-specific metadata

The header layout is part of the ABI contract. Changes require explicit versioning.

#Conformance

IndexBus provides conformance test suites that validate:

• Lane creation and initialization
• Write semantics under each on_full policy
• Read semantics and position tracking
• Multi-reader behavior
• Router and merge correctness
• Failure state transitions
• Header layout compatibility