mirascript-vm 0.1.105

Native Rust virtual machine for MiraScript
Documentation
# mirascript-vm

`mirascript-vm` is the native, single-threaded Rust runtime for MiraScript. Source
is compiled and validated independently from execution: a `MiraScript` contains
only the decoded program and owned constant table, while a `Runtime` owns globals,
the standard library, execution state, and every dynamically allocated value.

## Quick start

```rust
use mirascript_vm::{MiraRecord, MiraValue, Runtime, compile};

#[derive(MiraRecord)]
struct Foo {
    bar: u8,
}

let script = compile("foo.bar")?;
let mut runtime = Runtime::new();
let foo = runtime.insert_record(Foo { bar: 42 })?;
runtime.insert_global("foo", MiraValue::record(foo))?;

assert_eq!(runtime.run(&script)?, MiraValue::number(42.0));
# Ok::<(), Box<mirascript_vm::MiraError>>(())
```

One script can run in multiple runtimes, and one runtime can run any number of
scripts. Each run resets frames, registers, the call stack, timeout accounting,
and its execution generation. Globals, standard-library values, the arena, and
materialized string constants remain until the runtime is dropped. Re-entering
`Runtime::run` from a native callback returns `RuntimeErrorKind::ReentrantRun`.

## Values and arena ownership

`MiraValue` is an 8-byte, copyable NaN-box. Nil, booleans, numbers, and truly
static strings are inline; dynamic strings, arrays, records, functions, and
modules use 48-bit typed handles into the owning runtime's append-only arena.
Checked lookups reject foreign, out-of-range, and wrongly typed handles.

The compiled constant table never contains runtime handles. A string constant is
allocated only when its bytecode instruction executes and is cached by
`(ScriptId, constant_index)` in that runtime. Unexecuted branches allocate
nothing, clones of one script share the cache identity, and different runtimes
materialize their own copies.

Use `Runtime::insert` for an owned `MiraManageable`, or the category-specific
`insert_string`, `insert_array`, `insert_record`, `insert_function`, and
`insert_module` methods when a typed `MiraHandle<T>` is needed. The matching
checked `get_*` and `get_*_mut` methods let the host inspect or mutate live values.

## Host records, arrays, functions, and modules

All compound behavior is dispatched through `dyn MiraArray`, `dyn MiraRecord`,
`dyn MiraFunction`, and `dyn MiraModule`. Script and host implementations use the
same traits; `MiraManageable` carries an owned value until `Runtime::insert`
places it in the correct arena.

`#[derive(MiraRecord)]` supports all structs and `#[derive(MiraArray)]` supports
tuple and unit structs. Both preserve `#[mira(rename = "...")]`,
`#[mira(skip)]`, generics, dependency aliases, and `#[mira(crate = ...)]`.
Nested derived records and arrays are projection views: they retain a typed parent
handle and read the field from the runtime on every access instead of cloning it.

```rust
use mirascript_vm::{MiraRecord, MiraValue, Runtime, compile};

#[derive(MiraRecord)]
struct Position { x: f64, y: f64 }

#[derive(MiraRecord)]
struct User { name: String, position: Position }

let mut runtime = Runtime::new();
let user = runtime.insert_record(User {
    name: "Ada".into(),
    position: Position { x: 3.0, y: 4.0 },
})?;
runtime.insert_global("user", MiraValue::record(user))?;

let script = compile("user.position.x")?;
assert_eq!(runtime.run(&script)?, MiraValue::number(3.0));
runtime.get_record_mut(user)?.position.x = 10.0;
assert_eq!(runtime.run(&script)?, MiraValue::number(10.0));
# Ok::<(), Box<mirascript_vm::MiraError>>(())
```

Use `#[mira]` to expose native functions and inline modules. The original Rust
function is unchanged; the macro adds an upper-case companion constant that can
be inserted into a runtime. Inside a Mira module, function diagnostic names are
qualified while export keys remain local.

```rust
use mirascript_vm::{Runtime, mira};

#[mira]
mod arithmetic {
    use mirascript_vm::MiraValue;

    #[mira]
    pub const ANSWER: usize = 42;

    #[mira]
    pub fn add(a: f64, b: f64) -> f64 { a + b }

    #[mira]
    pub fn sum(start: f64, rest: &[MiraValue]) -> mirascript_vm::Result<f64> {
        rest.iter().try_fold(start, |sum, value| {
            Ok(sum + f64::try_from(*value)?)
        })
    }
}

assert_eq!(arithmetic::add(1.0, 2.0), 3.0);
let mut runtime = Runtime::new();
runtime.insert_global("arithmetic", ARITHMETIC)?;
assert_eq!(runtime.eval("arithmetic.add(1, 2)")?, 3.into());
assert_eq!(runtime.eval("arithmetic.sum(1, 2, 3)")?, 6.into());
# Ok::<(), Box<mirascript_vm::MiraError>>(())
```

`const = NAME` overrides the Rust companion constant, `rename = "full.name"`
overrides the `MiraFunction` or `MiraModule` diagnostic name, and `use = "key"`
overrides the direct parent module's export key. Consecutive `#[mira]` modules
build dotted default names; an unmarked module starts a new naming root.

`MiraExtern` is currently only a public, sealed marker. It has no constructor or
derive macro, and downstream crates cannot implement it.

## Execution options and providers

`Runtime::with_options` configures the timeout, checkpoint interval, maximum call
depth, maximum bounded array length, and a `RuntimeProviders` implementation for
random numbers, time, and debug output.

```rust
use std::rc::Rc;
use mirascript_vm::{RunOptions, Runtime, RuntimeProviders, compile};

struct Deterministic;
impl RuntimeProviders for Deterministic {
    fn random(&self) -> f64 { 0.25 }
}

let mut runtime = Runtime::with_options(RunOptions {
    providers: Rc::new(Deterministic),
    ..RunOptions::default()
});
assert_eq!(runtime.run(&compile("random()")?)?.as_number(), Some(0.25));
# Ok::<(), Box<mirascript_vm::MiraError>>(())
```

Timeout checks are cooperative. Loop backedges and function calls reach
checkpoints; a blocking native callback cannot be preempted.

## Lifetimes and errors

Strings, arrays, and records returned from a run remain valid in that runtime.
Script closures and modules retain their shared decoded program and execution
generation but cannot escape as results; cached callables from an older run return
`RuntimeErrorKind::ExecutionEnded`. The runtime has no garbage collector: all arena
values are released together when it is dropped.

`MiraError` separates compiler diagnostics, invalid bytecode, structured runtime
failures, conversion failures with field/index paths, and arbitrary host errors.
Runtime errors retain bytecode offsets and call-stack context.

## Development

```text
cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo test --workspace
cargo doc --workspace --no-deps
git diff --check
```