turi <-> tur Parity Guide

This guide answers one question: "does feature X behave the same under the interpreter as it does compiled?" It pairs the compiled path (tur build / tur emit-c, which lowers to C) against the tree-walking interpreter (turi, which backs tur interpret, tur repl, sandboxed turi_env_new, and the tests/run-turi.sh leg of the suite). tur run compiles via cc BY DEFAULT; it reaches the tree-walker only when the engine ladder selects it (--engine interp, TUR_ENGINE=interp, or :engine "interp" in build.tur -- see the performance guide's engine section).

What turi is

turi is the Turmeric eval runtime: a tree-walking interpreter over the same Expr tree the C codegen lowers (src/turi/eval.c). It is intentionally not a separate language -- every expression kind the compiler can emit, the interpreter aims to evaluate, modulo a short, documented escape-hatch list. The shared front-end (parser, macro expander, elaborator, substructural checker) runs identically on both paths, so type errors, linearity diagnostics, and macro expansion are the same; only the back end differs (C codegen vs. direct evaluation).

For embedding and the eval API see eval-api.md; for the interactive prompt see repl.md and repl-tutorial.md.

Because both paths share the elaborator, "feature X works under turi" almost always reduces to "the runtime ops behind X are evaluable" -- i.e. they are pure Turmeric, have an EX_* case arm in eval.c, or are backed by a native override (the wk_register_*_natives registrations, compiled into tur_core) rather than raw inline-C.

Parity matrix

Columns: tur = compiled path, turi = interpreter. Cells are OK, partial, none, or n/a. "Single-threaded" notes mean the interpreter runs the feature correctly but on one OS thread (it does not simulate preemptive concurrency).

Continuations -- captured-continuation re-entry through native HOFs

Multishot resume, escaping continuations, and resume through nested handlers all work under --interpret (turi-interpreter-delimited-control-plan.md): capturable handles run on the driver work-stack as a heap-owned TuriWsCont continuation (the turi analog of tur's heap DK chain), captured between the perform and the matching DK_PROMPT. Because the continuation is heap-owned and clonable, it survives the handle frame (escaping k), can be re-entered more than once (multishot, by cloning the captured slice per resume), and re-installs the enclosing handlers on resume (nested).

Capturing a continuation through a native / inline-C higher-order-function callback also works: a native HOF that re-applies a closure no longer does so on a live C frame -- the callback is reified onto the driver work-stack as an explicit resume continuation (turi-cek-stackless-reentry-plan.md), so interpreter recursion through driven positions is heap-bounded and delimited control composes with native HOFs the same way it does compiled. The C-scoped boundary forms (catch-unwind, atomically, async) still C-recurse -- a stack-depth concern shared with the compiled backend, guarded by a precise depth check, not a parity gap.

One-shot effects/handlers, call/cc/escape, abortive and context-capturing shift/reset, serializable/cloneable continuations, multishot/escaping/ nested resume, and capture through native HOF frames all work today.

Documented carve-outs

These are interpreter limitations by design, codified in docs/artifacts/turi-carve-out.txt (EX_* kinds) and docs/artifacts/turi-preload-carve-out.txt (unloaded modules), and ratcheted by tools/check_turi_parity.py / tools/check_turi_native_parity.py so they cannot drift silently.

• Inline-C (EX_INLINE_C). A #fx{Unsafe} c body declares a fixed C signature the tree-walker cannot execute. The escape hatch is the native override: stdlib inline-C functions register a C implementation (`wk_register_*_natives`, `try_exec_simple_inline_c`) that turi calls instead. *User* inline-C, and library inline-C with no native shim, fall through to a clean, actionable error pointing at `tur build` / `tur run`. It never silently miscompiles. Fixtures with ac body auto-skip under run-turi.sh -- no per-fixture marker needed.
• WASM async. No WASM target exists in the interpreter; n/a, not a gap.
• EX_CPS_CONT_APP. A CPS-pipeline node the elaborator never emits (the interpreter stops at elaboration), so there is nothing to evaluate -- carved as unreachable, not unimplemented. This is the only carved EX_* kind (tools/check_turi_parity.py reports 1 carved out, 0 gaps).
• Module preload gap. json.tur and schema.tur sit outside the static prelude[] array the parity ratchet tracks, but the JR0/RD reader-macro auto-load blocks (right after prelude[] in cmd_eval_h) preload them unconditionally, so their public names resolve under --interpret. They stay listed in turi-preload-carve-out.txt because they are gaps relative to prelude[], not because they are unavailable at runtime.

The interpreter also intentionally never frees its registered natives and process-lifetime closures, so the harnesses that exercise it default to ASAN_OPTIONS=detect_leaks=0 (the compiler/codegen path stays leak-checked).

Embedding the interpreter: keep every entry point in sync

tur --interpret, tur repl, and the WASM REPL are three separate entry points into the same tree-walker. A capability wired into only one of them is a parity bug that the tools/check_turi_* ratchets do not catch (they check elaboration coverage, not embedder wiring). Three rules keep them from drifting; each has bitten in practice.

• Native overrides live in tur_core, never in main.c. The C implementations that shadow stdlib inline-C bodies -- collection ops (collections_native.c), keyword/:Sym-keyed maps, contract panics, json/schema, lazy seqs -- must compile into tur_core (reached through one turi_env_register_interpreter_natives), because that is what lands in libturi.a / libturi_wasm.a. Anything registered from main.c compiles only into the tur executable, so an embedder or the WASM REPL that does not link main.c gets no override and hits inline-C not supported in interpreter mode for exactly those ops.
• Stdlib preload goes through one shared helper. Reader-macro data literals lower unconditionally (#map{...} -> hamt-of, #set{...} -> set-of) onto stdlib defmacros, so any entry point that builds a bare env without preloading stdlib fails them with "unknown function." Route all three entry points through the shared turi_env_preload_* helper (src/turi/preload.c) so they cannot diverge.
• Result display is a four-tier dispatch -- carry all four tiers. REPL / auto-display value printing cascades turi_try_show (TURI_STRUCT) -> turi_show_result (Pair/Cons) -> turi_try_show_by_tag (named ADT / struct / heap collection: Vec/Set/Map/user struct via its Show instance) -> turi_value_repr (raw-pointer fallback). Vec/Set/Map are TURI_INT heap pointers to the tree-walker, so an entry point missing the by_tag tier prints collections as raw pointers instead of dispatching their Show instance.

Performance note

turi is a tree walker: expect a roughly 10-100x slowdown versus compiled code. It is built for fast iteration, REPL/eval, sandboxing, and the parity test leg -- not for production hot loops. When throughput matters, tur build (or tur run once for a warm cache) and run the native binary.

How to ask "does feature X work?"

1. Run the parity checkers (both gate tests/run.sh):

sh python3 tools/check_turi_parity.py # EX_* kind coverage; 0 gaps expected python3 tools/check_turi_native_parity.py # module-preload parity python3 tools/check_turi_native_parity.py --worklist # name-level preload work list

check_turi_parity.py reports N/M EX_* kinds handled, K carved out, 0 gaps. Every unhandled kind must appear in docs/artifacts/turi-carve-out.txt with a rationale, and every carve-out entry that is actually handled is flagged stale -- so the file and the matrix above stay honest.

1. Try it directly:

sh ASAN_OPTIONS=detect_leaks=0 ./build/tur interpret your-program.tur

A clean run means the feature interprets. An inline-C not supported message means the feature bottoms out in inline-C with no native shim -- run it with tur build / tur run instead.

1. Consult the matrix above for the at-a-glance answer, and the requires.tur-only marker on a carved fixture for the per-case reason.

See also

• eval-api.md -- the libturi C embedding API and sandboxing surface.
• repl.md / repl-tutorial.md -- the interactive interpreter.
• docs/artifacts/turi-carve-out.txt / docs/artifacts/turi-preload-carve-out.txt -- the machine-checked carve-out lists.
• turi-parity-post-v1-plan.md -- the phased plan behind this matrix (archived; all phases landed).