flow

type Cache struct {
	TTL Duration `yaml:"ttl" json:"ttl"`
}

type Channel struct {
	// Reducer folds writes: replace (default), append, merge or sum.
	Reducer string `yaml:"reducer,omitempty" json:"reducer,omitempty"`
	// Default is the initial value.
	Default any `yaml:"default,omitempty" json:"default,omitempty"`
}

type Concurrency struct {
	Key string `yaml:"key" json:"key"`
	Max int    `yaml:"max" json:"max"`
}

type Duration time.Duration

type Flow struct {
	Version     string `yaml:"version,omitempty" json:"version,omitempty"`
	Name        string `yaml:"name" json:"name"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	// Start names the entry node. When empty, the entry node is the unique node
	// with no inbound transition.
	Start string `yaml:"start,omitempty" json:"start,omitempty"`
	// Channels declares the typed state of the flow. Nodes write deltas to
	// channels and each channel folds them with its reducer.
	Channels map[string]Channel `yaml:"channels,omitempty" json:"channels,omitempty"`
	// Output is an expression, evaluated on the context when the execution
	// completes, that yields its output: an object or null. It picks what the
	// execution returns, e.g. "{answer: channels.answer}" to keep working
	// memory out, or "results[last_node]" for the last node's result. When
	// empty the output is every channel, or the last node's result if the flow
	// declares no channels.
	Output string `yaml:"output,omitempty" json:"output,omitempty"`
	Nodes  []Node `yaml:"nodes" json:"nodes"`
	// Budget caps generic usage counters reported by workers (and the
	// built-in "steps" counter): exceeding one fails the execution with reason
	// budget_exceeded.
	Budget map[string]float64 `yaml:"budget,omitempty" json:"budget,omitempty"`
	// MaxSteps is the recursion limit (total node entries); 0 = DefaultMaxSteps.
	MaxSteps int `yaml:"max_steps,omitempty" json:"max_steps,omitempty"`
	// SearchAttributes are expressions evaluated on the start input and
	// indexed for List/Query.
	SearchAttributes map[string]string `yaml:"search_attributes,omitempty" json:"search_attributes,omitempty"`
	// Retention is how long a terminal execution is kept before it expires
	// (0 = forever). What happens then is OnExpire.
	Retention Duration `yaml:"retention,omitempty" json:"retention,omitempty"`
	// OnExpire is what expiry does to the execution: ExpireArchive (the
	// default) moves it to the archive, where it stays readable; ExpireDelete
	// removes it for good, archive included. It needs a Retention.
	OnExpire string `yaml:"on_expire,omitempty" json:"on_expire,omitempty"`
	// ArchiveRetention deletes an archived execution this long after it was
	// archived, by Retention or by hand (0 = keep the archive forever). It
	// does not apply with ExpireDelete, which leaves no archive.
	ArchiveRetention Duration `yaml:"archive_retention,omitempty" json:"archive_retention,omitempty"`
	// Triggers start this flow when a message arrives on a subject.
	Triggers []Trigger `yaml:"triggers,omitempty" json:"triggers,omitempty"`
	// contains filtered or unexported fields
}

type Node struct {
	ID   string `yaml:"id" json:"id"`
	Type string `yaml:"type" json:"type"`
	// Next is the static successor. Empty on a terminal node.
	Next string `yaml:"next,omitempty" json:"next,omitempty"`
	// OnFailure routes a permanent failure of the node (task, map, subflow,
	// join) to another node instead of failing the execution: retries
	// exhausted, a permanent error, an invalid output, a failed child, a join
	// whose policy was not met. The handler sees errors.<node>.
	OnFailure string `yaml:"on_failure,omitempty" json:"on_failure,omitempty"`
	// Meta is free-form configuration for whoever runs or shows the node: the
	// engine ignores it, but it is part of the definition, so it is versioned
	// with the flow hash and handed to the worker of each job (Job.Meta). It
	// must encode as JSON.
	Meta map[string]any `yaml:"meta,omitempty" json:"meta,omitempty"`

	// task, map: the worker kind and per-attempt policies.
	Kind         string       `yaml:"kind,omitempty" json:"kind,omitempty"`
	Timeout      Duration     `yaml:"timeout,omitempty" json:"timeout,omitempty"`
	Retry        *Retry       `yaml:"retry,omitempty" json:"retry,omitempty"`
	OutputSchema any          `yaml:"output_schema,omitempty" json:"output_schema,omitempty"`
	Cache        *Cache       `yaml:"cache,omitempty" json:"cache,omitempty"`
	Concurrency  *Concurrency `yaml:"concurrency,omitempty" json:"concurrency,omitempty"`
	// Dynamic lists the nodes a task worker may route to by returning `next`
	// (dynamic edges, LangGraph Command(goto)).
	Dynamic []string `yaml:"dynamic,omitempty" json:"dynamic,omitempty"`

	// choice
	Rules   []Rule `yaml:"rules,omitempty" json:"rules,omitempty"`
	OnError string `yaml:"on_error,omitempty" json:"on_error,omitempty"`

	// fanout
	Branches []string `yaml:"branches,omitempty" json:"branches,omitempty"`

	// join
	WaitFor []string `yaml:"wait_for,omitempty" json:"wait_for,omitempty"`
	Policy  string   `yaml:"policy,omitempty" json:"policy,omitempty"`

	// await (Timeout is required)
	Signal    string `yaml:"signal,omitempty" json:"signal,omitempty"`
	OnTimeout string `yaml:"on_timeout,omitempty" json:"on_timeout,omitempty"`

	// map
	Over        string `yaml:"over,omitempty" json:"over,omitempty"`
	MaxParallel int    `yaml:"max_parallel,omitempty" json:"max_parallel,omitempty"`

	// subflow
	Flow          string `yaml:"flow,omitempty" json:"flow,omitempty"`
	Input         string `yaml:"input,omitempty" json:"input,omitempty"`
	OnParentClose string `yaml:"on_parent_close,omitempty" json:"on_parent_close,omitempty"`
	// contains filtered or unexported fields
}

type Retry struct {
	// MaxAttempts is the total number of attempts (1 = no retry).
	MaxAttempts int      `yaml:"max_attempts" json:"max_attempts"`
	Backoff     string   `yaml:"backoff,omitempty" json:"backoff,omitempty"`
	Delay       Duration `yaml:"delay,omitempty" json:"delay,omitempty"`
	MaxDelay    Duration `yaml:"max_delay,omitempty" json:"max_delay,omitempty"`
}

type Rule struct {
	When    string `yaml:"when,omitempty" json:"when,omitempty"`
	Default bool   `yaml:"default,omitempty" json:"default,omitempty"`
	// To is the node the rule routes to, or End to complete the execution.
	To string `yaml:"to" json:"to"`
}

type Trigger struct {
	Subject string `yaml:"subject" json:"subject"`
	Stream  string `yaml:"stream,omitempty" json:"stream,omitempty"`
}

type ValidationError struct {
	// Flow is the name of the flow being validated.
	Flow string
	// Node is the id of the node at fault, as written; empty for a
	// flow-level problem.
	Node string
	// Field is the YAML path of the offending field inside Node, or inside
	// the flow when Node is empty: "retry.max_attempts", "rules[1].when",
	// "channels.c.reducer", "start". Empty when no single field applies.
	Field string
	// Msg describes the problem, without the flow, node and field.
	Msg string
	// Err is the underlying cause (an invalid name, an expression or schema
	// compile error), or nil.
	Err error
}