Module flow 

Flow — a governed conversation/tool DAG.

A Flow is a directed acyclic graph of Steps. A Step is the only node type; it unifies “conversation stage” and “tool-call milestone” by differing only in attributes, not in kind. A step is done when its completion Guard latches true; edges (after) are dependencies. The FlowMonitor maintains a Marking (the set of done steps) by observing the session trace, projects active steps’ postures into turn-boundary steering, and enforces ordering by admitting/denying tool calls.

The vocabulary is deliberately closed (see the crate docs / RFC): the only nouns are Flow, Step, Guard, Posture, Marking, Verdict. Words like phase, transition, watch, needs are lowering details and never appear here.

Because every Guard atom is a named, parameterized predicate, a Flow is fully serializable — enabling data-driven scripts edited without a recompile. The custom closure escape hatch is available in code but is not serializable.

Structs

CompiledFlow

A validated Flow plus its precomputed ToolPolicy.

Flow

A governed conversation/tool DAG.

FlowBuilder

Builder for a Flow using the cemented verbs.

FlowCtx

Evaluation context handed to a Guard: the session state plus the current flow marking.

FlowErrors

All problems found while compiling a Flow; non-empty on failure.

FlowExplanation

A model-readable explanation of the current control-plane state — the foundation of why did the assistant ask that?.

FlowMonitor

Observes the session trace, maintains the Marking, answers tool admissibility, and projects active postures.

Marking

The runtime position in a flow: which steps are done and how often each tool has succeeded.

NeverBuilder

Sub-builder for never(tool).until(guard).

Step

A node in the flow DAG — the only node type.

StepAction

An action fired the first time a step becomes active: run an agent in an AgentMode. Built with run. The result lands in {name}:result (the name defaults to the step id), so a downstream step can complete on it via Guard::resolved — this is how a flow drives orchestration in-session.

ToolPolicy

The precomputed tool-gating surface of a compiled flow: every tool name the flow reasons about, so introspection can enumerate and explain decisions.

Violation

A recorded conformance deviation (observe mode) or denial (enforce mode).

Enums

Constraint

A cross-cutting flow constraint.

Enforcement

How a FlowMonitor treats off-path activity — enforcement vs observation.

FlowError

A single problem found while compiling a Flow.

Guard

A boolean predicate over (state, marking) — the only predicate type.

Pred

A serializable predicate atom — the closed set of guard primitives.

Verdict

The conformance status of a step.

Functions

render_ground

Render a grounding template against state.

run

Build a step-enter action that runs agent in mode when the step first activates. Pair with FlowMonitor::on_enter.

Type Aliases

ModeDeprecated

Deprecated alias for Enforcement, kept for one release.

SharedFlowMonitor

A shared, lock-protected FlowMonitor — the form in which the Live control plane owns a governed flow, so runtime surfaces (e.g. LiveHandle::why_blocked) can snapshot it concurrently. All monitor methods are synchronous: lock briefly and never hold the guard across an await.