PtcRunner.Kernel.Evaluation (PtcRunner v0.14.0)

Copy Markdown View Source

Internal subordinate PTC-Lisp evaluation boundary.

Evaluation reserves the single transactional mission-continuation lease, executes source exclusively against a mission environment, and commits candidate memory/history only after successful bounded completion. Every failure path releases the lease without changing the prior continuation.

An ordinary successful value is projected as :continued; an explicit (return value) is projected as :returned; and (fail value) is projected as :failed. Failed results report whether capability activity occurred, whether the failure value is the exact result of the last recorded capability call, and whether correcting the program is effect-safe. The latter says only that the evaluation performed no write or unknown effect; callers combine all three facts with the bounded failure shape before requesting a correction. Terminal provider-policy provenance is reported separately. It is derived from the private tool ledger for normal outcomes and from the evaluation owner for sandbox hard stops, so a later expression failure, timeout, or heap kill cannot erase it.

Continued and returned evaluations atomically commit native memory and exact bounded history before exposing only an inert public value. Continued results additionally expose bounded chronological prints for the next agent turn. Runtime-tool results use the strict :kernel_json projection and reject ambiguous collections. Code-owned analysis sessions opt into the preserving :public projection because their trusted frontend formats an Elixir observation rather than returning JSON to workflow Lisp.

Mission-scoped evaluation is strict for data/<name>: a missing grant is a runtime error that lists the same granted names the mission inventory publishes, calling a granted value is not_callable naming the symbol, and data/params without a supplied params map names kernel/eval-with and kernel/eval-source-with. PtcRunner.Lisp.run/2 stays permissive.

Summary

Functions

evaluate_source(state, mission_name, mission_environment, source, timeout_ms, event_sink \\ nil, inspection_sink \\ nil, opts \\ [])

@spec evaluate_source(
  PtcRunner.Kernel.RunState.t(),
  binary(),
  map(),
  binary(),
  non_neg_integer(),
  term(),
  term(),
  keyword()
) :: map()

Evaluates bounded subordinate source for an explicitly named mission.