#Validation and Compilation

ByteOr pipelines pass through a structured validation and compilation pipeline before execution. This page describes the lowering process from source plan to executable format.

#Pipeline Overview

Source Plan (PipelinePlanV2)
  │
  ▼
Parse and decode
  │
  ▼
Structural validation
  │
  ▼
Semantic validation (target-specific)
  │
  ▼
Lowering and compilation
  │
  ▼
Canonical execution plan + compile report

#Structural Validation

Structural validation checks that the source plan is well-formed:

• Required fields are present
• Types are correct
• References resolve (stage IDs, boundary IDs)
• No duplicates in stage lists

#Semantic Validation

Semantic validation applies target-specific rules:

#SingleRing Rules

• Stages must be in topological order
• No self-dependencies or forward dependencies
• Strict ordering requires shards == 1
• Producer must be Single (current v1)
• Scheduling must be Dedicated (current v1)
• Stage count within validation limits

#LaneGraph Rules

• Connections must reference valid stages and boundaries
• Lane-kind intents must be supported (feature-gated kinds require flags)
• SequencedSlots capacity must be > 0
• FanoutBroadcast consumers must be > 0 and within limits
• Graph must be a valid DAG

#Lowering

During lowering, the compiler transforms the validated source plan into the canonical execution format:

• SingleRing — stage dependencies and constraints are resolved into the execution order
• LaneGraph — the compiler may insert bridges, routers, and merge roles to satisfy lane-kind constraints and topology requirements

The lowering step is deterministic. The same validated plan always produces the same execution format.

#Compile Report

The compiler produces a CompileReportV1 alongside the execution plan:

• Spec — the original PipelineSpecV1
• Diagnostics — structured list of compiler actions (bridge insertions, router placements, merge additions)

#WASM Compilation Path

In Cloud, validation and lowering run through a WASM-compiled version of the ByteOr compiler. This ensures:

• The same compiler logic runs in the browser editor and on the server
• Preview validation matches final version creation
• No divergence between client-side and server-side compilation

#Failure Lifecycle

When validation or compilation fails, the failure is reported as a structured result rather than an opaque error. The failure lifecycle follows defined transitions:

1. Validation failure — spec rejected before lowering, with a diagnostic explaining why
2. Compilation failure — lowering could not produce a valid execution plan
3. Runtime failure — execution-time failures follow the v1 failure lifecycle contract

Each failure state has defined transitions. Recovery requires addressing the root cause and re-validating, not retrying the same input.