# BEIST/OS Technical Architecture

## System Overview

BEIST/OS is an event-driven operating system designed to run as PID 1 in containers, providing a high-performance event routing and execution platform.

## Core Components

### 1. Event Queue (event_queue.zig)

**Design**: Lock-free ring buffer using atomic operations

**Performance Characteristics**:
- Push: 34M ops/sec @ 29ns latency
- Pop: 87M ops/sec @ 11ns latency
- Memory: O(capacity) pre-allocated
- Concurrency: Lock-free multi-producer/multi-consumer

**Implementation Details**:
```zig
pub const EventQueue = struct {
    buffer: []?Event,        // Pre-allocated ring buffer
    head: Atomic(usize),     // Consumer position
    tail: Atomic(usize),     // Producer position
    capacity: usize,         // Power of 2 for fast modulo
};
```

**Key Algorithms**:
- Compare-and-swap for atomic updates
- Memory ordering: Acquire-Release semantics
- Overflow handling: Fail-fast with QueueFull error

### 2. Pattern Router (router.zig)

**Design**: Compiled pattern matching with O(1) best-case routing

**Pattern Types**:
- Literal: `system:ready` - Exact match
- Single wildcard: `http:*` - One segment match
- Multi wildcard: `error:**` - Multiple segment match

**Compilation Process**:
```
Pattern String → Segment Array → Compiled Pattern
"http:*:error" → [literal("http:"), single_wildcard, literal(":error")]
```

**Routing Algorithm**:
1. Iterate compiled patterns
2. Match event type against pattern segments
3. Collect matching handlers
4. Execute in registration order

### 3. Resource System (resource.zig)

**Structure**:
```json
{
  "namespace": "string",
  "name": "string",
  "version": "semver",
  "on": {
    "event:pattern": [
      {"action": "type", ...parameters}
    ]
  }
}
```

**Action Types**:
- `echo`: Print message
- `emit`: Generate new event
- `exec`: Run process
- `spawn`: Launch handler
- `http`: HTTP operations
- `persist`: State storage

**Memory Management**:
- Resources own their handler definitions
- Patterns reference resource memory
- Cleanup cascades from resources down

### 4. Main Runtime (main.zig)

**Initialization Sequence**:
1. Initialize event queue (64K capacity)
2. Create router
3. Load resources from filesystem
4. Compile patterns
5. Emit `system:ready`
6. Enter event loop

**Event Loop**:
```zig
while (!should_shutdown) {
    if (queue.pop()) |event| {
        handlers = router.route(event);
        for (handlers) |handler| {
            new_events = handler.execute(event);
            for (new_events) |new_event| {
                queue.push(new_event);
            }
        }
    } else {
        sleep(1ms);
    }
}
```

## Execution Models

### Current: In-Process Execution

All handlers run in the same process space.

**Advantages**:
- Maximum performance (60M events/sec)
- Zero-copy event passing
- Minimal latency (11-29ns)

**Limitations**:
- No isolation
- Shared failure domain
- Limited to trusted code

### Planned: Multi-Tier Execution

#### Tier Architecture

| Tier | Mode | Performance | Isolation | Use Case |
|------|------|------------|-----------|----------|
| 0 | Kernel (eBPF) | ∞ events/sec | Kernel | System events |
| 1 | In-Process | 60M/sec | None | Routing, transforms |
| 2 | Thread Pool | 10M/sec | Thread | CPU-bound work |
| 3 | Process Pool | 1M/sec | Process | User code |
| 4 | WASM Sandbox | 5M/sec | Perfect | Plugins |

#### Process Pool Design

```zig
pub const ProcessPool = struct {
    workers: []Worker,
    available: Queue(*Worker),
    busy: HashMap(EventId, *Worker),
    
    pub fn dispatch(self: *ProcessPool, handler: Handler, event: Event) !void {
        const worker = try self.available.pop();
        try worker.send(event);
        try self.busy.put(event.id, worker);
    }
};
```

#### io_uring Integration

```zig
pub const IoUringTransport = struct {
    ring: IoUring,
    
    pub fn sendEvent(self: *IoUringTransport, fd: i32, event: Event) !void {
        const bytes = try serialize(event);
        const sqe = try self.ring.get_sqe();
        sqe.prep_send(fd, bytes, 0);
        try self.ring.submit();
    }
};
```

#### WASM Runtime

```zig
pub const WasmRuntime = struct {
    engine: wasmtime.Engine,
    modules: HashMap(ResourceId, wasmtime.Module),
    
    pub fn execute(self: *WasmRuntime, handler: Handler, event: Event) ![]Event {
        const module = self.modules.get(handler.resource.id);
        const instance = try module.instantiate();
        const result = try instance.call("handle_event", .{event});
        return deserialize(result);
    }
};
```

## Event Flow

### Event Lifecycle

```
1. Event Creation
   ↓
2. Queue Push (29ns)
   ↓
3. Queue Pop (11ns)
   ↓
4. Pattern Matching (O(patterns))
   ↓
5. Handler Execution (varies by tier)
   ↓
6. New Event Generation
   ↓
7. Repeat
```

### Event Structure

```zig
pub const Event = struct {
    id: u64,                  // Unique identifier
    type: []const u8,         // Pattern-matchable type
    source: []const u8,       // Originating resource
    data: ?[]const u8,        // Optional payload
    timestamp: i64,           // Creation time
    depth: u32,               // Chain depth
    parent_id: ?u64,          // Triggering event
};
```

### Event Patterns

**Syntax**:
- `:` - Namespace separator
- `*` - Single segment wildcard
- `**` - Multi-segment wildcard

**Examples**:
- `http:get:/api/users` - Specific route
- `http:*:/api/*` - Any method, any API endpoint
- `error:**` - Any error, any depth
- `*:timeout` - Any timeout
- `system:*` - Any system event

## Performance Characteristics

### Memory Usage

| Component | Size | Scaling |
|-----------|------|---------|
| Event | 128 bytes | O(queue_size) |
| Pattern | 64 bytes + segments | O(patterns) |
| Handler | 256 bytes | O(handlers) |
| Resource | 1KB average | O(resources) |

### Throughput

| Operation | Rate | Latency |
|-----------|------|---------|
| Event Push | 34M/sec | 29ns |
| Event Pop | 87M/sec | 11ns |
| Pattern Match | 100M/sec | 10ns |
| Handler Dispatch | 60M/sec | 17ns |

### Scalability

- **Vertical**: Limited by CPU cores for in-process
- **Horizontal**: Unlimited with distributed events
- **Queue Size**: 64K events (configurable)
- **Pattern Count**: Thousands without degradation
- **Resource Count**: Hundreds typical, thousands possible

## Security Model

### Current: Trust-Based

All code runs with same privileges as beistd.

### Planned: Capability-Based

```zig
pub const Capability = enum {
    Network,
    Filesystem,
    Process,
    System,
};

pub const Resource = struct {
    capabilities: []Capability,
    // ...
};
```

### Isolation Levels

1. **None**: In-process trusted code
2. **Thread**: Separate stack, shared memory
3. **Process**: Full Unix isolation
4. **Container**: Namespace isolation
5. **WASM**: Complete sandboxing

## File System Layout

### Container Structure
```
/
├── beistd              # Main binary (3MB)
├── resources/          # User resources
│   ├── *.beist        # Resource definitions
│   └── handlers/      # Handler code
└── tmp/               # Temporary files
```

### Development Structure
```
project/
├── .beist/            # Development resources
│   ├── dev.beist     # Dev environment
│   └── test.beist    # Test runners
├── src/              # Application code
│   └── *.beist      # App resources
└── beist.lock       # Locked dependencies
```

## Network Protocol (Planned)

### Event Wire Format

```
[Magic: 4][Version: 1][Flags: 1][Length: 4][Event: N]
```

### REPL Protocol

WebSocket with JSON-RPC:
```json
{
  "method": "emit",
  "params": {
    "type": "test:event",
    "data": {"key": "value"}
  },
  "id": 1
}
```

## Configuration

### Environment Variables
- `BEIST_QUEUE_SIZE`: Event queue capacity
- `BEIST_RESOURCE_PATH`: Resource directory
- `BEIST_REPL_PORT`: REPL server port
- `BEIST_LOG_LEVEL`: Logging verbosity

### Configuration File (.beist.config.json)
```json
{
  "queue_size": 65536,
  "resource_path": "/resources",
  "execution_mode": "hybrid",
  "repl": {
    "enabled": true,
    "port": 9999
  }
}
```

## Error Handling

### Error Events

All errors become events:
```zig
catch |err| {
    try queue.push(.{
        .type = "error:handler:execution",
        .source = handler.resource.id,
        .data = @errorName(err),
    });
}
```

### Recovery Strategies

1. **Restart Handler**: Process pool workers
2. **Circuit Breaker**: Disable failing handlers
3. **Fallback**: Alternative handler patterns
4. **Dead Letter**: Unhandled event queue

## Monitoring & Observability

### Built-in Metrics

- Events per second
- Queue depth
- Handler execution time
- Pattern match performance
- Memory usage

### Event Tracing

Every event carries:
- Unique ID
- Parent ID
- Depth counter
- Timestamp

Enables full trace reconstruction.

### Export Formats (Planned)

- OpenTelemetry
- Prometheus
- StatsD
- JSON logs

## Future Enhancements

### Near Term
- Process pool execution
- Hot reload
- WebSocket REPL
- File watching

### Medium Term
- io_uring integration
- WASM runtime
- Distributed events
- Persistence layer

### Long Term
- eBPF programs
- GPU dispatch
- Quantum handlers (joke?)
- Neural event routing (not a joke!)

## Conclusion

BEIST/OS achieves its performance through:
1. Lock-free data structures
2. Pre-compiled patterns
3. Zero-copy event passing
4. Minimal allocations
5. Cache-friendly layouts

The architecture is designed to scale from embedded devices to distributed clusters while maintaining conceptual simplicity.

---

*"Architecture is the art of how to waste space productively." - Philip Johnson*

*"In BEIST/OS, we waste nothing. Every byte serves events."*