@celestia-island/plana-types 0.1.0

package/src/malkuth.rs

@@ -0,0 +1,145 @@
+//! malkuth supervision protocol types.
+//!
+//! Wire types for the restart-authorization gate and worker lifecycle
+//! management across the celestia-island supervision tree.
+//!
+//! ## Phase 0: authorization gate
+//! - RestartProposal: generated after a repo rebuild completes
+//! - RestartGateDecision: OreXis audit result (allow/review/block)
+//! - GateDecision: enum for the three-state gate
+//!
+//! ## Phase 1: worker lifecycle
+//! - DrainRequest / WorkerRegistration / WorkerStatus / HealthResponse
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use ts_rs::TS;
+
+/// A rebuild has completed and restart is proposed for a supervised worker.
+#[derive(Debug, Clone, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+pub struct RestartProposal {
+    pub proposal_id: String,
+    pub worker_id: String,
+    pub repo_path: String,
+    pub git_diff_summary: String,
+    pub affected_services: Vec<String>,
+    pub risk_estimate: RestartRisk,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+#[serde(rename_all = "snake_case")]
+pub enum RestartRisk {
+    Low,
+    Medium,
+    High,
+    Critical,
+}
+
+/// OreXis LAYER3_PREFLIGHT_GUARD gate decision for a restart proposal.
+#[derive(Debug, Clone, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+pub struct RestartGateDecision {
+    pub proposal_id: String,
+    pub decision: GateDecision,
+    pub findings: Vec<String>,
+    pub reason: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+#[serde(rename_all = "snake_case")]
+pub enum GateDecision {
+    /// Proceed with restart.
+    Allow,
+    /// Escalate to human for review.
+    Review,
+    /// Block restart — security risk detected.
+    Block,
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Phase 1 — worker lifecycle wire types
+// ═══════════════════════════════════════════════════════════════
+
+/// External request to drain (gracefully shut down) a supervised worker.
+/// Sent to malkuth daemon after a restart proposal has been approved.
+#[derive(Debug, Clone, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+pub struct DrainRequest {
+    /// Which worker to drain.
+    pub worker_id: String,
+    /// Authorization: must match a previously approved GateDecision.proposal_id.
+    pub proposal_id: String,
+    /// Optional drain budget in seconds (default derived from worker config).
+    pub drain_budget_secs: Option<u64>,
+}
+
+/// Registers a new worker with the malkuth supervisor.
+/// Sent by a worker at startup to announce its presence and capabilities.
+#[derive(Debug, Clone, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+pub struct WorkerRegistration {
+    pub worker_id: String,
+    pub worker_kind: String,
+    pub repo_path: String,
+    pub connections: Vec<ConnectionEndpoint>,
+    pub health_check_path: Option<String>,
+    pub drain_budget_secs: u64,
+}
+
+/// Describes how clients connect to a supervised worker.
+#[derive(Debug, Clone, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+pub struct ConnectionEndpoint {
+    pub protocol: ConnectionProtocol,
+    pub address: String,
+    pub port: u16,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+#[serde(rename_all = "snake_case")]
+pub enum ConnectionProtocol {
+    Http,
+    Ws,
+    Ipc,
+    Tcp,
+}
+
+/// Current status of a supervised worker returned by malkuth when queried.
+#[derive(Debug, Clone, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+pub struct WorkerStatus {
+    pub worker_id: String,
+    pub state: WorkerState,
+    pub pid: Option<u32>,
+    pub restart_count: u32,
+    pub last_restart_at: Option<String>,
+    pub connections: Vec<ConnectionEndpoint>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+#[serde(rename_all = "snake_case")]
+pub enum WorkerState {
+    Running,
+    /// Worker is accepting /readyz but not new work (drain in progress).
+    Draining,
+    Stopped,
+    Crashed,
+}
+
+/// Health probe response returned by each worker at `/healthz` or `/readyz`.
+#[derive(Debug, Clone, Serialize, Deserialize, TS, JsonSchema)]
+#[ts(export, export_to = "ws/malkuth.ts")]
+pub struct HealthResponse {
+    pub worker_id: String,
+    pub healthy: bool,
+    pub ready: bool,
+    /// If not ready, the reason (e.g. "draining", "starting").
+    pub not_ready_reason: Option<String>,
+    pub uptime_secs: u64,
+    pub version: String,
+}

package/src/mcp/aporia.rs

@@ -0,0 +1,272 @@
+use uuid::Uuid;
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct RagDbWriteResult {
+    pub doc_id: Uuid,
+    pub embedding_dim: usize,
+    pub content: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct RagDocResult {
+    pub doc_id: Uuid,
+    pub similarity: f64,
+    pub content: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(type = "Record<string, unknown> | null")]
+    pub metadata: Option<serde_json::Value>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct RagDbReadResult {
+    pub count: usize,
+    pub results: Vec<RagDocResult>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct RagDbDeleteResult {
+    pub doc_id: Uuid,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct LlmChatResult {
+    pub model: String,
+    pub tokens: String,
+    pub response: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct TranslateReportResult {
+    pub target_language: String,
+    pub original_length: usize,
+    pub translated_length: usize,
+    pub translation: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct MediaAssetRegisterResult {
+    pub asset_id: Uuid,
+    pub asset_type: String,
+    pub source_url: String,
+    pub tags: Vec<String>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct MediaAssetItem {
+    pub asset_id: Uuid,
+    pub asset_type: String,
+    pub source_url: String,
+    #[ts(type = "Record<string, unknown>")]
+    pub metadata: serde_json::Value,
+    pub tags: Vec<String>,
+    pub created_at: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct MediaAssetRetrieveResult {
+    pub count: usize,
+    pub assets: Vec<MediaAssetItem>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct WorkspaceIndexResult {
+    pub total_files: usize,
+    pub total_chunks: usize,
+    pub total_bytes: usize,
+    pub duration_ms: u64,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct WorkspaceSearchDoc {
+    pub doc_id: Uuid,
+    pub file_path: String,
+    pub start_line: usize,
+    pub end_line: usize,
+    pub language: String,
+    pub similarity: f64,
+    pub snippet: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct WorkspaceSearchResult {
+    pub count: usize,
+    pub results: Vec<WorkspaceSearchDoc>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct WorkspaceStatusResult {
+    pub total_files: usize,
+    pub total_chunks: usize,
+    pub total_bytes: usize,
+    pub last_indexed: Option<String>,
+    pub is_indexing: bool,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct RagDbStatsResult {
+    pub total_documents: usize,
+    pub total_media_assets: usize,
+    pub embedding_dimensions: Option<usize>,
+    pub storage_backend: String,
+}
+
+// ── Tool result structs (analysis) ──
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct CorrelationInfo {
+    pub variable: String,
+    pub correlation: f64,
+    pub lag: usize,
+    pub direction: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct Hypothesis {
+    pub cause: String,
+    pub effect: String,
+    pub strength: f64,
+    pub reasoning: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct CausalReasonResult {
+    pub correlations: Vec<CorrelationInfo>,
+    pub hypotheses: Vec<Hypothesis>,
+    pub recommended_actions: Vec<String>,
+    pub confidence: f64,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct AnomalyInfo {
+    pub index: usize,
+    pub value: f64,
+    pub expected: f64,
+    pub deviation: f64,
+    pub timestamp: Option<i64>,
+    pub severity: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct AnomalyResult {
+    pub anomalies: Vec<AnomalyInfo>,
+    pub total_points: usize,
+    pub anomaly_count: usize,
+    pub anomaly_ratio: f64,
+    pub method: String,
+    pub threshold: f64,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct RagDbWriteParams {
+    pub content: String,
+    #[serde(default)]
+    pub embedding: Option<Vec<f64>>,
+    #[serde(default)]
+    #[ts(type = "Record<string, unknown> | null")]
+    pub metadata: Option<serde_json::Value>,
+    #[serde(default)]
+    pub source: Option<String>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct RagDbReadParams {
+    pub query_embedding: Vec<f64>,
+    #[serde(default)]
+    pub limit: Option<usize>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct RagDbDeleteParams {
+    pub id: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct AnomalyDetectParams {
+    pub values: Vec<f64>,
+    #[serde(default)]
+    pub method: Option<String>,
+    #[serde(default)]
+    pub threshold: Option<f64>,
+    #[serde(default)]
+    pub timestamps: Option<Vec<i64>>,
+    #[serde(default)]
+    pub window_size: Option<usize>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct CausalReasonParams {
+    pub target: String,
+    pub target_values: Vec<f64>,
+    #[serde(default)]
+    pub candidates: Option<std::collections::HashMap<String, Vec<f64>>>,
+    #[serde(default)]
+    pub max_lag: Option<usize>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct WorkspaceIndexParams {
+    pub workspace_root: String,
+    #[serde(default)]
+    pub full_rebuild: Option<bool>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct WorkspaceSearchParams {
+    pub query: String,
+    #[serde(default)]
+    pub limit: Option<usize>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct LlmChatParams {
+    pub prompt: String,
+    #[serde(default)]
+    pub model: Option<String>,
+    #[serde(default)]
+    pub system_prompt: Option<String>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct TranslateReportParams {
+    pub content: String,
+    #[serde(default)]
+    pub target_language: Option<String>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct RagDbStatsParams {}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/aporia.ts")]
+pub struct WorkspaceStatusParams {}

package/src/mcp/eleos.rs

@@ -0,0 +1,210 @@
+use crate::enums::WebSearchEngine;
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/eleos.ts")]
+pub struct WebSearchItem {
+    pub url: String,
+    pub title: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/eleos.ts")]
+pub struct WebSearchResult {
+    pub query: String,
+    pub engine: WebSearchEngine,
+    pub count: usize,
+    pub results: Vec<WebSearchItem>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/eleos.ts")]
+pub struct WebFetchResult {
+    pub url: String,
+    pub title: String,
+    pub status_code: u16,
+    pub headers: String,
+    pub content: String,
+    pub content_preview: String,
+    pub content_length: usize,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/eleos.ts")]
+pub struct RemoteRefEntry {
+    pub ref_id: String,
+    pub url: String,
+    pub title: String,
+    pub ref_type: String,
+    pub registered_at: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/eleos.ts")]
+pub struct QueryRemoteRefsResult {
+    pub count: usize,
+    pub refs: Vec<RemoteRefEntry>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/eleos.ts")]
+pub struct RegisterRemoteRefsResult {
+    pub ref_id: String,
+    pub url: String,
+    pub registered: bool,
+}
+
+// ── Tool parameter structs (for .d.ts API signature generation) ──
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/eleos.ts")]
+pub struct WebFetchParams {
+    pub url: String,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ts_rs::TS)]
+#[ts(export, export_to = "mcp/eleos.ts")]
+pub struct WebSearchParams {
+    pub query: String,
+    pub engine: Option<String>,
+    pub limit: Option<u64>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::enums::WebSearchEngine;
+    use serde_json::json;
+
+    #[test]
+    fn web_search_result_round_trip() {
+        let r = WebSearchResult {
+            query: "rust async runtime".into(),
+            engine: WebSearchEngine::Duckduckgo,
+            count: 2,
+            results: vec![
+                WebSearchItem {
+                    url: "https://tokio.rs".into(),
+                    title: "Tokio".into(),
+                },
+                WebSearchItem {
+                    url: "https://async.rs".into(),
+                    title: "async-std".into(),
+                },
+            ],
+        };
+        let v = serde_json::to_value(&r).unwrap();
+        // WebSearchEngine serializes as PascalCase variant name.
+        assert_eq!(v["engine"], "Duckduckgo");
+        assert_eq!(v["count"], 2);
+        assert_eq!(v["results"][0]["url"], "https://tokio.rs");
+        let back: WebSearchResult = serde_json::from_value(v).unwrap();
+        assert_eq!(back.results.len(), 2);
+    }
+
+    #[test]
+    fn web_search_result_empty() {
+        let r = WebSearchResult {
+            query: "nothing".into(),
+            engine: WebSearchEngine::Duckduckgo,
+            count: 0,
+            results: vec![],
+        };
+        let v = serde_json::to_value(&r).unwrap();
+        assert_eq!(v["results"], json!([]));
+    }
+
+    #[test]
+    fn web_fetch_result_round_trip() {
+        let r = WebFetchResult {
+            url: "https://example.com".into(),
+            title: "Example".into(),
+            status_code: 200,
+            headers: "content-type: text/html".into(),
+            content: "<html>...</html>".into(),
+            content_preview: "<html>...".into(),
+            content_length: 1024,
+        };
+        let v = serde_json::to_value(&r).unwrap();
+        assert_eq!(v["status_code"], 200);
+        assert_eq!(v["content_length"], 1024);
+        let back: WebFetchResult = serde_json::from_value(v).unwrap();
+        assert_eq!(back.status_code, 200);
+    }
+
+    #[test]
+    fn remote_ref_entry_round_trip() {
+        let r = RemoteRefEntry {
+            ref_id: "ref-001".into(),
+            url: "https://docs.rs".into(),
+            title: "Rust Docs".into(),
+            ref_type: "documentation".into(),
+            registered_at: "2026-07-07T00:00:00Z".into(),
+        };
+        let v = serde_json::to_value(&r).unwrap();
+        assert_eq!(v["ref_type"], "documentation");
+        let back: RemoteRefEntry = serde_json::from_value(v).unwrap();
+        assert_eq!(back.ref_id, "ref-001");
+    }
+
+    #[test]
+    fn query_remote_refs_result_round_trip() {
+        let r = QueryRemoteRefsResult {
+            count: 1,
+            refs: vec![RemoteRefEntry {
+                ref_id: "r1".into(),
+                url: "https://x.com".into(),
+                title: "X".into(),
+                ref_type: "article".into(),
+                registered_at: "2026-01-01".into(),
+            }],
+        };
+        let v = serde_json::to_value(&r).unwrap();
+        assert_eq!(v["count"], 1);
+    }
+
+    #[test]
+    fn register_remote_refs_result_round_trip() {
+        let r = RegisterRemoteRefsResult {
+            ref_id: "ref-002".into(),
+            url: "https://new.url".into(),
+            registered: true,
+        };
+        let v = serde_json::to_value(&r).unwrap();
+        assert_eq!(v["registered"], true);
+    }
+
+    #[test]
+    fn web_search_params_minimal() {
+        let p = WebSearchParams {
+            query: "test".into(),
+            engine: None,
+            limit: None,
+        };
+        let v = serde_json::to_value(&p).unwrap();
+        assert_eq!(v["query"], "test");
+        assert_eq!(v["engine"], serde_json::Value::Null);
+    }
+
+    #[test]
+    fn web_search_params_with_all_fields() {
+        let p = WebSearchParams {
+            query: "test".into(),
+            engine: Some("duckduckgo".into()),
+            limit: Some(10),
+        };
+        let v = serde_json::to_value(&p).unwrap();
+        assert_eq!(v["limit"], 10);
+    }
+
+    #[test]
+    fn web_search_engine_enum_round_trip() {
+        let e = WebSearchEngine::Duckduckgo;
+        let s = serde_json::to_string(&e).unwrap();
+        // serde uses PascalCase variant name; as_str() returns the wire value.
+        assert_eq!(s, r#""Duckduckgo""#);
+        let back: WebSearchEngine = serde_json::from_str(&s).unwrap();
+        assert_eq!(back, e);
+        // as_str() gives the lowercase domain vocabulary string.
+        assert_eq!(e.as_str(), "duckduckgo");
+    }
+}