// ============================================================================
// 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 SiteResult

~[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 koru_parser.ParseResult
| parse -error []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.koru_interpreter.HandlePool,
    auto_discharge: bool = true
}
| result { value: @import("root").koru_std.koru_interpreter.Value, used: u64, handles: u32 }
| exhausted { used: u64, last_event: []const u8, handles: u32 }
| validation -error []const u8
| event -denied []const u8
| dispatch -error { event_name: []const u8, message: []const u8 }
| scope -not-found []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.koru_interpreter.HandlePool = null,
    fail_fast: bool = true,
    auto_discharge: bool = true,
    shape: ?[]const u8 = null
}
| result { value: @import("root").koru_std.koru_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 []const u8
| shape -error { branch: []const u8, field: ?[]const u8, message: []const u8 }
| event -denied []const u8
| dispatch -error { event_name: []const u8, message: []const u8 }
| scope -not-found []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.koru_interpreter.HandlePool = null,
    fail_fast: bool = true,
    auto_discharge: bool = true,
    shape: ?[]const u8 = null
}
| result { value: @import("root").koru_std.koru_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 []const u8
| shape -error { branch: []const u8, field: ?[]const u8, message: []const u8 }
| event -denied []const u8
| dispatch -error { event_name: []const u8, message: []const u8 }
| scope -not-found []const u8

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