#Spec authoring path (ByteOr OSS)

This guide records the supported v1 path from author intent to a concrete PipelineSpecV1.

#Decision

• OSS has one active public source authoring path.
  • PipelinePlanV2 is the source contract for full SingleRing and LaneGraph parity.
• Lowering lives in byteor-pipeline-lower.
  • Input: a source authoring document plus explicit ExecutionTargetV1.
  • Output: PipelineSpecV1::{SingleRing,LaneGraph}.
• Direct spec authoring remains available for narrow cases where the caller already knows the exact canonical shape.
  • SingleRingBuilder and single_ring_chain(...) still produce PipelineSpecV1::SingleRing(...).
• Lowering remains explicit.
  • SingleRing lowering is direct.
  • LaneGraph lowering is direct.

#Why the source contract changed

• SingleRing is intentionally narrow: single producer, dedicated stage threads, explicit dependencies, and small validation-aligned limits.
• LaneGraph is the whole-plant topology surface for fanout, merge, bridge wiring, and role-based execution.
• The earlier graph-shaped plan was good enough to bootstrap dual-target lowering, but it could not represent full SingleRing dependency-DAG semantics or LaneGraph runtime policy cleanly.
• PipelinePlanV2 keeps shared catalog metadata in one envelope while allowing target-specific payloads where the execution models genuinely differ.

#Practical guidance

• Use PipelinePlanV2 plus byteor-pipeline-lower::lower_v2(...) when you want the intended full-parity source authoring path.
• PipelinePlanV2::SingleRing(...) carries explicit dependency-DAG semantics.
• PipelinePlanV2::LaneGraph(...) carries explicit topology plus runtime policy such as on_full.
• Use SingleRingBuilder or single_ring_chain(...) when the runtime shape is already explicitly one sequenced ring and you do not need a model-neutral planning document.

#Plan-level versus lowering-level settings

• PipelinePlanV2::SingleRing(...) owns the explicit dependency DAG and SingleRing execution constraints.
• PipelinePlanV2::LaneGraph(...) owns topology, lane intents, and on_full.

#Support matrix

• PipelineSpecV1::SingleRing
  • Supports SP execution with producer=single and scheduling=dedicated.
  • Rejects v1 non-goals such as producer=mpmc and scheduling=work_queue.
  • PipelinePlanV2 lowering can encode explicit dependency DAGs within the current validated v1 limits.
• PipelineSpecV1::LaneGraph
  • Supports whole-plant graphs with endpoints, lanes, and roles.
  • Supports SP execution and explicit role-runner execution where the executor implements the validated shape.
  • PipelinePlanV2 carries the LaneGraph source semantics directly, including on_full.

#Auto-fusion posture

Automatic lowering-time fusion is intentionally out of scope for the v1 contract.

• If you want fused behavior in v1, model it explicitly as a stage operation or stage resolver identity.
• Future lowering passes can be added in byteor-pipeline-lower, but they are not part of the v1 promise today.

#Stage identity note

This guide is about how a spec gets produced, not how a stage implementation is resolved.

• SingleRing stage behavior is represented via StageOpV1.
• Resolver-backed stage identities are still cold-path startup decisions, not hot-path dynamic lookups.