Module flow 

Governed-conversation flow primitives: Flow, Step, Guard, FlowMonitor.

Modules

decided

The decided guard atom: a guard on what a decision model concluded about the conversation, rather than on a state key something else wrote.

stack

FlowStack — the runtime above the DAG: a main flow plus its digressions.

timing

Voice timing per stage: how the conversation sounds while a step is active.

verbatim

Verbatim stages: text the model must say word for word, verified.

Structs

CompiledFlow

A validated Flow plus its precomputed ToolSurface.

Decided

A guard on a decision: the question’s id and what is expected.

DecisionRecord

An answer as recorded in state under decision_key.

DecisionScope

See FlowStack::decision_scope.

Edge

A dependency edge into a step.

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.

FlowSnapshot

Observed governance state for a simulator, UI, or handoff.

FlowStack

The main flow plus its digressions, with push-on-trigger and resume-on-completion.

GuardTrace

A Guard evaluated to a truth tree: each predicate node with its prose description and whether it currently holds. Serializable, so a devtool can render exactly which atom a stuck step is waiting on.

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).

Overlay

A digression the runtime can enter: its trigger, governed flow and resume policy. Built from a compiled flow so it carries proof of compilation.

RepairPolicy

A step’s repair policy for the weird paths (silence, no-match, the user stalling). The stack sets repair:{step}:reprompt once the step has been active reprompt_after turns without completing, and repair:{step}:escalate after escalate_after. When escalate_to is set, the authoring layer lowers an extra edge gated on the escalate signal — a deterministic “give up and hand off”.

ResetBuilder

Intermediate for reset(steps).when(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 on_enter. 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.

ToolSurface

The precomputed tool surface of a compiled flow: every tool name the flow reasons about (step allow/deny, once, never…until, confirm), so introspection can enumerate and explain gating decisions. Distinct from tool::ToolPolicy, which is a per-tool runtime policy (timeout/cache/confirm).

VerbatimRequirement

The published requirement of the active verbatim stage.

Violation

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

VoiceTiming

Voice pacing for one stage. Every field is optional; an unset field leaves the session’s own behaviour alone.

Enums

Constraint

A cross-cutting flow constraint.

Enforcement

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

Expect

What a decided guard expects of an answer.

FlowError

A single problem found while compiling a Flow.

Guard

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

Join

How a step’s dependency edges combine.

Outcome

How an answer came out.

Pred

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

Resume

How the main flow continues after a digression (overlay) completes.

Verdict

The conformance status of a step.

Constants

DECISION_PREFIX

Prefix of the state keys answers are recorded under.

DECISION_TURN_KEY

The state key holding the caller turn answers are currently about.

DEFAULT_REPROMPT

The reprompt sent when a stage sets reprompt_after_ms but no text.

OVERLAY_STATE_KEY

The state key that names the active digression (null when the main flow is driving). Published by the control plane at every turn boundary.

TERMINATED_STATE_KEY

The state key raised (true) once a Resume::Terminate digression has ended the conversation. Governance is inert from then on: no postures, no admitted tools. The runtime does not hang up by itself — the application decides how a call ends — so watch this key (or FlowStack::is_terminated) and close the session. Published by the control plane at every turn boundary.

TOOL_CALL_KEY

Written when the governed flow admits a tool call, before it runs: {"tool": name, "id": call id}. With TOOL_DENIED_KEY and TOOL_RESULT_KEY it puts every governance decision about a tool in the mutation journal, in order, which is what makes a recorded session replayable as a scenario.

TOOL_DENIED_KEY

Written when the governed flow refuses a tool call: {"tool": name, "id": call id, "reason": why}.

TOOL_RESULT_KEY

Written when an admitted tool call completes: {"tool": name, "id": call id, "ok": succeeded}.

VERBATIM_KEY

The state key under which the active verbatim requirement is published.

VOICE_TIMING_KEY

The state key the active stage’s merged timing is published under.

Functions

correction_flag

The state key raised for one turn when the user corrects slot: its value changed from one captured value to another. See FlowStack::with_correction.

decision_key

The state key an answer to question is recorded under.

escalate_flag

The state key raised when a stage’s repair policy escalates.

on_enter

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

render_ground

Render a grounding template against state.

reprompt_flag

The state key raised when a stage’s repair policy asks for a reprompt.

verbatim_flag

The state key holding whether step’s text was said verbatim.

Type Aliases

SharedFlowMonitor

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

SharedFlowStack

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