reasoninglayer 0.1.2

//! Phase 2 resource clients — fuzzy, causal, statistical, namespaces, collections, reviews,
//! ingestion, cognitive, oversight, and more.
//!
//! **Phase 3 typed resources (fully typed DTOs):** fuzzy, causal, statistical, communities,
//! visualization, constraints.
//!
//! **Phase 2 JSON resources (still `serde_json::Value` on both sides; typed upgrades landing in
//! patch releases):** namespaces, collections, reasoning, control, reviews, action_reviews,
//! webhook_actions, ilp, cdl, synthetic, utilities, ingestion, execution, proof_engine,
//! conversation, research, cognitive, oversight, neuro_symbolic.
//!
//! Resources in Phase 1 (sorts, terms, inference, query) and Phase 2a (health, admin, osfql,
//! context, rl_training, rag, generation, image_extraction, extract, preferences, discovery,
//! functions, ontology, analysis, scenarios, spaces, row, sources, ui, optimize) use strongly-typed
//! DTOs from [`crate::types`].

use serde_json::Value;

use crate::error::Error;
use crate::http::HttpClient;
use crate::types::common::RequestOptions;

/// Alias for a freeform JSON payload used by Phase 2 resources.
pub type Json = Value;

// ─── Builder helpers ──────────────────────────────────────────────────────────

macro_rules! simple_post {
    ($name:ident, $path:literal) => {
        pub async fn $name(
            &self,
            request: &Json,
            options: Option<&RequestOptions>,
        ) -> Result<Json, Error> {
            self.http.post($path, request, options).await
        }
    };
}

macro_rules! simple_get {
    ($name:ident, $path:literal) => {
        pub async fn $name(&self, options: Option<&RequestOptions>) -> Result<Json, Error> {
            self.http.get($path, None, options).await
        }
    };
}

// ─── Fuzzy (typed) ────────────────────────────────────────────────────────────

use crate::types::fuzzy::{
    FindSimilarRequest, FuzzyMergeRequest, FuzzyMergeResponse, FuzzySearchTopKRequest,
    FuzzySubsumptionRequest, FuzzySubsumptionResponse, FuzzyUnifyRequest, FuzzyUnifyResponse,
    PredictEffectRequest, PredictEffectResponse, SimilaritySearchResponse,
};

#[derive(Debug, Clone)]
pub struct FuzzyClient {
    http: HttpClient,
}

impl FuzzyClient {
    /// Fuzzy-unify two terms.
    pub async fn fuzzy_unify(
        &self,
        request: FuzzyUnifyRequest,
        options: Option<&RequestOptions>,
    ) -> Result<FuzzyUnifyResponse, Error> {
        self.http.post("/fuzzy/unify", &request, options).await
    }

    /// Alias for [`Self::fuzzy_unify`] using friendlier naming (matches TS `compareSimilarity`).
    pub async fn compare_similarity(
        &self,
        term1_id: impl Into<String>,
        term2_id: impl Into<String>,
        options: Option<&RequestOptions>,
    ) -> Result<FuzzyUnifyResponse, Error> {
        self.fuzzy_unify(
            FuzzyUnifyRequest {
                term1_id: term1_id.into(),
                term2_id: term2_id.into(),
                threshold: None,
                similarity_mode: None,
                fail_on_unknown: None,
            },
            options,
        )
        .await
    }

    /// Fuzzy-merge two terms.
    pub async fn fuzzy_merge(
        &self,
        request: FuzzyMergeRequest,
        options: Option<&RequestOptions>,
    ) -> Result<FuzzyMergeResponse, Error> {
        self.http.post("/fuzzy/merge", &request, options).await
    }

    /// Check fuzzy subsumption between two terms.
    pub async fn fuzzy_subsumption(
        &self,
        request: FuzzySubsumptionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<FuzzySubsumptionResponse, Error> {
        self.http
            .post("/fuzzy/subsumption", &request, options)
            .await
    }

    /// Find all terms similar to a query term.
    pub async fn find_similar(
        &self,
        request: FindSimilarRequest,
        options: Option<&RequestOptions>,
    ) -> Result<SimilaritySearchResponse, Error> {
        self.http.post("/fuzzy/similar", &request, options).await
    }

    /// Top-K similarity search.
    pub async fn search_top_k(
        &self,
        request: FuzzySearchTopKRequest,
        options: Option<&RequestOptions>,
    ) -> Result<SimilaritySearchResponse, Error> {
        self.http.post("/fuzzy/top-k", &request, options).await
    }

    /// Predict the effect for a query point.
    pub async fn predict_effect(
        &self,
        request: PredictEffectRequest,
        options: Option<&RequestOptions>,
    ) -> Result<PredictEffectResponse, Error> {
        self.http
            .post("/fuzzy/predict-effect", &request, options)
            .await
    }
}

// ─── Constraints ──────────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct ConstraintsClient {
    http: HttpClient,
}

impl ConstraintsClient {
    simple_post!(solve, "/constraints/solve");
    simple_post!(create_session, "/constraint-sessions");

    pub async fn list_sessions(&self, options: Option<&RequestOptions>) -> Result<Json, Error> {
        self.http.get("/constraint-sessions", None, options).await
    }

    pub async fn get_session(
        &self,
        session_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        let path = format!("/constraint-sessions/{}", encode(session_id));
        self.http.get(&path, None, options).await
    }

    pub async fn delete_session(
        &self,
        session_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<(), Error> {
        let path = format!("/constraint-sessions/{}", encode(session_id));
        let _: Json = self.http.delete(&path, None, options).await?;
        Ok(())
    }

    pub async fn add_constraints(
        &self,
        session_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        let path = format!("/constraint-sessions/{}/constraints", encode(session_id));
        self.http.post(&path, request, options).await
    }

    pub async fn bind_variables(
        &self,
        session_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        let path = format!("/constraint-sessions/{}/bindings", encode(session_id));
        self.http.post(&path, request, options).await
    }

    simple_post!(cleanup, "/constraint-sessions/cleanup");
}

// ─── Namespaces (typed) ───────────────────────────────────────────────────────

use crate::types::namespaces::{
    AddExportRequest, AddImportRequest, CreateChildNamespaceRequest, CreateRootNamespaceRequest,
    NamespaceListResponse, NamespaceResponse, UpdateMetadataRequest, UpdateVisibilityRequest,
};

#[derive(Debug, Clone)]
pub struct NamespacesClient {
    http: HttpClient,
    tenant_id: std::sync::Arc<String>,
}

impl NamespacesClient {
    pub async fn create_root(
        &self,
        request: CreateRootNamespaceRequest,
        options: Option<&RequestOptions>,
    ) -> Result<NamespaceResponse, Error> {
        self.http.post("/namespaces", &request, options).await
    }

    pub async fn create_child(
        &self,
        request: CreateChildNamespaceRequest,
        options: Option<&RequestOptions>,
    ) -> Result<NamespaceResponse, Error> {
        self.http.post("/namespaces/child", &request, options).await
    }

    pub async fn get(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<NamespaceResponse, Error> {
        self.http
            .get(&format!("/namespaces/{}", encode(id)), None, options)
            .await
    }

    pub async fn delete(&self, id: &str, options: Option<&RequestOptions>) -> Result<(), Error> {
        let _: Json = self
            .http
            .delete(&format!("/namespaces/{}", encode(id)), None, options)
            .await?;
        Ok(())
    }

    pub async fn update_visibility(
        &self,
        id: &str,
        request: UpdateVisibilityRequest,
        options: Option<&RequestOptions>,
    ) -> Result<NamespaceResponse, Error> {
        self.http
            .put(
                &format!("/namespaces/{}/visibility", encode(id)),
                &request,
                options,
            )
            .await
    }

    pub async fn update_metadata(
        &self,
        id: &str,
        request: UpdateMetadataRequest,
        options: Option<&RequestOptions>,
    ) -> Result<NamespaceResponse, Error> {
        self.http
            .put(
                &format!("/namespaces/{}/metadata", encode(id)),
                &request,
                options,
            )
            .await
    }

    pub async fn get_children(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<NamespaceListResponse, Error> {
        self.http
            .get(
                &format!("/namespaces/{}/children", encode(id)),
                None,
                options,
            )
            .await
    }

    pub async fn get_ancestors(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<NamespaceListResponse, Error> {
        self.http
            .get(
                &format!("/namespaces/{}/ancestors", encode(id)),
                None,
                options,
            )
            .await
    }

    pub async fn add_import(
        &self,
        id: &str,
        request: AddImportRequest,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/namespaces/{}/imports", encode(id)),
                &request,
                options,
            )
            .await
    }

    pub async fn add_export(
        &self,
        id: &str,
        request: AddExportRequest,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/namespaces/{}/exports", encode(id)),
                &request,
                options,
            )
            .await
    }

    pub async fn list_for_tenant(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<NamespaceListResponse, Error> {
        self.http
            .get(
                &format!("/namespaces/tenant/{}", encode(self.tenant_id.as_str())),
                None,
                options,
            )
            .await
    }

    pub async fn get_by_path(
        &self,
        path: &str,
        options: Option<&RequestOptions>,
    ) -> Result<NamespaceResponse, Error> {
        self.http
            .get(
                &format!(
                    "/namespaces/path/{}/{}",
                    encode(self.tenant_id.as_str()),
                    path
                ),
                None,
                options,
            )
            .await
    }
}

// ─── Collections ──────────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct CollectionsClient {
    http: HttpClient,
}

impl CollectionsClient {
    simple_post!(create, "/collections");

    pub async fn get(&self, id: &str, options: Option<&RequestOptions>) -> Result<Json, Error> {
        self.http
            .get(&format!("/collections/{}", encode(id)), None, options)
            .await
    }

    pub async fn update(
        &self,
        id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .put(&format!("/collections/{}", encode(id)), request, options)
            .await
    }

    pub async fn delete(&self, id: &str, options: Option<&RequestOptions>) -> Result<(), Error> {
        let _: Json = self
            .http
            .delete(&format!("/collections/{}", encode(id)), None, options)
            .await?;
        Ok(())
    }

    pub async fn get_children(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/collections/{}/children", encode(id)),
                None,
                options,
            )
            .await
    }

    pub async fn get_descendants(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/collections/{}/descendants", encode(id)),
                None,
                options,
            )
            .await
    }

    pub async fn get_ancestors(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/collections/{}/ancestors", encode(id)),
                None,
                options,
            )
            .await
    }

    pub async fn list_for_namespace(
        &self,
        namespace_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/collections/namespace/{}", encode(namespace_id)),
                None,
                options,
            )
            .await
    }

    pub async fn get_roots(
        &self,
        namespace_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/collections/namespace/{}/roots", encode(namespace_id)),
                None,
                options,
            )
            .await
    }

    pub async fn get_by_path(
        &self,
        namespace_id: &str,
        path: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/collections/path/{}/{}", encode(namespace_id), path),
                None,
                options,
            )
            .await
    }

    simple_post!(query_in_collection, "/collections/query/in-collection");
    simple_post!(query_by_path, "/collections/query/by-path");
}

// ─── Causal reasoning (typed) ─────────────────────────────────────────────────

use crate::types::causal::{
    AddCausalRelationRequest, AddCausalRelationResponse, CausalAncestorRequest,
    CausalAncestorResponse, CausesRequest, CausesResponse, CounterfactualRequest,
    CounterfactualResponse, DSeparatedRequest, DSeparatedResponse, GetCausalModelResponse,
    InterventionRequest, InterventionResponse, RootCauseAnalysisRequest, RootCauseAnalysisResponse,
    RootCauseWithProofResponse, ValidateDidRequest,
};

#[derive(Debug, Clone)]
pub struct CausalClient {
    http: HttpClient,
}

impl CausalClient {
    /// Check direct causation.
    pub async fn check_causes(
        &self,
        request: CausesRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CausesResponse, Error> {
        self.http.post("/causal/causes", &request, options).await
    }

    /// Check causal ancestry.
    pub async fn check_ancestor(
        &self,
        request: CausalAncestorRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CausalAncestorResponse, Error> {
        self.http.post("/causal/ancestor", &request, options).await
    }

    /// Check d-separation.
    pub async fn check_d_separated(
        &self,
        request: DSeparatedRequest,
        options: Option<&RequestOptions>,
    ) -> Result<DSeparatedResponse, Error> {
        self.http
            .post("/causal/d-separated", &request, options)
            .await
    }

    /// Apply a do-calculus intervention.
    pub async fn intervene(
        &self,
        request: InterventionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<InterventionResponse, Error> {
        self.http
            .post("/causal/intervention", &request, options)
            .await
    }

    /// Evaluate a counterfactual query via Pearl's three-step algorithm.
    pub async fn counterfactual(
        &self,
        request: CounterfactualRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CounterfactualResponse, Error> {
        self.http
            .post("/causal/counterfactual", &request, options)
            .await
    }

    /// Add a causal relation.
    pub async fn add_relation(
        &self,
        request: AddCausalRelationRequest,
        options: Option<&RequestOptions>,
    ) -> Result<AddCausalRelationResponse, Error> {
        self.http.post("/causal/relations", &request, options).await
    }

    /// Get the causal model.
    pub async fn get_model(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<GetCausalModelResponse, Error> {
        self.http.get("/causal/model", None, options).await
    }

    /// Root cause analysis.
    pub async fn root_cause(
        &self,
        request: RootCauseAnalysisRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RootCauseAnalysisResponse, Error> {
        self.http
            .post("/causal/root-cause", &request, options)
            .await
    }

    /// Root cause analysis with proof tree.
    pub async fn root_cause_with_proof(
        &self,
        request: RootCauseAnalysisRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RootCauseWithProofResponse, Error> {
        self.http
            .post("/causal/root-cause-with-proof", &request, options)
            .await
    }

    /// Validate a difference-in-differences design (response shape TBD; returned as JSON).
    pub async fn validate_did(
        &self,
        request: ValidateDidRequest,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post("/causal/validate-did", &request, options)
            .await
    }
}

// ─── Statistical (typed) ──────────────────────────────────────────────────────

use crate::types::statistical::{
    ConditionalIndependenceRequest, ConditionalIndependenceResponse, CorrelationRequest,
    CorrelationResponse, DiscoverCausalRequest, DiscoverCausalResponse, DiscoveryStatusResponse,
    DynamicDiscoveryRequest, DynamicDiscoveryResponse, InterventionObservationRequest,
    InterventionObservationResponse, ObserveMultiRequest, ObserveMultiResponse, ObservePairRequest,
    ObservePairResponse, ObserveSingleRequest, ObserveSingleResponse, PartialCorrelationRequest,
    PartialCorrelationResponse, StatisticalSuccessResponse,
};

#[derive(Debug, Clone)]
pub struct StatisticalClient {
    http: HttpClient,
}

impl StatisticalClient {
    pub async fn observe_single(
        &self,
        request: ObserveSingleRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ObserveSingleResponse, Error> {
        self.http
            .post("/statistical/observe", &request, options)
            .await
    }

    pub async fn observe_pair(
        &self,
        request: ObservePairRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ObservePairResponse, Error> {
        self.http
            .post("/statistical/observe-pair", &request, options)
            .await
    }

    pub async fn observe_multi(
        &self,
        request: ObserveMultiRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ObserveMultiResponse, Error> {
        self.http
            .post("/statistical/observe-multi", &request, options)
            .await
    }

    pub async fn correlation(
        &self,
        request: CorrelationRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CorrelationResponse, Error> {
        self.http
            .post("/statistical/correlation", &request, options)
            .await
    }

    pub async fn partial_correlation(
        &self,
        request: PartialCorrelationRequest,
        options: Option<&RequestOptions>,
    ) -> Result<PartialCorrelationResponse, Error> {
        self.http
            .post("/statistical/partial-correlation", &request, options)
            .await
    }

    pub async fn test_independence(
        &self,
        request: ConditionalIndependenceRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ConditionalIndependenceResponse, Error> {
        self.http
            .post("/statistical/test-independence", &request, options)
            .await
    }

    pub async fn discover_causal(
        &self,
        request: DiscoverCausalRequest,
        options: Option<&RequestOptions>,
    ) -> Result<DiscoverCausalResponse, Error> {
        self.http
            .post("/statistical/discover-causal", &request, options)
            .await
    }

    pub async fn dynamic_discovery(
        &self,
        request: DynamicDiscoveryRequest,
        options: Option<&RequestOptions>,
    ) -> Result<DynamicDiscoveryResponse, Error> {
        self.http
            .post("/statistical/dynamic-discovery", &request, options)
            .await
    }

    pub async fn discovery_status(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<DiscoveryStatusResponse, Error> {
        self.http
            .get("/statistical/discovery-status", None, options)
            .await
    }

    pub async fn intervention_observation(
        &self,
        request: InterventionObservationRequest,
        options: Option<&RequestOptions>,
    ) -> Result<InterventionObservationResponse, Error> {
        self.http
            .post("/statistical/intervention-observation", &request, options)
            .await
    }

    pub async fn reset_discovery(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<StatisticalSuccessResponse, Error> {
        self.http
            .post(
                "/statistical/reset-discovery",
                &serde_json::json!({}),
                options,
            )
            .await
    }

    pub async fn clear_data(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<StatisticalSuccessResponse, Error> {
        self.http
            .post("/statistical/clear-data", &serde_json::json!({}), options)
            .await
    }
}

// ─── Communities (typed) ──────────────────────────────────────────────────────

use crate::types::communities::{
    DetectCommunitiesRequest, DetectCommunitiesResponse, GetMembershipsRequest,
    GetMembershipsResponse, SearchCommunitiesRequest, SearchCommunitiesResponse,
};

#[derive(Debug, Clone)]
pub struct CommunitiesClient {
    http: HttpClient,
}

impl CommunitiesClient {
    pub async fn detect(
        &self,
        request: DetectCommunitiesRequest,
        options: Option<&RequestOptions>,
    ) -> Result<DetectCommunitiesResponse, Error> {
        self.http
            .post("/communities/detect", &request, options)
            .await
    }

    pub async fn search(
        &self,
        request: SearchCommunitiesRequest,
        options: Option<&RequestOptions>,
    ) -> Result<SearchCommunitiesResponse, Error> {
        self.http
            .post("/communities/search", &request, options)
            .await
    }

    pub async fn memberships(
        &self,
        request: GetMembershipsRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GetMembershipsResponse, Error> {
        self.http
            .post("/communities/memberships", &request, options)
            .await
    }
}

// ─── Visualization (typed) ────────────────────────────────────────────────────

use crate::types::constraints::{ConstraintGraphRequest, ConstraintGraphResponse};
use crate::types::visualization::{
    GlbLubComputationTrace, GlbLubTraceRequest, HypergraphRequest, HypergraphResponse,
    LatticeVisualizationRequest, LatticeVisualizationResponse, ResiduationStateRequest,
    ResiduationStateResponse, TriggerDependencyRequest, TriggerDependencyResponse,
};

#[derive(Debug, Clone)]
pub struct VisualizationClient {
    http: HttpClient,
}

impl VisualizationClient {
    pub async fn lattice(
        &self,
        request: LatticeVisualizationRequest,
        options: Option<&RequestOptions>,
    ) -> Result<LatticeVisualizationResponse, Error> {
        self.http
            .post("/visualization/lattice", &request, options)
            .await
    }

    /// Get the sort lattice as a DOT format string.
    pub async fn lattice_dot(&self, options: Option<&RequestOptions>) -> Result<Json, Error> {
        self.http
            .get("/visualization/lattice/dot", None, options)
            .await
    }

    pub async fn glb_lub_trace(
        &self,
        request: GlbLubTraceRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GlbLubComputationTrace, Error> {
        self.http
            .post("/visualization/lattice/glb-lub-trace", &request, options)
            .await
    }

    pub async fn constraint_graph(
        &self,
        request: ConstraintGraphRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ConstraintGraphResponse, Error> {
        self.http
            .post("/visualization/constraints", &request, options)
            .await
    }

    pub async fn hypergraph(
        &self,
        request: HypergraphRequest,
        options: Option<&RequestOptions>,
    ) -> Result<HypergraphResponse, Error> {
        self.http
            .post("/visualization/hypergraph", &request, options)
            .await
    }

    pub async fn term_subgraph(
        &self,
        term_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<HypergraphResponse, Error> {
        self.http
            .get(
                &format!("/visualization/hypergraph/term/{}", encode(term_id)),
                None,
                options,
            )
            .await
    }

    pub async fn residuation_state(
        &self,
        request: ResiduationStateRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ResiduationStateResponse, Error> {
        self.http
            .post("/visualization/residuation", &request, options)
            .await
    }

    pub async fn trigger_dependencies(
        &self,
        request: TriggerDependencyRequest,
        options: Option<&RequestOptions>,
    ) -> Result<TriggerDependencyResponse, Error> {
        self.http
            .post("/visualization/residuation/triggers", &request, options)
            .await
    }
}

// ─── Reasoning (advanced inference ops) ───────────────────────────────────────

#[derive(Debug, Clone)]
pub struct ReasoningClient {
    http: HttpClient,
}

impl ReasoningClient {
    simple_post!(subsumption, "/reasoning/subsumption");
    simple_post!(merge, "/reasoning/merge");
    simple_post!(residuate, "/reasoning/residuate");
    simple_post!(goal_residuation, "/reasoning/goal-residuation");
    simple_post!(entailment, "/reasoning/entailment");
    simple_post!(disentailment, "/reasoning/disentailment");
    simple_post!(temporal_plan, "/reasoning/temporal-plan");
    simple_post!(resource_coordination, "/reasoning/resource-coordination");
    simple_post!(assess, "/reasoning/assess");
}

// ─── Control flow ─────────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct ControlClient {
    http: HttpClient,
}

impl ControlClient {
    simple_post!(cond, "/control/cond");
    simple_post!(call_once, "/control/call-once");
    simple_post!(implies, "/control/implies");
    simple_post!(naf, "/control/naf");
    simple_post!(forall, "/control/forall");
    simple_post!(findall, "/control/findall");
    simple_post!(cut, "/control/cut");
    simple_post!(undo, "/control/undo");
    simple_post!(assign_backtrackable, "/control/assign/backtrackable");
    simple_post!(assign_global, "/control/assign/global");
    simple_post!(global_get, "/control/global/get");
    simple_post!(global_incr, "/control/global/incr");
    simple_post!(create_module, "/modules");
    simple_post!(add_symbol, "/modules/symbols");
    simple_post!(list_symbols, "/modules/symbols/list");
    simple_post!(import_module, "/modules/import");
    simple_post!(resolve_symbol, "/modules/resolve");
}

// ─── Reviews ──────────────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct ReviewsClient {
    http: HttpClient,
}

impl ReviewsClient {
    simple_get!(pending, "/reviews/pending");

    pub async fn summary(
        &self,
        tenant_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/reviews/summary/{}", encode(tenant_id)),
                None,
                options,
            )
            .await
    }

    simple_post!(approve, "/reviews/approve");
    simple_post!(reject, "/reviews/reject");
    simple_post!(merge, "/reviews/merge");
    simple_post!(correct, "/reviews/correct");
    simple_post!(re_extract, "/reviews/re-extract");
    simple_post!(add, "/reviews/add");
    simple_post!(bulk_approve, "/reviews/bulk-approve");
    simple_post!(bulk_reject, "/reviews/bulk-reject");
    simple_post!(bulk_merge, "/reviews/bulk-merge");
}

// ─── Action reviews ───────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct ActionReviewsClient {
    http: HttpClient,
}

impl ActionReviewsClient {
    simple_get!(pending, "/action-reviews/pending");
    simple_post!(approve, "/action-reviews/approve");
    simple_post!(reject, "/action-reviews/reject");
    simple_post!(modify, "/action-reviews/modify");
    simple_get!(summary, "/action-reviews/summary");
    simple_post!(bulk_approve, "/action-reviews/bulk-approve");
    simple_post!(bulk_reject, "/action-reviews/bulk-reject");
}

// ─── Webhook actions ──────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct WebhookActionsClient {
    http: HttpClient,
}

impl WebhookActionsClient {
    simple_post!(register, "/external-actions");
    simple_get!(list, "/external-actions");

    pub async fn invoke(
        &self,
        name: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/external-actions/{}/invoke", encode(name)),
                request,
                options,
            )
            .await
    }

    pub async fn complete(
        &self,
        invocation_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/invocations/{}/complete", encode(invocation_id)),
                request,
                options,
            )
            .await
    }

    simple_get!(list_invocations, "/invocations");
}

// ─── ILP ──────────────────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct IlpClient {
    http: HttpClient,
}

impl IlpClient {
    simple_post!(learn, "/ilp/learn");
    simple_post!(evaluate, "/ilp/evaluate");
    simple_get!(patterns, "/ilp/patterns");
    simple_post!(synthesize, "/ilp/synthesize");
    simple_post!(gflownet_sample, "/ilp/gflownet/sample");
}

// ─── CDL ──────────────────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct CdlClient {
    http: HttpClient,
}

impl CdlClient {
    simple_post!(forward_chain, "/cdl/forward-chain");
    simple_post!(soft_unify, "/cdl/soft-unify");
    simple_post!(forward_chain_tagged, "/cdl/forward-chain-tagged");
    simple_post!(monadic_fixpoint, "/cdl/monadic-fixpoint");
    simple_post!(derived_inference, "/cdl/derived-inference");
    simple_post!(classify_safety, "/cdl/classify-safety");
    simple_get!(status, "/cdl/status");
}

// ─── Synthetic data ───────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct SyntheticClient {
    http: HttpClient,
}

impl SyntheticClient {
    simple_post!(generate, "/synthetic/generate");
    simple_post!(export_jsonl, "/synthetic/export-jsonl");
    simple_post!(verify_faithfulness, "/synthetic/verify-faithfulness");
    simple_post!(verbalize, "/synthetic/verbalize");
    simple_post!(generation_prompt, "/synthetic/generation-prompt");
    simple_post!(negatives, "/synthetic/negatives");
    simple_post!(verify_round_trip, "/synthetic/verify-round-trip");
    simple_post!(check_diversity, "/synthetic/check-diversity");
    simple_post!(calibrate, "/synthetic/calibrate");
}

// ─── Utilities (strings, arithmetic, copy) ────────────────────────────────────

#[derive(Debug, Clone)]
pub struct UtilitiesClient {
    http: HttpClient,
}

impl UtilitiesClient {
    // arithmetic
    simple_post!(mult, "/arithmetic/mult");
    simple_post!(div, "/arithmetic/div");
    simple_post!(add, "/arithmetic/add");
    simple_post!(sub, "/arithmetic/sub");
    simple_post!(math, "/arithmetic/math");
    simple_post!(bitwise, "/arithmetic/bitwise");
    simple_post!(modular, "/arithmetic/modular");
    // strings
    simple_post!(str_concat, "/strings/concat");
    simple_post!(str_length, "/strings/length");
    simple_post!(str_substr, "/strings/substr");
    simple_post!(str_op, "/strings/op");
    simple_post!(str_compare, "/strings/compare");
    simple_post!(str_from_number, "/strings/from-number");
    simple_post!(str_asc, "/strings/asc");
    simple_post!(str_chr, "/strings/chr");
    simple_post!(str_compare_predicate, "/strings/compare-predicate");
    simple_post!(str_compare_batch, "/strings/compare-batch");
    // copy
    simple_post!(copy_term, "/copy/term");
    simple_post!(copy_batch, "/copy/batch");
    simple_post!(copy_deep, "/copy/deep");
}

// ─── Ingestion ────────────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct IngestionClient {
    http: HttpClient,
}

impl IngestionClient {
    simple_post!(ingest_markdown, "/ingest/markdown");
    simple_post!(ingest_markdown_batch, "/ingest/markdown/batch");
    simple_post!(ingest_document, "/ingest/document");
    simple_post!(ingest_document_batch, "/ingest/document/batch");
    simple_post!(ingest_rdf, "/ingest/rdf");
    simple_post!(start_session, "/ingest/sessions");
    simple_get!(list_sessions, "/ingest/sessions");

    pub async fn get_session(
        &self,
        session_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/ingest/sessions/{}", encode(session_id)),
                None,
                options,
            )
            .await
    }

    pub async fn delete_session(
        &self,
        session_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<(), Error> {
        let _: Json = self
            .http
            .delete(
                &format!("/ingest/sessions/{}", encode(session_id)),
                None,
                options,
            )
            .await?;
        Ok(())
    }

    pub async fn session_stats(
        &self,
        session_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/ingest/sessions/{}/stats", encode(session_id)),
                None,
                options,
            )
            .await
    }

    pub async fn document_stats(
        &self,
        session_id: &str,
        document_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!(
                    "/ingest/sessions/{}/documents/{}/stats",
                    encode(session_id),
                    encode(document_id)
                ),
                None,
                options,
            )
            .await
    }

    pub async fn list_incomplete(
        &self,
        session_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/ingest/sessions/{}/incomplete", encode(session_id)),
                None,
                options,
            )
            .await
    }

    pub async fn resume(
        &self,
        session_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/ingest/sessions/{}/resume", encode(session_id)),
                request,
                options,
            )
            .await
    }

    pub async fn progress(
        &self,
        session_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/ingest/sessions/{}/progress", encode(session_id)),
                None,
                options,
            )
            .await
    }

    simple_get!(queue_metrics, "/ingest/queue-metrics");
    simple_post!(recover_stuck, "/ingest/recover-stuck");
    simple_post!(reprocess_failed, "/ingest/reprocess-failed");

    pub async fn cancel_document(
        &self,
        session_id: &str,
        document_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!(
                    "/ingest/sessions/{}/documents/{}/cancel",
                    encode(session_id),
                    encode(document_id)
                ),
                &serde_json::json!({}),
                options,
            )
            .await
    }

    simple_get!(list_dlq, "/ingest/dlq");
    simple_get!(dlq_count, "/ingest/dlq/count");

    pub async fn abandon_dlq(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/ingest/dlq/{}/abandon", encode(id)),
                &serde_json::json!({}),
                options,
            )
            .await
    }
}

// ─── Execution engine (Wild_Life) ─────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct ExecutionClient {
    http: HttpClient,
}

impl ExecutionClient {
    simple_post!(create_session, "/execution/sessions");

    pub async fn get_session(
        &self,
        sid: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/execution/sessions/{}", encode(sid)),
                None,
                options,
            )
            .await
    }

    pub async fn delete_session(
        &self,
        sid: &str,
        options: Option<&RequestOptions>,
    ) -> Result<(), Error> {
        let _: Json = self
            .http
            .delete(
                &format!("/execution/sessions/{}", encode(sid)),
                None,
                options,
            )
            .await?;
        Ok(())
    }

    pub async fn bind(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/bind", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn mark(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/mark", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn backtrack(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/backtrack", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn bindings(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/bindings", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn push_goal(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/goals", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn get_goals(
        &self,
        sid: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/execution/sessions/{}/goals", encode(sid)),
                None,
                options,
            )
            .await
    }

    pub async fn pop_goal(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/goals/pop", encode(sid)),
                request,
                options,
            )
            .await
    }

    simple_post!(curry, "/execution/curry");
    simple_post!(curry_apply, "/execution/curry/apply");
    simple_post!(curry_detect, "/execution/curry/detect");

    pub async fn lazy_eval(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/lazy-eval", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn residuate(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/residuate", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn release_residuations(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/residuations/release", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn get_residuations(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/residuations", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn append_residuations(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/residuations/append", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn mark_residuations_pending(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/residuations/pending", encode(sid)),
                request,
                options,
            )
            .await
    }

    simple_post!(cleanup, "/execution/cleanup");
    simple_get!(stats, "/execution/stats");
}

// ─── Proof engine ─────────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct ProofEngineClient {
    http: HttpClient,
}

impl ProofEngineClient {
    // Term store
    simple_post!(term_store_create_session, "/term-store/sessions");

    pub async fn term_store_get_session(
        &self,
        sid: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/term-store/sessions/{}", encode(sid)),
                None,
                options,
            )
            .await
    }

    pub async fn term_store_create_term(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/terms", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn term_store_create_variable(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/variables", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn term_store_bind(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/bind", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn term_store_unify(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/unify", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn term_store_dereference(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/dereference", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn term_store_set_feature(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/feature", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn term_store_get_term(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/term", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn term_store_mark(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/mark", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn term_store_backtrack(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/backtrack", encode(sid)),
                request,
                options,
            )
            .await
    }

    // Rule store
    simple_post!(rule_store_create_session, "/rule-store/sessions");

    pub async fn rule_store_get_session(
        &self,
        store_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/rule-store/sessions/{}", encode(store_id)),
                None,
                options,
            )
            .await
    }

    pub async fn rule_store_assert(
        &self,
        store_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/rule-store/sessions/{}/assert", encode(store_id)),
                request,
                options,
            )
            .await
    }

    pub async fn rule_store_retract(
        &self,
        store_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/rule-store/sessions/{}/retract", encode(store_id)),
                request,
                options,
            )
            .await
    }

    pub async fn rule_store_find(
        &self,
        store_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/rule-store/sessions/{}/find", encode(store_id)),
                request,
                options,
            )
            .await
    }

    pub async fn rule_store_mark(
        &self,
        store_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/rule-store/sessions/{}/mark", encode(store_id)),
                request,
                options,
            )
            .await
    }

    pub async fn rule_store_undo(
        &self,
        store_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/rule-store/sessions/{}/undo", encode(store_id)),
                request,
                options,
            )
            .await
    }

    // Eval registry
    simple_post!(eval_builtin, "/eval/builtin");
    simple_post!(list_eval_functions, "/eval/functions");
}

// ─── Conversation ─────────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct ConversationClient {
    http: HttpClient,
}

impl ConversationClient {
    simple_post!(message, "/conversation/message");
    simple_get!(history, "/conversation/history");

    pub async fn get_turns(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/conversation/{}/turns", encode(id)),
                None,
                options,
            )
            .await
    }

    pub async fn delete(&self, id: &str, options: Option<&RequestOptions>) -> Result<(), Error> {
        let _: Json = self
            .http
            .delete(&format!("/conversation/{}", encode(id)), None, options)
            .await?;
        Ok(())
    }

    simple_get!(list_templates, "/templates");
    simple_post!(create_template, "/templates");

    pub async fn update_template(
        &self,
        id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .put(&format!("/templates/{}", encode(id)), request, options)
            .await
    }

    pub async fn delete_template(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<(), Error> {
        let _: Json = self
            .http
            .delete(&format!("/templates/{}", encode(id)), None, options)
            .await?;
        Ok(())
    }
}

// ─── Research (custom microservice routes) ────────────────────────────────────

#[derive(Debug, Clone)]
pub struct ResearchClient {
    http: HttpClient,
}

impl ResearchClient {
    simple_post!(search_papers, "/research/papers/search");
    simple_post!(create_session, "/research/sessions");

    pub async fn get_session(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(&format!("/research/sessions/{}", encode(id)), None, options)
            .await
    }

    pub async fn run_cycle(
        &self,
        id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/research/sessions/{}/cycle", encode(id)),
                request,
                options,
            )
            .await
    }

    pub async fn findings(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/research/sessions/{}/findings", encode(id)),
                None,
                options,
            )
            .await
    }

    pub async fn gaps(&self, id: &str, options: Option<&RequestOptions>) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/research/sessions/{}/gaps", encode(id)),
                None,
                options,
            )
            .await
    }

    pub async fn contradictions(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/research/sessions/{}/contradictions", encode(id)),
                None,
                options,
            )
            .await
    }

    pub async fn report(&self, id: &str, options: Option<&RequestOptions>) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/research/sessions/{}/report", encode(id)),
                None,
                options,
            )
            .await
    }

    simple_post!(ingest_paper, "/research/ingest");
    simple_post!(verify_claim, "/research/verify-claim");
}

// ─── Cognitive agents ─────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct CognitiveClient {
    http: HttpClient,
}

impl CognitiveClient {
    simple_post!(create_agent, "/cognitive/agents");

    pub async fn get_agent(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(&format!("/cognitive/agents/{}", encode(id)), None, options)
            .await
    }

    pub async fn delete_agent(
        &self,
        id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<(), Error> {
        let _: Json = self
            .http
            .delete(&format!("/cognitive/agents/{}", encode(id)), None, options)
            .await?;
        Ok(())
    }

    pub async fn add_goal(
        &self,
        agent_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/cognitive/agents/{}/goals", encode(agent_id)),
                request,
                options,
            )
            .await
    }

    pub async fn add_belief(
        &self,
        agent_id: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/cognitive/agents/{}/beliefs", encode(agent_id)),
                request,
                options,
            )
            .await
    }

    simple_post!(create_sort, "/cognitive/agents/sorts");
    simple_post!(add_rule, "/cognitive/agents/rules");
    simple_post!(run_cycle, "/cognitive/agents/cycle");
    simple_post!(get_state, "/cognitive/agents/state");
    simple_post!(reflect, "/cognitive/agents/reflect");
    simple_post!(adapt, "/cognitive/agents/adapt");
    simple_post!(run_integrated_cycle, "/cognitive/agents/integrated-cycle");
    simple_post!(subscribe, "/cognitive/agents/subscribe");

    pub async fn get_drives(
        &self,
        agent_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/cognitive/agents/{}/drives", encode(agent_id)),
                None,
                options,
            )
            .await
    }

    pub async fn get_extended_state(
        &self,
        agent_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/cognitive/agents/{}/extended-state", encode(agent_id)),
                None,
                options,
            )
            .await
    }

    // Plan library
    simple_post!(store_plan, "/cognitive/agents/plans");
    simple_post!(find_plans, "/cognitive/agents/plans/find");
    simple_post!(update_plan_stats, "/cognitive/agents/plans/stats");

    pub async fn delete_plan(
        &self,
        plan_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<(), Error> {
        let _: Json = self
            .http
            .delete(
                &format!("/cognitive/agents/plans/{}", encode(plan_id)),
                None,
                options,
            )
            .await?;
        Ok(())
    }

    // HTN
    simple_post!(add_htn_method, "/cognitive/agents/htn/methods");
    simple_post!(decompose_goal, "/cognitive/agents/htn/decompose");
    simple_post!(list_htn_methods, "/cognitive/agents/htn/methods/list");

    // Messaging
    simple_post!(send_message, "/cognitive/agents/messages");
    simple_post!(get_inbox, "/cognitive/agents/messages/inbox");
    simple_post!(broadcast_message, "/cognitive/agents/messages/broadcast");
    simple_post!(mark_messages_read, "/cognitive/agents/messages/read");

    // Episodic memory
    simple_post!(record_episode, "/cognitive/agents/episodes");
    simple_post!(recall_episodes, "/cognitive/agents/episodes/recall");
    simple_post!(episode_stats, "/cognitive/agents/episodes/stats");

    // Feedback
    simple_post!(feedback, "/cognitive/feedback");
    simple_post!(learn_correction, "/cognitive/learn_correction");

    /// Build the WebSocket URL for agent event streaming (you connect via [`crate::ws::WebSocketConnection`]).
    pub fn agent_events_url(&self, agent_id: &str) -> Result<String, Error> {
        let base = &self.http.config.base_url;
        let tenant = &self.http.config.tenant_id;
        let ws_base = base
            .replace("http://", "ws://")
            .replace("https://", "wss://");
        Ok(format!(
            "{ws_base}/api/v1/cognitive/agents/ws?agent_id={}&tenant_id={}",
            encode(agent_id),
            encode(tenant)
        ))
    }

    /// Build the bidirectional cognitive cycle WebSocket URL.
    pub fn cognitive_cycle_url(&self, agent_id: &str) -> Result<String, Error> {
        let base = &self.http.config.base_url;
        let tenant = &self.http.config.tenant_id;
        let ws_base = base
            .replace("http://", "ws://")
            .replace("https://", "wss://");
        Ok(format!(
            "{ws_base}/ws/cognitive/{}?tenant_id={}",
            encode(agent_id),
            encode(tenant)
        ))
    }
}

// ─── Oversight ────────────────────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct OversightClient {
    http: HttpClient,
}

impl OversightClient {
    simple_post!(judge, "/oversight/judge");
    simple_post!(judge_refine, "/oversight/judge/refine");
    simple_post!(create_session, "/oversight/sessions");

    pub async fn ingest_step(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/oversight/sessions/{}/ingest", encode(sid)),
                request,
                options,
            )
            .await
    }

    pub async fn get_session(
        &self,
        sid: &str,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .get(
                &format!("/oversight/sessions/{}", encode(sid)),
                None,
                options,
            )
            .await
    }

    pub async fn finalize(
        &self,
        sid: &str,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http
            .post(
                &format!("/oversight/sessions/{}/finalize", encode(sid)),
                request,
                options,
            )
            .await
    }

    /// Build the WebSocket URL for live oversight session streaming.
    pub fn session_stream_url(&self, session_id: &str) -> Result<String, Error> {
        let base = &self.http.config.base_url;
        let tenant = &self.http.config.tenant_id;
        let ws_base = base
            .replace("http://", "ws://")
            .replace("https://", "wss://");
        Ok(format!(
            "{ws_base}/ws/oversight/{}?tenant_id={}",
            encode(session_id),
            encode(tenant)
        ))
    }
}

// ─── Neuro-symbolic (admin) ───────────────────────────────────────────────────

#[derive(Debug, Clone)]
pub struct NeuroSymbolicClient {
    http: HttpClient,
}

impl NeuroSymbolicClient {
    simple_get!(status, "/admin/neuro-symbolic/status");
    simple_post!(train, "/admin/neuro-symbolic/train");
    simple_post!(train_embeddings, "/admin/neuro-symbolic/train/embeddings");
    simple_get!(diagnostics, "/admin/neuro-symbolic/diagnostics");
    simple_post!(train_e2e, "/admin/neuro-symbolic/train/e2e");
    simple_post!(train_from_traces, "/admin/neuro-symbolic/train/from-traces");
    simple_post!(train_gflownet, "/admin/neuro-symbolic/train/gflownet");
    simple_post!(save_weights, "/admin/neuro-symbolic/save-weights");
    simple_get!(verify_embeddings, "/admin/neuro-symbolic/embeddings/verify");
    simple_post!(sort_box, "/admin/neuro-symbolic/embeddings/sort-box");
}

// ─── Internal: helper to build all Phase 2 clients in one go ─────────────────

pub(crate) struct Phase2Clients {
    pub fuzzy: FuzzyClient,
    pub constraints: ConstraintsClient,
    pub namespaces: NamespacesClient,
    pub collections: CollectionsClient,
    pub causal: CausalClient,
    pub statistical: StatisticalClient,
    pub communities: CommunitiesClient,
    pub visualization: VisualizationClient,
    pub reasoning: ReasoningClient,
    pub control: ControlClient,
    pub reviews: ReviewsClient,
    pub action_reviews: ActionReviewsClient,
    pub webhook_actions: WebhookActionsClient,
    pub ilp: IlpClient,
    pub cdl: CdlClient,
    pub synthetic: SyntheticClient,
    pub utilities: UtilitiesClient,
    pub ingestion: IngestionClient,
    pub execution: ExecutionClient,
    pub proof_engine: ProofEngineClient,
    pub conversation: ConversationClient,
    pub research: ResearchClient,
    pub cognitive: CognitiveClient,
    pub oversight: OversightClient,
    pub neuro_symbolic: NeuroSymbolicClient,
}

pub(crate) fn build_all(http: &HttpClient) -> Phase2Clients {
    let tenant_id = std::sync::Arc::new(http.config.tenant_id.clone());
    Phase2Clients {
        fuzzy: FuzzyClient { http: http.clone() },
        constraints: ConstraintsClient { http: http.clone() },
        namespaces: NamespacesClient {
            http: http.clone(),
            tenant_id,
        },
        collections: CollectionsClient { http: http.clone() },
        causal: CausalClient { http: http.clone() },
        statistical: StatisticalClient { http: http.clone() },
        communities: CommunitiesClient { http: http.clone() },
        visualization: VisualizationClient { http: http.clone() },
        reasoning: ReasoningClient { http: http.clone() },
        control: ControlClient { http: http.clone() },
        reviews: ReviewsClient { http: http.clone() },
        action_reviews: ActionReviewsClient { http: http.clone() },
        webhook_actions: WebhookActionsClient { http: http.clone() },
        ilp: IlpClient { http: http.clone() },
        cdl: CdlClient { http: http.clone() },
        synthetic: SyntheticClient { http: http.clone() },
        utilities: UtilitiesClient { http: http.clone() },
        ingestion: IngestionClient { http: http.clone() },
        execution: ExecutionClient { http: http.clone() },
        proof_engine: ProofEngineClient { http: http.clone() },
        conversation: ConversationClient { http: http.clone() },
        research: ResearchClient { http: http.clone() },
        cognitive: CognitiveClient { http: http.clone() },
        oversight: OversightClient { http: http.clone() },
        neuro_symbolic: NeuroSymbolicClient { http: http.clone() },
    }
}

fn encode(s: &str) -> String {
    url::form_urlencoded::byte_serialize(s.as_bytes()).collect()
}