#ByteOr v1 production profile

This document describes the recommended path through the ByteOr OSS workspace for users who want a clear, supportable baseline.

#Blessed path

For the current initial OSS commit, the recommended flow is:

1. Author a PipelinePlanV1 source document and choose an explicit ExecutionTargetV1.
2. Validate the plan with byteor-pipeline-plan::validate_plan_v1.
3. Lower with byteor-pipeline-lower::lower_v1(...) into the PipelineSpecV1 runtime target.
4. Validate the resulting spec with byteor-pipeline-spec::validate_v1.
5. Use byteor-pipeline-backings-mem for deterministic in-memory tests and bring-up.
6. Use byteor-transport-shm plus byteor-pipeline-backings-shm when you need the SHM path.
7. Run the executor from byteor-pipeline-exec.

Migration note:

• The earlier narrow graph-shaped plan is no longer part of the supported OSS authoring surface.
• PipelinePlanV1 is the supported source contract for full SingleRing and LaneGraph parity.

#Recommended v1 execution shapes

#SingleRing

Treat this as the primary v1 runtime path when you need explicit ring semantics.

• single producer
• dedicated stage threads
• fixed stage membership and dependency wiring at startup
• up to 4 stages per ring in the current OSS v1 backing
• final stage release semantics rather than a separate consumer gating cell
• strict ordering for one shard, per_key for multi-shard execution

Authoring note:

• The blessed source path is now PipelinePlanV1::SingleRing(...) with explicit dependency DAGs.
• Direct spec authoring remains valid when callers already own the exact runtime shape.

#LaneGraph

Use this when you need the whole-plant topology surface.

• named lanes and endpoints
• explicit roles such as stage, bridge, router, and merge
• SP and explicit MP role-runner execution paths where the executor supports the validated shape

Authoring note:

• LaneGraph.on_full is part of the authored LaneGraph source contract and the runtime contract.

#What to rely on

It is reasonable to build on these parts of the OSS surface today:

• byteor-abi layouts and generated header workflow
• byteor-pipeline-plan authoring model and plan validation
• byteor-pipeline-lower explicit lowering into runtime specs
• byteor-pipeline-spec data model, validation, kv codec, canonicalization, and describe helpers
• byteor-pipeline-kernel sequencing and wait primitives

Treat these as useful but still easier to change while the workspace remains pre-1.0:

• executor convenience helpers and function naming
• SHM file/path conventions
• stage registry ergonomics
• xtask command UX and optional gate toggles

#Explicitly not the blessed v1 path

The current OSS v1 baseline does not bless the following as supported production behavior:

• MPMC claiming into one SingleRing
• work-queue scheduling over one SingleRing
• dynamic topology mutation at runtime
• macro-only authoring with no builder-based equivalent
• distributed durability/replication guarantees

If you need one of those, treat it as a future milestone rather than something the initial OSS commit already promises.