fathomdb 0.5.5

//! JSON-based FFI surface for admin-plane operations that need richer
//! serde shapes than a flat string list.
//!
//! Pack P7.6a introduces this module so the Python and TypeScript SDKs
//! can register recursive FTS property schemas via the engine's
//! [`Engine::register_fts_property_schema_with_entries`] entry point.
//! The types are plain serde structures — no pyo3 / napi dependencies —
//! so translation can be unit- and integration-tested directly via
//! `cargo test` without linking against libpython or libnode, mirroring
//! the pattern established by [`crate::search_ffi`].

use serde::{Deserialize, Serialize};

use crate::{
    Engine, EngineError, FtsPropertyPathMode, FtsPropertyPathSpec, FtsPropertySchemaRecord,
};
use fathomdb_engine::{
    BatchEmbedder, Capabilities, ConfigureEmbeddingOutcome, ConfigureVecOutcome, CurrentConfig,
    EmbedderError, FtsProfile, KindDescription, ProjectionImpact, QueryEmbedder,
    QueryEmbedderIdentity, VecIndexStatus, VecProfile, VectorSource,
};

/// Extraction mode for a single registered FTS property path, serialized
/// as `"scalar"` or `"recursive"` on the wire.
#[derive(Clone, Copy, Debug, Deserialize, Serialize, Eq, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum PyPropertyPathMode {
    /// Treat the path as a scalar — matches legacy pre-Phase-4 behaviour.
    Scalar,
    /// Recursively walk every scalar leaf rooted at the path.
    Recursive,
}

impl From<PyPropertyPathMode> for FtsPropertyPathMode {
    fn from(value: PyPropertyPathMode) -> Self {
        match value {
            PyPropertyPathMode::Scalar => Self::Scalar,
            PyPropertyPathMode::Recursive => Self::Recursive,
        }
    }
}

/// A single registered property-FTS path with its extraction mode.
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
pub struct PyPropertyPathSpec {
    /// JSON path to the property (must start with `$.`).
    pub path: String,
    /// Whether to treat this path as a scalar or recursively walk it.
    pub mode: PyPropertyPathMode,
    /// Optional BM25 weight multiplier for this path.
    #[serde(default)]
    pub weight: Option<f32>,
}

impl From<PyPropertyPathSpec> for FtsPropertyPathSpec {
    fn from(value: PyPropertyPathSpec) -> Self {
        let base = match value.mode {
            PyPropertyPathMode::Recursive => FtsPropertyPathSpec::recursive(value.path),
            PyPropertyPathMode::Scalar => FtsPropertyPathSpec::scalar(value.path),
        };
        match value.weight {
            Some(w) => base.with_weight(w),
            None => base,
        }
    }
}

/// JSON envelope for [`register_fts_property_schema_with_entries_json`].
///
/// Wire shape:
/// ```json
/// {
///   "kind": "KnowledgeItem",
///   "entries": [
///     {"path": "$.title", "mode": "scalar"},
///     {"path": "$.payload", "mode": "recursive"}
///   ],
///   "separator": " ",
///   "exclude_paths": []
/// }
/// ```
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
pub struct PyRegisterFtsPropertySchemaRequest {
    /// Node kind to register.
    pub kind: String,
    /// Ordered list of path specs.
    pub entries: Vec<PyPropertyPathSpec>,
    /// Concatenation separator. Use a single space when unspecified by
    /// the caller.
    #[serde(default = "default_separator")]
    pub separator: String,
    /// JSON paths to exclude from recursive walks.
    #[serde(default)]
    pub exclude_paths: Vec<String>,
}

fn default_separator() -> String {
    " ".to_owned()
}

/// Error produced by the admin FFI JSON translation path.
#[derive(Debug)]
pub enum AdminFfiError {
    /// The request JSON could not be deserialized.
    Parse(serde_json::Error),
    /// Engine rejected the request.
    Engine(EngineError),
    /// Response serialization failed.
    Serialize(serde_json::Error),
}

impl std::fmt::Display for AdminFfiError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Parse(e) => write!(f, "admin request JSON parse error: {e}"),
            Self::Engine(e) => write!(f, "admin operation error: {e}"),
            Self::Serialize(e) => write!(f, "admin response serialize error: {e}"),
        }
    }
}

impl std::error::Error for AdminFfiError {}

/// Register (or update) an FTS property projection schema whose entries
/// may include recursive-mode paths. The `request_json` payload must
/// match [`PyRegisterFtsPropertySchemaRequest`].
///
/// Returns the serialized [`FtsPropertySchemaRecord`] on success.
///
/// # Errors
/// Returns [`AdminFfiError`] on JSON parse, engine execution, or
/// response serialization failure.
pub fn register_fts_property_schema_with_entries_json(
    engine: &Engine,
    request_json: &str,
) -> Result<String, AdminFfiError> {
    let request: PyRegisterFtsPropertySchemaRequest =
        serde_json::from_str(request_json).map_err(AdminFfiError::Parse)?;
    let entries: Vec<FtsPropertyPathSpec> = request.entries.into_iter().map(Into::into).collect();
    let record: FtsPropertySchemaRecord = engine
        .register_fts_property_schema_with_entries(
            &request.kind,
            &entries,
            Some(request.separator.as_str()),
            &request.exclude_paths,
        )
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&record).map_err(AdminFfiError::Serialize)
}

/// Request envelope for [`set_fts_profile_json`].
#[derive(Debug, Deserialize)]
struct SetFtsProfileRequest {
    kind: String,
    tokenizer: String,
}

/// Set the FTS tokenizer profile for a node kind.
///
/// `request_json` must be `{"kind":"K","tokenizer":"T"}`.
///
/// Returns the serialized [`FtsProfile`] on success.
///
/// # Errors
/// Returns [`AdminFfiError`] on JSON parse, engine execution, or
/// response serialization failure.
pub fn set_fts_profile_json(engine: &Engine, request_json: &str) -> Result<String, AdminFfiError> {
    let request: SetFtsProfileRequest =
        serde_json::from_str(request_json).map_err(AdminFfiError::Parse)?;
    let profile: FtsProfile = engine
        .admin()
        .service()
        .set_fts_profile(&request.kind, &request.tokenizer)
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&profile).map_err(AdminFfiError::Serialize)
}

/// Retrieve the FTS tokenizer profile for a node kind.
///
/// Returns `"null"` if no profile has been set for `kind`.
///
/// # Errors
/// Returns [`AdminFfiError`] on engine execution or response serialization failure.
pub fn get_fts_profile_json(engine: &Engine, kind: &str) -> Result<String, AdminFfiError> {
    let profile: Option<FtsProfile> = engine
        .admin()
        .service()
        .get_fts_profile(kind)
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&profile).map_err(AdminFfiError::Serialize)
}

/// Request envelope for [`set_vec_profile_json`].
///
/// Used purely for typed validation of incoming JSON; fields are read by
/// `serde_json` deserialization but not accessed in code after that.
#[derive(Debug, Deserialize)]
#[allow(dead_code)]
struct SetVecProfileRequest {
    model_identity: String,
    #[serde(default)]
    model_version: Option<String>,
    dimensions: u32,
    #[serde(default)]
    normalization_policy: Option<String>,
}

/// Set (or update) the global vector embedding profile.
///
/// `request_json` must be valid JSON with at least `model_identity` and
/// `dimensions` fields, e.g.
/// `{"model_identity":"...","model_version":"...","dimensions":384,"normalization_policy":"l2"}`.
///
/// Returns the serialized [`VecProfile`] on success.
///
/// # Errors
/// Returns [`AdminFfiError`] on JSON parse, engine execution, or
/// response serialization failure.
pub fn set_vec_profile_json(engine: &Engine, request_json: &str) -> Result<String, AdminFfiError> {
    // Typed validation: ensures model_identity and dimensions are present.
    // Gives a clear parse error if required fields are missing, rather than
    // storing a profile with NULL fields and failing cryptically on get_vec_profile.
    let _validated: SetVecProfileRequest =
        serde_json::from_str(request_json).map_err(AdminFfiError::Parse)?;
    let profile: VecProfile = engine
        .admin()
        .service()
        .set_vec_profile(request_json)
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&profile).map_err(AdminFfiError::Serialize)
}

/// Retrieve the vector embedding profile for a specific node kind.
///
/// Returns `"null"` if no profile has been persisted for this kind yet.
///
/// # Errors
/// Returns [`AdminFfiError`] on engine execution or response serialization failure.
pub fn get_vec_profile_json(engine: &Engine, kind: &str) -> Result<String, AdminFfiError> {
    let profile: Option<VecProfile> = engine
        .admin()
        .service()
        .get_vec_profile(kind)
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&profile).map_err(AdminFfiError::Serialize)
}

/// Estimate the cost of rebuilding a projection for a given node kind and facet.
///
/// `facet` must be `"fts"` or `"vec"`.
///
/// Returns the serialized [`ProjectionImpact`] on success.
///
/// # Errors
/// Returns [`AdminFfiError`] on engine execution or response serialization failure.
pub fn preview_projection_impact_json(
    engine: &Engine,
    kind: &str,
    facet: &str,
) -> Result<String, AdminFfiError> {
    let impact: ProjectionImpact = engine
        .admin()
        .service()
        .preview_projection_impact(kind, facet)
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&impact).map_err(AdminFfiError::Serialize)
}

/// Request envelope for [`configure_vec_kind_json`].
#[derive(Debug, Deserialize)]
struct ConfigureVecKindRequest {
    kind: String,
    #[serde(default = "default_vec_source")]
    source: String,
}

fn default_vec_source() -> String {
    "chunks".to_owned()
}

/// Wire envelope for [`configure_embedding_json`].
///
/// `acknowledge_rebuild_impact` defaults to `false`. The `identity`
/// fields carry what the caller-supplied (Python / TypeScript) embedder
/// reports from its own `identity()` call — on the Rust side these are
/// wrapped in a tiny identity-only shim so `AdminService::configure_embedding`
/// still reads identity off a `QueryEmbedder`, preserving the
/// "identity belongs to the embedder" invariant.
#[derive(Debug, Deserialize)]
struct ConfigureEmbeddingRequest {
    model_identity: String,
    #[serde(default)]
    model_version: Option<String>,
    dimensions: u32,
    #[serde(default)]
    normalization_policy: Option<String>,
    #[serde(default = "default_max_tokens")]
    max_tokens: usize,
    #[serde(default)]
    acknowledge_rebuild_impact: bool,
}

fn default_max_tokens() -> usize {
    512
}

#[derive(Debug)]
struct IdentityOnlyEmbedder {
    identity: QueryEmbedderIdentity,
    max_tokens: usize,
}

impl QueryEmbedder for IdentityOnlyEmbedder {
    fn embed_query(&self, _text: &str) -> Result<Vec<f32>, EmbedderError> {
        Err(EmbedderError::Unavailable(
            "identity-only FFI shim cannot embed; configure_embedding only reads identity()"
                .to_owned(),
        ))
    }
    fn identity(&self) -> QueryEmbedderIdentity {
        self.identity.clone()
    }
    fn max_tokens(&self) -> usize {
        self.max_tokens
    }
}

/// Configure managed vector indexing for a given node `kind`.
///
/// `request_json` must be `{"kind":"K","source":"chunks"}`. Only
/// `"chunks"` is accepted today; future source modes will extend the set.
///
/// Returns the serialized [`ConfigureVecOutcome`].
///
/// # Errors
/// Returns [`AdminFfiError`] on JSON parse, engine execution, or response
/// serialization failure.
pub fn configure_vec_kind_json(
    engine: &Engine,
    request_json: &str,
) -> Result<String, AdminFfiError> {
    let request: ConfigureVecKindRequest =
        serde_json::from_str(request_json).map_err(AdminFfiError::Parse)?;
    let source = match request.source.as_str() {
        "chunks" => VectorSource::Chunks,
        other => {
            return Err(AdminFfiError::Engine(EngineError::InvalidConfig(format!(
                "unsupported vector source mode: {other:?}"
            ))));
        }
    };
    let outcome: ConfigureVecOutcome = engine
        .admin()
        .service()
        .configure_vec_kind(&request.kind, source)
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&outcome).map_err(AdminFfiError::Serialize)
}

/// Admin FFI for `AdminService::configure_embedding`.
///
/// `request_json` must match [`ConfigureEmbeddingRequest`]: identity
/// fields (echoed verbatim from the caller's embedder), plus optional
/// `acknowledge_rebuild_impact`.
///
/// Returns the JSON-serialized [`ConfigureEmbeddingOutcome`].
///
/// # Errors
/// Returns [`AdminFfiError`] on JSON parse, engine execution, or response
/// serialization failure.
pub fn configure_embedding_json(
    engine: &Engine,
    request_json: &str,
) -> Result<String, AdminFfiError> {
    let request: ConfigureEmbeddingRequest =
        serde_json::from_str(request_json).map_err(AdminFfiError::Parse)?;
    let identity = QueryEmbedderIdentity {
        model_identity: request.model_identity,
        model_version: request.model_version.unwrap_or_default(),
        dimension: request.dimensions as usize,
        normalization_policy: request.normalization_policy.unwrap_or_default(),
    };
    let shim = IdentityOnlyEmbedder {
        identity,
        max_tokens: request.max_tokens,
    };
    let outcome: ConfigureEmbeddingOutcome = engine
        .admin()
        .service()
        .configure_embedding(&shim, request.acknowledge_rebuild_impact)
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&outcome).map_err(AdminFfiError::Serialize)
}

/// Retrieve the managed vector indexing status for a given node `kind`.
///
/// Returns the serialized [`VecIndexStatus`]. If the kind has no
/// `vector_index_schemas` row the status reports `enabled=false` and
/// `state="unconfigured"`.
///
/// # Errors
/// Returns [`AdminFfiError`] on engine execution or response
/// serialization failure.
pub fn get_vec_index_status_json(engine: &Engine, kind: &str) -> Result<String, AdminFfiError> {
    let status: VecIndexStatus = engine
        .admin()
        .service()
        .get_vec_index_status(kind)
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&status).map_err(AdminFfiError::Serialize)
}

/// Pack H: return the static install/build capabilities surface.
///
/// Wire shape: no request body (empty JSON object). Returns a serialized
/// [`Capabilities`] struct.
///
/// # Errors
/// Returns [`AdminFfiError::Serialize`] on response serialization failure.
pub fn capabilities_json() -> Result<String, AdminFfiError> {
    let caps: Capabilities = fathomdb_engine::AdminService::capabilities();
    serde_json::to_string(&caps).map_err(AdminFfiError::Serialize)
}

/// Pack H: return the runtime configuration snapshot.
///
/// Wire shape: no request body. Returns a serialized [`CurrentConfig`].
///
/// # Errors
/// Returns [`AdminFfiError`] on engine execution or response
/// serialization failure.
pub fn current_config_json(engine: &Engine) -> Result<String, AdminFfiError> {
    let cfg: CurrentConfig = engine
        .admin()
        .service()
        .current_config()
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&cfg).map_err(AdminFfiError::Serialize)
}

/// Pack H: return the per-kind view.
///
/// Wire shape: raw kind string. Returns a serialized [`KindDescription`].
///
/// # Errors
/// Returns [`AdminFfiError`] on engine execution or response
/// serialization failure.
pub fn describe_kind_json(engine: &Engine, kind: &str) -> Result<String, AdminFfiError> {
    let desc: KindDescription = engine
        .admin()
        .service()
        .describe_kind(kind)
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&desc).map_err(AdminFfiError::Serialize)
}

/// Pack H: wire-level envelope for [`configure_vec_kinds_json`].
#[derive(Debug, Deserialize)]
struct ConfigureVecKindsRequest {
    items: Vec<ConfigureVecKindsItem>,
}

#[derive(Debug, Deserialize)]
struct ConfigureVecKindsItem {
    kind: String,
    source: String,
}

/// Pack H: batch form of `configure_vec_kind_json`.
///
/// Wire shape: `{"items":[{"kind":"K","source":"chunks"}, ...]}`. Returns a
/// JSON array of [`ConfigureVecOutcome`] in input order.
///
/// # Errors
/// Returns [`AdminFfiError`] on JSON parse, engine execution, or response
/// serialization failure. Per-kind atomicity matches
/// [`fathomdb_engine::AdminService::configure_vec_kind`]; a failure on
/// item N leaves items 0..N committed.
pub fn configure_vec_kinds_json(
    engine: &Engine,
    request_json: &str,
) -> Result<String, AdminFfiError> {
    let request: ConfigureVecKindsRequest =
        serde_json::from_str(request_json).map_err(AdminFfiError::Parse)?;
    let mut items: Vec<(String, VectorSource)> = Vec::with_capacity(request.items.len());
    for it in request.items {
        let source = match it.source.as_str() {
            "chunks" => VectorSource::Chunks,
            other => {
                return Err(AdminFfiError::Engine(EngineError::InvalidConfig(format!(
                    "unsupported vector source mode: {other:?}"
                ))));
            }
        };
        items.push((it.kind, source));
    }
    let outcomes: Vec<ConfigureVecOutcome> = engine
        .admin()
        .service()
        .configure_vec_kinds(&items)
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&outcomes).map_err(AdminFfiError::Serialize)
}

/// Request envelope for [`drain_vector_projection_json`].
#[derive(Debug, Deserialize)]
struct DrainVectorProjectionRequest {
    timeout_ms: u64,
}

/// Adapter that exposes a `&dyn QueryEmbedder` (the engine's read-time
/// embedder held on `ExecutionCoordinator`) as a [`BatchEmbedder`].
///
/// Pack F1.5 routes admin-side vector-projection drains through the same
/// embedder that serves read-time `semantic_search`, preserving the
/// "identity belongs to the embedder" invariant: callers of the FFI
/// cannot override identity or supply an alternative embedder — the
/// engine's coordinator is the sole source of truth.
struct QueryEmbedderBatchAdapter<'a> {
    inner: &'a dyn QueryEmbedder,
}

impl BatchEmbedder for QueryEmbedderBatchAdapter<'_> {
    fn batch_embed(&self, texts: &[String]) -> Result<Vec<Vec<f32>>, EmbedderError> {
        let mut out = Vec::with_capacity(texts.len());
        for text in texts {
            out.push(self.inner.embed_query(text)?);
        }
        Ok(out)
    }
    fn identity(&self) -> QueryEmbedderIdentity {
        self.inner.identity()
    }
    fn max_tokens(&self) -> usize {
        self.inner.max_tokens()
    }
}

/// Drain the vector-projection queue using the engine's configured
/// read-time embedder.
///
/// Wire shape:
/// ```json
/// { "timeout_ms": 5000 }
/// ```
///
/// Returns the serialized
/// [`fathomdb_engine::vector_projection_actor::DrainReport`].
///
/// If the engine was opened without a query embedder (or the built-in
/// feature flag is disabled), returns an [`AdminFfiError::Engine`]
/// wrapping [`EngineError::EmbedderNotConfigured`]. The caller never
/// supplies an embedder — identity belongs to the embedder wired into
/// the engine, not the FFI request.
///
/// # Errors
/// Returns [`AdminFfiError`] on JSON parse, missing embedder, engine
/// execution, or response serialization failure.
pub fn drain_vector_projection_json(
    engine: &Engine,
    request_json: &str,
) -> Result<String, AdminFfiError> {
    let request: DrainVectorProjectionRequest =
        serde_json::from_str(request_json).map_err(AdminFfiError::Parse)?;
    let embedder_arc = engine
        .coordinator()
        .query_embedder()
        .cloned()
        .ok_or_else(|| AdminFfiError::Engine(EngineError::EmbedderNotConfigured))?;
    let adapter = QueryEmbedderBatchAdapter {
        inner: embedder_arc.as_ref(),
    };
    let report = engine
        .admin()
        .service()
        .drain_vector_projection(
            &adapter,
            std::time::Duration::from_millis(request.timeout_ms),
        )
        .map_err(AdminFfiError::Engine)?;
    serde_json::to_string(&report).map_err(AdminFfiError::Serialize)
}

#[cfg(test)]
#[allow(clippy::expect_used)]
mod tests {
    use super::{PyPropertyPathMode, PyPropertyPathSpec, PyRegisterFtsPropertySchemaRequest};
    use crate::FtsPropertyPathSpec;

    #[test]
    fn property_path_mode_snake_case_wire_form() {
        let json = serde_json::to_string(&PyPropertyPathMode::Scalar).expect("serialize");
        assert_eq!(json, "\"scalar\"");
        let json = serde_json::to_string(&PyPropertyPathMode::Recursive).expect("serialize");
        assert_eq!(json, "\"recursive\"");
    }

    #[test]
    fn property_path_spec_roundtrip() {
        let spec = PyPropertyPathSpec {
            path: "$.payload".to_owned(),
            mode: PyPropertyPathMode::Recursive,
            weight: None,
        };
        let json = serde_json::to_string(&spec).expect("serialize");
        let parsed: PyPropertyPathSpec = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(spec, parsed);
    }

    #[test]
    fn register_request_defaults_separator_and_exclude_paths() {
        let request: PyRegisterFtsPropertySchemaRequest =
            serde_json::from_str(r#"{"kind":"K","entries":[{"path":"$.title","mode":"scalar"}]}"#)
                .expect("parse");
        assert_eq!(request.kind, "K");
        assert_eq!(request.separator, " ");
        assert!(request.exclude_paths.is_empty());
        assert_eq!(request.entries.len(), 1);
    }

    #[test]
    fn weight_round_trips_through_py_property_path_spec() {
        let json = r#"{"path": "$.title", "mode": "scalar", "weight": 10.0}"#;
        let spec: PyPropertyPathSpec = serde_json::from_str(json).expect("deserialize");
        assert_eq!(spec.weight, Some(10.0_f32));
        let fts_spec: FtsPropertyPathSpec = spec.into();
        let _ = fts_spec; // conversion must not panic
    }

    #[test]
    fn weight_absent_defaults_to_none() {
        let json = r#"{"path": "$.body", "mode": "scalar"}"#;
        let spec: PyPropertyPathSpec = serde_json::from_str(json).expect("deserialize");
        assert_eq!(spec.weight, None);
    }

    #[test]
    fn register_request_roundtrip_recursive_entry() {
        let request = PyRegisterFtsPropertySchemaRequest {
            kind: "KnowledgeItem".to_owned(),
            entries: vec![
                PyPropertyPathSpec {
                    path: "$.title".to_owned(),
                    mode: PyPropertyPathMode::Scalar,
                    weight: None,
                },
                PyPropertyPathSpec {
                    path: "$.payload".to_owned(),
                    mode: PyPropertyPathMode::Recursive,
                    weight: None,
                },
            ],
            separator: " ".to_owned(),
            exclude_paths: vec!["$.payload.ignored".to_owned()],
        };
        let json = serde_json::to_string(&request).expect("serialize");
        let parsed: PyRegisterFtsPropertySchemaRequest =
            serde_json::from_str(&json).expect("deserialize");
        assert_eq!(request, parsed);
    }
}