gemini_adk_fluent_rs/spec/

codegen.rs

//! Generate a standalone Rust application from a [`SessionSpec`].
//!
//! Because L2 never invents runtime semantics — every spec field lowers to a
//! builder method — code generation is *pretty-printing*, not compilation:
//! [`SessionSpec::to_rust`] emits the fluent `Live::builder()` chain the
//! document is equivalent to, as a complete `main.rs` (with a matching
//! `Cargo.toml` from [`SessionSpec::to_cargo_toml`]). The Studio's **Code**
//! tab serves both: draw the flow, read the program; edit the JSON, the
//! program follows.

use std::fmt::Write as _;

use gemini_adk_rs::flow::{Constraint, Flow, Guard, Pred};
use serde_json::Value;

use super::{
    ContextDeliverySpec, EffectSpec, PersistenceSpec, PromotePolicy, RuntimeSpec, SessionSpec,
    SpecModality, StateType, SteeringSpec, ToolSpec, TriggerSpec, WatchCondition,
};

impl SessionSpec {
    /// The complete `main.rs` this spec is equivalent to.
    pub fn to_rust(&self) -> String {
        let mut out = String::new();
        let name = if self.name.is_empty() {
            "app"
        } else {
            &self.name
        };
        let _ = writeln!(
            out,
            "//! {name} — generated by Flow Studio from a SessionSpec."
        );
        if !self.description.is_empty() {
            let _ = writeln!(out, "//! {}", self.description);
        }
        out.push_str("//!\n//! The chain below is exactly what the JSON document lowers to;\n");
        out.push_str("//! edit either — they stay equivalent.\n\n");
        out.push_str("use serde_json::json;\n");
        out.push_str("use gemini_adk_fluent_rs::prelude::*;\n");
        if !self.extract.is_empty() {
            out.push_str(
                "use gemini_adk_fluent_rs::gemini_adk_rs::live::extractor::{\n    \
                 ExtractionTrigger, FieldPromotion, LlmExtractor,\n};\n",
            );
        }
        if !self.computed.is_empty() {
            out.push_str("use gemini_adk_fluent_rs::gemini_adk_rs::expr::Expr;\n");
        }
        if let Some(runtime) = &self.runtime {
            let mut live_imports = Vec::new();
            if runtime.steering.is_some() {
                live_imports.push("SteeringMode");
            }
            if runtime.context_delivery.is_some() {
                live_imports.push("ContextDelivery");
            }
            if runtime.repair.is_some() {
                live_imports.push("RepairConfig");
            }
            match runtime.persistence {
                Some(PersistenceSpec::Fs { .. }) => live_imports.push("FsPersistence"),
                Some(PersistenceSpec::Memory) => live_imports.push("MemoryPersistence"),
                None => {}
            }
            if !live_imports.is_empty() {
                let _ = writeln!(
                    out,
                    "use gemini_adk_fluent_rs::live::{{{}}};",
                    live_imports.join(", ")
                );
            }
        }
        if self.memory.is_some() {
            out.push_str("use gemini_memory_rs::prelude::*;\n");
            out.push_str("use gemini_memory_rs::runtime::LiveMemoryExt;\n");
        }
        let needs_arc = !self.extract.is_empty()
            || self.memory.is_some()
            || self
                .runtime
                .as_ref()
                .is_some_and(|r| r.persistence.is_some());
        if needs_arc {
            out.push_str("use std::sync::Arc;\n");
        }
        out.push('\n');
        if !self.state.is_empty() {
            out.push_str(&gen_state_keys(&self.state));
            out.push('\n');
        }
        out.push_str(
            "#[tokio::main]\nasync fn main() -> Result<(), Box<dyn std::error::Error>> {\n",
        );
        out.push_str("    let state = State::new();\n");
        for (key, field) in &self.state {
            if let Some(default) = &field.default {
                let _ = writeln!(
                    out,
                    "    let _ = state.set({}, json!({}));",
                    rust_str(key),
                    compact(default)
                );
            }
        }
        out.push('\n');
        if self.memory.is_some() {
            out.push_str("    // ── Memory ─────────────────────────────────────────────\n");
            out.push_str(
                "    // In-process engine for local runs; swap the repository and event\n    \
                 // log for durable backends in production.\n",
            );
            out.push_str(
                "    let memory_engine = MemoryEngine::in_memory(UserId::new(\"local-user\"));\n",
            );
            out.push_str(
                "    let memory = Arc::new(memory_engine.begin_session(SessionId::new(\
                 \"session-1\")));\n\n",
            );
        }

        if !self.tools.is_empty() {
            out.push_str("    // ── Tools ──────────────────────────────────────────────\n");
            out.push_str("    let mut tools = ToolDispatcher::new();\n");
            for tool in &self.tools {
                out.push_str(&gen_tool(tool));
            }
            out.push('\n');
        }

        let flow = self.effective_flow().unwrap_or_default();
        if !flow.steps.is_empty() {
            out.push_str("    // ── Governed flow ──────────────────────────────────────\n");
            out.push_str(&gen_flow(&flow));
            out.push('\n');
        }

        out.push_str("    // ── Session ────────────────────────────────────────────\n");
        out.push_str("    let session = Live::builder()\n");
        let instruction = if self.instruction.is_empty() {
            "Follow the conversation flow you are given."
        } else {
            &self.instruction
        };
        let _ = writeln!(out, "        .instruction({})", rust_str(instruction));
        if let Some(greeting) = &self.greeting {
            let _ = writeln!(out, "        .greeting({})", rust_str(greeting));
        }
        match self.modality {
            SpecModality::Text => out.push_str("        .text_only()\n"),
            SpecModality::Audio => {
                let voice = self.voice.as_deref().unwrap_or("Puck");
                let known = ["Puck", "Aoede", "Charon", "Fenrir", "Kore"];
                if known.contains(&voice) {
                    let _ = writeln!(out, "        .voice(Voice::{voice})");
                } else {
                    let _ = writeln!(
                        out,
                        "        .voice(Voice::Custom({}.into()))",
                        rust_str(voice)
                    );
                }
            }
        }
        out.push_str("        .state(state.clone())\n");
        if !self.tools.is_empty() {
            out.push_str("        .dispatcher(tools)\n");
        }
        for params in &self.mcp {
            let _ = writeln!(out, "        .tools(T::mcp({}))", rust_str(params));
        }
        if !flow.steps.is_empty() {
            out.push_str("        .govern(flow)\n");
        }
        for computed in &self.computed {
            out.push_str(&gen_computed(computed));
        }
        if let Some(memory) = &self.memory {
            if memory.slots.is_empty() {
                out.push_str("        .with_memory(memory.clone())\n");
            } else {
                let slots: Vec<String> = memory
                    .slots
                    .iter()
                    .map(|s| {
                        format!(
                            "MemorySlot::new({}, {})",
                            rust_str(&s.predicate),
                            rust_str(&s.to)
                        )
                    })
                    .collect();
                let _ = writeln!(
                    out,
                    "        .with_memory_slots(memory.clone(), [{}])",
                    slots.join(", ")
                );
            }
        }
        for tool in &self.tools {
            match (tool.background, tool.scheduling) {
                (_, Some(scheduling)) => {
                    let variant = match scheduling {
                        super::SchedulingSpec::Interrupt => "Interrupt",
                        super::SchedulingSpec::WhenIdle => "WhenIdle",
                        super::SchedulingSpec::Silent => "Silent",
                    };
                    let _ = writeln!(
                        out,
                        "        .tool_background_with_scheduling({}, \
                         FunctionResponseScheduling::{variant})",
                        rust_str(&tool.name)
                    );
                }
                (true, None) => {
                    let _ = writeln!(out, "        .tool_background({})", rust_str(&tool.name));
                }
                (false, None) => {}
            }
        }
        if let Some(runtime) = &self.runtime {
            out.push_str(&gen_runtime(runtime));
        }
        for extract in &self.extract {
            out.push_str(&gen_extract(extract));
        }
        for phase in &self.phases {
            out.push_str(&gen_phase(phase));
        }
        if let Some(initial) = &self.initial_phase {
            let _ = writeln!(out, "        .initial_phase({})", rust_str(initial));
        }
        for watch in &self.watch {
            out.push_str(&gen_watch(watch));
        }
        for pattern in &self.patterns {
            out.push_str(&gen_pattern(pattern));
        }
        if self.modality == SpecModality::Text {
            out.push_str("        .on_text(|t| print!(\"{t}\"))\n");
            out.push_str("        .on_turn_complete(|| async { println!(); })\n");
        }
        out.push_str("        .connect_from_env()\n        .await?;\n\n");

        match self.modality {
            SpecModality::Audio => {
                out.push_str(
                    "    // Microphone in, speakers out, barge-in handled.\n    \
                     // Requires the `voice-io` feature (see Cargo.toml).\n    \
                     session.talk().await?;\n",
                );
            }
            SpecModality::Text => {
                out.push_str(
                    "    // Minimal text REPL — type a line, read the reply.\n    \
                     let stdin = std::io::stdin();\n    \
                     let mut line = String::new();\n    \
                     while stdin.read_line(&mut line)? > 0 {\n        \
                     session.send_text(line.trim()).await?;\n        \
                     line.clear();\n    }\n    \
                     session.disconnect().await?;\n",
                );
            }
        }
        out.push_str("    Ok(())\n}\n");
        out
    }

    /// A `Cargo.toml` to pair with [`to_rust`](Self::to_rust).
    pub fn to_cargo_toml(&self) -> String {
        let name = if self.name.is_empty() {
            "flow-app".to_string()
        } else {
            self.name.replace([' ', '_'], "-").to_lowercase()
        };
        let features = if self.modality == SpecModality::Audio {
            r#", features = ["gemini-llm", "voice-io"]"#
        } else {
            r#", features = ["gemini-llm"]"#
        };
        let memory_dep = if self.memory.is_some() {
            "gemini-memory-rs = \"0.8\"\n"
        } else {
            ""
        };
        format!(
            "[package]\nname = \"{name}\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n\
             [dependencies]\ngemini-adk-fluent-rs = {{ version = \"0.8\"{features} }}\n\
             {memory_dep}tokio = {{ version = \"1\", features = [\"full\"] }}\n\
             serde_json = \"1\"\n"
        )
    }
}

/// One declared tool as a `SimpleTool` registration.
fn gen_tool(tool: &ToolSpec) -> String {
    let mut out = String::new();
    let description = if tool.description.is_empty() {
        format!("Tool '{}'", tool.name)
    } else {
        tool.description.clone()
    };
    let params = match &tool.parameters {
        Some(schema) => format!("Some(json!({}))", compact(schema)),
        None => "None".to_string(),
    };
    let writes_state = !tool.set_state.is_empty();
    if writes_state {
        out.push_str("    {\n        let state = state.clone();\n");
    } else {
        out.push_str("    {\n");
    }
    let _ = writeln!(
        out,
        "        tools.register(SimpleTool::new(\n            {},\n            {},\n            {params},",
        rust_str(&tool.name),
        rust_str(&description),
    );
    if writes_state {
        out.push_str(
            "            move |_args| {\n                let state = state.clone();\n                async move {\n",
        );
    } else {
        out.push_str("            move |_args| async move {\n");
    }
    if let Some(http) = &tool.http {
        let _ = writeln!(
            out,
            "                    // HTTP binding: {} {} — replace with your client of choice.",
            http.method, http.url
        );
    }
    for (key, value) in &tool.set_state {
        let _ = writeln!(
            out,
            "                    let _ = state.set({}, json!({}));",
            rust_str(key),
            compact(value)
        );
    }
    let response = tool
        .response
        .clone()
        .unwrap_or_else(|| serde_json::json!({"ok": true}));
    if writes_state {
        let _ = writeln!(out, "                    Ok(json!({}))", compact(&response));
        out.push_str("                }\n            },\n        ));\n    }\n");
    } else {
        let _ = writeln!(out, "                Ok(json!({}))", compact(&response));
        out.push_str("            },\n        ));\n    }\n");
    }
    out
}

/// The flow as its builder chain.
fn gen_flow(flow: &Flow) -> String {
    let mut out = String::from("    let flow = Flow::new()\n");
    for step in &flow.steps {
        let _ = writeln!(out, "        .step({})", rust_str(&step.id));
        for dep in &step.after {
            match &dep.when {
                Some(when) => {
                    let _ = writeln!(
                        out,
                        "        .after_when({}, {})",
                        rust_str(&dep.step),
                        gen_guard(when)
                    );
                }
                None => {
                    let _ = writeln!(out, "        .after({})", rust_str(&dep.step));
                }
            }
        }
        if step.join == gemini_adk_rs::flow::Join::Any {
            out.push_str("        .join_any()\n");
        }
        if let Some(posture) = &step.posture {
            let _ = writeln!(out, "        .posture({})", rust_str(posture));
        }
        if let Some(ground) = &step.ground {
            let _ = writeln!(out, "        .ground({})", rust_str(ground));
        }
        if !step.allow.is_empty() {
            let _ = writeln!(out, "        .allow({})", str_array(&step.allow));
        }
        if !step.deny.is_empty() {
            let _ = writeln!(out, "        .deny({})", str_array(&step.deny));
        }
        if let Some(gate) = &step.gate {
            let _ = writeln!(out, "        .gate({})", gen_guard(gate));
        }
        if step.terminal {
            out.push_str("        .terminal()\n");
        }
        if let Some(done) = &step.done {
            let _ = writeln!(out, "        .done({})", gen_guard(done));
        }
    }
    for constraint in &flow.constraints {
        match constraint {
            Constraint::Once(tool) => {
                let _ = writeln!(out, "        .once({})", rust_str(tool));
            }
            Constraint::Before(a, b) => {
                let _ = writeln!(out, "        .before({}, {})", rust_str(a), rust_str(b));
            }
            Constraint::NeverUntil { tool, until } => {
                let _ = writeln!(
                    out,
                    "        .never({}).until({})",
                    rust_str(tool),
                    gen_guard(until)
                );
            }
            Constraint::Require(steps) => {
                let _ = writeln!(out, "        .require({})", str_array(steps));
            }
            Constraint::Reset { steps, when } => {
                let _ = writeln!(
                    out,
                    "        .reset({}).when({})",
                    str_array(steps),
                    gen_guard(when)
                );
            }
        }
    }
    if !flow.ambient.is_empty() {
        let _ = writeln!(out, "        .ambient({})", str_array(&flow.ambient));
    }
    for tool in &flow.confirm_tools {
        let _ = writeln!(
            out,
            "        // confirm-gated: {tool} (see Per-Tool Policies)"
        );
    }
    out.push_str("        .build()\n        .expect(\"validated in the Flow Studio\");\n");
    out
}

/// A guard as its constructor expression.
fn gen_guard(guard: &Guard) -> String {
    match guard {
        Guard::Spec(pred) => gen_pred(pred),
        Guard::Custom(_) => "Guard::custom(|_| todo!(\"custom guard\"))".to_string(),
    }
}

fn gen_pred(pred: &Pred) -> String {
    match pred {
        Pred::Always => "Guard::always()".to_string(),
        Pred::IsTrue(key) => format!("Guard::is_true({})", rust_str(key)),
        Pred::IsSet(key) => format!("Guard::is_set({})", rust_str(key)),
        Pred::Eq(key, value) => format!("Guard::eq({}, json!({}))", rust_str(key), compact(value)),
        Pred::Captured(fields) => format!("Guard::captured({})", str_array(fields)),
        Pred::CalledOk(tool) => format!("Guard::called_ok({})", rust_str(tool)),
        Pred::Done(step) => format!("Guard::done({})", rust_str(step)),
        Pred::All(preds) => format!(
            "Guard::all([{}])",
            preds.iter().map(gen_pred).collect::<Vec<_>>().join(", ")
        ),
        Pred::Any(preds) => format!(
            "Guard::any([{}])",
            preds.iter().map(gen_pred).collect::<Vec<_>>().join(", ")
        ),
        Pred::Not(pred) => format!("Guard::not({})", gen_pred(pred)),
    }
}

fn gen_extract(extract: &super::ExtractSpec) -> String {
    let mut out = String::new();
    out.push_str("        .extractor(Arc::new(\n");
    let _ = writeln!(
        out,
        "            LlmExtractor::new(\n                {}.to_string(),\n                \
         Arc::new(GeminiLlm::new(Default::default())),\n                {}.to_string(),\n                {},\n            )",
        rust_str(&extract.name),
        rust_str(&extract.instruction),
        extract.window
    );
    let _ = writeln!(
        out,
        "            .with_schema(json!({}))",
        compact(&extract.schema)
    );
    let trigger = match extract.trigger {
        TriggerSpec::EveryTurn => "EveryTurn",
        TriggerSpec::AfterToolCall => "AfterToolCall",
        TriggerSpec::OnGenerationComplete => "OnGenerationComplete",
        TriggerSpec::OnPhaseChange => "OnPhaseChange",
    };
    let _ = writeln!(
        out,
        "            .with_trigger(ExtractionTrigger::{trigger})"
    );
    if !extract.promote.is_empty() {
        out.push_str("            .with_promotions(vec![\n");
        for promote in &extract.promote {
            let ctor = match promote.policy {
                PromotePolicy::KeepKnown => "keep_known",
                PromotePolicy::Overwrite => "overwrite",
                PromotePolicy::TrueOnly => "true_only",
                PromotePolicy::NonEmpty => "non_empty",
            };
            let mut rule = format!("FieldPromotion::{ctor}({})", rust_str(&promote.field));
            if let Some(to) = &promote.to {
                let _ = write!(rule, ".to({})", rust_str(to));
            }
            let _ = writeln!(out, "                {rule},");
        }
        out.push_str("            ])\n");
    }
    out.push_str("        ))\n");
    out
}

fn gen_phase(phase: &super::PhaseSpec) -> String {
    let mut out = String::new();
    let _ = writeln!(out, "        .phase({})", rust_str(&phase.name));
    if let Some(instruction) = &phase.instruction {
        let _ = writeln!(out, "            .instruction({})", rust_str(instruction));
    }
    if !phase.tools.is_empty() {
        let owned: Vec<String> = phase
            .tools
            .iter()
            .map(|t| format!("{}.into()", rust_str(t)))
            .collect();
        let _ = writeln!(out, "            .tools(vec![{}])", owned.join(", "));
    }
    if !phase.needs.is_empty() {
        let _ = writeln!(out, "            .needs(&{})", str_slice(&phase.needs));
    }
    if phase.prompt_on_enter == Some(true) {
        out.push_str("            .prompt_on_enter()\n");
    }
    for transition in &phase.transitions {
        let guard = gen_guard(&transition.when);
        let _ = writeln!(
            out,
            "            .transition({}, move |s: &State| {guard}.eval_state(s))",
            rust_str(&transition.to)
        );
    }
    if !phase.on_enter.is_empty() {
        out.push_str("            .on_enter(move |_state, _writer| async move {\n");
        out.push_str(&gen_effects(&phase.on_enter, "                "));
        out.push_str("            })\n");
    }
    if phase.terminal {
        out.push_str("            .terminal()\n");
    }
    out.push_str("            .done()\n");
    out
}

fn gen_pattern(pattern: &super::PatternSpec) -> String {
    let mut out = String::new();
    let guard = gen_guard(&pattern.when);
    let (method, arg) = match (pattern.sustained_secs, pattern.turns) {
        (Some(secs), _) => (
            "when_sustained",
            format!("std::time::Duration::from_secs({secs})"),
        ),
        (_, Some(turns)) => ("when_turns", turns.to_string()),
        _ => ("when_turns", "1".to_string()),
    };
    let _ = writeln!(
        out,
        "        .{method}({}, move |s: &State| {guard}.eval_state(s), {arg},",
        rust_str(&pattern.name)
    );
    out.push_str("            move |_state, _writer| async move {\n");
    out.push_str(&gen_effects(&pattern.effects, "                "));
    out.push_str("            })\n");
    out
}

/// The closed effect vocabulary as executable lines. `remember` becomes a
/// documented seam (like an HTTP binding): the spec-driven runtime routes it
/// through the session's `MemoryBinding`; a generated app names the note and
/// leaves the engine call to the application.
fn gen_effects(effects: &[EffectSpec], indent: &str) -> String {
    let mut out = String::new();
    for effect in effects {
        match effect {
            EffectSpec::Set(map) => {
                for (key, value) in map {
                    let _ = writeln!(
                        out,
                        "{indent}let _ = _state.set({}, json!({}));",
                        rust_str(key),
                        compact(value)
                    );
                }
            }
            EffectSpec::Context(text) => {
                let _ = writeln!(
                    out,
                    "{indent}let _ = _writer.send_client_content(vec![Content::model({})], false).await;",
                    rust_str(text)
                );
            }
            EffectSpec::Prompt(text) => {
                let _ = writeln!(
                    out,
                    "{indent}let _ = _writer.send_client_content(vec![Content::model({})], true).await;",
                    rust_str(text)
                );
            }
            EffectSpec::Remember(note) => {
                let _ = writeln!(
                    out,
                    "{indent}// remember (durable): {} — route through your memory engine\n\
                     {indent}// (`MemorySession::apply_explicit_command`, see gemini-memory-rs).",
                    rust_str(note)
                );
            }
        }
    }
    out
}

/// A computed variable: the expression rides along as data (its JSON is the
/// source of truth in both phrasings) and evaluates through `Expr::eval`.
fn gen_computed(computed: &super::ComputedSpec) -> String {
    let mut out = String::new();
    let expr_json = serde_json::to_value(&computed.from).unwrap_or(Value::Null);
    let deps: Vec<String> = computed.from.keys_read().into_iter().collect();
    let _ = writeln!(
        out,
        "        .computed({}, &{}, {{",
        rust_str(&computed.key),
        str_array(&deps)
    );
    let _ = writeln!(
        out,
        "            let expr: Expr = serde_json::from_value(json!({}))",
        compact(&expr_json)
    );
    out.push_str("                .expect(\"expression validated in the Flow Studio\");\n");
    out.push_str("            move |s: &State| expr.eval(s)\n        })\n");
    out
}

/// The declared state dictionary as typed key constants.
fn gen_state_keys(state: &std::collections::BTreeMap<String, super::StateFieldSpec>) -> String {
    let mut out = String::new();
    out.push_str("/// Typed keys for the declared state dictionary.\n");
    out.push_str("#[allow(dead_code)]\nmod keys {\n");
    out.push_str("    use gemini_adk_fluent_rs::prelude::StateKey;\n\n");
    for (key, field) in state {
        let rust_type = match field.kind {
            Some(StateType::Boolean) => "bool",
            Some(StateType::Number) => "f64",
            Some(StateType::String) => "String",
            _ => "serde_json::Value",
        };
        if !field.description.is_empty() {
            let _ = writeln!(out, "    /// {}", field.description);
        }
        let _ = writeln!(
            out,
            "    pub const {}: StateKey<{rust_type}> = StateKey::new({});",
            const_name(key),
            rust_str(key)
        );
    }
    out.push_str("}\n");
    out
}

/// `session:turn_count` → `SESSION_TURN_COUNT`.
fn const_name(key: &str) -> String {
    let mut out = String::with_capacity(key.len());
    for c in key.chars() {
        if c.is_ascii_alphanumeric() {
            out.push(c.to_ascii_uppercase());
        } else {
            out.push('_');
        }
    }
    if out.is_empty() {
        // Empty key produces empty string after char filtering; use "_" for valid Rust
        return "_".to_string();
    }
    if out.chars().next().is_some_and(|c| c.is_ascii_digit()) {
        out.insert(0, '_');
    }
    out
}

/// The `runtime` section as its builder setters.
fn gen_runtime(runtime: &RuntimeSpec) -> String {
    let mut out = String::new();
    if let Some(t) = runtime.temperature {
        let _ = writeln!(out, "        .temperature({t:?})");
    }
    if let Some(budget) = runtime.thinking_budget {
        let _ = writeln!(out, "        .thinking({budget})");
    }
    if runtime.include_thoughts == Some(true) {
        out.push_str("        .include_thoughts()\n");
    }
    if let Some(t) = runtime.transcription {
        match (t.input, t.output) {
            (true, true) => out.push_str("        .transcription()\n"),
            (true, false) => out.push_str("        .input_transcription()\n"),
            (false, true) => out.push_str("        .output_transcription()\n"),
            (false, false) => {}
        }
    }
    if runtime.proactive_audio == Some(true) {
        out.push_str("        .proactive_audio()\n");
    }
    if let Some(vad) = &runtime.vad {
        out.push_str("        .vad(AutomaticActivityDetection {\n");
        let sens = |s: super::SensitivitySpec| match s {
            super::SensitivitySpec::Low => "Sensitivity::SensitivityLow",
            super::SensitivitySpec::Medium => "Sensitivity::SensitivityMedium",
            super::SensitivitySpec::High => "Sensitivity::SensitivityHigh",
        };
        let _ = writeln!(
            out,
            "            start_of_speech_sensitivity: {},",
            vad.start_sensitivity
                .map_or("None".to_string(), |s| format!("Some({})", sens(s)))
        );
        let _ = writeln!(
            out,
            "            end_of_speech_sensitivity: {},",
            vad.end_sensitivity
                .map_or("None".to_string(), |s| format!("Some({})", sens(s)))
        );
        let _ = writeln!(
            out,
            "            prefix_padding_ms: {:?},",
            vad.prefix_padding_ms
        );
        let _ = writeln!(
            out,
            "            silence_duration_ms: {:?},",
            vad.silence_duration_ms
        );
        out.push_str("            disabled: None,\n        })\n");
    }
    if let Some(audio) = &runtime.audio {
        if audio.denoise == Some(true) {
            out.push_str("        .mic_denoise() // feature `denoise`\n");
        }
        if let Some(gate) = &audio.noise_gate {
            let _ = writeln!(
                out,
                "        .mic_noise_gate({:?}, {})",
                gate.threshold_rms, gate.hold_frames
            );
        }
        if let Some(vad) = &audio.client_vad {
            let base = match vad.preset {
                Some(super::ClientVadPreset::NoisyStreet) => "VadConfig::noisy_street()",
                _ => "VadConfig::default()",
            };
            let mut overrides = String::new();
            if let Some(v) = vad.start_threshold_db {
                let _ = write!(overrides, " start_threshold_db: {v:?},");
            }
            if let Some(v) = vad.stop_threshold_db {
                let _ = write!(overrides, " stop_threshold_db: {v:?},");
            }
            if let Some(v) = vad.min_speech_frames {
                let _ = write!(overrides, " min_speech_frames: {v},");
            }
            if let Some(v) = vad.hangover_frames {
                let _ = write!(overrides, " hangover_frames: {v},");
            }
            if overrides.is_empty() {
                let _ = writeln!(out, "        .input_vad({base})");
            } else {
                let _ = writeln!(
                    out,
                    "        .input_vad(VadConfig {{{overrides} ..{base} }})"
                );
            }
        }
        if audio.authority == Some(super::AuthoritySpec::Client) {
            out.push_str("        .client_interruption_authority()\n");
        }
        if let Some(eot_ms) = audio.eot_hold_ms {
            let _ = writeln!(out, "        .turn_commit_eot_hold_ms({eot_ms})");
        }
        if let Some(min_int_ms) = audio.min_interruption_ms {
            let _ = writeln!(
                out,
                "        .turn_commit_min_interruption_ms({min_int_ms})"
            );
        }
    }
    if let Some(ms) = runtime.soft_turn_timeout_ms {
        let _ = writeln!(
            out,
            "        .soft_turn_timeout(std::time::Duration::from_millis({ms}))"
        );
    }
    if let Some(steering) = runtime.steering {
        let variant = match steering {
            SteeringSpec::InstructionUpdate => "InstructionUpdate",
            SteeringSpec::ContextInjection => "ContextInjection",
            SteeringSpec::Hybrid => "Hybrid",
        };
        let _ = writeln!(out, "        .steering_mode(SteeringMode::{variant})");
    }
    if let Some(delivery) = runtime.context_delivery {
        let variant = match delivery {
            ContextDeliverySpec::Immediate => "Immediate",
            ContextDeliverySpec::Deferred => "Deferred",
        };
        let _ = writeln!(out, "        .context_delivery(ContextDelivery::{variant})");
    }
    if let Some(repair) = runtime.repair {
        let _ = writeln!(
            out,
            "        .repair(RepairConfig {{ nudge_after: {}, escalate_after: {} }})",
            repair.nudge_after, repair.escalate_after
        );
    }
    match &runtime.persistence {
        Some(PersistenceSpec::Fs { dir }) => {
            let _ = writeln!(
                out,
                "        .persistence(Arc::new(FsPersistence::new({})))",
                rust_str(dir)
            );
        }
        Some(PersistenceSpec::Memory) => {
            out.push_str("        .persistence(Arc::new(MemoryPersistence::new()))\n");
        }
        None => {}
    }
    if let Some(id) = &runtime.session_id {
        let _ = writeln!(out, "        .session_id({})", rust_str(id));
    }
    if runtime.lossy_audio {
        out.push_str("        .lossy_audio()\n");
    }
    if runtime.lossy_transcript {
        out.push_str("        .lossy_transcript()\n");
    }
    out
}

fn gen_watch(watch: &super::WatchSpec) -> String {
    let mut out = String::new();
    let _ = writeln!(out, "        .watch({})", rust_str(&watch.key));
    let condition = match &watch.condition {
        WatchCondition::Changed => "            .changed()".to_string(),
        WatchCondition::ChangedTo(value) => {
            format!("            .changed_to(json!({}))", compact(value))
        }
        WatchCondition::CrossedAbove(threshold) => {
            format!("            .crossed_above({threshold:?})")
        }
        WatchCondition::CrossedBelow(threshold) => {
            format!("            .crossed_below({threshold:?})")
        }
        WatchCondition::BecameTrue => "            .became_true()".to_string(),
        WatchCondition::BecameFalse => "            .became_false()".to_string(),
    };
    let _ = writeln!(out, "{condition}");
    if watch.effects.is_empty() {
        out.push_str("            .then(move |_old, _new, _state| async move {\n");
    } else {
        out.push_str(
            "            .then_with_writer(move |_old, _new, _state, _writer| async move {\n",
        );
    }
    for (key, value) in &watch.set {
        let _ = writeln!(
            out,
            "                let _ = _state.set({}, json!({}));",
            rust_str(key),
            compact(value)
        );
    }
    out.push_str(&gen_effects(&watch.effects, "                "));
    out.push_str("            })\n");
    out
}

/// A Rust string literal for `s`.
fn rust_str(s: &str) -> String {
    let mut out = String::with_capacity(s.len() + 2);
    out.push('"');
    for c in s.chars() {
        match c {
            '"' => out.push_str("\\\""),
            '\\' => out.push_str("\\\\"),
            '\n' => out.push_str("\\n"),
            '\t' => out.push_str("\\t"),
            '\r' => out.push_str("\\r"),
            c if c.is_control() => {
                let _ = write!(out, "\\u{{{:x}}}", c as u32);
            }
            c => out.push(c),
        }
    }
    out.push('"');
    out
}

/// `["a", "b"]` — an array literal of string literals.
fn str_array(items: &[String]) -> String {
    format!(
        "[{}]",
        items
            .iter()
            .map(|s| rust_str(s))
            .collect::<Vec<_>>()
            .join(", ")
    )
}

/// `["a", "b"]` for `&[&str]` positions.
fn str_slice(items: &[String]) -> String {
    str_array(items)
}

/// Compact JSON — valid `json!` macro input.
fn compact(value: &Value) -> String {
    serde_json::to_string(value).unwrap_or_else(|_| "null".to_string())
}

#[cfg(test)]
mod tests {
    use super::super::SessionSpec;
    use serde_json::json;

    fn spec() -> SessionSpec {
        SessionSpec::from_value(json!({
            "name": "collections",
            "instruction": "Collect payments.",
            "greeting": "Say hello.",
            "tools": [
                {"name": "verify_identity", "description": "Verify the caller.",
                 "set_state": {"identity_verified": true}},
                {"name": "charge_card", "response": {"charged": true}}
            ],
            "extract": [{
                "name": "ptp", "instruction": "Extract the promise to pay.",
                "schema": {"type": "object"},
                "promote": [{"field": "ptp_amount"}]
            }],
            "phases": [{"name": "greet", "instruction": "Welcome.",
                        "transitions": [{"to": "main", "when": {"is_true": "greeted"}}]},
                       {"name": "main"}],
            "initial_phase": "greet",
            "watch": [{"key": "risk", "condition": {"crossed_above": 0.9},
                       "set": {"alert": true}}],
            "flow": {
                "steps": [
                    {"id": "verify", "posture": "Verify.", "allow": ["verify_identity"],
                     "done": {"is_true": "identity_verified"}},
                    {"id": "pay", "after": ["verify"],
                     "gate": {"all": [{"captured": ["ptp_amount"]},
                                       {"not": {"is_true": "disputed"}}]},
                     "allow": ["charge_card"], "done": {"called_ok": "charge_card"}}
                ],
                "constraints": [
                    {"once": "charge_card"},
                    {"never_until": {"tool": "charge_card",
                                     "until": {"is_true": "identity_verified"}}},
                    {"require": ["pay"]}
                ]
            }
        }))
        .expect("parses")
    }

    #[test]
    fn generated_main_contains_the_full_chain() {
        let code = spec().to_rust();
        for fragment in [
            "let flow = Flow::new()",
            ".step(\"verify\")",
            ".done(Guard::is_true(\"identity_verified\"))",
            ".gate(Guard::all([Guard::captured([\"ptp_amount\"]), Guard::not(Guard::is_true(\"disputed\"))]))",
            ".never(\"charge_card\").until(Guard::is_true(\"identity_verified\"))",
            ".once(\"charge_card\")",
            ".require([\"pay\"])",
            "tools.register(SimpleTool::new(",
            "state.set(\"identity_verified\", json!(true))",
            "LlmExtractor::new(",
            "FieldPromotion::keep_known(\"ptp_amount\")",
            ".phase(\"greet\")",
            ".transition(\"main\", move |s: &State| Guard::is_true(\"greeted\").eval_state(s))",
            ".watch(\"risk\")",
            ".crossed_above(0.9)",
            ".connect_from_env()",
            "session.send_text(line.trim()).await?",
        ] {
            assert!(
                code.contains(fragment),
                "missing fragment: {fragment}\n---\n{code}"
            );
        }
    }

    #[test]
    fn audio_specs_generate_talk_and_voice_feature() {
        let mut audio = spec();
        audio.modality = super::super::SpecModality::Audio;
        audio.voice = Some("Kore".into());
        let code = audio.to_rust();
        assert!(code.contains(".voice(Voice::Kore)"));
        assert!(code.contains("session.talk().await?"));
        assert!(audio.to_cargo_toml().contains("voice-io"));
    }

    #[test]
    fn turn_commit_tuning_knobs_generate_builder_calls() {
        let spec = SessionSpec::from_value(json!({
            "name": "tuned",
            "instruction": "Talk to me.",
            "runtime": {
                "audio": {
                    "eot_hold_ms": 800,
                    "min_interruption_ms": 1400
                }
            }
        }))
        .expect("parses");
        let code = spec.to_rust();
        assert!(
            code.contains(".turn_commit_eot_hold_ms(800)"),
            "missing eot_hold_ms in codegen:\n{code}"
        );
        assert!(
            code.contains(".turn_commit_min_interruption_ms(1400)"),
            "missing min_interruption_ms in codegen:\n{code}"
        );
    }

    #[test]
    fn string_escaping_is_sound() {
        assert_eq!(super::rust_str("say \"hi\"\n"), "\"say \\\"hi\\\"\\n\"");
    }

    #[test]
    fn new_sections_generate_their_wiring() {
        let spec = SessionSpec::from_value(json!({
            "name": "concierge",
            "instruction": "Help the guest.",
            "state": {
                "verified": {"type": "boolean", "default": false,
                             "description": "Identity has been checked."},
                "session:turn_count": {"type": "number"}
            },
            "computed": [{"key": "high_risk",
                          "from": {"gt": [{"key": "score"}, {"const": 0.5}]}}],
            "memory": {"slots": [{"predicate": "dietary_identity", "to": "user:diet"}]},
            "tools": [
                {"name": "record_score", "set_state": {"score": 0.9}},
                {"name": "log_event", "scheduling": "silent"}
            ],
            "runtime": {
                "temperature": 0.4,
                "soft_turn_timeout_ms": 1500,
                "steering": "context_injection",
                "repair": {"nudge_after": 2, "escalate_after": 5},
                "persistence": {"fs": {"dir": "/tmp/sessions"}},
                "session_id": "guest-1"
            },
            "patterns": [{"name": "stuck", "when": {"is_true": "confused"}, "turns": 3,
                          "effects": [{"prompt": "Offer to help."},
                                       {"remember": "guest got stuck"}]}],
            "flow": {"steps": [
                {"id": "assess", "posture": "Assess.",
                 "allow": ["record_score", "log_event"],
                 "done": {"is_true": "high_risk"}}
            ]}
        }))
        .expect("parses");
        let code = spec.to_rust();
        for fragment in [
            "mod keys {",
            "pub const VERIFIED: StateKey<bool> = StateKey::new(\"verified\");",
            "pub const SESSION_TURN_COUNT: StateKey<f64> = StateKey::new(\"session:turn_count\");",
            "let _ = state.set(\"verified\", json!(false));",
            ".computed(\"high_risk\", &[\"score\"], {",
            "serde_json::from_value(json!({\"gt\":[{\"key\":\"score\"},{\"const\":0.5}]}))",
            "MemoryEngine::in_memory(UserId::new(\"local-user\"))",
            ".with_memory_slots(memory.clone(), [MemorySlot::new(\"dietary_identity\", \"user:diet\")])",
            ".tool_background_with_scheduling(\"log_event\", FunctionResponseScheduling::Silent)",
            ".temperature(0.4)",
            ".soft_turn_timeout(std::time::Duration::from_millis(1500))",
            ".steering_mode(SteeringMode::ContextInjection)",
            ".repair(RepairConfig { nudge_after: 2, escalate_after: 5 })",
            ".persistence(Arc::new(FsPersistence::new(\"/tmp/sessions\")))",
            ".session_id(\"guest-1\")",
            "send_client_content(vec![Content::model(\"Offer to help.\")], true)",
            "// remember (durable): \"guest got stuck\"",
        ] {
            assert!(
                code.contains(fragment),
                "missing fragment: {fragment}\n---\n{code}"
            );
        }
        assert!(spec.to_cargo_toml().contains("gemini-memory-rs"));
    }

    #[test]
    fn empty_state_key_name_generates_valid_const_name() {
        // Test that empty state key names are handled gracefully in codegen
        let key = "";
        let name = super::const_name(key);
        // const_name should never return an empty string, should be at least "_"
        // to produce valid Rust code
        assert!(
            !name.is_empty(),
            "const_name produced empty string for empty key"
        );
        assert!(
            name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'),
            "const_name produced invalid Rust identifier: {name}"
        );
    }

    #[test]
    fn state_key_name_starting_with_digit_is_escaped() {
        let name = super::const_name("123abc");
        assert!(
            name.starts_with('_'),
            "const_name should prepend _ to digit-starting keys, got {name}"
        );
        assert_eq!(name, "_123ABC");
    }
}