osiris/README.md

# OSIRIS

**Object Storage with Rhai Scripting Integration**

OSIRIS is a Rust-native object storage layer built on HeroDB, providing structured storage with automatic indexing, Rhai scripting support, and signatory-based access control.

## Overview

OSIRIS provides a trait-based architecture for storing and retrieving typed objects with:
- **Automatic Indexing**: Fields marked with `#[index]` are automatically indexed
- **Rhai Integration**: Full scripting support with builder patterns
- **Context-Based Storage**: Multi-tenant contexts with signatory-based access control
- **Type Safety**: Compile-time guarantees through the `Object` trait
- **HeroDB Backend**: Built on top of HeroDB (Redis-compatible)

## Quick Start

### Build OSIRIS

```bash
cargo build --release --features rhai-support
```

### Run a Rhai Script

```bash
cargo run --bin runner --features rhai-support -- runner1 \
  --redis-url redis://localhost:6379 \
  --db-id 1 \
  --script-file examples/engine/01_note.rhai
```

### Example Script

```rhai
// Get a context (requires signatories)
let ctx = get_context(["alice_pk", "bob_pk"]);

// Create a note
let note = note("notes")
    .title("My First Note")
    .content("This is the content")
    .tag("topic", "rust")
    .tag("priority", "high");

// Save to context
ctx.save(note);

// Query by index
let ids = ctx.query("notes", "tags:tag", "topic=rust");
print(`Found ${ids.len()} notes`);
```

## Architecture

### Core Components

```
OSIRIS
├── objects/           – Domain objects (Note, Event, User, etc.)
│   ├── note/
│   │   ├── mod.rs    – Note struct and impl
│   │   └── rhai.rs   – Rhai bindings
│   └── event/
│       ├── mod.rs    – Event struct and impl
│       └── rhai.rs   – Rhai bindings
├── store/            – Storage layer
│   ├── generic_store.rs  – Type-safe storage
│   └── type_registry.rs  – Custom type registration
├── rhai/             – Rhai integration
│   ├── instance.rs   – OsirisContext (multi-tenant)
│   └── engine.rs     – Engine configuration
└── bin/
    └── runner.rs     – Standalone script runner
```

### Object Trait

All OSIRIS objects implement the `Object` trait:

```rust
#[derive(Debug, Clone, Serialize, Deserialize, DeriveObject)]
pub struct Note {
    pub base_data: BaseData,
    
    #[index]
    pub title: Option<String>,
    
    pub content: Option<String>,
    
    #[index]
    pub tags: BTreeMap<String, String>,
}
```

The `#[derive(DeriveObject)]` macro automatically:
- Implements the `Object` trait
- Generates index keys from `#[index]` fields
- Provides serialization/deserialization

## Key Features

### 1. Signatory-Based Access Control

Contexts use signatory-based access instead of owner-based permissions:

```rhai
// Single participant
let ctx = get_context(["alice_pk"]);

// Shared context (all must be signatories)
let ctx = get_context(["alice_pk", "bob_pk", "charlie_pk"]);
```

Access is granted only if all participants are signatories of the script.

### 2. Automatic Indexing

Fields marked with `#[index]` are automatically indexed in HeroDB:

```rust
#[index]
pub title: Option<String>,  // Indexed for fast queries

pub content: Option<String>, // Not indexed
```

Query by indexed fields:
```rhai
let ids = ctx.query("notes", "title", "My Note");
let ids = ctx.query("notes", "tags:tag", "topic=rust");
```

### 3. Multi-Instance Support

Create multiple OSIRIS instances pointing to different databases:

```bash
cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:redis://localhost:6379:1 \
  --instance my:redis://localhost:6379:2 \
  --script-file script.rhai
```

```rhai
// Instances are automatically available
freezone.save(note);
my.save(note);
```

### 4. Builder Pattern

Fluent API for creating objects:

```rhai
let event = event("calendar", "Team Meeting")
    .description("Weekly sync")
    .location("Conference Room A")
    .category("meetings")
    .all_day(false);

ctx.save(event);
```

## Creating Custom Objects

See [docs/CREATING_NEW_OBJECTS.md](docs/CREATING_NEW_OBJECTS.md) for a complete guide on creating new object types.

Quick example:

```rust
#[derive(Debug, Clone, Serialize, Deserialize, DeriveObject)]
pub struct Task {
    pub base_data: BaseData,
    
    #[index]
    pub title: String,
    
    pub completed: bool,
}
```

## Storage Model

### HeroDB Keyspace

```
obj:<ns>:<id>              → JSON serialized object
idx:<ns>:<field>:<value>   → Set of object IDs
scan:<ns>                  → Set of all object IDs in namespace
```

Example:
```
obj:notes:abc123           → {"base_data":{...},"title":"My Note",...}
idx:notes:title:My Note    → {abc123, def456}
idx:notes:tag:topic:rust   → {abc123, xyz789}
scan:notes                 → {abc123, def456, xyz789}
```

### Context Storage

Contexts store member privileges and metadata:
```
ctx:<context_id>:members   → Map of user_id → privileges
ctx:<context_id>:meta      → Context metadata
```

## Examples

The `examples/` directory contains comprehensive examples:

- **`examples/engine/`** - Object creation and storage examples
  - `01_note.rhai` - Note creation and querying
  - `02_event.rhai` - Event management
  - `03_user.rhai` - User objects
  - And more...

- **`examples/freezone/`** - Complete freezone registration flow

Run examples:
```bash
cargo run --example engine examples/engine/01_note.rhai
```

## Documentation

- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Detailed architecture and design patterns
- **[docs/CREATING_NEW_OBJECTS.md](docs/CREATING_NEW_OBJECTS.md)** - Guide for creating custom objects

## Building and Testing

```bash
# Build with Rhai support
cargo build --features rhai-support

# Run tests
cargo test --lib --features rhai-support

# Build release binary
cargo build --release --features rhai-support --bin runner
```

## Integration

OSIRIS is used by:
- **ZDFZ Backend** - Freezone company and resident management
- **Hero Actor System** - Distributed job execution with object storage

## License

See LICENSE file.