kotoba-core 0.1.22

# Kotoba Core

[![Crates.io](https://img.shields.io/crates/v/kotoba-core.svg)](https://crates.io/crates/kotoba-core)
[![Documentation](https://docs.rs/kotoba-core/badge.svg)](https://docs.rs/kotoba-core)
[![License](https://img.shields.io/crates/l/kotoba-core.svg)](https://github.com/com-junkawasaki/kotoba)

**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`)
```rust
// 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

| Metric | Status |
|--------|--------|
| **Compilation** | ✅ Clean (no warnings) |
| **Tests** | ✅ 100% coverage on core types |
| **Documentation** | ✅ Complete API docs |
| **Dependencies** | ✅ Minimal, secure |
| **Performance** | ✅ Zero-cost abstractions |

## 🔧 Usage

### Basic Usage
```rust
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
```rust
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:

| Crate | Purpose | Dependency |
|-------|---------|------------|
| `kotoba-graph` | Graph data structures | **Required** |
| `kotoba-execution` | Query execution engine | **Required** |
| `kotoba-jsonnet` | Configuration processing | **Required** |
| `kotoba-storage` | Persistence layer | **Required** |
| `kotoba-security` | Authentication & authorization | **Required** |
| `kotoba-server` | HTTP server components | **Required** |
| `kotoba-rewrite` | Graph transformations | **Required** |

## 🧪 Testing

```bash
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](https://github.com/com-junkawasaki/kotoba) for contribution guidelines.

## 📄 License

Licensed under MIT OR Apache-2.0. See [LICENSE](https://github.com/com-junkawasaki/kotoba/blob/main/LICENSE) for details.