Kotoba Core

Core components for the Kotoba graph processing system. Provides fundamental types, IR definitions, and common utilities used across the entire Kotoba ecosystem.

🎯 Overview

Kotoba Core serves as the foundational layer for all Kotoba crates, providing:

• Unified Type System: Common data types with serialization support
• Error Handling: Consistent error types across the ecosystem
• IR Definitions: Intermediate representations for graph processing
• Cryptographic Primitives: Content hashing and integrity verification

🏗️ Architecture

Core Components

Types System (types.rs)

// Fundamental data types
pub type VertexId = Uuid;
pub type EdgeId = Uuid;
pub type Label = String;

// Extensible value system
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
pub enum Value {
    Null,
    Bool(bool),
    Int(i64),
    String(String),
}

// Cryptographic primitives
pub struct ContentHash(String);
impl ContentHash {
    pub fn sha256(data: [u8; 32]) -> Self;
}

Intermediate Representations (ir/)

• catalog.rs: Schema and catalog management for graph databases
• query.rs: Query representation and optimization structures
• rule.rs: Graph rewriting and transformation rules
• patch.rs: Atomic graph modification operations
• strategy.rs: Execution strategy patterns and algorithms

📊 Quality Metrics

🔧 Usage

Basic Usage

use kotoba_core::prelude::*;

// Working with core types
let vertex_id = VertexId::new_v4();
let value = Value::String("Hello, Kotoba!".to_string());

// Hash generation
let data = [42u8; 32];
let hash = ContentHash::sha256(data);

// Error handling
fn process_graph() -> Result<GraphRef_> {
    // Implementation using unified error types
    Ok(GraphRef_("graph_hash".to_string()))
}

IR Usage

use kotoba_core::ir::{query::QueryIR, rule::RuleIR};

// Query processing
let query = QueryIR::parse("MATCH (n) RETURN n")?;

// Rule application
let rule = RuleIR::new("optimization_rule");

🔗 Ecosystem Integration

Kotoba Core is the foundation for:

🧪 Testing

cargo test -p kotoba-core

Test Coverage:

• ✅ Value serialization/deserialization
• ✅ Content hash generation
• ✅ UUID type validation
• ✅ IR structure validation

📈 Performance

• Zero-cost abstractions for type system
• Efficient serialization with Serde
• Minimal runtime overhead for core operations
• Cryptographic operations optimized for performance

🔒 Security

• Cryptographically secure hash generation (SHA-256)
• Type-safe value system preventing injection attacks
• UUID-based identifiers for secure resource management
• No unsafe code in core functionality

📚 API Reference

Core Types

• [Value] - Extensible value type system
• [VertexId] / [EdgeId] - UUID-based identifiers
• [ContentHash] - Cryptographic content verification
• [Properties] - Key-value property storage

IR Modules

• [catalog] - Schema and catalog management
• [query] - Query representation and optimization
• [rule] - Graph rewriting rules
• [patch] - Graph transformation operations
• [strategy] - Execution strategy patterns

🤝 Contributing

See the main Kotoba repository for contribution guidelines.

📄 License

Licensed under MIT OR Apache-2.0. See LICENSE for details.