khive-pack-session 0.10.0

Session verb pack - store/list/resume/export over the notes substrate
Documentation
//! `session.store` - store a session record as a `kind=session` note.

use serde_json::{json, Value};

use khive_runtime::{KhiveRuntime, NamespaceToken, RuntimeError};

use super::{deser, to_session_record, StoreParams, StoreResult};
use crate::vocab::SESSION_KIND;

const VERB: &str = "session.store";

pub(crate) async fn handle_store(
    runtime: &KhiveRuntime,
    token: &NamespaceToken,
    params: Value,
) -> Result<Value, RuntimeError> {
    let p: StoreParams = deser(params)?;
    p.validate(VERB)?;

    let mut properties = serde_json::Map::new();
    if let Some(provider) = &p.provider {
        properties.insert("provider".into(), json!(provider));
    }
    if let Some(provider_session_id) = &p.provider_session_id {
        properties.insert("provider_session_id".into(), json!(provider_session_id));
    }
    if let Some(tags) = &p.tags {
        properties.insert("tags".into(), json!(tags));
    }

    // Session content is caller-supplied and often longer than the embedder's
    // input budget. The report variant keeps the committed record a success and
    // discloses the truncation, as comm, kg and knowledge writes do, instead of
    // failing a write that has already been stored.
    let core = runtime.core();
    let (note, embedding_truncation) = core
        .create_note_with_embedding_content_and_report(
            token,
            SESSION_KIND,
            p.title.as_deref(),
            &p.content,
            None,
            None,
            Some(Value::Object(properties)),
            vec![],
        )
        .await?;

    let result = StoreResult {
        ok: true,
        session: to_session_record(&note),
    };
    let mut response = serde_json::to_value(result).expect("StoreResult serializes");
    if embedding_truncation.any_truncated() {
        response["warnings"] = json!([khive_runtime::retrieval::EMBEDDING_INPUT_TRUNCATED_WARNING]);
    }
    Ok(response)
}

#[cfg(test)]
mod tests {
    use khive_runtime::{KhiveRuntime, Namespace};
    use serde_json::json;

    use super::handle_store;

    struct TruncationEmbeddingService;

    #[async_trait::async_trait]
    impl lattice_embed::EmbeddingService for TruncationEmbeddingService {
        async fn embed(
            &self,
            texts: &[String],
            _model: lattice_embed::EmbeddingModel,
        ) -> Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
            Ok(vec![vec![1.0]; texts.len()])
        }

        fn supports_model(&self, _model: lattice_embed::EmbeddingModel) -> bool {
            true
        }

        fn name(&self) -> &'static str {
            "session-truncation-test"
        }
    }

    struct TruncationEmbedderProvider;

    #[async_trait::async_trait]
    impl khive_runtime::EmbedderProvider for TruncationEmbedderProvider {
        fn name(&self) -> &str {
            "session-truncation-test"
        }

        fn dimensions(&self) -> usize {
            1
        }

        async fn build(
            &self,
        ) -> Result<std::sync::Arc<dyn lattice_embed::EmbeddingService>, khive_runtime::RuntimeError>
        {
            Ok(std::sync::Arc::new(TruncationEmbeddingService))
        }
    }

    #[tokio::test]
    async fn store_over_embedding_budget_keeps_the_session_and_discloses_truncation() {
        let rt = KhiveRuntime::memory().expect("in-memory runtime");
        rt.register_embedder(TruncationEmbedderProvider);
        let token = rt.authorize(Namespace::local()).expect("authorize local");
        let content = "x".repeat(lattice_embed::MAX_TEXT_BYTES + 1);

        let response = handle_store(&rt, &token, json!({ "content": content }))
            .await
            .expect("an over-budget session must not fail after it is committed");

        assert_eq!(
            response["warnings"],
            json!([khive_runtime::retrieval::EMBEDDING_INPUT_TRUNCATED_WARNING]),
            "store must disclose the truncated embedding input: {response}"
        );
        let id = uuid::Uuid::parse_str(response["session"]["id"].as_str().expect("session id"))
            .expect("session id is a uuid");
        let stored = rt
            .core()
            .notes(&token)
            .expect("notes store")
            .get_note(id)
            .await
            .expect("read the stored session")
            .expect("the session is stored");
        assert_eq!(stored.content.len(), lattice_embed::MAX_TEXT_BYTES + 1);
    }

    #[tokio::test]
    async fn store_within_embedding_budget_has_no_warning() {
        let rt = KhiveRuntime::memory().expect("in-memory runtime");
        rt.register_embedder(TruncationEmbedderProvider);
        let token = rt.authorize(Namespace::local()).expect("authorize local");

        let response = handle_store(&rt, &token, json!({ "content": "short session" }))
            .await
            .expect("store a session");

        assert!(
            response.get("warnings").is_none(),
            "no warning expected: {response}"
        );
    }

    #[tokio::test]
    async fn empty_content_rejected() {
        let rt = KhiveRuntime::memory().expect("in-memory runtime");
        let token = rt.authorize(Namespace::local()).expect("authorize local");

        let err = handle_store(&rt, &token, json!({ "content": "" }))
            .await
            .unwrap_err();

        let khive_runtime::RuntimeError::InvalidInput(msg) = err else {
            panic!("expected InvalidInput, got {err:?}");
        };
        assert!(
            msg.contains("content must not be empty"),
            "error must name the empty-content violation; got: {msg}",
        );
    }

    #[tokio::test]
    async fn blank_title_rejected() {
        let rt = KhiveRuntime::memory().expect("in-memory runtime");
        let token = rt.authorize(Namespace::local()).expect("authorize local");

        let err = handle_store(&rt, &token, json!({ "content": "hello", "title": "" }))
            .await
            .unwrap_err();

        let khive_runtime::RuntimeError::InvalidInput(msg) = err else {
            panic!("expected InvalidInput, got {err:?}");
        };
        assert!(
            msg.contains("title must be a non-empty string when provided"),
            "error must name the blank-title violation; got: {msg}",
        );
    }

    #[tokio::test]
    async fn blank_provider_rejected() {
        let rt = KhiveRuntime::memory().expect("in-memory runtime");
        let token = rt.authorize(Namespace::local()).expect("authorize local");

        let err = handle_store(&rt, &token, json!({ "content": "hello", "provider": "" }))
            .await
            .unwrap_err();

        let khive_runtime::RuntimeError::InvalidInput(msg) = err else {
            panic!("expected InvalidInput, got {err:?}");
        };
        assert!(
            msg.contains("provider must be a non-empty string when provided"),
            "error must name the blank-provider violation; got: {msg}",
        );
    }

    #[tokio::test]
    async fn blank_provider_session_id_rejected() {
        let rt = KhiveRuntime::memory().expect("in-memory runtime");
        let token = rt.authorize(Namespace::local()).expect("authorize local");

        let err = handle_store(
            &rt,
            &token,
            json!({ "content": "hello", "provider_session_id": "" }),
        )
        .await
        .unwrap_err();

        let khive_runtime::RuntimeError::InvalidInput(msg) = err else {
            panic!("expected InvalidInput, got {err:?}");
        };
        assert!(
            msg.contains("provider_session_id must be a non-empty string when provided"),
            "error must name the blank-provider_session_id violation; got: {msg}",
        );
    }

    #[tokio::test]
    async fn empty_tag_entry_rejected() {
        let rt = KhiveRuntime::memory().expect("in-memory runtime");
        let token = rt.authorize(Namespace::local()).expect("authorize local");

        let err = handle_store(
            &rt,
            &token,
            json!({ "content": "hello", "tags": ["good", ""] }),
        )
        .await
        .unwrap_err();

        let khive_runtime::RuntimeError::InvalidInput(msg) = err else {
            panic!("expected InvalidInput, got {err:?}");
        };
        assert!(
            msg.contains("tags entries must be non-empty strings"),
            "error must name the empty-tag-entry violation; got: {msg}",
        );
    }
}