// SCOPE DECLARATION - [norun] declaration collected by collect-scopes
~[comptime|transform] pub tor register {
    source: Source,
    invocation: *const Invocation,
    item: *const Item,
    program: *const Program,
    allocator: std.mem.Allocator
} -> SiteResult

~[retain] pub tor get-scope { name: string }
| 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,
    events_fn: ?EventsLookupFn,
    input_fn: ?InputLookupFn
}
| not-found

// SCOPE-VOCABULARY - Render a scope's vocabulary for an external reader
//
// The whole point of the enumeration surface: a model driving this interpreter
// must be told, accurately, what it may call — and that description must come
// from the register declaration, not a hand-typed script that can drift. This
// renders exactly the surface the register block enforces, as one line per
// event with its named arguments and possession phantoms:
//
//   open(path: string)
//   append(handle: string<!open>, text: string)
//   close(handle: string<!open>)
//   say(text: string)
//
// No JSON schema, no second source of truth: the prompt and the enforcement
// are the same bytes.
//
// @retain: scope_vocabulary_event is referenced from generated Zig code in user
// pipelines (std/bridge:vocabulary compiles to scope_vocabulary_event.handler).
~[retain] pub tor scope-vocabulary { name: string }
| ok string
| not-found

// SCOPE-MANIFEST - Serve a scope's vocabulary as a data contract (JSON)
//
// The manifest record is minted at scope creation (register) from the same
// EventEntry data the dispatch tables are emitted from; this tor serializes
// it to JSON so a running program can serve it as a contract endpoint
// (Orisha) or hand it to a tool. The emitted JSON has no hand-authored bytes:
// every field derives from the scope declaration, so the served contract and
// the enforcement cannot drift. Defined flows (session growth) are NOT part
// of this record — it is the compiled base, minted before any session exists.
//
// @retain: scope_manifest_event is referenced from generated Zig code in user
// pipelines (Orisha serves it as the .json endpoint; explain consumes it).
~[retain] pub tor scope-manifest { name: string }
| ok string
| not-found

// SCOPE-GRAMMAR - the wire grammar, rendered from the register block
//
// The third render from the scope table, and the one that closes the R2
// loop: scope-vocabulary tells a model WHAT it may call, scope-manifest
// serves it as data, and scope-grammar teaches HOW a call is written — the
// wire's shape rules (the constant half, WIRE_GRAMMAR_TEXT, kept beside the
// parser that enforces it) above this scope's own verb lines (rendered by
// scope-vocabulary, so the signatures cannot drift from enforcement either).
// A prompt built from this render and a turn judged by parse.wire are the
// same declaration read twice: the lesson and the law.
//
// @retain: scope_grammar_event is referenced from generated Zig code in user
// pipelines (kopium's agent prompt is built from it).
~[retain] pub tor scope-grammar { name: string }
| ok string
| not-found

// EXPLAIN-RUNTIME - the `[explainer]` for the scope registry
//
// koruc's `koru_explain_gather` calls every discovered `[explainer]` once with
// the program AST; the `explain` command renders whatever this returns. This
// explainer builds every registered scope's manifest through the SAME shared
// producer (`scopeManifestForScope`) the register emission uses, then reports:
// a note (the human vocabulary lines) plus a `manifest` property carrying the
// EXACT JSON the `scope-manifest` tor serves — so `explain` shows the served
// contract bytes, never a hand-written copy.
//
// @retain: explain_runtime_event is referenced from generated code (koruc's
// koru_explain_gather invokes every discovered [explainer]).
~[comptime|explainer] pub tor explain-runtime {
    program: *const ast.Program,
    allocator: std.mem.Allocator
} -> ExplainReport

// PARSE - Parse interpreter source without executing it
//
// Delegates to `std/interpreter:parse`, which is the interpreter's own parser.
// It takes no file name on purpose: interpreted source has no file, therefore
// no host half and no ``. This entry point used to hold a copy of the
// COMPILER's file parser (`std/koru:parse.source`), which derives its
// host/pure mode from the filename extension — so a synthetic `"x.kz"`
// silently put interpreted source in host mode and made `` mandatory, the
// exact inverse of the rule `run` enforces.
~pub tor parse.source { source: string, allocator: std.mem.Allocator }
| parsed *const ast.Flow
| parse-error { message: string, line: u32, column: u32 }

~[retain] pub tor parse.wire { source: string }
| parsed *const ast.Flow
| parse-error { message: string, line: u32, column: u32 }

// EVAL - Run a parsed AST against a named scope
~pub tor eval {
    flow: *const ast.Flow,
    scope: string,
    budget: ?u64,
    handle_pool: ?*@import("root").koru_std.koru_interpreter.HandlePool,
    auto_discharge: bool,
    defined: ?*@import("root").koru_std.koru_interpreter.DefinedFlows
}
| result {
    value: @import("root").koru_std.koru_interpreter.Value,
    used: u64,
    handles: u32
}
| exhausted { used: u64, last_event: string, handles: u32 }
| validation-error string
| event-denied string
| dispatch-error { event_name: string, message: string }
| scope-not-found string

// 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 tor run {
    source: string,
    scope: string,
    budget: ?u64,
    handle_pool: ?*@import("root").koru_std.koru_interpreter.HandlePool,
    fail_fast: bool,
    auto_discharge: bool,
    shape: ?[]const u8,
    defined: ?*@import("root").koru_std.koru_interpreter.DefinedFlows
}
| result {
    value: @import("root").koru_std.koru_interpreter.Value,
    used: u64,
    handles: u32
}
| exhausted { used: u64, last_event: string, handles: u32 }
| parse-error { message: string, line: u32, column: u32 }
| validation-error string
| shape-error { branch: string, field: ?[]const u8, message: string }
| event-denied string
| dispatch-error { event_name: string, message: string }
| scope-not-found string

// RUN_CACHED - Parse and execute Koru source against a named scope with cached parsing
~pub tor run-cached {
    source: string,
    scope: string,
    budget: ?u64,
    handle_pool: ?*@import("root").koru_std.koru_interpreter.HandlePool,
    fail_fast: bool,
    auto_discharge: bool,
    shape: ?[]const u8
}
| result {
    value: @import("root").koru_std.koru_interpreter.Value,
    used: u64,
    handles: u32
}
| exhausted { used: u64, last_event: string, handles: u32 }
| parse-error { message: string, line: u32, column: u32 }
| validation-error string
| shape-error { branch: string, field: ?[]const u8, message: string }
| event-denied string
| dispatch-error { event_name: string, message: string }
| scope-not-found string

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