Module const_eval 

Bounded, sandboxed compile-time evaluator for const initializers.

This module is the entire surface added by issue burin-labs/harn#1791. It takes a Harn AST expression that appears on the right-hand side of a const NAME = ... binding and either returns a ConstValue or a ConstEvalError. The evaluator runs entirely inside the parser crate, has zero access to the host or the runtime VM, and enforces three hard caps on every call:

1. Step budget — every reduction increments a step counter. When the counter exceeds MAX_STEPS (default 100_000), evaluation aborts with ConstEvalErrorKind::StepLimit. The check is performed on every step, not amortized.
2. Recursion depth — every recursive call into the interpreter increments a depth counter. Exceeding MAX_DEPTH (default 256) aborts with ConstEvalErrorKind::RecursionLimit.
3. Sandbox denylist — any expression that reaches harness, spawns concurrency, mutates state, performs I/O, calls into a non-allowlisted builtin, references an unknown identifier, or invokes a user-defined function is rejected with ConstEvalErrorKind::SandboxViolation or ConstEvalErrorKind::Disallowed.

The evaluator is allowlist-based: only explicitly permitted node shapes evaluate. Newly added stdlib surface is sandboxed by default.

Cache key shape

Each successful fold is keyed by:

• the SHA-256 of the binding’s source-text expression (mirrors what downstream prompt-template specialization would consume), and
• the tuple (MAX_STEPS, MAX_DEPTH, evaluator_version).

The cache itself is not implemented here — this module just exposes the inputs so a downstream consumer (e.g. compile-time prompt rendering) can wire it up without re-deriving the contract.

Structs

ConstEvalError

A const-eval failure carries a span (so the typechecker can attribute the diagnostic to the offending sub-expression) and a human-friendly detail.

Enums

ConstEvalErrorKind

Reason a const-eval call failed. Mapped 1:1 to diagnostic codes:

ConstValue

A fully folded compile-time value.

Constants

EVAL_VERSION

Stable version tag participating in the cache key. Bump when any observable semantic of the const-evaluator changes.

MAX_DEPTH

Hard cap on recursion depth into the interpreter. Each eval_node invocation increments the depth counter.

MAX_STEPS

Hard cap on the number of reduction steps performed by a single const_eval call. Checked on every step.

Functions

const_eval

Public entry point: fold a single AST node into a ConstValue or return a ConstEvalError. The env argument supplies earlier const bindings visible to this expression.

Type Aliases

ConstEnv

Environment mapping a const name to its already-folded value. The typechecker primes this with bindings encountered earlier in the same file (i.e. const X: int = 1 lets const Y: int = X + 2 resolve).