# Getting started
The supported embedding path is:
1. create a [`RuntimeBuilder`](crate::runtime::RuntimeBuilder);
2. select [`ExecutionMode::Checked`](crate::runtime::ExecutionMode::Checked) for structured failures;
3. declare the file entry with `as fn(...)` and load it through `load_script`;
4. obtain its universal [`Function`](crate::runtime::Function) at local path `""`;
5. pack arguments with [`AbiCallBuilder`](crate::runtime::AbiCallBuilder) and call it.
```rust,no_run
use lehit::runtime::{AbiCallError, AbiCallStatus, ExecutionMode, RuntimeBuilder};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut runtime = RuntimeBuilder::new()
.with_execution_mode(ExecutionMode::Checked)
.build()?;
runtime.load_script(
"app://entry.lt",
"as fn(argument: usize) -> i32
let values: [i32; 2] = [11, 22] return values[argument]",
)?;
let function = runtime.function("app://entry.lt", "")?.abi_function()?;
let mut call = function.abi_call_builder();
call.push_rust_value_argument(1usize)?;
assert_eq!(call.call()?.into_rust_value::<i32>()?, 22);
let mut call = function.abi_call_builder();
call.push_rust_value_argument(3usize)?;
assert!(matches!(
call.call(),
Err(AbiCallError::Execution(status))
if status == AbiCallStatus::BOUNDS_VIOLATION
));
Ok(())
}
```
## Script entry functions
Exactly one script-wide function contract may declare the entry signature:
```lehit
as fn(argument: u32) -> u32
return argument + 1
```
The entry uses the script module path and an empty local path, so hosts retrieve it with `runtime.function("app://entry.lt", "")`. Argument names from the contract are available to top-level statements.
Declaring more than one file function contract is a compilation error. Other file-level contracts do not create an entry.
If a script has top-level statements or expressions but no function contract, Lehit creates an implicit `fn() -> void` entry. It does not infer arguments or a return type; use `as fn(...) -> T` when either is required. An empty or declaration-only script without `as fn(...)` has no entry function, although its explicitly declared functions remain available by their local names.
`reload_script` derives the entry in the same way as `load_script`. Reload is transactional, and functions obtained before a successful reload remain tied to their previous leased JIT unit.
## Direct and checked execution
[`ExecutionMode::Direct`](crate::runtime::ExecutionMode::Direct) uses the smallest internal generated ABI, but backend traps or wrapping behavior may be process-visible. [`ExecutionMode::Checked`](crate::runtime::ExecutionMode::Checked) passes an internal execution context through generated calls. The universal adapter hides that context, returns an `AbiCallStatus`, and sends detailed [`ExecutionError`](crate::runtime::ExecutionError) values only through an optional error channel.
Checked execution is the recommended host-facing default. It does not validate arbitrary native pointers or make Lehit a sandbox; see [`crate::guides::safety`].
The universal Lehit ABI is available in both modes. In checked mode its compact [`AbiCallStatus`](crate::runtime::AbiCallStatus) reports instrumented failures. In direct mode it returns success if control returns normally; backend traps are not converted into a status.
## Detailed error diagnostics
The ABI status intentionally contains only a fixed-width `u32` category. Install an [`ErrorChannel`](crate::runtime::ErrorChannel) when detailed operation data is needed for logging:
```rust,no_run
use lehit::runtime::{ExecutionMode, RuntimeBuilder, RuntimeErrorReport};
let runtime = RuntimeBuilder::new()
.with_execution_mode(ExecutionMode::Checked)
.with_error_channel(|report: &RuntimeErrorReport| {
eprintln!("Lehit execution failed: {}", report.error);
})
.build()?;
# Ok::<(), Box<dyn std::error::Error>>(())
```
The channel is diagnostic side effect, not the source of call correctness: `AbiCallBuilder::call` returns an error even when no channel is installed. Channels may be invoked concurrently, and a panic from a channel is contained by the runtime trampoline rather than unwinding through JIT frames.
## Module paths
Every source unit has a canonical path such as `app://entry.lt`. Imports, reload, unload, diagnostics, and nominal type identities use this path. Do not reuse one path for unrelated modules in the same runtime.
## Reload and leases
Loading or reloading is transactional: failed compilation does not commit partial workspace state. Existing functions and leased values retain their original JIT unit, so they can remain valid after a newer unit replaces the registry entry. The complete lifecycle example is available as `examples/embed.rs`.
## Errors
There are two main phases:
- building/loading returns [`WorkspaceError`](crate::runtime::WorkspaceError);
- constructing or invoking the universal ABI returns [`AbiCallError`](crate::runtime::AbiCallError), including checked execution failures.
Use [`workspace_error_diagnostics`](crate::runtime::workspace_error_diagnostics) when a user-facing host needs source labels and locations.