reasoninglayer 1.0.3

//! 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 uuid::Uuid;

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;

/// Parse a string as a UUID, returning a [`Error::Validation`] with the field
/// name on failure. Used at API boundaries where the SDK accepts `&str` /
/// `Into<String>` for ergonomics but the generated DTO requires a [`Uuid`].
fn parse_uuid(value: &str, field: &'static str) -> Result<Uuid, Error> {
    Uuid::parse_str(value).map_err(|err| Error::Validation {
        field: Some(field.to_string()),
        message: format!("expected a UUID, got {value:?}: {err}"),
    })
}

// ─── 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::api_spec::{
    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> {
        let term1_id = term1_id.into();
        let term2_id = term2_id.into();
        self.fuzzy_unify(
            FuzzyUnifyRequest {
                term1_id: parse_uuid(&term1_id, "term1_id")?,
                term2_id: parse_uuid(&term2_id, "term2_id")?,
                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 (typed) ──────────────────────────────────────────────────────

use crate::types::constraints::{
    AddConstraintsRequest, AddConstraintsResponse, BindVariablesRequest, BindVariablesResponse,
    CleanupSessionsResponse, ConstraintSessionListResponse, ConstraintSessionStatus,
    CreateConstraintSessionRequest, CreateConstraintSessionResponse, SolveConstraintRequest,
    SolveConstraintResponse,
};

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

impl ConstraintsClient {
    /// One-shot constraint solve.
    pub async fn solve(
        &self,
        request: SolveConstraintRequest,
        options: Option<&RequestOptions>,
    ) -> Result<SolveConstraintResponse, Error> {
        self.http
            .post("/constraints/solve", &request, options)
            .await
    }

    /// Create a persistent constraint session for incremental solving.
    pub async fn create_session(
        &self,
        request: CreateConstraintSessionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CreateConstraintSessionResponse, Error> {
        self.http
            .post("/constraint-sessions", &request, options)
            .await
    }

    /// List all active constraint sessions for the authenticated tenant.
    pub async fn list_sessions(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<ConstraintSessionListResponse, Error> {
        self.http.get("/constraint-sessions", None, options).await
    }

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

    /// Delete a constraint session. The backend returns a small `success`/`message` payload
    /// that is not surfaced.
    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(())
    }

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

    /// Bind variables in a session, propagating constraint satisfaction.
    pub async fn bind_variables(
        &self,
        session_id: &str,
        request: BindVariablesRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BindVariablesResponse, Error> {
        let path = format!("/constraint-sessions/{}/bindings", encode(session_id));
        self.http.post(&path, &request, options).await
    }

    /// Sweep stale sessions for the authenticated tenant. Takes no body.
    pub async fn cleanup(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<CleanupSessionsResponse, Error> {
        self.http
            .post(
                "/constraint-sessions/cleanup",
                &serde_json::json!({}),
                options,
            )
            .await
    }
}

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

use crate::api_spec::{
    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
    }

    /// Add an import edge from this namespace to another. The backend returns
    /// 200 OK with an empty body on success.
    pub async fn add_import(
        &self,
        id: &str,
        request: AddImportRequest,
        options: Option<&RequestOptions>,
    ) -> Result<(), Error> {
        let _: Json = self
            .http
            .post(
                &format!("/namespaces/{}/imports", encode(id)),
                &request,
                options,
            )
            .await?;
        Ok(())
    }

    /// Add an exported symbol to this namespace. The backend returns 200 OK
    /// with an empty body on success.
    pub async fn add_export(
        &self,
        id: &str,
        request: AddExportRequest,
        options: Option<&RequestOptions>,
    ) -> Result<(), Error> {
        let _: Json = self
            .http
            .post(
                &format!("/namespaces/{}/exports", encode(id)),
                &request,
                options,
            )
            .await?;
        Ok(())
    }

    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 (typed) ──────────────────────────────────────────────────────

use crate::api_spec::{
    CollectionListResponse, CollectionResponse, CreateCollectionRequest,
    QueryByCollectionPathRequest, QueryInCollectionRequest, UpdateCollectionRequest,
};
use crate::types::query::TermListResponse;

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

impl CollectionsClient {
    /// Create a new collection.
    pub async fn create(
        &self,
        request: CreateCollectionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CollectionResponse, Error> {
        self.http.post("/collections", &request, options).await
    }

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

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

    /// Delete a collection by ID.
    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(())
    }

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

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

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

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

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

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

    /// Query terms inside a specific collection.
    pub async fn query_in_collection(
        &self,
        request: QueryInCollectionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<TermListResponse, Error> {
        self.http
            .post("/collections/query/in-collection", &request, options)
            .await
    }

    /// Query terms by collection path prefix.
    pub async fn query_by_path(
        &self,
        request: QueryByCollectionPathRequest,
        options: Option<&RequestOptions>,
    ) -> Result<TermListResponse, Error> {
        self.http
            .post("/collections/query/by-path", &request, options)
            .await
    }
}

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

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

#[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.
    pub async fn validate_did(
        &self,
        request: ValidateDidRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ValidateDidResponse, Error> {
        self.http
            .post("/causal/validate-did", &request, options)
            .await
    }
}

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

use crate::api_spec::{
    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::api_spec::{
    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::api_spec::{ConstraintGraphRequest, ConstraintGraphResponse};
use crate::api_spec::{
    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 GraphViz DOT format string.
    ///
    /// This endpoint returns `text/plain` (not JSON), so the response is decoded as a UTF-8
    /// string rather than a JSON value.
    pub async fn lattice_dot(&self, options: Option<&RequestOptions>) -> Result<String, Error> {
        self.http
            .get_text("/visualization/lattice/dot", 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 (typed) ────────────────────────────────────────────────────────

use crate::api_spec::{
    DisentailmentRequest, DisentailmentResponse, EntailmentRequest, EntailmentResponse,
    EvidenceAssessmentRequest, EvidenceAssessmentResponse, GoalResiduationRequest,
    GoalResiduationResponse, ResiduationRequest, ResiduationResponse, ResourceCoordinationRequest,
    ResourceCoordinationResponse, TemporalPlanRequest, TemporalPlanResponse,
};
use crate::types::reasoning::{
    FuzzyMergeRequestReasoning, FuzzyMergeResponseReasoning, FuzzySubsumptionRequestReasoning,
    FuzzySubsumptionResponseReasoning,
};

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

impl ReasoningClient {
    /// Fuzzy subsumption check (`general` ⊒ `specific`?).
    pub async fn subsumption(
        &self,
        request: FuzzySubsumptionRequestReasoning,
        options: Option<&RequestOptions>,
    ) -> Result<FuzzySubsumptionResponseReasoning, Error> {
        self.http
            .post("/reasoning/subsumption", &request, options)
            .await
    }

    /// Merge two terms with fuzzy accumulation.
    pub async fn merge(
        &self,
        request: FuzzyMergeRequestReasoning,
        options: Option<&RequestOptions>,
    ) -> Result<FuzzyMergeResponseReasoning, Error> {
        self.http.post("/reasoning/merge", &request, options).await
    }

    /// Per-term residuation analysis.
    pub async fn residuate(
        &self,
        request: ResiduationRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ResiduationResponse, Error> {
        self.http
            .post("/reasoning/residuate", &request, options)
            .await
    }

    /// Goal-level residuation analysis.
    pub async fn goal_residuation(
        &self,
        request: GoalResiduationRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GoalResiduationResponse, Error> {
        self.http
            .post("/reasoning/goal-residuation", &request, options)
            .await
    }

    /// Entailment check using OSF clauses.
    pub async fn entailment(
        &self,
        request: EntailmentRequest,
        options: Option<&RequestOptions>,
    ) -> Result<EntailmentResponse, Error> {
        self.http
            .post("/reasoning/entailment", &request, options)
            .await
    }

    /// Disentailment check using OSF clauses.
    pub async fn disentailment(
        &self,
        request: DisentailmentRequest,
        options: Option<&RequestOptions>,
    ) -> Result<DisentailmentResponse, Error> {
        self.http
            .post("/reasoning/disentailment", &request, options)
            .await
    }

    /// Temporal planning with diversity constraints.
    pub async fn temporal_plan(
        &self,
        request: TemporalPlanRequest,
        options: Option<&RequestOptions>,
    ) -> Result<TemporalPlanResponse, Error> {
        self.http
            .post("/reasoning/temporal-plan", &request, options)
            .await
    }

    /// N-way resource coordination planning.
    pub async fn resource_coordination(
        &self,
        request: ResourceCoordinationRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ResourceCoordinationResponse, Error> {
        self.http
            .post("/reasoning/resource-coordination", &request, options)
            .await
    }

    /// Evidence assessment with quality-weighted aggregation.
    pub async fn assess(
        &self,
        request: EvidenceAssessmentRequest,
        options: Option<&RequestOptions>,
    ) -> Result<EvidenceAssessmentResponse, Error> {
        self.http.post("/reasoning/assess", &request, options).await
    }
}

// ─── Control flow (typed) ─────────────────────────────────────────────────────

use crate::api_spec::{
    AddSymbolRequest, AddSymbolResponse, BacktrackableAssignRequest, BacktrackableAssignResponse,
    CallOnceRequest, CallOnceResponse, CondRequest, CondResponse, CreateModuleRequest,
    CreateModuleResponse, CutRequest, CutResponse, FindallRequest,
    FindallResponse, ForallRequest, ForallResponse, GlobalAssignRequest, GlobalAssignResponse,
    GlobalGetRequest, GlobalGetResponse, GlobalIncrementRequest, GlobalIncrementResponse,
    ImpliesRequest, ImpliesResponse, ImportModuleRequest, ImportModuleResponse, ListSymbolsRequest,
    ListSymbolsResponse, NafResponse, ResolveSymbolRequest, ResolveSymbolResponse, UndoRequest,
    UndoResponse,
};
use crate::types::control::ControlNafRequest;

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

impl ControlClient {
    /// Conditional execution.
    pub async fn cond(
        &self,
        request: CondRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CondResponse, Error> {
        self.http.post("/control/cond", &request, options).await
    }

    /// Call-once: succeed at most once for the given goal.
    pub async fn call_once(
        &self,
        request: CallOnceRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CallOnceResponse, Error> {
        self.http
            .post("/control/call-once", &request, options)
            .await
    }

    /// Logical implication operator.
    pub async fn implies(
        &self,
        request: ImpliesRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ImpliesResponse, Error> {
        self.http.post("/control/implies", &request, options).await
    }

    /// Negation as failure.
    pub async fn naf(
        &self,
        request: ControlNafRequest,
        options: Option<&RequestOptions>,
    ) -> Result<NafResponse, Error> {
        self.http.post("/control/naf", &request, options).await
    }

    /// Universal quantification.
    pub async fn forall(
        &self,
        request: ForallRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ForallResponse, Error> {
        self.http.post("/control/forall", &request, options).await
    }

    /// Findall: collect every solution.
    pub async fn findall(
        &self,
        request: FindallRequest,
        options: Option<&RequestOptions>,
    ) -> Result<FindallResponse, Error> {
        self.http.post("/control/findall", &request, options).await
    }

    /// Commit / cut.
    pub async fn cut(
        &self,
        request: CutRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CutResponse, Error> {
        self.http.post("/control/cut", &request, options).await
    }

    /// Undo a previous control action.
    pub async fn undo(
        &self,
        request: UndoRequest,
        options: Option<&RequestOptions>,
    ) -> Result<UndoResponse, Error> {
        self.http.post("/control/undo", &request, options).await
    }

    /// Backtrackable variable assignment.
    pub async fn assign_backtrackable(
        &self,
        request: BacktrackableAssignRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BacktrackableAssignResponse, Error> {
        self.http
            .post("/control/assign/backtrackable", &request, options)
            .await
    }

    /// Global (non-backtrackable) variable assignment.
    pub async fn assign_global(
        &self,
        request: GlobalAssignRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GlobalAssignResponse, Error> {
        self.http
            .post("/control/assign/global", &request, options)
            .await
    }

    /// Read a global variable.
    pub async fn global_get(
        &self,
        request: GlobalGetRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GlobalGetResponse, Error> {
        self.http
            .post("/control/global/get", &request, options)
            .await
    }

    /// Atomically increment a global variable.
    pub async fn global_incr(
        &self,
        request: GlobalIncrementRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GlobalIncrementResponse, Error> {
        self.http
            .post("/control/global/incr", &request, options)
            .await
    }

    /// Create a new module.
    pub async fn create_module(
        &self,
        request: CreateModuleRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CreateModuleResponse, Error> {
        self.http.post("/modules", &request, options).await
    }

    /// Add a symbol to a module.
    pub async fn add_symbol(
        &self,
        request: AddSymbolRequest,
        options: Option<&RequestOptions>,
    ) -> Result<AddSymbolResponse, Error> {
        self.http.post("/modules/symbols", &request, options).await
    }

    /// List symbols in a module.
    pub async fn list_symbols(
        &self,
        request: ListSymbolsRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ListSymbolsResponse, Error> {
        self.http
            .post("/modules/symbols/list", &request, options)
            .await
    }

    /// Import a module.
    pub async fn import_module(
        &self,
        request: ImportModuleRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ImportModuleResponse, Error> {
        self.http.post("/modules/import", &request, options).await
    }

    /// Resolve a (possibly qualified) symbol within a session.
    pub async fn resolve_symbol(
        &self,
        request: ResolveSymbolRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ResolveSymbolResponse, Error> {
        self.http.post("/modules/resolve", &request, options).await
    }
}

// ─── Reviews (typed) ──────────────────────────────────────────────────────────

use crate::api_spec::{
    AddPendingReviewRequest, AddPendingReviewResponse, ApproveEntityRequest, BulkApproveRequest,
    BulkMergeRequest, BulkRejectRequest, BulkReviewResponse, CorrectEntityRequest,
    ListPendingReviewsResponse, MergeEntityRequest, ReExtractRequest, ReExtractResponse,
    RejectEntityRequest, ReviewActionResponse,
};
use crate::types::reviews::{ListPendingReviewsQuery, ReviewSummaryResponse};

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

impl ReviewsClient {
    /// List pending entity reviews. Requires `tenant_id` in the query.
    pub async fn pending(
        &self,
        query: ListPendingReviewsQuery,
        options: Option<&RequestOptions>,
    ) -> Result<ListPendingReviewsResponse, Error> {
        self.http
            .get_with_typed_query("/reviews/pending", &query, options)
            .await
    }

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

    /// Approve a pending entity review.
    pub async fn approve(
        &self,
        request: ApproveEntityRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ReviewActionResponse, Error> {
        self.http.post("/reviews/approve", &request, options).await
    }

    /// Reject a pending entity review.
    pub async fn reject(
        &self,
        request: RejectEntityRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ReviewActionResponse, Error> {
        self.http.post("/reviews/reject", &request, options).await
    }

    /// Merge a pending entity into an existing target term.
    pub async fn merge(
        &self,
        request: MergeEntityRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ReviewActionResponse, Error> {
        self.http.post("/reviews/merge", &request, options).await
    }

    /// Apply manual corrections to a pending entity review.
    pub async fn correct(
        &self,
        request: CorrectEntityRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ReviewActionResponse, Error> {
        self.http.post("/reviews/correct", &request, options).await
    }

    /// Re-run extraction on a pending entity review.
    pub async fn re_extract(
        &self,
        request: ReExtractRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ReExtractResponse, Error> {
        self.http
            .post("/reviews/re-extract", &request, options)
            .await
    }

    /// Add an entity to the pending-review queue.
    pub async fn add(
        &self,
        request: AddPendingReviewRequest,
        options: Option<&RequestOptions>,
    ) -> Result<AddPendingReviewResponse, Error> {
        self.http.post("/reviews/add", &request, options).await
    }

    /// Bulk-approve pending reviews.
    pub async fn bulk_approve(
        &self,
        request: BulkApproveRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BulkReviewResponse, Error> {
        self.http
            .post("/reviews/bulk-approve", &request, options)
            .await
    }

    /// Bulk-reject pending reviews.
    pub async fn bulk_reject(
        &self,
        request: BulkRejectRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BulkReviewResponse, Error> {
        self.http
            .post("/reviews/bulk-reject", &request, options)
            .await
    }

    /// Bulk-merge pending reviews into a target term.
    pub async fn bulk_merge(
        &self,
        request: BulkMergeRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BulkReviewResponse, Error> {
        self.http
            .post("/reviews/bulk-merge", &request, options)
            .await
    }
}

// ─── Action reviews (typed) ───────────────────────────────────────────────────

use crate::api_spec::{
    ActionReviewResponse, ActionReviewSummaryDto, ApproveActionRequest, BulkActionReviewResponse,
    BulkApproveActionsRequest, BulkRejectActionsRequest, ListActionReviewsResponse,
    ModifyActionRequest, RejectActionRequest,
};
use crate::types::action_reviews::{ActionReviewSummaryQuery, ListActionReviewsQuery};

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

impl ActionReviewsClient {
    /// List pending action reviews. Backend requires `tenant_id` in the query.
    pub async fn pending(
        &self,
        query: ListActionReviewsQuery,
        options: Option<&RequestOptions>,
    ) -> Result<ListActionReviewsResponse, Error> {
        self.http
            .get_with_typed_query("/action-reviews/pending", &query, options)
            .await
    }

    /// Aggregate action-review summary. Backend requires `tenant_id` in the query.
    pub async fn summary(
        &self,
        query: ActionReviewSummaryQuery,
        options: Option<&RequestOptions>,
    ) -> Result<ActionReviewSummaryDto, Error> {
        self.http
            .get_with_typed_query("/action-reviews/summary", &query, options)
            .await
    }

    /// Approve an action for execution.
    pub async fn approve(
        &self,
        request: ApproveActionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ActionReviewResponse, Error> {
        self.http
            .post("/action-reviews/approve", &request, options)
            .await
    }

    /// Reject a pending action.
    pub async fn reject(
        &self,
        request: RejectActionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ActionReviewResponse, Error> {
        self.http
            .post("/action-reviews/reject", &request, options)
            .await
    }

    /// Modify a pending action (approve with edited parameters).
    pub async fn modify(
        &self,
        request: ModifyActionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ActionReviewResponse, Error> {
        self.http
            .post("/action-reviews/modify", &request, options)
            .await
    }

    /// Bulk-approve pending actions.
    pub async fn bulk_approve(
        &self,
        request: BulkApproveActionsRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BulkActionReviewResponse, Error> {
        self.http
            .post("/action-reviews/bulk-approve", &request, options)
            .await
    }

    /// Bulk-reject pending actions.
    pub async fn bulk_reject(
        &self,
        request: BulkRejectActionsRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BulkActionReviewResponse, Error> {
        self.http
            .post("/action-reviews/bulk-reject", &request, options)
            .await
    }
}

// ─── Webhook actions (typed) ──────────────────────────────────────────────────

use crate::api_spec::{
    InvokeActionRequest, InvokeActionResponse, ListExternalActionsResponse,
    ListPendingInvocationsResponse, RegisterExternalActionRequest, RegisterExternalActionResponse,
    WebhookCallbackRequest, WebhookCallbackResponse,
};

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

impl WebhookActionsClient {
    /// Register a new external (webhook-backed) action.
    pub async fn register(
        &self,
        request: RegisterExternalActionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RegisterExternalActionResponse, Error> {
        self.http.post("/external-actions", &request, options).await
    }

    /// List registered external actions for the authenticated tenant.
    pub async fn list(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<ListExternalActionsResponse, Error> {
        self.http.get("/external-actions", None, options).await
    }

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

    /// Complete a pending invocation by posting the result back to the SDK.
    pub async fn complete(
        &self,
        invocation_id: &str,
        request: WebhookCallbackRequest,
        options: Option<&RequestOptions>,
    ) -> Result<WebhookCallbackResponse, Error> {
        self.http
            .post(
                &format!("/invocations/{}/complete", encode(invocation_id)),
                &request,
                options,
            )
            .await
    }

    /// List pending invocations awaiting webhook completion.
    pub async fn list_pending_invocations(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<ListPendingInvocationsResponse, Error> {
        self.http.get("/invocations", None, options).await
    }

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

// ─── ILP (typed) ──────────────────────────────────────────────────────────────

use crate::api_spec::{
    EvaluatePatternRequest, EvaluatePatternResponse, GFlowNetSampleRequest, GFlowNetSampleResponse,
    LearnPatternRequest, LearnPatternResponse, ListPatternsResponse, SynthesizeRequest,
    SynthesizeResponse,
};

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

impl IlpClient {
    /// Learn an arithmetic pattern from training examples.
    pub async fn learn(
        &self,
        request: LearnPatternRequest,
        options: Option<&RequestOptions>,
    ) -> Result<LearnPatternResponse, Error> {
        self.http.post("/ilp/learn", &request, options).await
    }

    /// Evaluate a learned pattern on new inputs.
    pub async fn evaluate(
        &self,
        request: EvaluatePatternRequest,
        options: Option<&RequestOptions>,
    ) -> Result<EvaluatePatternResponse, Error> {
        self.http.post("/ilp/evaluate", &request, options).await
    }

    /// List learned patterns.
    pub async fn patterns(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<ListPatternsResponse, Error> {
        self.http.get("/ilp/patterns", None, options).await
    }

    /// Synthesise a hypothesis from training examples.
    pub async fn synthesize(
        &self,
        request: SynthesizeRequest,
        options: Option<&RequestOptions>,
    ) -> Result<SynthesizeResponse, Error> {
        self.http.post("/ilp/synthesize", &request, options).await
    }

    /// Sample candidate hypotheses via the neural-guided GFlowNet.
    pub async fn gflownet_sample(
        &self,
        request: GFlowNetSampleRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GFlowNetSampleResponse, Error> {
        self.http
            .post("/ilp/gflownet/sample", &request, options)
            .await
    }
}

// ─── CDL (typed) ──────────────────────────────────────────────────────────────

use crate::api_spec::{
    CdlStatusResponse, ClassifySafetyRequest, ClassifySafetyResponse, DerivedInferenceRequest,
    DerivedInferenceResponse, DifferentiableFcRequest, DifferentiableFcResponse,
    DynamicAddSortRequest, DynamicAddSortResponse, MonadicFixpointRequest, MonadicFixpointResponse,
    SoftUnifyRequest, SoftUnifyResponse, TaggedFcRequest, TaggedFcResponse,
};

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

impl CdlClient {
    /// Differentiable forward chaining.
    ///
    /// Note: corrected path (was `/cdl/forward-chain` which 404'd against the live backend).
    pub async fn forward_chain(
        &self,
        request: DifferentiableFcRequest,
        options: Option<&RequestOptions>,
    ) -> Result<DifferentiableFcResponse, Error> {
        self.http
            .post("/cdl/forward-chain/differentiable", &request, options)
            .await
    }

    /// Soft unification.
    pub async fn soft_unify(
        &self,
        request: SoftUnifyRequest,
        options: Option<&RequestOptions>,
    ) -> Result<SoftUnifyResponse, Error> {
        self.http.post("/cdl/soft-unify", &request, options).await
    }

    /// Tagged forward chaining.
    ///
    /// Note: corrected path (was `/cdl/forward-chain-tagged` which 404'd against the live backend).
    pub async fn forward_chain_tagged(
        &self,
        request: TaggedFcRequest,
        options: Option<&RequestOptions>,
    ) -> Result<TaggedFcResponse, Error> {
        self.http
            .post("/cdl/forward-chain/tagged", &request, options)
            .await
    }

    /// Monadic fixpoint computation.
    pub async fn monadic_fixpoint(
        &self,
        request: MonadicFixpointRequest,
        options: Option<&RequestOptions>,
    ) -> Result<MonadicFixpointResponse, Error> {
        self.http
            .post("/cdl/monadic-fixpoint", &request, options)
            .await
    }

    /// Derived-inference scoring.
    pub async fn derived_inference(
        &self,
        request: DerivedInferenceRequest,
        options: Option<&RequestOptions>,
    ) -> Result<DerivedInferenceResponse, Error> {
        self.http
            .post("/cdl/derived-inference", &request, options)
            .await
    }

    /// Classify safety of a text input.
    pub async fn classify_safety(
        &self,
        request: ClassifySafetyRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ClassifySafetyResponse, Error> {
        self.http
            .post("/cdl/classify-safety", &request, options)
            .await
    }

    /// Dynamically add a new sort to the CDL embedding architecture.
    pub async fn dynamic_add_sort(
        &self,
        request: DynamicAddSortRequest,
        options: Option<&RequestOptions>,
    ) -> Result<DynamicAddSortResponse, Error> {
        self.http
            .post("/cdl/dynamic/add-sort", &request, options)
            .await
    }

    /// Status of the CDL service (model availability, parameter counts, etc.).
    pub async fn status(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<CdlStatusResponse, Error> {
        self.http.get("/cdl/status", None, options).await
    }
}

// ─── Synthetic data (typed) ───────────────────────────────────────────────────

use crate::api_spec::{
    CalibrationReportDto, CheckDiversityRequest, CheckDiversityResponse, ExportJsonlResponse,
    GenerateNegativesRequest, GenerateNegativesResponse, GenerateSyntheticDataRequest,
    GenerateSyntheticDataResponse, GenerationPromptRequest, GenerationPromptResponse,
    VerbalizeTermRequest, VerbalizeTermResponse, VerifyFaithfulnessRequest,
    VerifyFaithfulnessResponse, VerifyRoundTripRequest, VerifyRoundTripResponse,
};

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

impl SyntheticClient {
    pub async fn generate(
        &self,
        request: GenerateSyntheticDataRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GenerateSyntheticDataResponse, Error> {
        self.http
            .post("/synthetic/generate", &request, options)
            .await
    }

    /// Export a previously-generated set as JSONL. Backend accepts free-form input.
    pub async fn export_jsonl(
        &self,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<ExportJsonlResponse, Error> {
        self.http
            .post("/synthetic/export-jsonl", request, options)
            .await
    }

    pub async fn verify_faithfulness(
        &self,
        request: VerifyFaithfulnessRequest,
        options: Option<&RequestOptions>,
    ) -> Result<VerifyFaithfulnessResponse, Error> {
        self.http
            .post("/synthetic/verify-faithfulness", &request, options)
            .await
    }

    pub async fn verbalize(
        &self,
        request: VerbalizeTermRequest,
        options: Option<&RequestOptions>,
    ) -> Result<VerbalizeTermResponse, Error> {
        self.http
            .post("/synthetic/verbalize", &request, options)
            .await
    }

    pub async fn generation_prompt(
        &self,
        request: GenerationPromptRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GenerationPromptResponse, Error> {
        self.http
            .post("/synthetic/generation-prompt", &request, options)
            .await
    }

    pub async fn negatives(
        &self,
        request: GenerateNegativesRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GenerateNegativesResponse, Error> {
        self.http
            .post("/synthetic/negatives", &request, options)
            .await
    }

    pub async fn verify_round_trip(
        &self,
        request: VerifyRoundTripRequest,
        options: Option<&RequestOptions>,
    ) -> Result<VerifyRoundTripResponse, Error> {
        self.http
            .post("/synthetic/verify-round-trip", &request, options)
            .await
    }

    pub async fn check_diversity(
        &self,
        request: CheckDiversityRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CheckDiversityResponse, Error> {
        self.http
            .post("/synthetic/check-diversity", &request, options)
            .await
    }

    /// Calibration takes free-form configuration; response is the calibration report.
    pub async fn calibrate(
        &self,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<CalibrationReportDto, Error> {
        self.http
            .post("/synthetic/calibrate", request, options)
            .await
    }
}

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

use crate::api_spec::{
    AscRequest, AscResponse, BatchCopyRequest, BatchCopyResponse, BatchStringCompareRequest,
    BatchStringCompareResponse, BitwiseRequest, BitwiseResponse, ChrRequest, ChrResponse,
    CopyTermRequest, CopyTermResponse, DeepCopyRequest, DeepCopyResponse, MathFunctionRequest,
    MathFunctionResponse, ModularArithRequest, ModularArithResponse, NumberToStringRequest,
    NumberToStringResponse, RelationalArithRequest, RelationalArithResponse,
    StringComparePredicateRequest, StringComparePredicateResponse, StringCompareRequest,
    StringCompareResponse, StringConcatRequest, StringConcatResponse, StringLengthRequest,
    StringLengthResponse, StringOpRequest, StringOpResponse, SubstringRequest, SubstringResponse,
};

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

impl UtilitiesClient {
    // ─── Arithmetic (3-way relational ops) ────────────────────────────────

    pub async fn mult(
        &self,
        request: RelationalArithRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RelationalArithResponse, Error> {
        self.http.post("/arithmetic/mult", &request, options).await
    }

    pub async fn div(
        &self,
        request: RelationalArithRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RelationalArithResponse, Error> {
        self.http.post("/arithmetic/div", &request, options).await
    }

    pub async fn add(
        &self,
        request: RelationalArithRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RelationalArithResponse, Error> {
        self.http.post("/arithmetic/add", &request, options).await
    }

    pub async fn sub(
        &self,
        request: RelationalArithRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RelationalArithResponse, Error> {
        self.http.post("/arithmetic/sub", &request, options).await
    }

    pub async fn math(
        &self,
        request: MathFunctionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<MathFunctionResponse, Error> {
        self.http.post("/arithmetic/math", &request, options).await
    }

    pub async fn bitwise(
        &self,
        request: BitwiseRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BitwiseResponse, Error> {
        self.http
            .post("/arithmetic/bitwise", &request, options)
            .await
    }

    pub async fn modular(
        &self,
        request: ModularArithRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ModularArithResponse, Error> {
        self.http
            .post("/arithmetic/modular", &request, options)
            .await
    }

    // ─── String operations ────────────────────────────────────────────────

    pub async fn str_concat(
        &self,
        request: StringConcatRequest,
        options: Option<&RequestOptions>,
    ) -> Result<StringConcatResponse, Error> {
        self.http.post("/strings/concat", &request, options).await
    }

    pub async fn str_length(
        &self,
        request: StringLengthRequest,
        options: Option<&RequestOptions>,
    ) -> Result<StringLengthResponse, Error> {
        self.http.post("/strings/length", &request, options).await
    }

    pub async fn str_substr(
        &self,
        request: SubstringRequest,
        options: Option<&RequestOptions>,
    ) -> Result<SubstringResponse, Error> {
        self.http.post("/strings/substr", &request, options).await
    }

    pub async fn str_op(
        &self,
        request: StringOpRequest,
        options: Option<&RequestOptions>,
    ) -> Result<StringOpResponse, Error> {
        self.http.post("/strings/op", &request, options).await
    }

    pub async fn str_compare(
        &self,
        request: StringCompareRequest,
        options: Option<&RequestOptions>,
    ) -> Result<StringCompareResponse, Error> {
        self.http.post("/strings/compare", &request, options).await
    }

    pub async fn str_from_number(
        &self,
        request: NumberToStringRequest,
        options: Option<&RequestOptions>,
    ) -> Result<NumberToStringResponse, Error> {
        self.http
            .post("/strings/from-number", &request, options)
            .await
    }

    pub async fn str_asc(
        &self,
        request: AscRequest,
        options: Option<&RequestOptions>,
    ) -> Result<AscResponse, Error> {
        self.http.post("/strings/asc", &request, options).await
    }

    pub async fn str_chr(
        &self,
        request: ChrRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ChrResponse, Error> {
        self.http.post("/strings/chr", &request, options).await
    }

    pub async fn str_compare_predicate(
        &self,
        request: StringComparePredicateRequest,
        options: Option<&RequestOptions>,
    ) -> Result<StringComparePredicateResponse, Error> {
        self.http
            .post("/strings/compare-predicate", &request, options)
            .await
    }

    pub async fn str_compare_batch(
        &self,
        request: BatchStringCompareRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BatchStringCompareResponse, Error> {
        self.http
            .post("/strings/compare-batch", &request, options)
            .await
    }

    // ─── Copy operations ──────────────────────────────────────────────────

    pub async fn copy_term(
        &self,
        request: CopyTermRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CopyTermResponse, Error> {
        self.http.post("/copy/term", &request, options).await
    }

    pub async fn copy_batch(
        &self,
        request: BatchCopyRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BatchCopyResponse, Error> {
        self.http.post("/copy/batch", &request, options).await
    }

    pub async fn copy_deep(
        &self,
        request: DeepCopyRequest,
        options: Option<&RequestOptions>,
    ) -> Result<DeepCopyResponse, Error> {
        self.http.post("/copy/deep", &request, options).await
    }
}

// ─── Ingestion (typed for markdown/document; session-mgmt stays Json) ─────────

use crate::api_spec::{
    IngestDocumentBatchRequest, IngestDocumentRequest, IngestDocumentResponse,
    IngestMarkdownBatchRequest, IngestMarkdownRequest,
};
use crate::types::ingestion::IngestMarkdownResponse;

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

impl IngestionClient {
    /// Ingest a single markdown document.
    pub async fn ingest_markdown(
        &self,
        request: IngestMarkdownRequest,
        options: Option<&RequestOptions>,
    ) -> Result<IngestMarkdownResponse, Error> {
        self.http.post("/ingest/markdown", &request, options).await
    }

    /// Ingest a batch of markdown documents.
    pub async fn ingest_markdown_batch(
        &self,
        request: IngestMarkdownBatchRequest,
        options: Option<&RequestOptions>,
    ) -> Result<IngestMarkdownResponse, Error> {
        self.http
            .post("/ingest/markdown/batch", &request, options)
            .await
    }

    /// Ingest a single document (PDF, DOCX, image with OCR, …).
    pub async fn ingest_document(
        &self,
        request: IngestDocumentRequest,
        options: Option<&RequestOptions>,
    ) -> Result<IngestDocumentResponse, Error> {
        self.http.post("/ingest/document", &request, options).await
    }

    /// Ingest a batch of documents.
    pub async fn ingest_document_batch(
        &self,
        request: IngestDocumentBatchRequest,
        options: Option<&RequestOptions>,
    ) -> Result<IngestDocumentResponse, Error> {
        self.http
            .post("/ingest/document/batch", &request, options)
            .await
    }

    /// RDF ingestion — the backend currently accepts and returns free-form JSON here.
    pub async fn ingest_rdf(
        &self,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<Json, Error> {
        self.http.post("/ingest/rdf", request, options).await
    }

    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 trail-based proof search (typed) ────────────

use crate::api_spec::{
    ApplyCurriedRequest, ApplyCurriedResponse, BacktrackRequest, BacktrackResponse,
    BindTermRequest, BindTermResponse, BindingsResponse, ChoicePointMarkerResponse,
    CreateCurriedFunctionRequest, CreateExecutionSessionRequest, CurriedFunctionResponse,
    CurryingContextResponse, DetectMissingAttributesRequest, ExecutionSessionResponse,
    GetBindingsRequest, GoalStackResponse, LazyEvalRequest, LazyEvalResponse,
    MarkChoicePointRequest, PushGoalRequest, PushGoalResponse, ReleaseResiduationsRequest,
    ReleaseResiduationsResponse, ResiduateGoalRequest,
};
use crate::types::execution::{
    ExecutionCleanupResponse, ExecutionStatsResponse, ResiduateGoalResponse,
};

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

impl ExecutionClient {
    /// Create a new execution session.
    pub async fn create_session(
        &self,
        request: CreateExecutionSessionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ExecutionSessionResponse, Error> {
        self.http
            .post("/execution/sessions", &request, options)
            .await
    }

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

    /// Delete a session.
    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(())
    }

    /// Bind a term inside the session.
    pub async fn bind(
        &self,
        sid: &str,
        request: BindTermRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BindTermResponse, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/bind", encode(sid)),
                &request,
                options,
            )
            .await
    }

    /// Drop a choice-point marker on the trail.
    pub async fn mark(
        &self,
        sid: &str,
        request: MarkChoicePointRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ChoicePointMarkerResponse, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/mark", encode(sid)),
                &request,
                options,
            )
            .await
    }

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

    /// Get current bindings (optionally filtered by term ids).
    pub async fn bindings(
        &self,
        sid: &str,
        request: GetBindingsRequest,
        options: Option<&RequestOptions>,
    ) -> Result<BindingsResponse, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/bindings", encode(sid)),
                &request,
                options,
            )
            .await
    }

    /// Push a goal onto the goal stack.
    pub async fn push_goal(
        &self,
        sid: &str,
        request: PushGoalRequest,
        options: Option<&RequestOptions>,
    ) -> Result<PushGoalResponse, Error> {
        self.http
            .post(
                &format!("/execution/sessions/{}/goals", encode(sid)),
                &request,
                options,
            )
            .await
    }

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

    /// Execute up to `max_steps` goals from the stack. Backend response shape is still in
    /// flux — surfaced as Json until it stabilises.
    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
    }

    /// Create a curried function value.
    pub async fn curry(
        &self,
        request: CreateCurriedFunctionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CurriedFunctionResponse, Error> {
        self.http.post("/execution/curry", &request, options).await
    }

    /// Apply arguments to a curried function.
    pub async fn curry_apply(
        &self,
        request: ApplyCurriedRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ApplyCurriedResponse, Error> {
        self.http
            .post("/execution/curry/apply", &request, options)
            .await
    }

    /// Detect a currying context based on call/definition attributes.
    pub async fn curry_detect(
        &self,
        request: DetectMissingAttributesRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CurryingContextResponse, Error> {
        self.http
            .post("/execution/curry/detect", &request, options)
            .await
    }

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

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

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

    /// Inspect pending residuations for a term. Backend payload still evolving.
    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
    }

    /// Append residuations for a term. Backend payload still evolving.
    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
    }

    /// Mark residuations as pending. Backend payload still evolving.
    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
    }

    /// Sweep stale execution sessions (admin operation).
    pub async fn cleanup(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<ExecutionCleanupResponse, Error> {
        self.http
            .post("/execution/cleanup", &serde_json::json!({}), options)
            .await
    }

    /// Aggregate execution-engine stats.
    pub async fn stats(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<ExecutionStatsResponse, Error> {
        self.http.get("/execution/stats", None, options).await
    }
}

// ─── Proof engine — term-store + rule-store + eval/builtin (typed) ────────────

use crate::api_spec::{
    AssertRuleRequest, AssertRuleResponse, BacktrackTermStoreRequest, BacktrackTermStoreResponse,
    BindVariableRequest, BindVariableResponse, CreateRuleStoreRequest, CreateStoreTermRequest,
    CreateTermResponse, CreateTermStoreRequest, CreateVariableRequest, DereferenceRequest,
    DereferenceResponse, EvalBuiltinRequest, EvalBuiltinResponse, FindRulesRequest,
    FindRulesResponse, GetStoreTermRequest, GetStoreTermResponse,
    ListEvalFunctionsRequest as ListEvalFunctionsQuery, ListEvalFunctionsResponse,
    MarkRuleStoreRequest, MarkRuleStoreResponse, MarkTermStoreRequest,
    MarkTermStoreResponse, RetractRuleRequest, RetractRuleResponse, RuleStoreResponse,
    SetFeatureRequest, SetFeatureResponse, TermStoreSessionResponse, UndoRuleStoreRequest,
    UndoRuleStoreResponse, UnifyTermsRequest, UnifyTermsResponse,
};

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

impl ProofEngineClient {
    // ─── Term store ────────────────────────────────────────────────────────

    pub async fn term_store_create_session(
        &self,
        request: CreateTermStoreRequest,
        options: Option<&RequestOptions>,
    ) -> Result<TermStoreSessionResponse, Error> {
        self.http
            .post("/term-store/sessions", &request, options)
            .await
    }

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

    pub async fn term_store_create_term(
        &self,
        sid: &str,
        request: CreateStoreTermRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CreateTermResponse, 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: CreateVariableRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CreateTermResponse, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/variables", encode(sid)),
                &request,
                options,
            )
            .await
    }

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

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

    pub async fn term_store_dereference(
        &self,
        sid: &str,
        request: DereferenceRequest,
        options: Option<&RequestOptions>,
    ) -> Result<DereferenceResponse, 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: SetFeatureRequest,
        options: Option<&RequestOptions>,
    ) -> Result<SetFeatureResponse, 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: GetStoreTermRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GetStoreTermResponse, Error> {
        self.http
            .post(
                &format!("/term-store/sessions/{}/term", encode(sid)),
                &request,
                options,
            )
            .await
    }

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

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

    // ─── Rule store ────────────────────────────────────────────────────────

    pub async fn rule_store_create_session(
        &self,
        request: CreateRuleStoreRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RuleStoreResponse, Error> {
        self.http
            .post("/rule-store/sessions", &request, options)
            .await
    }

    pub async fn rule_store_get_session(
        &self,
        store_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<RuleStoreResponse, 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: AssertRuleRequest,
        options: Option<&RequestOptions>,
    ) -> Result<AssertRuleResponse, 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: RetractRuleRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RetractRuleResponse, 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: FindRulesRequest,
        options: Option<&RequestOptions>,
    ) -> Result<FindRulesResponse, 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: MarkRuleStoreRequest,
        options: Option<&RequestOptions>,
    ) -> Result<MarkRuleStoreResponse, 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: UndoRuleStoreRequest,
        options: Option<&RequestOptions>,
    ) -> Result<UndoRuleStoreResponse, Error> {
        self.http
            .post(
                &format!("/rule-store/sessions/{}/undo", encode(store_id)),
                &request,
                options,
            )
            .await
    }

    // ─── Eval registry ─────────────────────────────────────────────────────

    pub async fn eval_builtin(
        &self,
        request: EvalBuiltinRequest,
        options: Option<&RequestOptions>,
    ) -> Result<EvalBuiltinResponse, Error> {
        self.http.post("/eval/builtin", &request, options).await
    }

    pub async fn list_eval_functions(
        &self,
        query: ListEvalFunctionsQuery,
        options: Option<&RequestOptions>,
    ) -> Result<ListEvalFunctionsResponse, Error> {
        self.http
            .get_with_typed_query("/eval/functions", &query, options)
            .await
    }
}

// ─── Conversation (typed) ─────────────────────────────────────────────────────

use crate::api_spec::{
    ConversationMessageRequestDto as ConversationMessageRequest,
    ConversationMessageResponseDto as ConversationMessageResponse,
    ConversationTurnsResponseDto as ConversationTurnsResponse,
    CreateTemplateRequestDto as CreateTemplateRequest,
    ListTemplatesResponseDto as ListTemplatesResponse, QueryTemplateDto,
    UpdateTemplateRequestDto as UpdateTemplateRequest,
};

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

impl ConversationClient {
    /// Send a chat-style message; the engine replies with an answer plus optional OSF/QL
    /// execution metadata, claim annotations, and certificate references.
    pub async fn message(
        &self,
        request: ConversationMessageRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ConversationMessageResponse, Error> {
        self.http
            .post("/conversation/message", &request, options)
            .await
    }

    /// Fetch raw conversation history for the authenticated tenant. Backend response is
    /// free-form JSON; surface as Json until the shape stabilises.
    pub async fn history(&self, options: Option<&RequestOptions>) -> Result<Json, Error> {
        self.http.get("/conversation/history", None, options).await
    }

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

    /// Delete a conversation.
    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(())
    }

    /// List query templates (canned OSF/QL patterns).
    pub async fn list_templates(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<ListTemplatesResponse, Error> {
        self.http.get("/templates", None, options).await
    }

    /// Create a new query template.
    pub async fn create_template(
        &self,
        request: CreateTemplateRequest,
        options: Option<&RequestOptions>,
    ) -> Result<QueryTemplateDto, Error> {
        self.http.post("/templates", &request, options).await
    }

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

    /// Delete a query template.
    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 (legacy — backend endpoints not currently mounted) ──────────────
//
// **WARNING:** As of this release the backend has no `/research/*` routes wired
// in `routes.rs`; every method on this client will 404 against a live server.
// The client is kept for source compatibility with 0.1.x but is slated for
// removal in a future minor release. Do not write new code against it.

#[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 (typed core; plans/HTN/messaging/episodes still Json) ──

use crate::api_spec::{
    AdaptiveModifyRequest, AdaptiveModifyResponse, AddBeliefRequest, AddBeliefResponse,
    AddGoalRequest, AddGoalResponse, CreateAgentRequest, CreateAgentResponse,
    GetExtendedAgentStateResponse as ExtendedAgentStateResponse, GetAgentStateRequest,
    GetAgentStateResponse,
    ReflectionQueryRequest, ReflectionQueryResponse, RunCycleRequest, RunCycleResponse,
    RunIntegratedCycleRequest, RunIntegratedCycleResponse,
};

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

impl CognitiveClient {
    /// Create a new cognitive agent.
    pub async fn create_agent(
        &self,
        request: CreateAgentRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CreateAgentResponse, Error> {
        self.http.post("/cognitive/agents", &request, options).await
    }

    /// Get agent metadata. Backend response shape continues to evolve — surfaced as Json.
    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
    }

    /// Delete an agent.
    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(())
    }

    /// Add a goal to an agent. Backend response is currently {goal_id, message}.
    pub async fn add_goal(
        &self,
        agent_id: &str,
        request: AddGoalRequest,
        options: Option<&RequestOptions>,
    ) -> Result<AddGoalResponse, Error> {
        self.http
            .post(
                &format!("/cognitive/agents/{}/goals", encode(agent_id)),
                &request,
                options,
            )
            .await
    }

    /// Add a belief to an agent.
    pub async fn add_belief(
        &self,
        agent_id: &str,
        request: AddBeliefRequest,
        options: Option<&RequestOptions>,
    ) -> Result<AddBeliefResponse, 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");

    /// Run one perceive-reason-act cycle for the agent.
    pub async fn run_cycle(
        &self,
        request: RunCycleRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RunCycleResponse, Error> {
        self.http
            .post("/cognitive/agents/cycle", &request, options)
            .await
    }

    /// Get agent goals + beliefs.
    pub async fn get_state(
        &self,
        request: GetAgentStateRequest,
        options: Option<&RequestOptions>,
    ) -> Result<GetAgentStateResponse, Error> {
        self.http
            .post("/cognitive/agents/state", &request, options)
            .await
    }

    /// Reflective unification query against the agent's own rule base.
    pub async fn reflect(
        &self,
        request: ReflectionQueryRequest,
        options: Option<&RequestOptions>,
    ) -> Result<ReflectionQueryResponse, Error> {
        self.http
            .post("/cognitive/agents/reflect", &request, options)
            .await
    }

    /// Apply rule modifications during inference (homoiconic self-modification).
    pub async fn adapt(
        &self,
        request: AdaptiveModifyRequest,
        options: Option<&RequestOptions>,
    ) -> Result<AdaptiveModifyResponse, Error> {
        self.http
            .post("/cognitive/agents/adapt", &request, options)
            .await
    }

    /// Run a cycle of the 9-module integrated cognitive engine.
    pub async fn run_integrated_cycle(
        &self,
        request: RunIntegratedCycleRequest,
        options: Option<&RequestOptions>,
    ) -> Result<RunIntegratedCycleResponse, Error> {
        self.http
            .post("/cognitive/agents/integrated-cycle", &request, options)
            .await
    }

    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
    }

    /// Extended agent state including activations and episodic memories.
    pub async fn get_extended_state(
        &self,
        agent_id: &str,
        options: Option<&RequestOptions>,
    ) -> Result<ExtendedAgentStateResponse, 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 (typed) ────────────────────────────────────────────────────────

use crate::api_spec::{
    FormalJudgeRefinementResponse, FormalJudgeRequest, FormalJudgeResponse, IngestStepRequest,
    StepVerificationResponse,
};
use crate::types::oversight::{
    CreateOversightSessionRequest, CreateOversightSessionResponse, FinalizeOversightSessionRequest,
    FinalizeOversightSessionResponse, OversightSessionStatusResponse,
};

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

impl OversightClient {
    /// One-shot trajectory judgement. Returns verdict + safety score + violations + certificate.
    pub async fn judge(
        &self,
        request: FormalJudgeRequest,
        options: Option<&RequestOptions>,
    ) -> Result<FormalJudgeResponse, Error> {
        self.http.post("/oversight/judge", &request, options).await
    }

    /// Iterative-refinement judgement (paper §4.5).
    pub async fn judge_refine(
        &self,
        request: FormalJudgeRequest,
        options: Option<&RequestOptions>,
    ) -> Result<FormalJudgeRefinementResponse, Error> {
        self.http
            .post("/oversight/judge/refine", &request, options)
            .await
    }

    /// Create a streaming oversight session.
    pub async fn create_session(
        &self,
        request: CreateOversightSessionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<CreateOversightSessionResponse, Error> {
        self.http
            .post("/oversight/sessions", &request, options)
            .await
    }

    /// Stream a single trajectory step into a session.
    pub async fn ingest_step(
        &self,
        sid: &str,
        request: IngestStepRequest,
        options: Option<&RequestOptions>,
    ) -> Result<StepVerificationResponse, Error> {
        self.http
            .post(
                &format!("/oversight/sessions/{}/ingest", encode(sid)),
                &request,
                options,
            )
            .await
    }

    /// Get the rolling status of an oversight session.
    pub async fn get_session(
        &self,
        sid: &str,
        options: Option<&RequestOptions>,
    ) -> Result<OversightSessionStatusResponse, Error> {
        self.http
            .get(
                &format!("/oversight/sessions/{}", encode(sid)),
                None,
                options,
            )
            .await
    }

    /// Finalize an oversight session and emit the final verdict.
    pub async fn finalize(
        &self,
        sid: &str,
        request: FinalizeOversightSessionRequest,
        options: Option<&RequestOptions>,
    ) -> Result<FinalizeOversightSessionResponse, 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 (typed responses) ───────────────────────────────────

use crate::api_spec::{
    NeuroSymbolicStatusResponse, SortBoxResponse, TrainFromTracesResponse, TrainingTriggerResponse,
};
use crate::types::neuro_symbolic::{DiagnosticsSnapshot, EmbeddingVerifyResponse};

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

impl NeuroSymbolicClient {
    /// Status of the neuro-symbolic subsystem.
    pub async fn status(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<NeuroSymbolicStatusResponse, Error> {
        self.http
            .get("/admin/neuro-symbolic/status", None, options)
            .await
    }

    /// Trigger end-to-end training. Request payload is currently free-form.
    pub async fn train(
        &self,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<TrainingTriggerResponse, Error> {
        self.http
            .post("/admin/neuro-symbolic/train", request, options)
            .await
    }

    pub async fn train_embeddings(
        &self,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<TrainingTriggerResponse, Error> {
        self.http
            .post("/admin/neuro-symbolic/train/embeddings", request, options)
            .await
    }

    /// Diagnostic snapshot from the trace collector.
    pub async fn diagnostics(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<DiagnosticsSnapshot, Error> {
        self.http
            .get("/admin/neuro-symbolic/diagnostics", None, options)
            .await
    }

    pub async fn train_e2e(
        &self,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<TrainingTriggerResponse, Error> {
        self.http
            .post("/admin/neuro-symbolic/train/e2e", request, options)
            .await
    }

    pub async fn train_from_traces(
        &self,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<TrainFromTracesResponse, Error> {
        self.http
            .post("/admin/neuro-symbolic/train/from-traces", request, options)
            .await
    }

    pub async fn train_gflownet(
        &self,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<TrainingTriggerResponse, Error> {
        self.http
            .post("/admin/neuro-symbolic/train/gflownet", request, options)
            .await
    }

    pub async fn save_weights(
        &self,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<TrainingTriggerResponse, Error> {
        self.http
            .post("/admin/neuro-symbolic/save-weights", request, options)
            .await
    }

    pub async fn verify_embeddings(
        &self,
        options: Option<&RequestOptions>,
    ) -> Result<EmbeddingVerifyResponse, Error> {
        self.http
            .get("/admin/neuro-symbolic/embeddings/verify", None, options)
            .await
    }

    pub async fn sort_box(
        &self,
        request: &Json,
        options: Option<&RequestOptions>,
    ) -> Result<SortBoxResponse, Error> {
        self.http
            .post(
                "/admin/neuro-symbolic/embeddings/sort-box",
                request,
                options,
            )
            .await
    }
}

// ─── 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()
}