osiris/RUNNER.md

# OSIRIS Runner - Standalone Binary ✅

The OSIRIS runner is a standalone binary that executes Rhai scripts with full OSIRIS object support.

## 🎉 Status: FULLY OPERATIONAL

```
✅ Binary created at src/bin/runner/
✅ Rhai engine with OSIRIS objects
✅ Note and Event support
✅ Automatic indexing
✅ Query functionality
✅ Test scripts working
```

## 🚀 Quick Start

### Run a Script File

```bash
cargo run --bin runner --features rhai-support -- runner1 --script-file scripts/test_note.rhai
```

### Run Inline Script

```bash
cargo run --bin runner --features rhai-support -- runner1 \
  --script 'let note = note("test").title("Hi"); print(note.get_title());'
```

## 📝 Example Output

```
🚀 OSIRIS Runner
Runner ID: test1
HeroDB: redis://localhost:6379 (DB 1)

📝 Executing script...

─────────────────────────────────────
=== OSIRIS Note Test ===

Creating note...
Note created: Test from OSIRIS Runner
Storing note...
✓ Note stored with ID: 46a064c7-9062-4858-a390-c11f0d5877a7

Retrieving note...
✓ Retrieved: Test from OSIRIS Runner
  Content: This note was created using the OSIRIS standalone runner!

Querying notes by tag...
✓ Found notes:
  - 2c54e1ec-bed9-41ea-851c-f7313abbd7cd
  - 392f3f7f-47e7-444f-ba11-db38d74b12af
  - 46a064c7-9062-4858-a390-c11f0d5877a7
=== Test Complete ===
─────────────────────────────────────

✅ Script completed successfully!
```

## 📖 Usage

### Command Line Options

```
OSIRIS Rhai Script Runner

Usage: runner [OPTIONS] <RUNNER_ID>

Arguments:
  <RUNNER_ID>  Runner ID

Options:
  -r, --redis-url <REDIS_URL>
          HeroDB URL [default: redis://localhost:6379]
  -d, --db-id <DB_ID>
          HeroDB database ID [default: 1]
  -s, --script <SCRIPT>
          Script to execute in single-job mode (optional)
  -f, --script-file <SCRIPT_FILE>
          Script file to execute
  -h, --help
          Print help
  -V, --version
          Print version
```

### Script Examples

#### Create and Store a Note

```rhai
// scripts/test_note.rhai
let note = note("notes")
    .title("My Note")
    .content("This is the content")
    .tag("project", "osiris")
    .tag("priority", "high");

let id = put_note(note);
print(`Stored: ${id}`);

let retrieved = get_note("notes", id);
print(`Title: ${retrieved.get_title()}`);
```

#### Create and Store an Event

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

let id = put_event(event);
print(`Event stored: ${id}`);
```

#### Query by Index

```rhai
let ids = query("notes", "tags:tag", "project=osiris");
print("Found notes:");
for id in ids {
    let note = get_note("notes", id);
    print(`  - ${note.get_title()}`);
}
```

## 🏗️ Architecture

```
┌─────────────────────────────────────┐
│   OSIRIS Runner Binary              │
│   (osiris/src/bin/runner/)          │
├─────────────────────────────────────┤
│   ├── main.rs                       │
│   │   - CLI argument parsing        │
│   │   - Script loading              │
│   │   - Execution orchestration     │
│   └── engine.rs                     │
│       - Engine factory              │
│       - OSIRIS integration          │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   OSIRIS Rhai Support               │
│   (osiris/src/rhai_support/)        │
├─────────────────────────────────────┤
│   ├── note_rhai.rs                  │
│   │   - Note CustomType             │
│   │   - Builder methods             │
│   ├── event_rhai.rs                 │
│   │   - Event CustomType            │
│   │   - Builder methods             │
│   └── engine.rs                     │
│       - OsirisRhaiEngine            │
│       - Async → Sync bridge         │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   OSIRIS Core                       │
│   (osiris/src/)                     │
├─────────────────────────────────────┤
│   ├── objects/                      │
│   │   - Note, Event                 │
│   │   - #[derive(DeriveObject)]     │
│   ├── store/                        │
│   │   - GenericStore                │
│   │   - Automatic indexing          │
│   └── index/                        │
│       - FieldIndex                  │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   HeroDB                            │
│   (Redis-compatible storage)        │
└─────────────────────────────────────┘
```

## 🎯 Features

### 1. **Fluent Builder Pattern**
```rhai
let note = note("ns")
    .title("Title")
    .content("Content")
    .tag("key", "value");
```

### 2. **Automatic Indexing**
Fields marked with `#[index]` are automatically indexed:
```rust
#[derive(DeriveObject)]
pub struct Note {
    pub base_data: BaseData,
    
    #[index]
    pub title: Option<String>,  // Indexed!
    
    pub content: Option<String>, // Not indexed
    
    #[index]
    pub tags: BTreeMap<String, String>, // Indexed!
}
```

### 3. **Type-Safe Operations**
- Compile-time type checking
- Runtime validation
- Clear error messages

### 4. **Query Support**
```rhai
// Query by any indexed field
let ids = query("namespace", "field_name", "value");

// Query by tag
let ids = query("notes", "tags:tag", "project=osiris");

// Query by title
let ids = query("notes", "title", "My Note");
```

## 📚 Available Functions

### Note API

| Function | Description |
|----------|-------------|
| `note(ns)` | Create new note |
| `.title(s)` | Set title (chainable) |
| `.content(s)` | Set content (chainable) |
| `.tag(k, v)` | Add tag (chainable) |
| `.mime(s)` | Set MIME type (chainable) |
| `put_note(note)` | Store note, returns ID |
| `get_note(ns, id)` | Retrieve note by ID |
| `.get_id()` | Get note ID |
| `.get_title()` | Get note title |
| `.get_content()` | Get note content |
| `.to_json()` | Serialize to JSON |

### Event API

| Function | Description |
|----------|-------------|
| `event(ns, title)` | Create new event |
| `.description(s)` | Set description (chainable) |
| `.location(s)` | Set location (chainable) |
| `.category(s)` | Set category (chainable) |
| `.all_day(b)` | Set all-day flag (chainable) |
| `put_event(event)` | Store event, returns ID |
| `get_event(ns, id)` | Retrieve event by ID |
| `.get_id()` | Get event ID |
| `.get_title()` | Get event title |
| `.to_json()` | Serialize to JSON |

### Query API

| Function | Description |
|----------|-------------|
| `query(ns, field, value)` | Query by indexed field, returns array of IDs |

## 🧪 Testing

### Test Scripts Included

1. **`scripts/test_note.rhai`** - Complete note workflow
2. **`scripts/test_event.rhai`** - Complete event workflow

### Run Tests

```bash
# Test notes
cargo run --bin runner --features rhai-support -- test1 --script-file scripts/test_note.rhai

# Test events
cargo run --bin runner --features rhai-support -- test1 --script-file scripts/test_event.rhai
```

## 🔧 Building

### Development Build

```bash
cargo build --bin runner --features rhai-support
```

### Release Build

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

### Run Without Cargo

```bash
# After building
./target/release/runner runner1 --script-file scripts/test_note.rhai
```

## 📦 Integration with runner_rust

The OSIRIS runner can also be integrated into the runner_rust infrastructure for distributed task execution. See `runner_rust/src/engine/osiris.rs` for the integration.

## ✅ Verification

Run this to verify everything works:

```bash
cargo run --bin runner --features rhai-support -- test1 --script-file scripts/test_note.rhai
```

Expected output:
```
✅ Script completed successfully!
```

## 🎉 Success!

The OSIRIS runner is **fully operational** and ready for:
- ✅ Standalone script execution
- ✅ Integration with runner_rust
- ✅ Production use
- ✅ Custom object types (via derive macro)