glyph-runtime 0.0.1

# Glyph Runtime

The Glyph runtime provides an immutable-first virtual machine (VM) for executing Glyph programs with capability-based security.

## Features

### Immutable-First Design
- All values are immutable - operations create new values rather than modifying existing ones
- Variable bindings are immutable (no reassignment allowed)
- Collection operations (append, insert, etc.) return new collections
- Side effects only through capability-controlled intrinsics

### Stack-Based Execution
- Efficient stack-based VM with configurable limits
- Support for nested function calls with proper frame management
- Automatic memory management with configurable limits

### Capability-Based Security
- Programs must declare required capabilities upfront
- Fine-grained permission system for:
  - Audio synthesis (`audio.speak`)
  - Network access (`network.fetch` with URL patterns)
  - Display operations (`display.chart`, `display.image`)
  - User interaction (`wait.confirm`)
  - Memory limits
- Runtime enforcement prevents unauthorized operations

### Comprehensive Instruction Set
- Arithmetic: `Add`, `Sub`, `Mul`, `Div`, `Mod`, `Pow`
- Comparison: `Eq`, `Ne`, `Lt`, `Le`, `Gt`, `Ge`
- Logical: `And`, `Or`, `Not`
- Stack manipulation: `Push`, `Pop`, `Dup`, `Swap`, `Rot3`
- Control flow: `Jump`, `JumpIf`, `JumpIfNot`, `Call`, `Return`
- Data structures: `MakeList`, `MakeDict`, `ListAppend`, `DictInsert`
- Pattern matching: `Match`, `MatchValue`, `MatchType`
- Intrinsics: `CallIntrinsic` for built-in functions
- Debugging: `TraceValue`, `RecordTelemetry`

## Usage

```rust
use glyph_runtime::{VM, VMConfig, Instruction, Value, Capability};

// Configure VM with capabilities
let mut config = VMConfig::default();
config.capabilities.grant(Capability::AudioSpeak);

// Create VM instance
let mut vm = VM::new(config);

// Load bytecode program
vm.load_bytecode(vec![vec![
    Instruction::Push(Value::Str("Hello, Glyph!".to_string())),
    Instruction::CallIntrinsic("voice.speak".to_string()),
    Instruction::Halt,
]]);

// Execute program
match vm.execute() {
    Ok(result) => println!("Result: {}", result),
    Err(e) => eprintln!("Error: {}", e),
}
```

## Architecture

### VM Structure
```
VM
├── Stack (configurable size)
├── Call Frames (function contexts)
├── Global bindings (immutable)
├── Capability set (granted permissions)
├── Memory manager (tracks allocations)
└── Telemetry collector
```

### Execution Model
1. Instructions are fetched from bytecode
2. Stack-based operations manipulate values
3. Call frames manage function scope
4. Capabilities are checked before intrinsics
5. Memory limits are enforced continuously

## Examples

See the `examples/` directory for:
- `simple_vm.rs` - Basic arithmetic and list operations
- `capability_demo.rs` - Capability-based security demonstrations
- `vm_benchmark.rs` - Performance benchmarks

## Performance

The VM is designed for:
- Cold start: ≤ 150ms
- Arithmetic operations: > 4 ops/ms
- Memory efficiency: < 10MB for basic programs
- Deterministic execution with seed-based randomness