Interpreter

This library is in flux. APIs may change without notice. Generated from source on 6/15/2026.

Koru Interpreter Standard Library

interpreter.kz

Koru Interpreter Standard Library Enables runtime evaluation of Koru source code DESIGN: - Parses Koru source at runtime using the same parser as the compiler - Walks the AST and executes events via registered dispatchers - Tracks bindings in an environment as flow progresses - Uses the shape_checker for optional validation before execution Usage: ~import std/interpreter ~import std/runtime // Register events you want callable at runtime ~std/runtime:register(scope: "api") { greet process_order } // Interpret Koru source ~std/interpreter:run(source: user_input, scope: "api") | result r |> handle_result(value: r.value) | parse-error e |> respond(status: 400, body: e.message) | validation-error e |> respond(status: 400, body: e.message) | dispatch-error e |> respond(status: 500, body: e.event)

// ============================================================================
// VALUE SERIALIZATION - Convert interpreter Value to JSON
// ============================================================================
~[retain]pub event value.stringify {
    value: Value
}
| json []const u8

// ============================================================================
// MAIN INTERPRETER EVENTS
// ============================================================================
// 
// Parse and execute in one step - the main interpreter entry point
// Use ~get-scope to get the dispatcher first, then pass it here
~[retain]pub event run {
    source: []const u8,
    dispatcher: DispatchFn,
    cost_fn: ?CostFn,  // Optional cost lookup (null = default cost 1)
    creates_obligations_fn: ?ObligationsArrayFn,   // event -> []obligations it creates
    discharges_obligations_fn: ?ObligationsArrayFn, // event -> []obligations it discharges
    discharge_event_fn: ?DischargeEventFn,         // obligation -> event that discharges it
    creates_spec_fn: ?CreatesSpecFn = null,        // event -> []CreateSpec with field names
    discharges_spec_fn: ?DischargesSpecFn = null,  // event -> []DischargeSpec with arg names
    budget: ?u64,  // Optional budget limit (null = unlimited)
    handle_pool: ?*HandlePool,  // Optional external pool (for bridges)
    fail_fast: bool = true,
    scope_name: []const u8 = "default",  // Scope name for handle isolation
    auto_discharge: bool = true  // Auto-discharge undischarged handles at end
}
| result { value: Value, used: u64, handles: u32 }
| exhausted { used: u64, last_event: []const u8, handles: u32 }
| parse -error { message: []const u8, line: u32, column: u32 }
| validation -error []const u8
| dispatch -error { event_name: []const u8, message: []const u8 }

// Cached parse + execute (reuses parsed flow for identical source input)
~[retain]pub event run-cached {
    source: []const u8,
    dispatcher: DispatchFn,
    cost_fn: ?CostFn,  // Optional cost lookup (null = default cost 1)
    creates_obligations_fn: ?ObligationsArrayFn,   // event -> []obligations it creates
    discharges_obligations_fn: ?ObligationsArrayFn, // event -> []obligations it discharges
    discharge_event_fn: ?DischargeEventFn,         // obligation -> event that discharges it
    creates_spec_fn: ?CreatesSpecFn = null,        // event -> []CreateSpec with field names
    discharges_spec_fn: ?DischargesSpecFn = null,  // event -> []DischargeSpec with arg names
    budget: ?u64,  // Optional budget limit (null = unlimited)
    handle_pool: ?*HandlePool,  // Optional external pool (for bridges)
    fail_fast: bool = true,
    scope_name: []const u8 = "default",  // Scope name for handle isolation
    auto_discharge: bool = true  // Auto-discharge undischarged handles at end
}
| result { value: Value, used: u64, handles: u32 }
| exhausted { used: u64, last_event: []const u8, handles: u32 }
| parse -error { message: []const u8, line: u32, column: u32 }
| validation -error []const u8
| dispatch -error { event_name: []const u8, message: []const u8 }

// Execute pre-parsed AST - for benchmarks and advanced use
// This is the fast path: no parsing overhead, just execution!
~[retain]pub event eval {
    flow: *const ast.Flow,
    dispatcher: DispatchFn,
    cost_fn: ?CostFn,  // Optional cost lookup (null = default cost 1)
    creates_obligations_fn: ?ObligationsArrayFn,
    discharges_obligations_fn: ?ObligationsArrayFn,
    discharge_event_fn: ?DischargeEventFn,
    creates_spec_fn: ?CreatesSpecFn = null,        // event -> []CreateSpec with field names
    discharges_spec_fn: ?DischargesSpecFn = null,  // event -> []DischargeSpec with arg names
    budget: ?u64,  // Optional budget limit (null = unlimited)
    handle_pool: ?*HandlePool,  // Optional external pool (for bridges)
    scope_name: []const u8 = "default",  // Scope name for handle isolation
    auto_discharge: bool = true  // Auto-discharge undischarged handles at end
}
| result { value: Value, used: u64, handles: u32 }
| exhausted { used: u64, last_event: []const u8, handles: u32 }
| validation -error []const u8
| dispatch -error { event_name: []const u8, message: []const u8 }