Baton.Flow.Binding (Baton v0.27.4)

Copy Markdown View Source

Resolves portable flow bindings against a JSON-compatible runtime environment.

Bindings are deliberately small: an expression is a $-prefixed dotted path rooted at one of five roots. Maps and lists are traversed recursively, so a node can declare an entire input object without executable code in its persisted definition.

  • $input.… — the caller's input map, frozen at compile time.
  • $context.… — the context provider's output, frozen at compile time.
  • $steps.<node_id>.… — an upstream node's result. Only available at runtime, and Baton.Flow.Validator requires <node_id> to be one of the reading node's declared deps, so a binding can never bypass dependency gating. Naming a node that fanned out reads the whole expansion: its results as a list, in expansion order (see Baton.Flow.Runtime).
  • $run.… — run metadata (workflow_id, definition_ref). Runtime only.
  • $item.… — the current item of a fan-out expansion. Bound only while a Baton.Flow.FanOutSpec is being expanded, and on the expanded node at runtime.

Bindings are not confined to a node's bindings map: an LLM node's model resolves through here too, so $item.model gives each node of a fan-out its own model and $input.model defers the choice to the caller.

A path segment applied to a list maps over its elements rather than failing: $steps.review.data on a fanned-out review returns each expansion's data, in order. The mapping is strict — if any element is missing the segment the whole expression is :binding_not_found, so a typo cannot silently yield a short list.

Two environments resolve these. Baton.Flow.Compiler builds a compile-time environment in which steps and run are empty — which is why a fan-out collection must be rooted at $input. or $context., the only roots populated when expansion decides how many nodes to create. Baton.Flow.Runtime.environment/1 rebuilds the full environment per job.

Summary

Functions

Return all binding expressions nested in a value.

Resolve one binding expression against environment.

Resolve every binding expression nested in maps and lists; literals pass through.

Types

error()

@type error() ::
  {:invalid_binding, String.t()}
  | {:unknown_binding_root, String.t()}
  | {:binding_not_found, String.t()}

Functions

expressions(expression)

@spec expressions(term()) :: [String.t()]

Return all binding expressions nested in a value.

resolve(expression, environment)

@spec resolve(String.t(), map()) :: {:ok, term()} | {:error, error()}

Resolve one binding expression against environment.

resolve_value(expression, environment)

@spec resolve_value(term(), map()) :: {:ok, term()} | {:error, error()}

Resolve every binding expression nested in maps and lists; literals pass through.