Module step_runtime 

Per-step runtime state for @step-annotated persona functions.

The compiler emits a call to the __register_step builtin after each @step declaration so the runtime can dispatch on the step’s metadata when its function is invoked. While a step’s frame is on the call stack, an ActiveStep entry tracks per-step LLM usage, defaults llm_call’s model when the call site doesn’t override it, and bounds cumulative token and cost spend against the step’s budget.

This module owns three thread-locals (a per-program registry, a stack of currently-active steps, and a log of completed step summaries) but exposes only narrow helpers — current_active_step_* / record_step_llm_usage / etc. — so the call sites in crates/harn-vm/src/llm/, crates/harn-vm/src/vm/, and the compiler stay focused.

Structs

ActiveContextSnapshot

ActivePersona

ActiveStep

Tracks one in-flight step. The frame_depth is Vm::frames.len() captured immediately after push_closure_frame returns, so an ActiveStep is “alive” while Vm::frames.len() >= frame_depth.

CompletedStep

Snapshot persisted into [COMPLETED_STEPS] when the step’s frame unwinds. Receipts and harn persona inspect-style downstream consumers read it back via drain_completed_steps.

PersonaDefinition

PersonaHookInvocation

PersonaHookRegistration

StepDefinition

Static metadata captured from a @step(...) attribute.

Enums

StepErrorBoundary

Functions

active_step_frame_depth

Frame depth of the topmost active step, or None when no step is active. Used by handle_error to detect “this throw is exiting a step’s frame”.

active_step_model_default

Default model the topmost active step should impose on llm_call invocations whose options dict didn’t pin a model.

clear_persona_hooks

completed_step_to_json

Lower a CompletedStep into JSON for embedding in receipts / inspect output.

current_persona_name

drain_completed_steps

Drain the completed-step log. Used by receipt builders that want a per-step model + token + cost breakdown for the just-finished run.

finish_active_step

is_step_budget_exhausted

Returns true if the thrown value looks like a budget-exhausted error — either our typed step-budget dict or the existing crates/harn-vm/src/llm/cost.rs::budget_exceeded_error shape. Either form is treated identically by error_boundary because the per-step budget machinery layers onto the existing envelope; a step whose budget the preflight projection rejects is still a budget exhaustion the step authored.

is_tracked_function

mark_escalated

Annotate an existing budget-exhausted error with escalated: true and the step’s identity so the persona body / handoff receiver can route on it. Returns the original error if it isn’t a thrown dict. Ensures step and function keys reflect the just-finished step even when the underlying error was raised by the preflight budget machinery (which doesn’t know which step it’s running under).

matching_hooks

maybe_push_active_persona

maybe_push_active_step

Push an active step onto the stack iff function_name has metadata registered. Returns true when a frame was pushed so the call site can record that fact. Called from Vm::push_closure_frame after the new frame has been added.

peek_completed_steps

Read the completed-step log without clearing it. Use when callers want a peek without disturbing the global record stream.

pop_and_record

Pop the topmost active step (if its frame is the current one) and record an explicit completion status. Used when an error boundary rewrites or absorbs an in-flight error so the receipt log reflects the outcome the persona actually saw.

prune_below_frame

Drop any step entries whose owning frame has already been unwound, recording a CompletedStep summary for each. The current_frame_depth is Vm::frames.len() at the call site — entries with frame_depth > current_frame_depth are stale.

record_step_llm_usage

Record that llm_call consumed input_tokens / output_tokens for cost_usd. Updates the active step’s running totals and returns a budget-exhaustion error if the step’s ceiling is now breached.

register_persona

register_persona_from_dict

register_persona_hook

register_step

Bind a @step function name to its declared metadata. Idempotent: a second call replaces the prior definition (matches re-evaluation semantics of harn run and the conformance harness).

register_step_builtins

Register the __register_step host builtin. Compiler-emitted bytecode after every @step declaration calls it with (function_name, metadata_dict) so the runtime can later dispatch on the step’s metadata when its function is invoked.

register_step_from_dict

Builtin entry point invoked by compiler-emitted bytecode after every @step function declaration. Accepts a dict mirroring harn_modules::PersonaStepMetadata.

register_step_hook

reset_thread_local_state

Reset every thread-local owned by this module. Called between test runs and at the start of each top-level program execution so leftover registrations don’t leak across runs.

restore_active_context

step_definition_for_function

take_active_context

take_active_step

with_active_step

Get a snapshot of the topmost active step, if any. Used by the llm_call path to fill in defaults — never for mutation.

with_active_step_mut

Mutate the topmost active step (typically to attribute LLM usage).