#Spec Authoring

Pipeline specs in ByteOr are structured documents that describe what a pipeline does, how it is connected, and what execution constraints apply. This page covers authoring practices for both SingleRing and LaneGraph targets.

#The Spec Format

ByteOr uses a deterministic key-value (KV) format for pipeline specs. The format is:

• UTF-8 text with one key=value pair per line
• Newline-delimited and whitespace-sensitive
• Deterministic — the same logical spec always produces the same byte-for-byte encoding
• Canonicalizable — specs can be round-tripped through encode/decode without drift
• Diff-friendly — line-based format works naturally with version control

#KV Encoding Rules

• No quoting or escaping for simple values
• Nested structures use dotted key paths
• Arrays use indexed keys
• Boolean values are true or false
• Integer values are decimal

#Source Authoring Contract

The supported authoring surface is PipelinePlanV2. This is the source contract for both execution targets.

#Builder-First Rule

The builder API in byteor-pipeline-spec is the baseline authoring contract. Macros are optional ergonomics built on top of the builder. A macro-only surface without an equivalent builder path is not the supported baseline.

#Authoring a SingleRing Spec

1. Set the pipeline name and execution target to SingleRing
2. Define ingress and egress boundaries
3. List stages in topological order with explicit dependencies
4. Set execution constraints: shard count, ordering, producer, scheduling
5. Validate and compile

#Authoring a LaneGraph Spec

1. Set the pipeline name and execution target to LaneGraph
2. Define boundaries and stages
3. Define graph connections with lane-kind intents
4. Set boundary lane policies
5. Set the on_full backpressure policy
6. Validate and compile

#Validation Rules

The compiler validates specs before lowering. Common rejection reasons:

• Self-dependencies in stage lists
• Dependencies on later stages (violates topological order)
• Duplicate stage references
• Invalid constraint combinations (e.g., Strict ordering with shards > 1)
• Unsupported lane kinds without the required feature flag
• Topology violations in LaneGraph connections

#Version Creation

After validation and lowering, the compiler produces an immutable pipeline version. This version is:

• Content-addressed — identified by spec hash
• Immutable — once created, it cannot change
• Auditable — the full validation result and compilation diagnostics are recorded

In Cloud, version creation happens through the editor's compile path. The draft plan is lowered through the compiler-backed WASM pipeline and stored as a canonical version.

#Compile Diagnostics

The compiler emits structured diagnostics during lowering:

• Inserted bridges, routers, and merges (LaneGraph)
• Constraint resolutions
• Feature-gated capabilities used

These diagnostics are part of the compile report and can be inspected after version creation.