Module ring 

Ring buffers — orbit-core’s runtime substrate.

“orbit runtime yani ring” — the place where the fleet’s shared state actually lives at the lowest level. Higher-level shapes (cache mutations, metrics snapshots, event streams, etc.) reduce to one or more rings.

Shape

One Ring per OrbitTyped kind. A ring is one or more fixed-size circular lanes of Frames. Shared rings use one lock-free multi-writer claim sequence. Shared-ordered rings serialize writers and expose only committed counters. Per-node rings give every fleet member a disjoint lane whose head advances only after a frame is committed. When a lane head exceeds its capacity, the oldest slot in that lane is overwritten.

The frame layout mirrors the nwd1 seed (see VISION §13):

┌──────────┬──────┬──────┬─────────────┐
│ id (8)   │ kind │ ver  │ payload (N) │
│ NetId64  │  u8  │ u64  │   bytes     │
└──────────┴──────┴──────┴─────────────┘

Two kind bytes coexist on the wire and they mean different things (intentional, two-axis encoding):

• frame.id.kind() — which Rust type (the data shape).
• frame.kind — which message class (state / event / command / ack / invalidate / …). V0 leaves this open at 0; concrete classes appear when subscriber semantics arrive.

V0 backing

RwLock<Option<Frame>> per slot — simple, correct, slow. The SHM backing uses per-slot sequence numbers to prevent torn reads. Per-node lanes serialize concurrent publishers inside one process, commit the slot, then release-store their lane head.

Who mints

Writes go through Ring::write, which mints the NetId64. The COUNTER part is the position inside either the shared sequence or the writer node’s lane. NetId64s are therefore minted server-side, by the writer process. Browsers / external clients receive ids; they do not generate them.

Modules

cursor

Cursor and walking primitives for Orbit rings.

shm

ShmRing — POSIX SHM-backed ring buffer (V1 substrate).

Structs

Frame

One record in a ring — the on-wire shape (mirrors nwd1::Frame).

Ring

A fixed-capacity, fleet-wide append-only log keyed on KIND byte.

RingEventFd

Process-local fd readiness bridge for one shared Orbit ring.

RingSpec

Physical policy for one OrbitTyped ring.

Enums

RingTopology

Writer ownership for one OrbitTyped ring.