lehit 0.2.0

Embeddable Lehit language frontend and Cranelift JIT runtime
Documentation
# 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.