phaselane

package
v0.85.0-pre.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 10, 2026 License: BSD-3-Clause Imports: 4 Imported by: 0

README

kit/phaselane

github.com/vormadev/vorma/kit/phaselane

Lightweight phase/lane orchestration with callback cells and explicit transition planning.

Use this package when you want:

  • dynamic phase count
  • dynamic lane count per phase
  • explicit phase barriers
  • detached (no-wait) lane work
  • centralized transition policies (advance, jump, loop-back, repeat, stop)
  • row-to-row awaited lane values

Import

import "github.com/vormadev/vorma/kit/phaselane"

Core Model

  • Plan.Phases is the ordered phase list.
  • each PhaseCell provides one Run callback.
  • awaited cells finish before transition planning.
  • detached cells return completion tickets and do not patch state.
  • each row exposes awaited lane outputs to the next row.

Quick Start

plan := phaselane.Plan{
	Phases: []phaselane.Phase{
		{
			ID: "facts",
			Cells: []phaselane.PhaseCell{
				{
					LaneID:   "main",
					WaitMode: phaselane.CellWaitModeAwaitCompletion,
					Run: func(
						run_context context.Context,
						input phaselane.CellRunInput,
					) (phaselane.CellRunResult, error) {
						_ = run_context
						_ = input
						return phaselane.CellRunResult{
							LaneValue: "facts_ready",
							StatePatch: map[string]any{
								"facts_done": true,
							},
						}, nil
					},
				},
			},
			TransitionPolicyID: "facts_to_done",
		},
		{
			ID: "done",
			Cells: []phaselane.PhaseCell{
				{
					LaneID:   "main",
					WaitMode: phaselane.CellWaitModeAwaitCompletion,
					Run: func(
						run_context context.Context,
						input phaselane.CellRunInput,
					) (phaselane.CellRunResult, error) {
						_ = run_context
						_ = input
						return phaselane.CellRunResult{}, nil
					},
				},
			},
			TransitionPolicyID: "stop",
		},
	},
	TransitionPlanner: phaselane.TransitionPlanner{
		Policies: map[string]phaselane.TransitionPolicy{
			"facts_to_done": {
				Rules: []phaselane.TransitionRule{
					{
						RuleID: "advance",
						Matches: func(input phaselane.TransitionPlanInput) bool {
							return true
						},
						Decision: phaselane.TransitionDecision{
							Kind: phaselane.DecisionKindAdvance,
						},
					},
				},
			},
			"stop": {
				Rules: []phaselane.TransitionRule{
					{
						RuleID: "stop",
						Matches: func(input phaselane.TransitionPlanInput) bool {
							return true
						},
						Decision: phaselane.TransitionDecision{
							Kind: phaselane.DecisionKindStop,
						},
					},
				},
			},
		},
	},
}

result, err := phaselane.Run(phaselane.ExecutionInput{
	Context: context.Background(),
	Plan:    plan,
	MaxSteps: 64,
})
if err != nil {
	return err
}

_ = result

Detached Lanes

Use CellWaitModeDetached for no-wait callbacks.

  • detached callbacks run asynchronously
  • each detached launch returns one DetachedLaneTicket
  • detached callbacks may not return StatePatch
  • pending detached lane counts are visible in CellRunInput.PendingDetachedByLane

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CellRunInput 

type CellRunInput struct {
	CurrentPhaseID        PhaseID
	CurrentPhaseIndex     int
	StepIndex             int
	StateSnapshot         map[string]any
	PreviousRowLaneValues map[LaneID]any
	PendingDetachedByLane map[LaneID]int
}

CellRunInput is the full per-cell callback input.

type CellRunResult 

type CellRunResult struct {
	LaneValue  any
	StatePatch map[string]any
}

CellRunResult is one cell callback output payload.

type CellRunner 

type CellRunner func(
	run_context context.Context,
	input CellRunInput,
) (CellRunResult, error)

CellRunner executes one phase/lane cell.

type CellWaitMode 

type CellWaitMode string

CellWaitMode controls whether lane work gates phase completion. 

const (
	// CellWaitModeAwaitCompletion means lane work must finish before transition
	// planning executes.
	CellWaitModeAwaitCompletion CellWaitMode = "await-completion"
	// CellWaitModeDetached means lane work is launched and not awaited by the
	// critical path.
	CellWaitModeDetached CellWaitMode = "detached"
)

type DecisionKind 

type DecisionKind string

DecisionKind selects the next control-flow move after a phase finishes. 

const (
	// DecisionKindAdvance moves to the next phase in Plan.Phases.
	DecisionKindAdvance DecisionKind = "advance"
	// DecisionKindJump moves to TransitionDecision.TargetPhaseID.
	DecisionKindJump DecisionKind = "jump"
	// DecisionKindLoopBack moves to an earlier TransitionDecision.TargetPhaseID.
	DecisionKindLoopBack DecisionKind = "loop-back"
	// DecisionKindRepeat reruns the current phase.
	DecisionKindRepeat DecisionKind = "repeat"
	// DecisionKindStop ends orchestration.
	DecisionKindStop DecisionKind = "stop"
)

type DetachedLaneTicket 

type DetachedLaneTicket struct {
	LaneID LaneID
	Done   <-chan error
}

DetachedLaneTicket is one detached lane execution handle.

type ExecutionInput 

type ExecutionInput struct {
	Context      context.Context
	Plan         Plan
	InitialState State
	StartPhaseID PhaseID
	MaxSteps     int
}

ExecutionInput carries everything required for one orchestration run.

type ExecutionResult 

type ExecutionResult struct {
	FinalState          State
	Steps               []ExecutionStep
	DetachedLaneTickets []DetachedLaneTicket
}

ExecutionResult is the full orchestration run output.

func Run 

func Run(
	input ExecutionInput,
) (ExecutionResult, error)

Run executes a dynamic phase/lane matrix with first-class transition planning.

type ExecutionStep 

type ExecutionStep struct {
	PhaseRunSummary    PhaseRunSummary
	TransitionDecision TransitionDecision
}

ExecutionStep captures one executed phase and its transition decision.

type LaneID 

type LaneID string

LaneID identifies one lane column in the phase/lane matrix.

type LaneRunSummary 

type LaneRunSummary struct {
	LaneID                LaneID
	WaitMode              CellWaitMode
	DetachedTicketPresent bool
	ProducedLaneValue     bool
}

LaneRunSummary describes one lane launch in one phase step.

type Phase 

type Phase struct {
	ID                 PhaseID
	Cells              []PhaseCell
	TransitionPolicyID string
}

Phase defines one phase row and its transition policy.

type PhaseCell 

type PhaseCell struct {
	LaneID   LaneID
	WaitMode CellWaitMode
	Run      CellRunner
}

PhaseCell defines one lane cell inside one phase.

type PhaseID 

type PhaseID string

PhaseID identifies one phase row in the phase/lane matrix.

type PhaseRunSummary 

type PhaseRunSummary struct {
	PhaseID               PhaseID
	LaneRuns              []LaneRunSummary
	AwaitedLaneValues     map[LaneID]any
	PendingDetachedByLane map[LaneID]int
}

PhaseRunSummary describes one phase step execution.

type Plan 

type Plan struct {
	Phases            []Phase
	TransitionPlanner TransitionPlanner
}

Plan is the dynamic phase/lane matrix and transition planning bundle.

type State 

type State struct {
	Values map[string]any
}

State carries mutable batch state used by cell callbacks and transition policies.

type TransitionDecision 

type TransitionDecision struct {
	Kind          DecisionKind
	TargetPhaseID PhaseID
}

TransitionDecision is one policy-selected next-step decision.

type TransitionPlanInput 

type TransitionPlanInput struct {
	PolicyID         string
	Plan             *Plan
	State            *State
	CurrentPhaseID   PhaseID
	CurrentPhaseStep PhaseRunSummary
	CurrentStepIndex int
}

TransitionPlanInput is the input contract for transition rule matching.

type TransitionPlanner 

type TransitionPlanner struct {
	Policies map[string]TransitionPolicy
}

TransitionPlanner resolves next-step transitions using named policies.

type TransitionPolicy 

type TransitionPolicy struct {
	Rules []TransitionRule
}

TransitionPolicy is one reusable transition rule set.

type TransitionRule 

type TransitionRule struct {
	RuleID   string
	Matches  func(input TransitionPlanInput) bool
	Decision TransitionDecision
}

TransitionRule is one ordered branch in a transition policy.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.