clm-kernel 0.0.17

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Satori MCard Codec & Speech Act Calculus.
//! Canonical Path: kernel/clm_rust_core/src/satori/mcard_codec.rs
//! Deliverable: DEL-254-02
//!
//! Provides bidirectional translation between Satori conversational message ASTs
//! and content-addressed immutable MCards, categorizing speech acts according to the
//! 5 canonical Searle-Austin classes.

use crate::domain::{MCard, MCardPayload};
use crate::satori::element::{SatoriElement, SatoriMessage};
#[cfg(feature = "native")]
use crate::satori::parser::parse_satori_xml;
use crate::types::AgentDid;

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// Canonical Searle-Austin speech act taxonomy.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SatoriSpeechActType {
    /// Propositions, facts, observations: M_fact
    Assertive,
    /// Requests, questions, commands, PCard invocation: M_req -> PCard
    Directive,
    /// Commitments, promises, execution plans
    Commissive,
    /// Evaluations, sentiments, ratings
    Expressive,
    /// Authority-sealed transitions, VCard witnesses, Maxwell receipts
    Declarative,
}

impl SatoriSpeechActType {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Assertive => "assertive",
            Self::Directive => "directive",
            Self::Commissive => "commissive",
            Self::Expressive => "expressive",
            Self::Declarative => "declarative",
        }
    }

    pub fn from_str(s: &str) -> Option<Self> {
        match s.to_lowercase().as_str() {
            "assertive" => Some(Self::Assertive),
            "directive" => Some(Self::Directive),
            "commissive" => Some(Self::Commissive),
            "expressive" => Some(Self::Expressive),
            "declarative" => Some(Self::Declarative),
            _ => None,
        }
    }
}

/// Classifies a Satori message into one of the 5 Searle-Austin speech act types.
pub fn classify_speech_act(msg: &SatoriMessage) -> SatoriSpeechActType {
    // Directives: actions, buttons, execution commands
    for elem in &msg.elements {
        match elem {
            SatoriElement::Action { .. } | SatoriElement::Button { .. } => {
                return SatoriSpeechActType::Directive;
            }
            _ => {}
        }
    }

    // Inspect text content for keywords
    let full_text: String = msg
        .elements
        .iter()
        .filter_map(|e| match e {
            SatoriElement::Text { text } => Some(text.as_str()),
            _ => None,
        })
        .collect::<Vec<_>>()
        .join(" ");

    let lower = full_text.to_lowercase();
    if lower.contains("?") || lower.starts_with("please ") || lower.starts_with("can you ") {
        SatoriSpeechActType::Directive
    } else if lower.contains("i will ") || lower.contains("we promise ") || lower.contains("committed to") {
        SatoriSpeechActType::Commissive
    } else if lower.contains("thank") || lower.contains("congrat") || lower.contains("great") || lower.contains("sorry") {
        SatoriSpeechActType::Expressive
    } else if lower.contains("declared") || lower.contains("witnessed:") || lower.contains("receipt:") {
        SatoriSpeechActType::Declarative
    } else {
        SatoriSpeechActType::Assertive
    }
}

/// Converts a SatoriMessage to a canonical Content-Addressed MCard.
pub fn satori_to_mcard(
    msg: &SatoriMessage,
    speech_act: Option<SatoriSpeechActType>,
) -> Result<MCard, String> {
    let act_type = speech_act.unwrap_or_else(|| classify_speech_act(msg));
    let uri = format!("mcard:chat/message/{}", msg.id);

    let mut metadata = HashMap::new();
    metadata.insert(
        "speech_act_type".to_string(),
        serde_json::Value::String(act_type.as_str().to_string()),
    );
    metadata.insert(
        "satori_id".to_string(),
        serde_json::Value::String(msg.id.clone()),
    );
    metadata.insert(
        "channel_id".to_string(),
        serde_json::Value::String(msg.channel_id.clone()),
    );
    metadata.insert(
        "user_did".to_string(),
        serde_json::Value::String(msg.user_did.clone()),
    );
    metadata.insert(
        "timestamp".to_string(),
        serde_json::Value::Number(serde_json::Number::from(msg.timestamp)),
    );

    let author = AgentDid::new(&msg.user_did)
        .unwrap_or_else(|_| AgentDid::new("did:key:anonymous").unwrap());

    let payload = MCardPayload::Satori(msg.clone());

    Ok(MCard::with_metadata(
        uri,
        payload,
        metadata,
        author,
        msg.timestamp,
    ))
}

/// Reconstructs a SatoriMessage from a Content-Addressed MCard.
pub fn mcard_to_satori(card: &MCard) -> Result<SatoriMessage, String> {
    match &card.payload {
        MCardPayload::Satori(msg) => Ok(msg.clone()),
        MCardPayload::Structured(val) => SatoriMessage::from_mcard(val),
        MCardPayload::Text(xml_or_text) => {
            #[cfg(feature = "native")]
            let elements = parse_satori_xml(xml_or_text)
                .unwrap_or_else(|_| vec![SatoriElement::text(xml_or_text)]);
            #[cfg(not(feature = "native"))]
            let elements = vec![SatoriElement::text(xml_or_text)];


            let id = card
                .metadata
                .get("satori_id")
                .and_then(|v| v.as_str())
                .unwrap_or_else(|| card.uri.trim_start_matches("mcard:chat/message/"))
                .to_string();

            let channel_id = card
                .metadata
                .get("channel_id")
                .and_then(|v| v.as_str())
                .unwrap_or("")
                .to_string();

            let user_did = card
                .metadata
                .get("user_did")
                .and_then(|v| v.as_str())
                .unwrap_or(card.author.as_str())
                .to_string();

            let timestamp = card
                .metadata
                .get("timestamp")
                .and_then(|v| v.as_u64())
                .unwrap_or(card.sequence);

            Ok(SatoriMessage {
                id,
                channel_id,
                user_did,
                elements,
                timestamp,
            })
        }
        _ => Err(format!(
            "Unsupported MCard payload type for Satori conversion: {:?}",
            card.payload
        )),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::satori::element::SatoriElement;

    #[test]
    fn test_satori_to_mcard_roundtrip() {
        let elements = vec![
            SatoriElement::at("did:key:alice"),
            SatoriElement::text("Please execute transformation"),
            SatoriElement::button("btn_run", "Run"),
        ];

        let msg = SatoriMessage::new(
            "msg_turn_101",
            "chan_dev",
            "did:key:alice",
            elements,
            1725000000,
        );

        // Convert to MCard
        let card = satori_to_mcard(&msg, None).expect("Satori to MCard should succeed");

        assert_eq!(card.uri, "mcard:chat/message/msg_turn_101");
        assert_eq!(
            card.metadata.get("speech_act_type").and_then(|v| v.as_str()),
            Some("directive")
        );
        assert_eq!(card.sequence, 1725000000);
        assert!(!card.hash.as_str().is_empty());

        // Roundtrip back to Satori
        let roundtrip = mcard_to_satori(&card).expect("MCard to Satori should succeed");
        assert_eq!(roundtrip.id, msg.id);
        assert_eq!(roundtrip.channel_id, msg.channel_id);
        assert_eq!(roundtrip.user_did, msg.user_did);
        assert_eq!(roundtrip.elements.len(), 3);
        assert_eq!(roundtrip.timestamp, msg.timestamp);
    }

    #[test]
    fn test_speech_act_classification() {
        let assert_msg = SatoriMessage::new(
            "msg1",
            "chan",
            "did:key:alice",
            vec![SatoriElement::text("The server is operational.")],
            1720000000,
        );
        assert_eq!(classify_speech_act(&assert_msg), SatoriSpeechActType::Assertive);

        let directive_msg = SatoriMessage::new(
            "msg2",
            "chan",
            "did:key:alice",
            vec![
                SatoriElement::text("Do you want to proceed?"),
                SatoriElement::button("btn_yes", "Yes"),
            ],
            1720000001,
        );
        assert_eq!(classify_speech_act(&directive_msg), SatoriSpeechActType::Directive);

        let comm_msg = SatoriMessage::new(
            "msg3",
            "chan",
            "did:key:alice",
            vec![SatoriElement::text("I will deploy the update shortly.")],
            1720000002,
        );
        assert_eq!(classify_speech_act(&comm_msg), SatoriSpeechActType::Commissive);

        let expr_msg = SatoriMessage::new(
            "msg4",
            "chan",
            "did:key:alice",
            vec![SatoriElement::text("Thank you for your assistance!")],
            1720000003,
        );
        assert_eq!(classify_speech_act(&expr_msg), SatoriSpeechActType::Expressive);

        let decl_msg = SatoriMessage::new(
            "msg5",
            "chan",
            "did:key:alice",
            vec![SatoriElement::text("Receipt: Maxwell Gate Verified H^1=0")],
            1720000004,
        );
        assert_eq!(classify_speech_act(&decl_msg), SatoriSpeechActType::Declarative);
    }
}