Module eval 

Tree-walking evaluator — reference semantics for Jetro v2.

This module is the source of truth: when the optimiser or VM behaviour diverges from it, the VM is wrong. It is also the smallest path from AST to value and thus the easiest to reason about. vm is a faster path that caches compiled programs and resolved pointers, but every new feature lands here first.

Data flow

evaluate(expr, doc)
    │
    ▼
  apply_expr(&Expr, &Env)
    │
    ├── literals / operators    (inline)
    ├── chain navigation        (apply_chain → apply_step)
    ├── method calls            (dispatch_method → func_*/methods.rs)
    └── comprehensions / let    (recursive into new Env)

Env

Env owns the root doc, the “current” value (@), and a SmallVec<[(Arc<str>, Val); 4]> of let-bound names plus an Arc<MethodRegistry> for user-registered methods. Scopes are pushed by appending and popped by truncation — lookup is linear but SmallVec keeps the first four slots inline, which covers every realistic query.

Registry

MethodRegistry holds user methods behind Arc<dyn Method> and is itself Clone (via derive) so threading it through recursive calls is free.

Re-exports

pub use value::Val;

pub use methods::Method;

pub use methods::MethodRegistry;

Modules

builtins

Static builtin registry — zero vtable overhead via raw function pointers.

methods

util

Shared helpers used across eval / vm:

value

Structs

Env

EvalError

LamFrame

Saved-state token returned by Env::push_lam and consumed by Env::pop_lam. Lets hot loops bind a single lambda slot + swap current without cloning the whole Env per iteration.

Functions

evaluate

evaluate_with

evaluate_with_raw

Evaluate expr with the original JSON source bytes retained. Enables SIMD byte-scan fast paths for $..key descent queries.