#ByteOr v1 semantics

This document defines the normative v1 behavior for the ByteOr OSS spec surface.

RFC 2119/8174 keywords in this document are normative.

#Spec identity

• A ByteOr v1 spec MUST be represented as PipelineSpecV1.
• A PipelineSpecV1 MUST be exactly one of:
  • PipelineSpecV1::LaneGraph(...)
  • PipelineSpecV1::SingleRing(...)
• Executors MUST validate a spec before running it.
• Helpers that accept an invalid or unsupported spec shape MUST fail closed with an error rather than attempt best-effort execution.

#SingleRing model

PipelineSpecV1::SingleRing(...) describes a stage DAG executed over one sequenced ring.

#Core sequencing model

• The producer cursor MUST advance monotonically.
• Each stage MUST have exactly one gating sequence cell.
• Producer backpressure MUST be derived from the minimum active gating sequence.
• Barrier dependencies MUST be derived from validated stage dependencies.
• In the current OSS v1 backing, the final stage acts as the release/consumer boundary rather than using an extra dedicated gating cell.

#Current OSS limits and validation-aligned rules

• single_ring.shards MUST be >= 1.
• single_ring MUST contain at least one stage.
• The current OSS v1 backing supports at most SEQUENCED_SLOTS_V1_GATING = 4 stages per ring.
• Stages MUST be listed in topological order.
• Each depends_on list MUST be strictly increasing and duplicate-free.
• Each dependency index MUST reference an earlier stage.
• Non-source stages with non-identity behavior MUST declare dependencies explicitly.

#Supported v1 producer and scheduling modes

• single_ring.producer=single is the only supported v1 producer mode.
• single_ring.producer=mpmc MUST be rejected by v1 validation.
• single_ring.scheduling=dedicated is the only supported v1 scheduling mode.
• single_ring.scheduling=work_queue MUST be rejected by v1 validation.

#Ordering and sharding

• With single_ring.shards=1, single_ring.ordering=strict is valid.
• With single_ring.shards>1, single_ring.ordering=strict MUST be rejected.
• When single_ring.shards>1, single_ring.ordering=per_key is the normal v1 choice.
• unordered MAY be used when callers explicitly do not need ordering.

#Stage operations

The OSS v1 stage operation set is intentionally small and explicit.

• identity
• add_u8
• resolver_key via StageOpV1::ResolverKey { stage }

StageOpV1::ResolverKey MUST resolve a stable stage identity once at startup. Executors MUST NOT perform per-message dynamic stage lookup in the hot loop.

#Observability

The SHM SequencedSlots backing exposes a read-only runtime snapshot surface.

• byteor-pipeline-backings-shm::ShmSequencedSlots::snapshot() returns a SingleRingSnapshot.
• Snapshot consumers MAY use cursor, per-stage gating, and helper lag calculations to report health without entering the hot path.

#LaneGraph model

PipelineSpecV1::LaneGraph(...) describes a topology over named lanes, endpoints, and roles.

• Lanes MUST declare a concrete lane kind.
• Endpoints MUST bind to named lanes.
• Roles MUST reference existing lanes.
• Fanout width MUST remain within the v1-supported maximum.
• Executors MAY support only a subset of validated LaneGraph shapes, but unsupported shapes MUST be rejected explicitly.

In the current OSS workspace, LaneGraph is the whole-plant topology surface used for explicit roles such as stage, bridge, router, and merge.

#Authoring path

• OSS source authoring SHOULD use byteor-pipeline-plan::PipelinePlanV2 plus explicit lowering through byteor-pipeline-lower::lower_v2(...).
• PipelinePlanV2::SingleRing(...) is the intended source contract for authored SingleRing dependency DAGs.
• PipelinePlanV2::LaneGraph(...) is the intended source contract for authored LaneGraph topology and runtime policy.
• SingleRing specs MAY still be authored directly with SingleRingBuilder or single_ring_chain(...) when the caller already wants a concrete SingleRing spec.
• Whole-plant LaneGraph specs MAY be authored directly as canonical specs when the caller already owns that concrete representation.
• on_full MUST be treated as part of the LaneGraph source/lowering/runtime contract.
• the older graph-shaped migration-era plan SHOULD NOT be treated as the final full-parity authoring surface.
• The rationale and support matrix for the supported authoring paths are documented in docs/guides/spec-authoring.md.

#Format and determinism

• The kv encoding emitted by byteor-pipeline-spec is part of the documented OSS surface.
• Canonicalization and hashing helpers MUST produce deterministic results for equivalent v1 specs.
• Backwards-compatibility parsing MAY accept older LaneGraph-only kv blobs, but newly emitted v1 content SHOULD use the current tagged model.