// ============================================================================
// SCOPE DECLARATION - [norun] declaration collected by collect_scopes
// ============================================================================
~[comptime|transform]pub event register {
    source: Source,
    invocation: *const Invocation,
    item: *const Item,
    program: *const Program,
    allocator: std.mem.Allocator
}
| transformed { program: *const Program }

~[retain]pub event get_scope {
    name: []const u8
}
| scope {
dispatcher: DispatchFn,
cost_fn: ?CostFn,
creates_obligations_fn: ?ObligationsArrayFn,
discharges_obligations_fn: ?ObligationsArrayFn,
discharge_event_fn: ?DischargeEventFn,
creates_spec_fn: ?CreatesSpecFn,
discharges_spec_fn: ?DischargesSpecFn
}
| not_found {}

// ============================================================================
// PARSE - Parse Koru source using the interpreter parser
// ============================================================================
~pub event parse.source {
    source: []const u8,
    file_name: []const u8,
    allocator: std.mem.Allocator,
    fail_fast: bool = true
}
| parsed { ast: koru_parser.ParseResult }
| parse_error { message: []const u8 }

// ============================================================================
// EVAL - Run a parsed AST against a named scope
// ============================================================================
~pub event eval {
    ast: koru_parser.ParseResult,
    scope: []const u8,
    budget: ?u64,
    handle_pool: ?*@import("root").koru_std.interpreter.HandlePool,
    auto_discharge: bool = true
}
| result { value: @import("root").koru_std.interpreter.Value, used: u64, handles: u32 }
| exhausted { used: u64, last_event: []const u8, handles: u32 }
| validation_error { message: []const u8 }
| event_denied { name: []const u8 }
| dispatch_error { event_name: []const u8, message: []const u8 }
| scope_not_found { scope_name: []const u8 }

// ============================================================================
// RUN - Parse and execute Koru source against a named scope
// ============================================================================
// 
// shape: Optional event name to validate response shape against
// @retain: run_event is referenced from generated Zig code in user pipelines
// (std.runtime:run invocations in continuations compile to run_event.handler(...))
~[retain]pub event run {
    source: []const u8,
    scope: []const u8,
    budget: ?u64 = null,
    handle_pool: ?*@import("root").koru_std.interpreter.HandlePool = null,
    fail_fast: bool = true,
    auto_discharge: bool = true,
    shape: ?[]const u8 = null
}
| result { value: @import("root").koru_std.interpreter.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 { message: []const u8 }
| shape_error { branch: []const u8, field: ?[]const u8, message: []const u8 }
| event_denied { name: []const u8 }
| dispatch_error { event_name: []const u8, message: []const u8 }
| scope_not_found { scope_name: []const u8 }

// RUN_CACHED - Parse and execute Koru source against a named scope with cached parsing
~pub event run_cached {
    source: []const u8,
    scope: []const u8,
    budget: ?u64 = null,
    handle_pool: ?*@import("root").koru_std.interpreter.HandlePool = null,
    fail_fast: bool = true,
    auto_discharge: bool = true,
    shape: ?[]const u8 = null
}
| result { value: @import("root").koru_std.interpreter.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 { message: []const u8 }
| shape_error { branch: []const u8, field: ?[]const u8, message: []const u8 }
| event_denied { name: []const u8 }
| dispatch_error { event_name: []const u8, message: []const u8 }
| scope_not_found { scope_name: []const u8 }

// ============================================================================
// COLLECT SCOPES - Comptime event that walks AST and generates dispatchers
// ============================================================================
~[comptime]pub event collect_scopes {}
| collected {}