@spec eval_all(captures(), context()) ::
  {:ok, %{optional(atom()) => term()}, context()} | {:error, Ichor.Error.t()}

Eagerly invokes every capture's eval, in true source order (each %Capture{}'s own position, not captures' incidental map iteration order -- see Ichor.Capture's moduledoc for why those two can differ), threading context through -- the plain bottom-up fold that's correct for grammars with no special-form semantics (most config/markup/query grammars, as opposed to something like LISP's if/quote, which need to not evaluate an untaken branch at all). A list-valued capture (the same name captured more than once, e.g. inside a *) resolves to a list of values in the same order. Halts and returns immediately on the first error.

A %Capture{} built by hand rather than via dispatch_rule/5 (directly constructing this map for a test, say) defaults every position to 0 -- ties between those fall back to whatever order captures itself happens to enumerate in, same as this function's behavior before position existed. Give hand-built captures distinct positions if you need this function's ordering guarantee to hold for them too.

@spec evaluate(
  atom(),
  Ichor.Capture.raw_captures(),
  module(),
  context(),
  capture_shapes()
) ::
  {:ok, term(), context()} | {:error, Ichor.Error.t() | [Ichor.Error.t()]}

The single entry point tying Grammar.VM's raw capture tree to a grammar's Actions module: evaluates the root rule, then runs finalize/1 over whatever context that produced. Returns the final context alongside the value -- needed whenever more than one top-level match must thread context forward (e.g. loading a multi-form source file one top-level form at a time); callers that only need the value can just ignore it.

capture_shapes (from Grammar.VM.RuleCompiler.capture_shapes/1) says, per rule, which capture names sit under a */+/{n,m} -- needed so e.g. an op: that matched zero times still shows up as [], not as a missing key indistinguishable from "this rule shape never has an :op" (see that function's docs for why this can't just be inferred from the raw tree at dispatch time).

@spec evaluate_node(Ichor.Capture.node_t(), module(), context()) ::
  {:ok, term(), context()} | {:error, Ichor.Error.t()}

Evaluates a raw capture node (as found on any Ichor.Capture.node, or built directly by something like a macro's unreify) against actions_module, starting from context. See this module's own moduledoc for when you need this instead of an ordinary .eval thunk.