Struct FlowStack 

pub struct FlowStack { /* private fields */ }

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

While a digression is active, governance — tool admission, postures and grounds, explain() — delegates to the active layer, and the main flow’s marking is untouched, so Resume::Previous resumes exactly where it left off. Driven by State and guards: model-free and deterministic.

A digression stays the active layer through the turn on which it completes, so that turn’s projection carries its closing instruction (the terminal stage’s posture — “hand off to a human now”), and its Resume policy applies at the next turn boundary. Without that, a digression that completes on its entry turn would never be seen at all.

Implementations

impl FlowStack

pub fn new(main: CompiledFlow, mode: Enforcement) -> FlowStack

A stack over a compiled main flow with no digressions yet.

pub fn from_monitor(main: FlowMonitor) -> FlowStack

A stack whose main layer is an existing monitor (keeps its on_enter actions and mode). This is how a bare governed flow becomes the one governance object the control plane drives.

pub fn with_overlay(self, overlay: Overlay) -> FlowStack

Add a digression.

pub fn with_overlays( self, overlays: impl IntoIterator<Item = Overlay>, ) -> FlowStack

Add several digressions, in trigger-priority order.

pub fn with_ambient_tools( self, tools: impl IntoIterator<Item = String>, ) -> FlowStack

Admit installed service tools in the main flow and every digression. Tool-specific constraints still apply. Call this after adding overlays when constructing a stack, before it starts processing events.

pub fn with_repair( self, step: impl Into<String>, policy: RepairPolicy, ) -> FlowStack

Attach a repair policy to a main-flow step.

pub fn with_repairs( self, policies: impl IntoIterator<Item = (String, RepairPolicy)>, ) -> FlowStack

Attach repair policies keyed by main-flow step.

pub fn with_correction( self, slot: impl Into<String>, clear: impl IntoIterator<Item = String>, ) -> FlowStack

Watch slot for corrections: when its value changes from one captured value to another, correction_flag(slot) is raised for that turn and clear keys are removed from state.

Raising the flag does nothing by itself. The main flow reacts through a Constraint::Reset gated on it, which un-latches the stages downstream of the slot so they run again with the corrected value. A Conversation lowers exactly that for every collected slot, clearing the confirmation of any commit stage it re-opens.

pub fn with_corrections( self, corrections: impl IntoIterator<Item = (String, Vec<String>)>, ) -> FlowStack

Watch several slots; see with_correction.

pub fn correction_policies(&self) -> &BTreeMap<String, Vec<String>>

The watched slots and the keys each correction clears.

pub fn with_verbatim( self, step: impl Into<String>, text: impl Into<String>, ) -> FlowStack

Require step to say text word for word; see verbatim. The stack publishes the requirement while the step is active. Its completion guard must also require verbatim_flag(step), which a Conversation lowers for you.

pub fn with_verbatims( self, texts: impl IntoIterator<Item = (String, String)>, ) -> FlowStack

Verbatim requirements keyed by step.

pub fn verbatim_policies(&self) -> &BTreeMap<String, String>

The verbatim requirements keyed by step.

pub fn with_timing( self, step: impl Into<String>, timing: VoiceTiming, ) -> FlowStack

Attach voice timing to a step (main flow or digression).

pub fn with_timings( self, timings: impl IntoIterator<Item = (String, VoiceTiming)>, ) -> FlowStack

Attach voice timing keyed by step.

pub fn timing_policies(&self) -> &BTreeMap<String, VoiceTiming>

The voice timing keyed by step.

pub fn active_timing(&self, state: &State) -> VoiceTiming

The merged timing of the steps active right now in the driving layer (empty when none of them has timing, or the conversation is over).

pub fn publish_timing(&self, state: &State)

Publish active_timing to VOICE_TIMING_KEY in state, where the runtime’s audio path, timers and turn lifecycle read it. Writes only on change; removes the key when no timing applies. The stack calls this itself after every turn and tool call; call it once when installing the stack.

pub fn into_shared(self) -> Arc<Mutex<RawMutex, FlowStack>>

Wrap in a SharedFlowStack for shared ownership between the control lane (which advances it) and runtime accessors (which snapshot it).

pub fn mode(&self) -> Enforcement

The enforcement mode (shared by every layer).

pub fn overlays(&self) -> &[Overlay]

The digressions this stack can enter, in trigger-priority order.

pub fn overlays_mut(&mut self) -> &mut [Overlay]

Mutable access to the digressions, for connect-time merges.

pub fn repair_policies(&self) -> &BTreeMap<String, RepairPolicy>

The repair policies keyed by main-flow step.

pub fn main(&self) -> &FlowMonitor

The main flow’s monitor, whether or not it is currently driving.

pub fn current(&self) -> &FlowMonitor

The monitor currently driving — the active digression if any, else the main flow.

pub fn active_overlay(&self) -> Option<&str>

The name of the driving digression, if one is suspending the main flow.

pub fn overlay_path(&self) -> Vec<&str>

Every active digression, outermost first: a digression can itself be interrupted by another, which then drives until it completes.

pub fn is_complete(&self) -> bool

Whether the conversation is finished (main complete, or a Terminate digression ran).

pub fn is_terminated(&self) -> bool

Whether a Terminate digression ended the conversation. From then on the stack governs nothing: no active steps or postures, every tool denied. The runtime does not close the session by itself; the application reads this (or TERMINATED_STATE_KEY) and hangs up.

pub fn on_interrupted(&mut self, state: &State)

Count a barge-in against every active main step and escalate those whose policy’s escalate_after_interruptions is reached. Called by the control plane when the user interrupts the model.

pub fn on_tool_failed(&mut self, state: &State)

Count a failed (or timed-out) tool call against every active main step and escalate those whose policy’s escalate_after_tool_failures is reached.

pub fn on_turn(&mut self, state: &State)

Advance one turn.

A digression that completed on the previous turn has had its closing turn projected; its resume policy applies now, and the turn then proceeds as if the main flow had been driving all along (a new digression may trigger, or the main flow advances). Otherwise: advance the active digression, enter a triggered one (suspending the main flow), or advance the main flow.

pub fn on_turn_counted(&mut self, state: &State, counted: bool)

Advance one turn, saying whether it counts toward repair thresholds.

A turn the caller had no part in, such as the greeting or the model speaking a tool’s result, is not a stall: with counted false the flow advances as usual but no step’s reprompt_after / escalate_after count moves.

pub fn on_tool_ok(&mut self, tool: &str, state: &State)

Record a successful tool call against the active layer. A no-op once the conversation has been terminated: nothing is governing, so there is no marking for the call to advance. (In Enforce the call is denied before it runs; in Observe it runs but must not move a flow that has ended.)

A tool can itself fire a reset (reset(..).when(called_ok(..))), so the main layer sheds the repair signals of whatever that un-latches, exactly as the main layer does at a turn boundary. Repair is tracked for the main flow only, so a digression just delegates.

pub fn observe_tool(&mut self, tool: &str, ok: bool, state: &State)

Observe a tool call for conformance against the active layer (see FlowMonitor::observe_tool).

After termination nothing is advanced, but in Observe the call is still recorded as a deviation: a tool used after the conversation ended is exactly what that mode exists to catch, and the monitor cannot see it for itself because the denial is the stack’s, not the flow’s.

pub fn admits_tool(&self, tool: &str, state: &State) -> Result<(), String>

Whether tool is admitted right now (delegates to the active layer). Every tool is denied once the conversation has been terminated.

pub fn offers_tool(&self, tool: &str, state: &State) -> bool

Whether the active layer would admit tool once its never(tool).until(..) guards hold (see FlowMonitor::offers_tool). Nothing is offered after termination.

pub fn blocking_keys(&self, tool: &str, state: &State) -> BTreeSet<String>

The state keys read by the guards that refuse tool in the active layer right now (see FlowMonitor::blocking_keys).

pub fn explain(&self, state: &State) -> FlowExplanation

Explain the active layer’s control-plane state. After termination: nothing active, nothing admitted, every tool blocked with the reason — the conversation is over, so it is waiting for nothing. To ask instead what it never finished, read main(): its marking and unmet_requirements() are kept intact for exactly that audit.

pub fn snapshot(&self, state: &State) -> FlowSnapshot

Observe the current layer and whole-stack lifecycle together.

Callers holding a shared stack lock get one consistent marking and overlay path. Guard evaluation reads State, which may change independently; this is not a transaction across all session state.

pub fn decision_scope(&self, state: &State) -> DecisionScope

What a decision model should be asked now: the questions named by the driving layer’s guards and by the triggers of the digressions that can still be entered, and the state keys the driving layer could act on (for decisions that write a key). Empty after termination.

pub fn gate_scope(&self, tools: &[String], state: &State) -> DecisionScope

What decides whether tools are admitted now: the questions in the driving layer’s never(tool).until(..) guards on them (a stage’s commit), in the way of the frontier steps that allow one, and in the triggers of the digressions that would admit one of them, with the state keys those guards read. A call no decision governs gets an empty scope, so it is not held up by a decision round.

pub fn on_decisions(&mut self, state: &State)

Apply fresh decisions mid-turn: enter a digression whose trigger now holds, or re-evaluate the driving layer. Counts no turn and advances no repair policy, so it can run before a tool call is admitted: a caller who asks for a person and a model that transfers in the same turn then see the transfer counted inside the handoff digression.

pub fn relatch(&mut self, state: &State)

Re-evaluate the current layer after directly setting state.

This does not count a turn, trigger or resume digressions, or advance repair policies. Use on_turn for a user turn.

pub fn marking(&self) -> &Marking

The active layer’s marking (the last driving layer’s, after termination — kept for audit).

pub fn active_steps(&self, state: &State) -> Vec<&Step>

Steps of the active layer that are eligible but not yet done. Empty after termination.

pub fn active_postures(&self, state: &State) -> Vec<String>

Postures to project this turn: the active layer’s active steps’, or — on the turn a digression completes — its closing steps’ (see FlowMonitor::closing_postures). Empty after termination.

pub fn active_grounds(&self, state: &State) -> Vec<String>

Grounding lines to project this turn, chosen like active_postures.

pub fn unmet_requirements(&self) -> Vec<String>

The active layer’s unmet requirements. Empty after termination.

pub fn take_newly_active(&mut self, state: &State) -> Vec<String>

Steps of the active layer that became active since the last call.

pub fn enter_action(&self, step: &str) -> Option<&StepAction>

The on_enter action registered for a step of the active layer.

pub fn set_posture(&mut self, step_id: &str, posture: Option<String>) -> bool

Replace a main-flow step’s posture. Returns true when the step exists.

pub fn set_ground(&mut self, step_id: &str, ground: Option<String>) -> bool

Replace a main-flow step’s grounding template. Returns true when the step exists.

Trait Implementations

impl Debug for FlowStack

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.