token-optimizer 0.1.1

// ================================================================================
// PRODUCT  : sovereign-stack:token-optimizer
// COMPONENT: LLM Envelope (Transport Protocol)
// FILE     : crates/token-optimizer/src/llm_envelope/mod.rs
// ROLE     : Handles the JSON-wrapped TOML payload for efficient IPC and APIs.
// PURPOSE  : To bypass JavaScript object-mapping brittleness and optimize 
//            token consumption in LLM context windows.
// AUTHOR   : Chamara Somaratne assisted by Gemini, Ashby, Serge & Ciara 
//            (Sovereign Gestalt)
// LICENSE  : Apache-2.0
// ================================================================================

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

// ==============================================================================
// PHASE 1: TRAIT DEFINITIONS
// ==============================================================================

pub trait Envelopable: Serialize {
    fn to_toml_payload(&self) -> Result<String, String> {
        toml::to_string(self).map_err(|e| format!("TOML_SERIALIZATION_ERROR: {}", e))
    }
}

// ==============================================================================
// PHASE 2: THE SOVEREIGN ENVELOPE
// ==============================================================================

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Envelope {
    pub persona: String,
    pub metadata: HashMap<String, String>,
    pub payload: String,
}

impl Envelope {
    pub fn new(persona: &str, payload: String) -> Self {
        Self {
            persona: persona.to_string(),
            metadata: HashMap::new(),
            payload,
        }
    }

    pub fn pack<T: Envelopable>(persona: &str, data: &T) -> Result<String, String> {
        let toml_content = data.to_toml_payload()?;
        let envelope = Self::new(persona, toml_content);
        
        serde_json::to_string(&envelope).map_err(|e| format!("IPC_PACKING_ERROR: {}", e))
    }

    pub fn unpack(json_input: &str) -> Result<Self, String> {
        serde_json::from_str(json_input).map_err(|e| format!("IPC_UNPACKING_ERROR: {}", e))
    }
}

// ==============================================================================
// PHASE 3: ORACLE INTEGRATION
// PURPOSE: Prepare the envelope content for the final Oracle request.
// ==============================================================================

impl Envelope {
    // --------------------------------------------------------------------------------
    // 3.1 Prompt Synthesis (to_oracle_prompt)
    // PURPOSE: Formats the Envelope for the final Oracle request.
    // --------------------------------------------------------------------------------
    pub fn to_oracle_prompt(&self) -> String {
        format!(
            "--- START ENGRAM [{}] ---\n{}\n--- END ENGRAM ---",
            self.persona.to_uppercase(),
            self.payload
        )
    }
}