cellstate_pipeline/config/

markdown_printer.rs

//! Canonical Markdown generator for config AST
//! Generates deterministic Markdown output for round-trip testing

use crate::ast::*;

/// Quote a string value if it could be misinterpreted by YAML.
///
/// YAML special values include: null, true, false, ~, -, numbers, and strings
/// starting with special characters like !, &, *, >, |, {, [, :, #, @, `.
fn yaml_safe_string(s: &str) -> String {
    if s.is_empty() {
        return "\"\"".to_string();
    }

    // Check if it needs quoting
    let needs_quoting = s == "-"
        || s == "~"
        || s == "null"
        || s == "true"
        || s == "false"
        || s.starts_with('-')
        || s.starts_with('!')
        || s.starts_with('&')
        || s.starts_with('*')
        || s.starts_with('>')
        || s.starts_with('|')
        || s.starts_with('{')
        || s.starts_with('[')
        || s.starts_with(':')
        || s.starts_with('#')
        || s.starts_with('@')
        || s.starts_with('`')
        || s.contains(':')
        || s.contains('\n')
        || s.parse::<f64>().is_ok(); // Looks like a number

    if needs_quoting {
        // Use double quotes and escape any internal quotes
        format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\""))
    } else {
        s.to_string()
    }
}

/// Generate a deterministic, canonical Markdown representation of a CELLSTATE AST.
///
/// The output is a stable, round-trip friendly Markdown snapshot that serializes
/// adapters, providers, memories, policies, injections, caches, trajectories,
/// and agents in a deterministic order and format. Certain definition kinds
/// (e.g., Evolution, SummarizationPolicy) are omitted.
pub fn ast_to_markdown(ast: &CellstateAst) -> String {
    let mut output = String::new();

    // Sort definitions by type and name for deterministic output
    let mut adapters = Vec::new();
    let mut memories = Vec::new();
    let mut policies = Vec::new();
    let mut injections = Vec::new();
    let mut providers = Vec::new();
    let mut caches = Vec::new();
    let mut trajectories = Vec::new();
    let mut agents = Vec::new();
    let mut intents = Vec::new();

    for def in &ast.definitions {
        match def {
            Definition::Adapter(a) => adapters.push(a),
            Definition::Memory(m) => memories.push(m),
            Definition::Policy(p) => policies.push(p),
            Definition::Injection(i) => injections.push(i),
            Definition::Provider(prov) => providers.push(prov),
            Definition::Cache(c) => caches.push(c),
            Definition::Trajectory(t) => trajectories.push(t),
            Definition::Agent(a) => agents.push(a),
            Definition::Intent(i) => intents.push(i),
            // These definition types have no markdown representation yet.
            // Listed explicitly so adding a new Definition variant triggers
            // a compiler warning rather than being silently swallowed.
            Definition::Evolution(_) | Definition::SummarizationPolicy(_) => {}
        }
    }

    // Sort alphabetically by name
    adapters.sort_by(|a, b| a.name.cmp(&b.name));
    memories.sort_by(|a, b| a.name.cmp(&b.name));
    policies.sort_by(|a, b| a.name.cmp(&b.name));
    providers.sort_by(|a, b| a.name.cmp(&b.name));
    trajectories.sort_by(|a, b| a.name.cmp(&b.name));
    agents.sort_by(|a, b| a.name.cmp(&b.name));
    intents.sort_by(|a, b| a.name.cmp(&b.name));
    caches.sort_by(|a, b| a.backend.cmp(&b.backend)); // Cache has no name, sort by backend
                                                      // Injections have no name field - sort by (source, target) tuple
    injections.sort_by(|a, b| {
        a.source
            .cmp(&b.source)
            .then_with(|| a.target.cmp(&b.target))
    });

    // Generate Markdown for each type
    for adapter in adapters {
        output.push_str(&format!("```adapter {}\n", adapter.name));
        output.push_str(&format!("adapter_type: {}\n", adapter.adapter_type));
        output.push_str(&format!(
            "connection: {}\n",
            yaml_safe_string(&adapter.connection)
        ));
        if !adapter.options.is_empty() {
            output.push_str("options:\n");
            for (k, v) in &adapter.options {
                output.push_str(&format!("  {}: {}\n", k, yaml_safe_string(v)));
            }
        }
        output.push_str("```\n\n");
    }

    for provider in providers {
        output.push_str(&format!("```provider {}\n", provider.name));
        output.push_str(&format!("provider_type: {}\n", provider.provider_type));
        output.push_str(&format!(
            "api_key: {}\n",
            env_value_to_string(&provider.api_key)
        ));
        output.push_str(&format!("model: {}\n", yaml_safe_string(&provider.model)));
        if !provider.options.is_empty() {
            output.push_str("options:\n");
            for (k, v) in &provider.options {
                output.push_str(&format!("  {}: {}\n", k, yaml_safe_string(v)));
            }
        }
        output.push_str("```\n\n");
    }

    for memory in memories {
        output.push_str(&format!("```memory {}\n", memory.name));
        output.push_str(&format!("memory_type: {}\n", memory.memory_type));
        output.push_str("schema:\n");
        for field in &memory.schema {
            output.push_str(&format!("  - name: {}\n", field.name));
            output.push_str(&format!("    type: {}\n", field.field_type));
            output.push_str(&format!("    nullable: {}\n", field.nullable));
            if let Some(default) = &field.default {
                output.push_str(&format!("    default: {}\n", yaml_safe_string(default)));
            }
        }
        output.push_str(&format!("retention: {}\n", memory.retention));
        output.push_str(&format!("lifecycle: {}\n", memory.lifecycle));
        if let Some(parent) = &memory.parent {
            output.push_str(&format!("parent: {}\n", parent));
        }
        if !memory.indexes.is_empty() {
            output.push_str("indexes:\n");
            for index in &memory.indexes {
                output.push_str(&format!("  - field: {}\n", index.field));
                output.push_str(&format!("    type: {}\n", index.index_type));
            }
        }
        if !memory.inject_on.is_empty() {
            output.push_str("inject_on:\n");
            for trigger in &memory.inject_on {
                output.push_str(&format!("  - {}\n", trigger));
            }
        }
        if !memory.artifacts.is_empty() {
            output.push_str("artifacts:\n");
            for artifact in &memory.artifacts {
                output.push_str(&format!("  - {}\n", artifact));
            }
        }
        if !memory.modifiers.is_empty() {
            output.push_str("modifiers:\n");
            for modifier in &memory.modifiers {
                output.push_str(&format!("  - {}\n", modifier));
            }
        }
        output.push_str("```\n\n");
    }

    for policy in policies {
        output.push_str(&format!("```policy {}\n", policy.name));
        output.push_str("rules:\n");
        for rule in &policy.rules {
            output.push_str(&format!("  - trigger: {}\n", rule.trigger));
            output.push_str("    actions:\n");
            for action in &rule.actions {
                output.push_str(&action_to_yaml(action));
            }
        }
        output.push_str("```\n\n");
    }

    for injection in injections {
        output.push_str("```injection\n");
        output.push_str(&format!("source: {}\n", injection.source));
        output.push_str(&format!("target: {}\n", injection.target));
        output.push_str(&format!("mode: {}\n", injection.mode));
        output.push_str(&format!("priority: {}\n", injection.priority));
        if let Some(max_tokens) = injection.max_tokens {
            output.push_str(&format!("max_tokens: {}\n", max_tokens));
        }
        if let Some(filter) = &injection.filter {
            output.push_str(&format!("filter: {}\n", filter_expr_to_string(filter)));
        }
        output.push_str("```\n\n");
    }

    for cache in caches {
        output.push_str("```cache\n");
        output.push_str(&format!("backend: {}\n", cache.backend));
        if let Some(path) = &cache.path {
            output.push_str(&format!("path: {}\n", yaml_safe_string(path)));
        }
        output.push_str(&format!("size_mb: {}\n", cache.size_mb));
        output.push_str(&format!("default_freshness: {}\n", cache.default_freshness));
        if let Some(max_entries) = cache.max_entries {
            output.push_str(&format!("max_entries: {}\n", max_entries));
        }
        if let Some(ttl) = &cache.ttl {
            output.push_str(&format!("ttl: {}\n", yaml_safe_string(ttl)));
        }
        output.push_str("```\n\n");
    }

    for trajectory in trajectories {
        output.push_str(&format!("```trajectory {}\n", trajectory.name));
        if let Some(description) = &trajectory.description {
            output.push_str(&format!("description: {}\n", yaml_safe_string(description)));
        }
        output.push_str(&format!(
            "agent_type: {}\n",
            yaml_safe_string(&trajectory.agent_type)
        ));
        output.push_str(&format!("token_budget: {}\n", trajectory.token_budget));
        output.push_str("memory_refs:\n");
        for mem_ref in &trajectory.memory_refs {
            output.push_str(&format!("  - {}\n", yaml_safe_string(mem_ref)));
        }
        if let Some(metadata) = &trajectory.metadata {
            // Serialize JSON value - it's already safe YAML if it's valid JSON
            output.push_str(&format!("metadata: {}\n", metadata));
        }
        output.push_str("```\n\n");
    }

    for agent in agents {
        output.push_str(&format!("```agent {}\n", agent.name));
        output.push_str("capabilities:\n");
        for capability in &agent.capabilities {
            output.push_str(&format!("  - {}\n", yaml_safe_string(capability)));
        }
        output.push_str("constraints:\n");
        output.push_str(&format!(
            "  max_concurrent: {}\n",
            agent.constraints.max_concurrent
        ));
        output.push_str(&format!("  timeout_ms: {}\n", agent.constraints.timeout_ms));
        output.push_str("permissions:\n");
        output.push_str("  read:\n");
        for r in &agent.permissions.read {
            output.push_str(&format!("    - {}\n", yaml_safe_string(r)));
        }
        output.push_str("  write:\n");
        for w in &agent.permissions.write {
            output.push_str(&format!("    - {}\n", yaml_safe_string(w)));
        }
        output.push_str("  lock:\n");
        for l in &agent.permissions.lock {
            output.push_str(&format!("    - {}\n", yaml_safe_string(l)));
        }
        output.push_str("```\n\n");
    }

    for intent in intents {
        output.push_str(&format!("```intent {}\n", intent.name));
        if !intent.goals.is_empty() {
            output.push_str("goals:\n");
            for goal in &intent.goals {
                output.push_str(&format!("  - {}\n", yaml_safe_string(goal)));
            }
        }
        output.push_str(&format!(
            "autonomy_level: {}\n",
            autonomy_level_to_string(&intent.autonomy_level)
        ));
        output.push_str(&format!("drift_threshold: {}\n", intent.drift_threshold));
        if !intent.delegation_boundaries.authorized_actions.is_empty()
            || !intent.delegation_boundaries.requires_approval.is_empty()
            || !intent.delegation_boundaries.forbidden_actions.is_empty()
        {
            output.push_str("delegation_boundaries:\n");
            if !intent.delegation_boundaries.authorized_actions.is_empty() {
                output.push_str("  authorized_actions:\n");
                for action in &intent.delegation_boundaries.authorized_actions {
                    output.push_str(&format!("    - {}\n", yaml_safe_string(action)));
                }
            }
            if !intent.delegation_boundaries.requires_approval.is_empty() {
                output.push_str("  requires_approval:\n");
                for action in &intent.delegation_boundaries.requires_approval {
                    output.push_str(&format!("    - {}\n", yaml_safe_string(action)));
                }
            }
            if !intent.delegation_boundaries.forbidden_actions.is_empty() {
                output.push_str("  forbidden_actions:\n");
                for action in &intent.delegation_boundaries.forbidden_actions {
                    output.push_str(&format!("    - {}\n", yaml_safe_string(action)));
                }
            }
        }
        if !intent.resolution_rules.is_empty() {
            output.push_str("resolution_rules:\n");
            for rule in &intent.resolution_rules {
                output.push_str(&format!(
                    "  - condition: {}\n",
                    yaml_safe_string(&rule.condition)
                ));
                output.push_str("    priority:\n");
                for p in &rule.priority {
                    output.push_str(&format!("      - {}\n", yaml_safe_string(p)));
                }
                if let Some(ref escalate) = rule.escalate_to {
                    output.push_str(&format!(
                        "    escalate_to: {}\n",
                        yaml_safe_string(escalate)
                    ));
                }
                output.push_str(&format!("    max_authority: {}\n", rule.max_authority));
            }
        }
        if !intent.alignment_signals.is_empty() {
            output.push_str("alignment_signals:\n");
            for signal in &intent.alignment_signals {
                output.push_str(&format!("  - name: {}\n", yaml_safe_string(&signal.name)));
                output.push_str(&format!(
                    "    source: {}\n",
                    yaml_safe_string(&signal.source)
                ));
                output.push_str(&format!(
                    "    metric: {}\n",
                    yaml_safe_string(&signal.metric)
                ));
                output.push_str(&format!(
                    "    target: {}\n",
                    signal_target_to_yaml(&signal.target)
                ));
            }
        }
        output.push_str("```\n\n");
    }

    output
}

/// Converts an EnvValue into its canonical string representation for Markdown output.
/// This function is kept as a local helper because EnvValue::Literal uses yaml_safe_string
/// which is specific to the Markdown printer context.
///
/// # Examples
///
/// ```ignore
/// let e = EnvValue::Env("API_KEY".into());
/// assert_eq!(env_value_to_string(&e), "env:API_KEY");
///
/// let l = EnvValue::Literal("plain".into());
/// assert_eq!(env_value_to_string(&l), "plain");
/// ```
fn env_value_to_string(v: &EnvValue) -> String {
    match v {
        EnvValue::Env(var) => format!("env:{}", var),
        EnvValue::Literal(s) => yaml_safe_string(s),
    }
}

/// Convert action to YAML format (for policy rules).
fn action_to_yaml(a: &Action) -> String {
    match a {
        Action::Summarize(target) => {
            format!("      - type: summarize\n        target: {}\n", target)
        }
        Action::ExtractArtifacts(target) => format!(
            "      - type: extract_artifacts\n        target: {}\n",
            target
        ),
        Action::Checkpoint(target) => {
            format!("      - type: checkpoint\n        target: {}\n", target)
        }
        Action::Prune { target, criteria } => {
            format!(
                "      - type: prune\n        target: {}\n        criteria: {}\n",
                target,
                filter_expr_to_string(criteria)
            )
        }
        Action::Notify(msg) => format!("      - type: notify\n        target: {}\n", msg),
        Action::Inject { target, mode } => {
            format!(
                "      - type: inject\n        target: {}\n        mode: {}\n",
                target, mode
            )
        }
        Action::AutoSummarize {
            source_level,
            target_level,
            create_edges,
        } => {
            format!("      - type: auto_summarize\n        source_level: {:?}\n        target_level: {:?}\n        create_edges: {}\n", source_level, target_level, create_edges)
        }
    }
}

/// Formats a filter expression into a canonical, human-readable string.
///
/// The output uses operators `==`, `!=`, `>`, `<`, `>=`, `<=`, `contains`, `regex`, and `in`.
/// String values are quoted, numbers and booleans are unquoted, `null` is rendered as `null`,
/// special values are rendered as `current_trajectory`, `current_scope`, or `now`, and arrays
/// are simplified to `[...]`. `AND`/`OR` combine sub-expressions and are wrapped in
/// parentheses; `NOT` prefixes a single sub-expression.
///
/// # Examples
///
/// ```ignore
/// let expr = FilterExpr::And(vec![
///     FilterExpr::Comparison {
///         field: "age".into(),
///         op: CompareOp::Gt,
///         value: FilterValue::Number(18.0),
///     },
///     FilterExpr::Comparison {
///         field: "active".into(),
///         op: CompareOp::Eq,
///         value: FilterValue::Bool(true),
///     },
/// ]);
/// let s = filter_expr_to_string(&expr);
/// assert_eq!(s, "(age > 18 AND active == true)");
/// ```
fn filter_expr_to_string(f: &FilterExpr) -> String {
    match f {
        FilterExpr::Comparison { field, op, value } => {
            let op_str = match op {
                CompareOp::Eq => "==",
                CompareOp::Ne => "!=",
                CompareOp::Gt => ">",
                CompareOp::Lt => "<",
                CompareOp::Ge => ">=",
                CompareOp::Le => "<=",
                CompareOp::Contains => "contains",
                CompareOp::Regex => "regex",
                CompareOp::In => "in",
            };
            let value_str = match value {
                FilterValue::String(s) => format!("\"{}\"", s),
                FilterValue::Number(n) => n.to_string(),
                FilterValue::Bool(b) => b.to_string(),
                FilterValue::Null => "null".to_string(),
                FilterValue::CurrentTrajectory => "current_trajectory".to_string(),
                FilterValue::CurrentScope => "current_scope".to_string(),
                FilterValue::Now => "now".to_string(),
                FilterValue::Array(_) => "[...]".to_string(), // Simplified
            };
            format!("{} {} {}", field, op_str, value_str)
        }
        FilterExpr::And(exprs) => {
            let exprs_str = exprs
                .iter()
                .map(filter_expr_to_string)
                .collect::<Vec<_>>()
                .join(" AND ");
            format!("({})", exprs_str)
        }
        FilterExpr::Or(exprs) => {
            let exprs_str = exprs
                .iter()
                .map(filter_expr_to_string)
                .collect::<Vec<_>>()
                .join(" OR ");
            format!("({})", exprs_str)
        }
        FilterExpr::Not(expr) => format!("NOT {}", filter_expr_to_string(expr)),
    }
}

/// Converts an AutonomyLevel into its canonical lowercase string representation.
/// Kept as a local helper because AutonomyLevel is defined in cellstate_core.
fn autonomy_level_to_string(level: &AutonomyLevel) -> &'static str {
    match level {
        AutonomyLevel::Operator => "operator",
        AutonomyLevel::Collaborator => "collaborator",
        AutonomyLevel::Consultant => "consultant",
        AutonomyLevel::Approver => "approver",
        AutonomyLevel::Observer => "observer",
    }
}

/// Converts a SignalTarget into a YAML-compatible string representation.
fn signal_target_to_yaml(target: &SignalTarget) -> String {
    match target {
        SignalTarget::Above(v) => format!("{{type: above, value: {}}}", v),
        SignalTarget::Below(v) => format!("{{type: below, value: {}}}", v),
        SignalTarget::Between { min, max } => {
            format!("{{type: between, min: {}, max: {}}}", min, max)
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use cellstate_core::intent::SignalTarget;

    // ── yaml_safe_string ───────────────────────────────────────────────

    #[test]
    fn yaml_safe_empty_string() {
        assert_eq!(yaml_safe_string(""), "\"\"");
    }

    #[test]
    fn yaml_safe_plain_string() {
        assert_eq!(yaml_safe_string("hello"), "hello");
    }

    #[test]
    fn yaml_safe_quotes_reserved_words() {
        assert_eq!(yaml_safe_string("true"), "\"true\"");
        assert_eq!(yaml_safe_string("false"), "\"false\"");
        assert_eq!(yaml_safe_string("null"), "\"null\"");
    }

    #[test]
    fn yaml_safe_quotes_numbers() {
        assert_eq!(yaml_safe_string("42"), "\"42\"");
        assert_eq!(yaml_safe_string("3.14"), "\"3.14\"");
    }

    #[test]
    fn yaml_safe_quotes_special_prefixes() {
        assert_eq!(yaml_safe_string("-item"), "\"-item\"");
        assert_eq!(yaml_safe_string("!tag"), "\"!tag\"");
        assert_eq!(yaml_safe_string("&anchor"), "\"&anchor\"");
        assert_eq!(yaml_safe_string("*alias"), "\"*alias\"");
        assert_eq!(yaml_safe_string(":colon"), "\":colon\"");
        assert_eq!(yaml_safe_string("#comment"), "\"#comment\"");
    }

    #[test]
    fn yaml_safe_quotes_colons_in_middle() {
        assert_eq!(yaml_safe_string("key:value"), "\"key:value\"");
    }

    #[test]
    fn yaml_safe_escapes_internal_quotes() {
        // String with quotes doesn't need YAML quoting since it doesn't match any special rules
        let result = yaml_safe_string("say \"hi\"");
        assert_eq!(result, "say \"hi\"");
    }

    // ── type-to-string converters ──────────────────────────────────────

    #[test]
    fn adapter_type_strings() {
        assert_eq!(AdapterType::Postgres.to_string(), "postgres");
        assert_eq!(AdapterType::Redis.to_string(), "redis");
        assert_eq!(AdapterType::Memory.to_string(), "memory");
    }

    #[test]
    fn memory_type_strings() {
        assert_eq!(MemoryType::Ephemeral.to_string(), "ephemeral");
        assert_eq!(MemoryType::Working.to_string(), "working");
        assert_eq!(MemoryType::Episodic.to_string(), "episodic");
        assert_eq!(MemoryType::Semantic.to_string(), "semantic");
        assert_eq!(MemoryType::Procedural.to_string(), "procedural");
        assert_eq!(MemoryType::Meta.to_string(), "meta");
    }

    #[test]
    fn field_type_strings() {
        assert_eq!(FieldType::Text.to_string(), "text");
        assert_eq!(FieldType::Int.to_string(), "int");
        assert_eq!(FieldType::Float.to_string(), "float");
        assert_eq!(FieldType::Bool.to_string(), "bool");
        assert_eq!(FieldType::Json.to_string(), "json");
        assert_eq!(
            FieldType::Embedding(Some(1536)).to_string(),
            "embedding(1536)"
        );
        assert_eq!(FieldType::Embedding(None).to_string(), "embedding");
    }

    #[test]
    fn retention_strings() {
        assert_eq!(Retention::Persistent.to_string(), "persistent");
        assert_eq!(Retention::Session.to_string(), "session");
        assert_eq!(Retention::Scope.to_string(), "scope");
        assert!(Retention::Duration("3600s".into())
            .to_string()
            .contains("3600s"));
    }

    #[test]
    fn lifecycle_strings() {
        assert_eq!(Lifecycle::Explicit.to_string(), "explicit");
        assert!(Lifecycle::AutoClose(Trigger::ScopeClose)
            .to_string()
            .contains("scope_close"));
    }

    #[test]
    fn trigger_strings() {
        assert_eq!(Trigger::TaskStart.to_string(), "task_start");
        assert_eq!(Trigger::Manual.to_string(), "manual");
        assert_eq!(
            Trigger::Schedule("0 * * * *".into()).to_string(),
            "schedule:0 * * * *"
        );
    }

    #[test]
    fn index_type_strings() {
        assert_eq!(IndexType::Btree.to_string(), "btree");
        assert_eq!(IndexType::Hash.to_string(), "hash");
        assert_eq!(IndexType::Hnsw.to_string(), "hnsw");
    }

    #[test]
    fn injection_mode_strings() {
        assert_eq!(InjectionMode::Full.to_string(), "full");
        assert_eq!(InjectionMode::Summary.to_string(), "summary");
        assert_eq!(InjectionMode::TopK(5).to_string(), "topk:5");
        assert_eq!(InjectionMode::Relevant(0.8).to_string(), "relevant:0.8");
    }

    #[test]
    fn env_value_strings() {
        assert_eq!(
            env_value_to_string(&EnvValue::Literal("hello".into())),
            "hello"
        );
        assert_eq!(
            env_value_to_string(&EnvValue::Env("MY_VAR".into())),
            "env:MY_VAR"
        );
    }

    #[test]
    fn freshness_strings() {
        assert_eq!(FreshnessDef::Strict.to_string(), "strict");
        assert!(FreshnessDef::BestEffort {
            max_staleness: "60s".into()
        }
        .to_string()
        .contains("60s"));
    }

    // ── signal_target_to_yaml ──────────────────────────────────────────

    #[test]
    fn signal_target_above() {
        let s = signal_target_to_yaml(&SignalTarget::Above(0.9));
        assert!(s.contains("above"));
        assert!(s.contains("0.9"));
    }

    #[test]
    fn signal_target_below() {
        let s = signal_target_to_yaml(&SignalTarget::Below(0.1));
        assert!(s.contains("below"));
        assert!(s.contains("0.1"));
    }

    #[test]
    fn signal_target_between() {
        let s = signal_target_to_yaml(&SignalTarget::Between { min: 0.3, max: 0.7 });
        assert!(s.contains("between"));
        assert!(s.contains("0.3"));
        assert!(s.contains("0.7"));
    }

    // ── ast_to_markdown smoke ──────────────────────────────────────────

    #[test]
    fn ast_to_markdown_empty_ast() {
        let ast = CellstateAst {
            version: "1.0".into(),
            definitions: vec![],
        };
        let md = ast_to_markdown(&ast);
        // Empty AST produces empty output
        assert!(md.is_empty());
    }

    #[test]
    fn ast_to_markdown_with_adapter() {
        let ast = CellstateAst {
            version: "1.0".into(),
            definitions: vec![Definition::Adapter(AdapterDef {
                name: "test-adapter".into(),
                adapter_type: AdapterType::Postgres,
                connection: "postgres://localhost/test".into(),
                options: vec![],
            })],
        };
        let md = ast_to_markdown(&ast);
        assert!(md.contains("test-adapter"));
    }

    // ── provider type Display ──────────────────────────────────────────

    #[test]
    fn provider_type_strings() {
        assert_eq!(ProviderType::OpenAI.to_string(), "openai");
        assert_eq!(ProviderType::Anthropic.to_string(), "anthropic");
        assert_eq!(ProviderType::Local.to_string(), "local");
        assert_eq!(ProviderType::Custom.to_string(), "custom");
    }

    // ── cache backend Display ──────────────────────────────────────────

    #[test]
    fn cache_backend_strings() {
        assert_eq!(CacheBackendType::Lmdb.to_string(), "lmdb");
        assert_eq!(CacheBackendType::Memory.to_string(), "memory");
    }

    // ── autonomy_level_to_string ───────────────────────────────────────

    #[test]
    fn autonomy_level_strings() {
        assert_eq!(
            autonomy_level_to_string(&AutonomyLevel::Operator),
            "operator"
        );
        assert_eq!(
            autonomy_level_to_string(&AutonomyLevel::Collaborator),
            "collaborator"
        );
        assert_eq!(
            autonomy_level_to_string(&AutonomyLevel::Consultant),
            "consultant"
        );
        assert_eq!(
            autonomy_level_to_string(&AutonomyLevel::Approver),
            "approver"
        );
        assert_eq!(
            autonomy_level_to_string(&AutonomyLevel::Observer),
            "observer"
        );
    }

    // ── modifier Display ───────────────────────────────────────────────

    #[test]
    fn modifier_embeddable() {
        let m = ModifierDef::Embeddable {
            provider: "openai".into(),
        };
        assert_eq!(m.to_string(), "embeddable(provider: openai)");
    }

    #[test]
    fn modifier_summarizable() {
        let m = ModifierDef::Summarizable {
            style: SummaryStyle::Brief,
            on_triggers: vec![Trigger::TaskEnd, Trigger::TurnEnd],
        };
        let s = m.to_string();
        assert!(s.starts_with("summarizable(style: brief, on: ["));
        assert!(s.contains("task_end"));
        assert!(s.contains("turn_end"));
    }

    #[test]
    fn modifier_summarizable_detailed() {
        let m = ModifierDef::Summarizable {
            style: SummaryStyle::Detailed,
            on_triggers: vec![],
        };
        let s = m.to_string();
        assert!(s.contains("detailed"));
        assert!(s.contains("on: []"));
    }

    #[test]
    fn modifier_lockable_exclusive() {
        let m = ModifierDef::Lockable {
            mode: LockMode::Exclusive,
        };
        assert_eq!(m.to_string(), "lockable(mode: exclusive)");
    }

    #[test]
    fn modifier_lockable_shared() {
        let m = ModifierDef::Lockable {
            mode: LockMode::Shared,
        };
        assert_eq!(m.to_string(), "lockable(mode: shared)");
    }

    // ── action_to_yaml ─────────────────────────────────────────────────

    #[test]
    fn action_summarize() {
        let s = action_to_yaml(&Action::Summarize("scope".into()));
        assert!(s.contains("type: summarize"));
        assert!(s.contains("target: scope"));
    }

    #[test]
    fn action_extract_artifacts() {
        let s = action_to_yaml(&Action::ExtractArtifacts("trajectory".into()));
        assert!(s.contains("type: extract_artifacts"));
        assert!(s.contains("target: trajectory"));
    }

    #[test]
    fn action_checkpoint() {
        let s = action_to_yaml(&Action::Checkpoint("scope".into()));
        assert!(s.contains("type: checkpoint"));
        assert!(s.contains("target: scope"));
    }

    #[test]
    fn action_prune() {
        let s = action_to_yaml(&Action::Prune {
            target: "artifacts".into(),
            criteria: FilterExpr::Comparison {
                field: "age".into(),
                op: CompareOp::Gt,
                value: FilterValue::Number(30.0),
            },
        });
        assert!(s.contains("type: prune"));
        assert!(s.contains("target: artifacts"));
        assert!(s.contains("criteria: age > 30"));
    }

    #[test]
    fn action_notify() {
        let s = action_to_yaml(&Action::Notify("alert".into()));
        assert!(s.contains("type: notify"));
        assert!(s.contains("target: alert"));
    }

    #[test]
    fn action_inject() {
        let s = action_to_yaml(&Action::Inject {
            target: "context".into(),
            mode: InjectionMode::TopK(5),
        });
        assert!(s.contains("type: inject"));
        assert!(s.contains("target: context"));
        assert!(s.contains("mode: topk:5"));
    }

    #[test]
    fn action_auto_summarize() {
        let s = action_to_yaml(&Action::AutoSummarize {
            source_level: AbstractionLevelParsed::Raw,
            target_level: AbstractionLevelParsed::Summary,
            create_edges: true,
        });
        assert!(s.contains("type: auto_summarize"));
        assert!(s.contains("create_edges: true"));
    }

    // ── filter_expr_to_string ──────────────────────────────────────────

    #[test]
    fn filter_comparison_eq_string() {
        let f = FilterExpr::Comparison {
            field: "name".into(),
            op: CompareOp::Eq,
            value: FilterValue::String("alice".into()),
        };
        assert_eq!(filter_expr_to_string(&f), "name == \"alice\"");
    }

    #[test]
    fn filter_comparison_ne_bool() {
        let f = FilterExpr::Comparison {
            field: "active".into(),
            op: CompareOp::Ne,
            value: FilterValue::Bool(false),
        };
        assert_eq!(filter_expr_to_string(&f), "active != false");
    }

    #[test]
    fn filter_comparison_gt_number() {
        let f = FilterExpr::Comparison {
            field: "score".into(),
            op: CompareOp::Gt,
            value: FilterValue::Number(42.0),
        };
        assert_eq!(filter_expr_to_string(&f), "score > 42");
    }

    #[test]
    fn filter_comparison_lt() {
        let f = FilterExpr::Comparison {
            field: "x".into(),
            op: CompareOp::Lt,
            value: FilterValue::Number(10.0),
        };
        assert_eq!(filter_expr_to_string(&f), "x < 10");
    }

    #[test]
    fn filter_comparison_ge_le() {
        let ge = FilterExpr::Comparison {
            field: "a".into(),
            op: CompareOp::Ge,
            value: FilterValue::Number(1.0),
        };
        assert_eq!(filter_expr_to_string(&ge), "a >= 1");

        let le = FilterExpr::Comparison {
            field: "b".into(),
            op: CompareOp::Le,
            value: FilterValue::Number(99.0),
        };
        assert_eq!(filter_expr_to_string(&le), "b <= 99");
    }

    #[test]
    fn filter_comparison_contains() {
        let f = FilterExpr::Comparison {
            field: "tags".into(),
            op: CompareOp::Contains,
            value: FilterValue::String("rust".into()),
        };
        assert_eq!(filter_expr_to_string(&f), "tags contains \"rust\"");
    }

    #[test]
    fn filter_comparison_regex() {
        let f = FilterExpr::Comparison {
            field: "name".into(),
            op: CompareOp::Regex,
            value: FilterValue::String("^test.*".into()),
        };
        assert_eq!(filter_expr_to_string(&f), "name regex \"^test.*\"");
    }

    #[test]
    fn filter_comparison_in() {
        let f = FilterExpr::Comparison {
            field: "status".into(),
            op: CompareOp::In,
            value: FilterValue::Array(vec![
                FilterValue::String("a".into()),
                FilterValue::String("b".into()),
            ]),
        };
        assert_eq!(filter_expr_to_string(&f), "status in [...]");
    }

    #[test]
    fn filter_comparison_null() {
        let f = FilterExpr::Comparison {
            field: "deleted_at".into(),
            op: CompareOp::Eq,
            value: FilterValue::Null,
        };
        assert_eq!(filter_expr_to_string(&f), "deleted_at == null");
    }

    #[test]
    fn filter_comparison_special_values() {
        let ct = FilterExpr::Comparison {
            field: "traj".into(),
            op: CompareOp::Eq,
            value: FilterValue::CurrentTrajectory,
        };
        assert_eq!(filter_expr_to_string(&ct), "traj == current_trajectory");

        let cs = FilterExpr::Comparison {
            field: "scope".into(),
            op: CompareOp::Eq,
            value: FilterValue::CurrentScope,
        };
        assert_eq!(filter_expr_to_string(&cs), "scope == current_scope");

        let now = FilterExpr::Comparison {
            field: "ts".into(),
            op: CompareOp::Lt,
            value: FilterValue::Now,
        };
        assert_eq!(filter_expr_to_string(&now), "ts < now");
    }

    #[test]
    fn filter_and_expression() {
        let f = FilterExpr::And(vec![
            FilterExpr::Comparison {
                field: "age".into(),
                op: CompareOp::Gt,
                value: FilterValue::Number(18.0),
            },
            FilterExpr::Comparison {
                field: "active".into(),
                op: CompareOp::Eq,
                value: FilterValue::Bool(true),
            },
        ]);
        assert_eq!(filter_expr_to_string(&f), "(age > 18 AND active == true)");
    }

    #[test]
    fn filter_or_expression() {
        let f = FilterExpr::Or(vec![
            FilterExpr::Comparison {
                field: "role".into(),
                op: CompareOp::Eq,
                value: FilterValue::String("admin".into()),
            },
            FilterExpr::Comparison {
                field: "role".into(),
                op: CompareOp::Eq,
                value: FilterValue::String("super".into()),
            },
        ]);
        assert_eq!(
            filter_expr_to_string(&f),
            "(role == \"admin\" OR role == \"super\")"
        );
    }

    #[test]
    fn filter_not_expression() {
        let f = FilterExpr::Not(Box::new(FilterExpr::Comparison {
            field: "deleted".into(),
            op: CompareOp::Eq,
            value: FilterValue::Bool(true),
        }));
        assert_eq!(filter_expr_to_string(&f), "NOT deleted == true");
    }

    // ── FieldType Display additional coverage ─────────────────────────

    #[test]
    fn field_type_uuid_and_timestamp() {
        assert_eq!(FieldType::Uuid.to_string(), "uuid");
        assert_eq!(FieldType::Timestamp.to_string(), "timestamp");
    }

    #[test]
    fn field_type_enum_variants() {
        let f = FieldType::Enum(vec!["Active".into(), "Inactive".into(), "Pending".into()]);
        assert_eq!(f.to_string(), "enum(Active, Inactive, Pending)");
    }

    #[test]
    fn field_type_nested_array() {
        let f = FieldType::Array(Box::new(FieldType::Array(Box::new(FieldType::Int))));
        assert_eq!(f.to_string(), "array(array(int))");
    }

    // ── Retention Display additional coverage ──────────────────────────

    #[test]
    fn retention_max() {
        assert_eq!(Retention::Max(100).to_string(), "max(100)");
    }

    // ── Trigger Display additional coverage ────────────────────────────

    #[test]
    fn trigger_all_variants() {
        assert_eq!(Trigger::TaskEnd.to_string(), "task_end");
        assert_eq!(Trigger::ScopeClose.to_string(), "scope_close");
        assert_eq!(Trigger::TurnEnd.to_string(), "turn_end");
    }

    // ── IndexType Display additional coverage ──────────────────────────

    #[test]
    fn index_type_gin_and_ivfflat() {
        assert_eq!(IndexType::Gin.to_string(), "gin");
        assert_eq!(IndexType::Ivfflat.to_string(), "ivfflat");
    }

    // ── Lifecycle Display additional coverage ──────────────────────────

    #[test]
    fn lifecycle_auto_close_with_schedule() {
        let l = Lifecycle::AutoClose(Trigger::Schedule("5m".into()));
        assert_eq!(l.to_string(), "auto_close(schedule:5m)");
    }
}