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