Module stack 

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

A FlowMonitor governs one Flow. Real conversations leave the main task temporarily — a side question, a cancel, a hand-off — and expect to come back to it. A FlowStack holds the main monitor plus a set of Overlays (digressions): when an overlay’s trigger holds, the main flow is suspended untouched, the overlay’s own monitor drives the session until it completes, and the main flow then continues per the overlay’s Resume policy.

This is the only governance object the Live control plane drives. A session governed by a bare flow is a stack with no overlays, so every execution path — the simulator, a live session, a replay — advances the same type with the same semantics. The authoring layer lowers a conversation into a stack; it does not implement one.

Digressions nest: a digression can itself be interrupted by another (one not already on the active path), which drives until it completes and then resumes the one beneath it per its own Resume policy.

Structs

FlowStack

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

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

Enums

Resume

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

Constants

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

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.

escalate_flag

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

reprompt_flag

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

Type Aliases

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.