@spec append_pmap_call(t(), pmap_call()) :: t()

Appends a pmap/pcalls execution record to the context.

@spec append_print(t(), String.t()) :: t()

Appends a print message to the context.

Long messages are truncated to max_print_length characters (default: 2000).

@spec append_tool_call(t(), tool_call()) :: t()

Appends a tool call record to the context.

The entry's :result and :args are bounded to a preview when they exceed max_tool_call_result_bytes, so a looping/large tool use cannot accumulate full payloads in live eval state. See the "Tool-ledger retention" moduledoc section. Only the ledger copy is bounded; callers keep the full result for the program return and cache separately.

@spec consume_loop_iteration(non_neg_integer(), pos_integer() | nil) ::
  {:ok, non_neg_integer()} | {:error, :loop_limit_exceeded}

Consumes one recur jump against an activation-local iteration counter.

nil disables the bound. A positive limit applies to one loop or tail-recur function activation, not to the whole evaluation.

@spec current_origin(t()) :: map() | nil

Returns the current evaluator origin, if any.

@spec current_prelude_caller_user_ns(t()) :: map() | nil

Returns the user namespace active before the current prelude export, if any.

@spec direct_namespace?(t(), String.t()) :: boolean()

Returns true when a namespace was directly selected by the session.

@spec merge_env(t(), map()) :: t()

Merges new bindings into the environment.

@spec new(
  map(),
  map(),
  map(),
  (String.t(), map(), map() | nil -> term()),
  list(),
  keyword()
) :: t()

Creates a new evaluation context.

Options

• :loop_limit - Optional positive integer bound on one loop or tail-recur function activation (default: nil = disabled). Sequential loops, nested loops, and separate HOF callback invocations are separate activations.
• :max_print_length - Max characters per println call (default: 2000)
• :pmap_timeout - Shared absolute deadline in ms for each pmap/pcalls operation, including nested parallel calls (default: 5000). Increase for LLM-backed tools.
• :parallel_deadline_cap - Absolute monotonic-time ceiling in ms that clamps every parallel deadline regardless of when the operation starts (default: nil = no ceiling). Kernel runs pass their run deadline here.
• :pmap_max_concurrency - Max concurrent tasks in pmap/pcalls (default: the build-time System.schedulers_online() * 2, frozen into the semantic revision)
• :max_heap - Sandbox per-process heap cap in words (default: nil).
• :worker_max_heap - FIXED max_heap_size (in words) for every pmap/pcalls worker, top-level and nested (default: the :max_heap value). Not divided by concurrency. See PtcRunner.Lisp.Eval.ParallelRunner.
• :parallel_budget - shared PtcRunner.Lisp.Eval.ParallelBudget semaphore bounding the number of parallel workers alive at once across the whole run (default: nil = uncounted).

Examples

iex> ctx = PtcRunner.Lisp.Eval.Context.new(%{}, %{}, %{}, fn _, _, _ -> nil end, [])
iex> ctx.user_ns
%{}

iex> ctx = PtcRunner.Lisp.Eval.Context.new(%{}, %{}, %{}, fn _, _, _ -> nil end, [], max_print_length: 500)
iex> ctx.max_print_length
500

iex> ctx = PtcRunner.Lisp.Eval.Context.new(%{}, %{}, %{}, fn _, _, _ -> nil end, [], pmap_timeout: 60_000)
iex> ctx.pmap_timeout
60000

@spec prelude_ref_visible?(t(), String.t()) :: boolean()

Whether a prelude ref may be resolved from the current origin.

Under strict_transitive_calls a session-authored program may name a namespace it selected directly, or one no direct selection pulled in, but not one reached only transitively through another prelude's requirements. Calls made from inside a prelude export are never restricted.

Both the evaluator's resolution guard and PtcRunner.Lisp.Introspection's visibility filter read this, so what a program can discover and what it can call cannot drift apart.

@spec push_prelude_caller_user_ns(t(), map()) :: t()

Saves the user namespace active before entering a prelude export.

@spec push_prelude_origin(t(), map()) :: t()

Pushes a prelude-export origin for private tool authorization.

@spec push_prelude_returned_origin(t(), String.t()) :: t()

Pushes a prelude returned-closure origin without granting private tool authority.

@spec push_user_origin(t()) :: t()

Pushes a user-code origin that masks inherited prelude-export authority.

@spec recur_effects(t()) :: recur_effects()

Extracts accumulated side effects that must survive a recur jump.

@spec ref_namespace(String.t()) :: String.t() | nil

Returns the namespace part of a qualified prelude ref, or nil.

@spec reserve_tool_call(t()) :: :ok | {:error, :tool_call_limit_exceeded}

Atomically reserves one uncached tool invocation against the program-wide tool-call limit.

Returns :ok when unlimited (nil) or when the reservation succeeds, {:error, :tool_call_limit_exceeded} when the shared limit is exhausted.

@spec restore_recur_effects(t(), recur_effects()) :: t()

Restores side effects carried by a recur signal onto the next iteration context.

@spec session_authored_origin?(map() | nil) :: boolean()

Whether an origin is session-authored rather than a prelude export.

@spec transitive_namespace_requirers(t(), String.t()) :: [String.t()]

Returns the direct prelude ids that pulled a transitive namespace in.

@spec update_user_ns(t(), map()) :: t()

Updates the user namespace in the context.