Worked examples (ByteOr OSS)

    This guide gives a compact, canonical public worked-example surface for the ByteOr OSS workspace.

    It is intentionally narrower than the surrounding product documentation in byteor-docs.

    Use this guide when you want:

    • a stable OSS-owned example for the source authoring path,
    • a concrete SingleRing example,
    • a concrete LaneGraph example,
    • a simple mapping from source author intent to canonical spec shape.

    Do not use this guide as a product-runtime or industry-domain reference. Those belong in the central docs site.

    Example 1: Ordered SingleRing

    Use this shape when the runtime is one ordered control path and strict stage sequence is the main requirement.

    use byteor_pipeline_spec::{single_ring_chain, StageOpV1};

let spec = single_ring_chain(&[
    StageOpV1::AddU8 { delta: 1 },
    StageOpV1::AddU8 { delta: 2 },
])?;

    Representative fit:

    • deterministic build-step chains,
    • authoritative state updates,
    • simple replayable decision paths.

    The canonical spec.kv shape is line-oriented and deterministic:

    v=1
model=single_ring
single_ring.shards=1
single_ring.ordering=strict
single_ring.producer=single
single_ring.scheduling=dedicated
single_ring.shard_key=first_byte
single_ring.stages=2
stage.0.op=add_u8
stage.0.delta=1
stage.0.depends_on=
stage.1.op=add_u8
stage.1.delta=2
stage.1.depends_on=0

    Example 2: Graph-shaped LaneGraph

    Use this shape when you need explicit topology, fanout or merge intent, and target-aware lowering.

    The example below mirrors the checked-in lane_graph_v1_plan() test shape.

    use byteor_pipeline_plan::{
    ExecutionTargetV1, LaneGraphAuthoringV1, LaneIntent, OnFullV1, PlanBoundary,
    PlanBoundaryKind, PlanConnection, PlanConnectionDestination, PlanConnectionSource,
    PlanStage, PipelinePlanSourceV1, PipelinePlanV1,
};

let plan = PipelinePlanV1 {
    name: "lanegraph-v1".into(),
    target: ExecutionTargetV1::LaneGraph,
    stages: vec![
        PlanStage { name: "s0".into(), stage: "identity".into() },
        PlanStage { name: "s1".into(), stage: "add_u8".into() },
    ],
    boundaries: vec![
        PlanBoundary { name: "in".into(), kind: PlanBoundaryKind::Ingress },
        PlanBoundary { name: "out".into(), kind: PlanBoundaryKind::Egress },
    ],
    source: PipelinePlanSourceV1::LaneGraph(LaneGraphAuthoringV1 {
        boundary_lane: LaneIntent::Events,
        connections: vec![
            PlanConnection {
                from: PlanConnectionSource::BoundaryIngress { boundary: "in".into() },
                to: PlanConnectionDestination::StageIn { stage: "s0".into() },
                intent: LaneIntent::Events,
            },
            PlanConnection {
                from: PlanConnectionSource::StageOut { stage: "s0".into() },
                to: PlanConnectionDestination::StageIn { stage: "s1".into() },
                intent: LaneIntent::Events,
            },
            PlanConnection {
                from: PlanConnectionSource::StageOut { stage: "s1".into() },
                to: PlanConnectionDestination::BoundaryEgress { boundary: "out".into() },
                intent: LaneIntent::Events,
            },
        ],
        on_full: OnFullV1::Drop,
    }),
};

    Representative fit:

    • fanout and merge graphs,
    • branch-aware routing systems,
    • topology-first execution planning.

    Example 3: Rejected shape

    Use this example to understand what the validator rejects today.

    This SingleRing shape is invalid because strict ordering and shards > 1 do not belong together in the current v1 contract. The checked-in validator test uses shards=4; this shorter KV excerpt shows the same rejected rule.

    v=1
model=single_ring
single_ring.shards=2
single_ring.ordering=strict
single_ring.producer=single
single_ring.scheduling=dedicated
single_ring.shard_key=first_byte
single_ring.stages=1
stage.0.op=identity
stage.0.depends_on=

    How this maps to the central docs site

    This repo-owned guide is the canonical OSS worked-example anchor.

    For cross-layer product context, use the central docs site sections that own stack, runtime, and control-plane behavior:

    • /getting-started/ for stack composition and entry paths
    • /enterprise/ for runtime, governance, replay, and operator posture
    • /cloud/ for versions, deployments, approvals, agents, and replay workflow
    • /indexbus/ for transport patterns and runnable substrate examples

    The synced public mirror of this guide is intended to become the stable OSS-owned target for central examples pages that need one canonical repo reference.

    Provenance
    Need the canonical source?
    Use the public hub to orient yourself, then jump to repo-owned docs or rustdoc when you need contract-level detail.
    Reference hubSynced repo docs