runtime

Documentation

Overview

Package runtime is the txcl value-resolution layer. It owns the single function — Resolve — that walks an ast.Value against an Env and returns a concrete Go value.

Every consumer of a txcl Value (the processor's SET / EMIT / WITH paths; eventually the resonator's WHEN evaluator) calls Resolve rather than reaching inside Value nodes directly. This keeps the dispatch logic in one place and means new value shapes (FunctionCall when PR 3 wires it in, future node types after) add to one switch instead of being scattered.

See internal docs/todo-txcl-expressions.md and internal docs/todo-txcl-expressions-implementation.md for the broader plan.

Index

• func Resolve(v ast.Value, env Env) (any, error)
• type Env
• type JSONEnv
  • func (e JSONEnv) Get(path string) (any, bool)
• type MapEnv
  • func (m MapEnv) Get(path string) (any, bool)
• type MultiEnv
  • func (m MultiEnv) Get(path string) (any, bool)

Functions

func Resolve

func Resolve(v ast.Value, env Env) (any, error)

Resolve evaluates a Value against env. Single entry point shared by every caller that needs a runtime value from a parsed AST node.

Semantics:

• nil Value returns (nil, nil). Useful for optional fields (SelectAssignment.Default when HasDefault is false).
• Literal returns its wrapped V directly.
• PathRef returns env.Get(path)'s value. A missing path returns (nil, nil) — absence is not an error; callers can write nil into the envelope or compare against null in WHEN clauses.
• FunctionCall resolves each Arg (recursively) then dispatches through chassis/txcl/funcs. The registered function returns either a value or an error; the error propagates as a strict halt.

Callers must treat a non-nil error as a halt signal for the rule being evaluated (strict-by-default semantics — see design doc §5). Silent skipping is a footgun: a value that "couldn't be computed" is not the same as a value that "is empty."

Types

type Env

type Env interface {
	Get(path string) (any, bool)
}

Env is the resolution context used by Resolve when it walks a PathRef node. Decoupling the evaluator from a specific backing representation keeps the door open for in-memory sub-envelopes (e.g. a parsed value held in a variable after `&json(...)`) without changing Resolve's signature.

Implementations supplied here:

• JSONEnv — the standard chassis envelope (JSON string, gjson-backed). Used by the processor.
• MapEnv — a flat-key test helper. Used by runtime tests that don't want to construct real JSON.

type JSONEnv

type JSONEnv string

JSONEnv wraps a JSON-string envelope. Path lookups go through gjson; semantics match what every existing envelope read in the chassis does today. A missing path returns (nil, false).

func (JSONEnv) Get

func (e JSONEnv) Get(path string) (any, bool)

type MapEnv

type MapEnv map[string]any

MapEnv is a test helper. Reads flat-key (top-level only) values from an in-memory map. Tests that need nested-path behavior should pre-flatten the map or use JSONEnv with a real JSON string.

func (MapEnv) Get

func (m MapEnv) Get(path string) (any, bool)

type MultiEnv

type MultiEnv []Env

MultiEnv tries each Env in order; first match wins. Used to expose multiple envelope sources at the same resolution boundary.

Concrete use: the processor's EMIT overlay needs to see both the EXEC's fresh output (so `EMIT @reply = .text` projects the handler's reply) AND the scope input envelope (so `EMIT @reply = @web.req.body` can still reach the input). Composing them as a MultiEnv lets either path-shape work without the caller pre-merging two large JSON docs.

A nil or empty MultiEnv returns (nil, false) for every Get.

func (MultiEnv) Get

func (m MultiEnv) Get(path string) (any, bool)