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 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 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 on_tool_ok(&mut self, tool: &str, state: &State)

Record a successful tool call, then re-latch.

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