Module conversation 

The conversation compiler (Phase 1 MVP).

Authors describe a voice experience in terms of stages that say things, collect slots, commit tools behind confirmation, and advance via next transitions. A Conversation builder produces a serializable ConversationSpec (the single source of truth), and Conversation::compile lowers it to the governed CompiledFlow IR — so the high level is sugar over the low level, never a parallel runtime (see docs/plans/2026-06-06-conversation-compiler-rfc.md).

let convo = Conversation::new("booking")
    .stage("collect")
        .say("Help the user book a table.")
        .collect(["party_size", "slot"])
        .next("check", Guard::captured(["party_size", "slot"]))
    .stage("check")
        .ground("Party of {party_size} at {slot}.")
        .next("confirm", Guard::is_true("availability_ok"))
    .stage("confirm")
        .commit("book", Guard::is_true("user_confirmed"))
        .next("done", Guard::called_ok("book"))
    .stage("done").terminal()
    .require(["done"])
    .compile()?;
let mut monitor = convo.monitor(FlowMode::Enforce);

Lowering semantics (MVP)

• A stage lowers to a Flow Step. say → posture, ground → grounding template, allow → tool whitelist.
• commit(tool, when) gates a confirm-before-act tool (tool is auto-allowed in the stage).
• next(to, when) adds a forward edge: to depends on this stage (after) and its activation gate is when. Multiple incoming edges are an AND-join (all predecessors must complete) — richer topologies are Phase 3.
• A non-terminal stage’s completion is, in priority order: an explicit done, else captured(collect) when it collects slots, else the disjunction of its next conditions.

Structs

CommitSpec

A confirm-before-act tool, gated by when.

CompiledConversation

A compiled conversation: the validated main CompiledFlow, the extractors that fill its frames’ slots, any digressions, and the source spec.

CompiledOverlay

A compiled digression: its trigger, lowered flow, extractors, and resume policy.

Conversation

Fluent builder that produces a ConversationSpec; sugar over the spec.

ConversationSpec

The serializable authoring spec — the single source of truth from which the typed builder, YAML, and (later) codegen all derive.

FlowStack

The runtime above the DAG: the main flow plus its digressions, with push-on-trigger and resume-on-completion (MVP: nesting depth 1).

OverlaySpec

A digression (overlay): a named sub-flow that suspends the main flow when its trigger holds, runs to completion, then resumes per resume.

RepairPolicy

A stage’s repair policy for the weird paths (silence, no-match, the user stalling). The runtime sets repair:{stage}:reprompt once the stage has been active reprompt_after turns without completing, and repair:{stage}:escalate after escalate_after. When escalate_to is set, escalation also completes the stage and routes to that stage — a deterministic “give up and hand off”.

StageSpec

One authored conversation stage.

TransitionSpec

A transition: advance to to when when holds.

Enums

ConversationError

Error compiling a ConversationSpec into a CompiledConversation.

Resume

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