Struct FlowMonitor 

pub struct FlowMonitor { /* private fields */ }

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

Implementations

impl FlowMonitor

pub fn new(flow: Flow, mode: Enforcement) -> Self

Create a monitor for a (presumed-valid) flow.

Prefer FlowMonitor::compiled or FlowMonitor::try_new, which carry proof of compilation; this convenience skips compilation for flows already known valid (e.g. built in-process by trusted code).

pub fn compiled(flow: CompiledFlow, mode: Enforcement) -> Self

Create a monitor from a CompiledFlow — the validated path.

pub fn try_new(flow: Flow, mode: Enforcement) -> Result<Self, FlowErrors>

Compile flow and create a monitor, surfacing structural errors instead of trusting the caller.

pub fn into_shared(self) -> SharedFlowMonitor

Wrap this monitor in a SharedFlowMonitor for shared ownership between the control lane (which advances it) and runtime accessors (which snapshot it, e.g. LiveHandle::explain).

pub fn into_stack(self) -> FlowStack

Wrap this monitor as the main layer of a FlowStack with no digressions — the form the Live control plane drives.

pub fn restart(&mut self)

Re-enter the flow from its start: forget the marking, the fired on_enter actions and the reset edges. The flow, mode and registered actions are kept, and recorded violations stay for audit. State is not touched — the next re-latch runs against whatever facts it holds.

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

Explain the current control-plane state: active steps, which tools are admitted vs blocked (with reasons), and unmet requirements.

This is the deterministic answer to “why did the assistant ask that?” — model-readable, without the model driving control flow.

pub fn on_enter(self, step: impl Into<String>, action: StepAction) -> Self

Attach an action fired the first time step becomes active (see on_enter). Chainable at construction time.

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

Steps that became active since the last call — each reported exactly once over the session. Drives on_enter firing.

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

The enter-action registered for a step, if any.

pub async fn fire_enter_actions(&mut self, state: &State)

Fire enter-actions for every step that just became active. Convenience over take_newly_active + enter_action; call it right after on_turn.

pub fn mode(&self) -> Enforcement

The enforcement mode this monitor runs in.

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

Replace a step’s posture in place. Returns false if no such step.

Postures are re-projected at every turn boundary, so an edit takes effect on the next turn — the safe subset of live spec editing. The DAG, guards, and tool gates are structural and stay fixed.

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

Replace a step’s grounding template in place. Returns false if no such step. Same next-turn semantics as set_posture.

pub fn eval(&self, guard: &Guard, state: &State) -> bool

Evaluate a Guard against this monitor’s current context (the given state plus the monitor’s marking). Used to test overlay/digression triggers without exposing the internal context.

pub fn marking(&self) -> &Marking

The current marking.

pub fn violations(&self) -> &[Violation]

Recorded violations.

pub fn record_violation( &mut self, subject: impl Into<String>, reason: impl Into<String>, )

Record a deviation the caller detected — one this monitor cannot see for itself. A FlowStack uses it for a tool called after a Resume::Terminate digression ended the conversation: the denial is the stack’s, not this flow’s, so observe_tool would find nothing wrong.

pub fn flow(&self) -> &Flow

The underlying flow.

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

Re-evaluate completion latches to a fixpoint. Call after any event that can change state or the marking (turn boundary, tool completion).

Constraint::Reset constraints are applied first, on their guard’s rising edge: the named steps un-latch, their on_enter re-arms, and the called_ok evidence their completion guards reference is forgiven — the loop primitive over an otherwise monotonic marking.

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

Record a turn boundary, then re-latch.

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

The first half of on_turn: count the turn and apply Constraint::Reset edges, returning the steps that were un-latched.

A caller that keeps evidence about steps outside the marking — the FlowStack and its repair signals — needs to see a reset before the re-latch runs, or a completion guard that references that evidence re-completes the step on the spot. Follow with relatch; the reset edges are consumed, so the re-latch does not apply them twice.

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

Record a successful tool call, then re-latch.

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

The first half of on_tool_ok: count the call and apply Constraint::Reset edges, returning the steps that were un-latched.

A reset can be gated on a tool — reset(..).when(called_ok("start_over")) — in which case its edge fires here rather than at a turn boundary. A caller holding evidence outside the marking needs the same chance to shed it that begin_turn gives; follow with relatch.

pub fn reads_now(&self, state: &State) -> BTreeSet<String>

The state keys the flow could act on now: those read by the active steps’ gates and done guards, by the edges leaving them, and by the constraints. A decision that writes one of these is worth asking.

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

Steps that are eligible but not yet done.

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

Postures of the active steps — to inject as turn-boundary steering.

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

Rendered grounding lines of the active steps — curated, State- interpolated facts to inject as turn-boundary steering (anti-hallucination).

pub fn closing_steps(&self) -> Vec<&Step>

Terminal steps that are done — the flow’s closing.

A terminal step completes on eligibility, so it is never active and its posture is never among active_postures. Its instruction is the flow’s last word (“hand off to a human now”), which the FlowStack projects on the turn a digression completes.

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

Postures of the closing_steps.

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

Rendered grounding lines of the closing_steps.

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

Required steps not yet done (drives repair).

pub fn is_complete(&self) -> bool

Whether all required steps are done.

pub fn verdict(&self, step_id: &str, state: &State) -> Verdict

The conformance verdict for a step.

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

Decide whether a tool call may proceed. Ok(()) admits it; Err(reason) denies it (the caller blocks in Enforce mode, or records in Observe).

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

Whether tool would be admitted once every never(tool).until(..) guard on it holds: the active steps allow it and it has not used up a once, or a frontier step allows it. Under ContextUpdate steering the model is offered these tools, so that it can call one in the turn its guard comes to hold or its step opens; the call itself is still decided by admits_tool.

pub fn possible(&self, guard: &Guard, state: &State) -> Option<bool>

Evaluate guard as the caller’s next words could leave it, against this flow’s marking. See Guard::possible.

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

The steps one decision away: neither done nor active, but able to become active in the caller’s next turn because what stands in their way is a decided atom, in their gate, an incoming edge, or the done guard of the active step they follow.

A decision made after the caller’s turn ends cannot change the tools the model has for that turn: measured on Gemini 3.8 Live, a tool declared even 0 ms after the turn ended was not used in that turn’s reply (0 of 15), while one declared before it was (5 of 5). So under ContextUpdate steering these steps’ tools are offered ahead, and a call to one is decided at the gate: the questions in its way (frontier_questions) are asked about the turn in progress, the flow relatches, and the call is admitted only if the step opened.

pub fn frontier_questions(&self, tool: &str, state: &State) -> DecisionScope

The questions that decide whether a frontier step allowing tool opens, with the state keys their guards read: the step’s gate, its incoming edges, and the done guards of the active steps it follows. Empty when no frontier step allows tool.

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

The state keys read by the never(tool).until(..) guards that refuse tool right now. Empty when no such guard is refusing it.

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

Observe a tool call for conformance. In Enforce mode the caller has already gated via admits_tool; this records the call and, in Observe mode, logs a deviation if it was inadmissible.