Struct Vm 

pub struct Vm { /* private fields */ }

The Harn bytecode virtual machine.

Implementations

impl Vm

pub fn set_breakpoints_for_file(&mut self, file: &str, lines: Vec<usize>)

Replace breakpoints for a single source file. Pass an empty string (or call set_breakpoints for the wildcard equivalent) to install breakpoints that match every file — useful for ad-hoc CLI runs where the embedder doesn’t track per-file source paths.

pub fn set_breakpoints(&mut self, lines: Vec<usize>)

Backwards-compatible wildcard form. Stores all lines under the empty-string key, which matches any source file at the check site. Existing embedders that don’t track file scoping still work.

pub fn set_function_breakpoints(&mut self, names: Vec<String>)

Replace the function-breakpoint set. Every subsequent closure call whose name matches one of the provided strings will pause on entry. Empty vec clears the set.

pub fn function_breakpoint_names(&self) -> Vec<String>

Returns the current function-breakpoint name set. Used by the DAP adapter to build the setFunctionBreakpoints response with verified=true per registered name.

pub fn take_pending_function_bp(&mut self) -> Option<String>

Drain any pending function-breakpoint name latched by the most recent closure entry. Returns Some(name) exactly once per hit so the caller can emit a single stopped event.

pub fn set_step_mode(&mut self, step: bool)

Enable step mode (stop at the next source line regardless of frame depth — i.e. step-in semantics, descending into calls).

pub fn set_step_over(&mut self)

Enable step-over mode (stop at the next source line in the current frame or a shallower one, skipping past any nested calls).

pub fn set_debug_hook<F>(&mut self, hook: F)

where F: FnMut(&DebugState) -> DebugAction + 'static,

Register a debug hook invoked whenever execution advances to a new source line.

pub fn clear_debug_hook(&mut self)

Clear the current debug hook.

pub fn set_step_out(&mut self)

Enable step-out mode (stop at the next source line after the current frame has returned — strictly shallower than where the user requested the step-out).

pub fn is_stopped(&self) -> bool

Check if the VM is stopped at a debug point.

pub fn debug_state(&self) -> DebugState

Get the current debug state (variables, line, etc.).

pub fn call_sites_on_line(&self, line: u32) -> Vec<(u32, String)>

Call sites (name + ip) on line within the current frame’s chunk — drives DAP stepInTargets (#112). Walks the chunk’s parallel lines array, surfaces every Call / MethodCall / CallSpread and pairs it with the name of the constant or identifier preceding the call when we can derive it cheaply.

pub fn install_cancel_token(&mut self, token: Arc<AtomicBool>)

Install (or replace) the cooperative cancellation token on this VM. Callers (DAP adapter, embedded host) flip the wrapped AtomicBool to request graceful shutdown; the step loop checks is_cancel_requested() at every instruction and exits with VmError::Cancelled when set.

pub fn signal_cancel(&mut self) -> Arc<AtomicBool>

Signal cooperative cancellation on this VM — the step loop unwinds on its next instruction check. Lazily allocates a fresh token when none is installed so hosts don’t need to pre-plumb it on every launch. Returns the Arc so the caller can hold onto it and re-signal later if needed.

pub fn is_cancel_requested(&self) -> bool

True when cooperative cancellation has been requested.

pub fn identifiers_in_scope(&self, _frame_id: usize) -> Vec<String>

Identifiers visible at the given frame’s scope — locals plus every registered builtin + async builtin. Drives DAP completions (#109) so the REPL autocomplete surfaces everything the unified evaluator can reach.

pub fn debug_stack_frames(&self) -> Vec<(String, usize)>

Get all stack frames for the debugger.

pub fn debug_stack_frames_with_sources( &self, ) -> Vec<(String, usize, Option<String>)>

Get all stack frames plus their source keys for debugger clients that can retrieve synthetic sources through DAP source.

pub fn debug_source_for_path(&self, path: &str) -> Option<String>

Return cached source text by debugger source key. This covers entry programs, real imports that have already been read, and synthetic sources such as stdlib modules or generated in-memory modules.

pub async fn step_execute(&mut self) -> Result<Option<(VmValue, bool)>, VmError>

Execute one instruction, returning whether to stop (breakpoint/step). Returns Ok(None) to continue, Ok(Some(val)) on program end, Err on error.

Line-change detection reads the line of the instruction we’re about to execute (lines[ip]) rather than the byte before ip. After a jump, ip-1 still points into the skipped region, which previously reported phantom stops on the tail of a not-taken branch (e.g. host_metadata_save() highlighted even though any_stale was false). Using lines[ip] — combined with cleanup ops emitted at line 0 after branch/loop exits — keeps the debugger aligned with what’s actually going to run.

pub fn frame_count(&self) -> usize

Number of live call frames. Used by the DAP adapter to translate stackTrace ids (1-based, innermost first) back to the VM’s 0-based outermost-first index when processing restartFrame.

pub fn restart_frame(&mut self, frame_id: usize) -> Result<(), VmError>

Rewind the given frame to its entry state so stepping resumes from the first instruction of the function with the original arguments re-bound. Higher frames above frame_id are dropped. Returns an error if the frame has no captured initial_env (scratch / evaluator frames don’t) or if the id is out of range.

Side effects already performed by the restarted frame (tool calls, file writes, host_call round-trips) are not rolled back — DAP leaves that to the adapter’s discretion. The IDE should warn on frames whose source text contains obvious side-effectful calls before invoking restartFrame.

pub async fn set_variable_in_frame( &mut self, name: &str, value_expr: &str, frame_id: usize, ) -> Result<VmValue, VmError>

Assign a new value to a named binding in the paused VM’s env. Returns the value that was actually stored (after coercion, if the VM performed any) so the caller can echo it back to the DAP client. Fails if the name does not resolve to a mutable binding in any live scope.

The provided value_expr goes through the unified evaluator so callers can type expressions like plan.tasks.len() + 1 in the Locals inline-edit field, not just literals.

pub async fn evaluate_in_frame( &mut self, expr: &str, _frame_id: usize, ) -> Result<VmValue, VmError>

Evaluate a Harn expression against the currently paused frame’s scope and return its value. This is the single evaluation path used by hover tips, watch expressions, conditional breakpoints, logpoint interpolation, and setVariable / setExpression before we had a unified evaluator there were four separate mini-parsers, each with its own rough edges (see burin-code #85).

The expression is wrapped as let __r = (<expr>) so arbitrary infix chains, ternaries, and access paths parse uniformly. A scratch CallFrame runs the wrapped bytecode with saved_env pointing at the caller’s env, so the compiled expression sees every local in scope. When the scratch frame pops, the caller’s env is automatically restored.

A fixed instruction budget guards against runaway expressions (infinite loops, accidental recursion) wedging the debugger. Side effects — including llm_call, host_*, and file mutators — are not blocked here; callers that invoke this for read-only surfaces (hover, watch) should reject obviously-side-effectful expressions before calling.

impl Vm

pub fn register_builtin<F>(&mut self, name: &str, f: F)

where F: Fn(&[VmValue], &mut String) -> Result<VmValue, VmError> + 'static,

Register a sync builtin function.

pub fn register_builtin_with_metadata<F>( &mut self, metadata: VmBuiltinMetadata, f: F, )

where F: Fn(&[VmValue], &mut String) -> Result<VmValue, VmError> + 'static,

Register a sync builtin function with discoverable metadata.

pub fn unregister_builtin(&mut self, name: &str)

Remove a sync builtin (so an async version can take precedence).

pub fn register_async_builtin<F, Fut>(&mut self, name: &str, f: F)

where F: Fn(Vec<VmValue>) -> Fut + 'static, Fut: Future<Output = Result<VmValue, VmError>> + 'static,

Register an async builtin function.

pub fn register_async_builtin_with_metadata<F, Fut>( &mut self, metadata: VmBuiltinMetadata, f: F, )

where F: Fn(Vec<VmValue>) -> Fut + 'static, Fut: Future<Output = Result<VmValue, VmError>> + 'static,

Register an async builtin function with discoverable metadata.

pub async fn call_closure_pub( &mut self, closure: &VmClosure, args: &[VmValue], ) -> Result<VmValue, VmError>

Public wrapper for call_closure, used by the MCP server to invoke tool handler closures from outside the VM execution loop.

impl Vm

pub async fn execute(&mut self, chunk: &Chunk) -> Result<VmValue, VmError>

Execute a compiled chunk.

impl Vm

pub fn format_runtime_error(&self, error: &VmError) -> String

impl Vm

pub async fn load_module_exports( &mut self, path: &Path, ) -> Result<BTreeMap<String, Rc<VmClosure>>, VmError>

Load a module file and return the exported function closures that would be visible to a wildcard import.

pub async fn load_module_exports_from_source( &mut self, source_key: impl Into<PathBuf>, source: &str, ) -> Result<BTreeMap<String, Rc<VmClosure>>, VmError>

Load synthetic source keyed by a synthetic module path and return the exported function closures that a wildcard import would expose.

pub async fn load_module_exports_from_import( &mut self, import_path: &str, ) -> Result<BTreeMap<String, Rc<VmClosure>>, VmError>

Load a module by import path (std/foo, relative module path, or package import) and return the exported function closures that a wildcard import would expose.

impl Vm

pub fn new() -> Self

pub fn set_bridge(&mut self, bridge: Rc<HostBridge>)

Set the bridge for delegating unknown builtins in bridge mode.

pub fn set_denied_builtins(&mut self, denied: HashSet<String>)

Set builtins that are denied in sandbox mode. When called, the given builtin names will produce a permission error.

pub fn set_source_info(&mut self, file: &str, text: &str)

Set source info for error reporting (file path and source text).

pub fn start(&mut self, chunk: &Chunk)

Initialize execution (push the initial frame).

pub fn set_source_dir(&mut self, dir: &Path)

Set the source directory for import resolution and introspection. Also auto-detects the project root if not already set.

pub fn set_project_root(&mut self, root: &Path)

Explicitly set the project root directory. Used by ACP/CLI to override auto-detection.

pub fn project_root(&self) -> Option<&Path>

Get the project root directory, falling back to source_dir.

pub fn builtin_names(&self) -> Vec<String>

Return all registered builtin names (sync + async).

pub fn builtin_metadata(&self) -> Vec<VmBuiltinMetadata>

Return discoverable metadata for registered builtins.

pub fn builtin_metadata_for(&self, name: &str) -> Option<&VmBuiltinMetadata>

Return discoverable metadata for a registered builtin name.

pub fn set_global(&mut self, name: &str, value: VmValue)

Set a global constant (e.g. pi, e). Stored separately from the environment so user-defined variables can shadow them.

pub fn output(&self) -> &str

Get the captured output.

pub fn take_output(&mut self) -> String

Drain and return the captured output, leaving the buffer empty. Used by the async-builtin dispatch path to forward closure output from a child VM back to its parent.

pub fn append_output(&mut self, text: &str)

Append text to this VM’s captured output. Used to forward output from child VMs (e.g. closures invoked via call_closure_pub) back into the parent stream.

Trait Implementations

impl Default for Vm

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Vm

fn drop(&mut self)

Executes the destructor for this type.