jsonatapy 2.2.4__tar.gz → 2.2.6__tar.gz

{jsonatapy-2.2.4 → jsonatapy-2.2.6}/CHANGELOG.md

@@ -19,6 +19,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+## [2.2.6] - 2026-07-20
+
+### Added
+- Host-callable custom functions (Rust core): `Evaluator::register_fn` and
+  `Evaluator::register_fn_override` let a host register native functions callable
+  from an expression as `$name(...)` — the equivalent of jsonata-js's
+  `registerFunction`. Functions are plain closures
+  (`Fn(&[JValue]) -> Result<JValue, EvaluatorError>`) and resolve after the
+  expression's own bindings/lambdas and before built-ins. `register_fn` rejects
+  collisions with built-ins; `register_fn_override` allows deliberately replacing
+  the impure built-ins (`$now`, `$millis`, `$random`, `$eval`) for determinism
+  injection or sandboxing. Evaluation stays synchronous. See
+  `examples/host_functions.rs` and the Rust crate docs.
+- Host-callable custom functions (Python binding): `JsonataExpression.register(name,
+  func)` and `.register_override(name, func)` expose the above to Python. The callable
+  receives already-evaluated positional arguments and must return a JSON-compatible
+  value synchronously; an `async def` (coroutine) is rejected at call time with
+  guidance to await I/O outside jsonata and pass results via `bindings`. Collision and
+  compilable-builtin-override rules are validated at `register()` time.
+- Host-callable custom functions (C ABI): `jsonata_register_fn(expr, name, fn, user_data)`
+  and `jsonata_register_fn_override(...)` expose the feature to C and any language with C
+  interop. The callback receives its arguments as a JSON array string and returns a JSON
+  result string (jsonata copies it; the host retains ownership), or NULL to signal an error.
+  See `bindings/c/jsonata.h`, `bindings/c/README.md`, and `bindings/c/examples/smoke.c`.
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [2.2.5] - 2026-07-14
+
+### Added
+- C API (`capi` cargo feature): use the engine from C, C++, or any language with C interop.
+  Eight functions, JSON text in/out (`jsonata_compile`, `jsonata_evaluate`, `jsonata_bind_var`,
+  `jsonata_free_expr`, `jsonata_free_string`, `jsonata_last_error_message`,
+  `jsonata_last_error_code`, `jsonata_version`), thread-local error slot, and engine panics
+  caught at the boundary instead of aborting the host process. Ships with a hand-written
+  header (`bindings/c/jsonata.h`), build/link/CMake documentation (`bindings/c/README.md`),
+  and a CI-gated smoke test compiled as both C and C++. Build with
+  `cargo build --release --features capi`.
+
+### Fixed
+- Performance regression in v2.2.4 on small/fast expressions (issue #74): the
+  `JSONATAPY_FORCE_TREE_WALKER` test toggle read the environment variable on every
+  evaluation (both `evaluate()` and `evaluate_json()`), costing ~100-200ns per call —
+  10-30% of a sub-microsecond expression. The toggle is now a process-wide atomic seeded
+  from the environment once at import (whole-process forcing works unchanged) and flippable
+  via a private test hook. Small-expression benchmarks recover 5-16%; the remaining few
+  percent vs v2.2.3 on tiny payloads is the documented cost of lazy conversion (which makes
+  realistic workloads up to 48% faster, see 2.2.4 notes).
+
+### Changed
+- Benchmark tooling: PR benchmark comments and release regression issues now state their
+  comparison baseline explicitly (which commit/release, recorded when, on which runner),
+  and the vs-jsonata-js comparison is labeled as such.
+
 ## [2.2.4] - 2026-07-13
 
 ### Added

{jsonatapy-2.2.4 → jsonatapy-2.2.6}/Cargo.lock

@@ -586,7 +586,7 @@ dependencies = [
 
 [[package]]
 name = "jsonata-core"
-version = "2.2.4"
+version = "2.2.6"
 dependencies = [
  "assert_cmd",
  "base64",

{jsonatapy-2.2.4 → jsonatapy-2.2.6}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jsonata-core"
-version = "2.2.4"
+version = "2.2.6"
 edition = "2021"
 authors = ["txjmb <txjmb@users.noreply.github.com>"]
 description = "High-performance Rust implementation of JSONata query and transformation language"
@@ -63,6 +63,7 @@ simd = ["dep:simd-json"]
 python = ["dep:pyo3"]
 cli = ["dep:clap"]
 bench = []   # exposes _bench facade for Criterion benchmarks
+capi = []
 
 [dev-dependencies]
 criterion = "0.8"

{jsonatapy-2.2.4 → jsonatapy-2.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jsonatapy
-Version: 2.2.4
+Version: 2.2.6
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -47,19 +47,26 @@ Project-URL: Documentation, https://github.com/txjmb/jsonata-core
 Project-URL: Homepage, https://github.com/txjmb/jsonata-core
 Project-URL: Repository, https://github.com/txjmb/jsonata-core
 
-# jsonata-core + jsonatapy
+# jsonata-core (rust) + jsonatapy + jsonata C-ABI library + jsonata cli
+#### Pypi stats
+[![jsonatapy Downloads Last Month](https://assets.piptrends.com/get-last-month-downloads-badge/jsonatapy.svg 'jsonatapy Downloads Last Month by pip Trends')](https://piptrends.com/package/jsonatapy) [![jsonatapy Downloads Last Week](https://assets.piptrends.com/get-last-week-downloads-badge/jsonatapy.svg 'jsonatapy Downloads Last Week by pip Trends')](https://piptrends.com/package/jsonatapy) [![jsonatapy Average Daily Downloads](https://assets.piptrends.com/get-average-downloads-badge/jsonatapy.svg 'jsonatapy Average Daily Downloads by pip Trends')](https://piptrends.com/package/jsonatapy)
 
-High-performance [JSONata](https://jsonata.org/) implementation in Rust, with Python bindings.
+#### Crates.io stats
+![downloads](https://shieldcn.dev/crates/d/jsonata-core.svg)
+
+High-performance [JSONata](https://jsonata.org/) implementation in Rust, with Python binding and C ABI/library.  If you use this library, please add a github star!
 
 Much of this project was built using Claude Code with significant human oversight. There was no performant
 JSONata implementation in Python, so the goal was to port JSONata to Rust (with a PyO3 wrapper
 for Python) and see how fast it could go. The answer: faster than V8 for most expression
-workloads, and faster than the next pure-Rust implementation.  The rust versions are published on crates.io, and the python wheels on pypi.
+workloads, and faster than the next pure-Rust implementation.  The rust versions are published on crates.io, and the python wheels on pypi.  There is also a command-line binary and Python command-line available (works great with uvx) for use in scripting.  The Python library is also usable in a command-line fashion, and a C-compatible library is available for those who want to easily use jsonata in C/C++.
 
-Many, many thanks to the incredible work of all the maintainers of the [JSONata](https://github.com/jsonata-js/jsonata) reference library.  JSONata is a very powerful, well-designed, and useful language that has made an impact on many projects.  This project leverages their outstanding work to extend that capability to Python and Rust and would not be possible without that project.  The implementation in Rust was strongly influenced by their implementation.  The 1600+ tests they created provided the scaffolding and validation for all of this project.  This project will continue to follow and be a derivative of the reference project as the JSONata reference library evolves.
+Many, many thanks to the incredible work of all the maintainers of the [JSONata](https://github.com/jsonata-js/jsonata) reference library.  JSONata is a very powerful, well-designed, and useful language that has made an impact on many projects.  This project leverages their outstanding work to extend that capability to Python and Rust and would not be possible without that project.  The implementation in Rust was strongly influenced by their implementation.  The 1600+ (1682/1682 passing for last build of this project) tests they created provided the scaffolding and validation for all of this project.  This project will continue to follow and be a derivative of the reference project as the JSONata reference library evolves.
 
 Release versions will follow the reference jsonata-js project major and minor release numbers, but not necessarily patches.  This will make it easier for adopters of this library to understand each release's JSONata API compatibility.  As an example, 2.1.7 should be compliant with 2.1.x jsonata-js tests, but may have fixes specific to this library.  If a patch release for jsonata-js is relevant for this project, it will be included in a patch release that may or may not follow the patch numbers of the upstream project.
 
+This project currently chooses not to implement async, because it has limited value for most of the most common use-cases.  We 
+
 [![Crates.io](https://img.shields.io/crates/v/jsonata-core.svg)](https://crates.io/crates/jsonata-core)
 [![PyPI version](https://badge.fury.io/py/jsonatapy.svg)](https://pypi.org/project/jsonatapy/)
 [![Python versions](https://img.shields.io/pypi/pyversions/jsonatapy.svg)](https://pypi.org/project/jsonatapy/)
@@ -141,7 +148,7 @@ Supports Python 3.10, 3.11, 3.12, 3.13, 3.14 on Linux, macOS (Intel & ARM), and
 
 ## Command-line quick start
 
-Both packages also ship a CLI, `jq`-shaped, with an identical contract:
+Both packages also ship a binary CLI and a Python-based CLI, `jq`-shaped, with an identical contract:
 
 ```bash
 pip install jsonatapy
@@ -151,6 +158,24 @@ echo '{"orders":[{"product":"Laptop","price":1200}]}' | jsonatapy 'orders[price
 
 See [CLI Reference](docs/cli.md) for the full flag/exit-code contract.
 
+## C / C++ quick start
+
+The engine exposes a small C ABI (8 functions, JSON text in/out), usable
+from C, C++, or any language with C interop:
+
+```c
+JsonataExpr *expr = jsonata_compile("$sum(items.price)");
+char *result = jsonata_evaluate(expr, "{\"items\":[{\"price\":2},{\"price\":3}]}");
+// result: "5"
+jsonata_free_string(result);
+jsonata_free_expr(expr);
+```
+
+Build with `cargo build --release --features capi` and include
+[`bindings/c/jsonata.h`](bindings/c/jsonata.h). See the
+[C API guide](bindings/c/README.md) for linking (gcc/clang, Makefile,
+CMake), the memory/threading contract, and error handling.
+
 ---
 
 ## What is JSONata?

{jsonatapy-2.2.4 → jsonatapy-2.2.6}/README.md

@@ -1,16 +1,23 @@
-# jsonata-core + jsonatapy
+# jsonata-core (rust) + jsonatapy + jsonata C-ABI library + jsonata cli
+#### Pypi stats
+[![jsonatapy Downloads Last Month](https://assets.piptrends.com/get-last-month-downloads-badge/jsonatapy.svg 'jsonatapy Downloads Last Month by pip Trends')](https://piptrends.com/package/jsonatapy) [![jsonatapy Downloads Last Week](https://assets.piptrends.com/get-last-week-downloads-badge/jsonatapy.svg 'jsonatapy Downloads Last Week by pip Trends')](https://piptrends.com/package/jsonatapy) [![jsonatapy Average Daily Downloads](https://assets.piptrends.com/get-average-downloads-badge/jsonatapy.svg 'jsonatapy Average Daily Downloads by pip Trends')](https://piptrends.com/package/jsonatapy)
 
-High-performance [JSONata](https://jsonata.org/) implementation in Rust, with Python bindings.
+#### Crates.io stats
+![downloads](https://shieldcn.dev/crates/d/jsonata-core.svg)
+
+High-performance [JSONata](https://jsonata.org/) implementation in Rust, with Python binding and C ABI/library.  If you use this library, please add a github star!
 
 Much of this project was built using Claude Code with significant human oversight. There was no performant
 JSONata implementation in Python, so the goal was to port JSONata to Rust (with a PyO3 wrapper
 for Python) and see how fast it could go. The answer: faster than V8 for most expression
-workloads, and faster than the next pure-Rust implementation.  The rust versions are published on crates.io, and the python wheels on pypi.
+workloads, and faster than the next pure-Rust implementation.  The rust versions are published on crates.io, and the python wheels on pypi.  There is also a command-line binary and Python command-line available (works great with uvx) for use in scripting.  The Python library is also usable in a command-line fashion, and a C-compatible library is available for those who want to easily use jsonata in C/C++.
 
-Many, many thanks to the incredible work of all the maintainers of the [JSONata](https://github.com/jsonata-js/jsonata) reference library.  JSONata is a very powerful, well-designed, and useful language that has made an impact on many projects.  This project leverages their outstanding work to extend that capability to Python and Rust and would not be possible without that project.  The implementation in Rust was strongly influenced by their implementation.  The 1600+ tests they created provided the scaffolding and validation for all of this project.  This project will continue to follow and be a derivative of the reference project as the JSONata reference library evolves.
+Many, many thanks to the incredible work of all the maintainers of the [JSONata](https://github.com/jsonata-js/jsonata) reference library.  JSONata is a very powerful, well-designed, and useful language that has made an impact on many projects.  This project leverages their outstanding work to extend that capability to Python and Rust and would not be possible without that project.  The implementation in Rust was strongly influenced by their implementation.  The 1600+ (1682/1682 passing for last build of this project) tests they created provided the scaffolding and validation for all of this project.  This project will continue to follow and be a derivative of the reference project as the JSONata reference library evolves.
 
 Release versions will follow the reference jsonata-js project major and minor release numbers, but not necessarily patches.  This will make it easier for adopters of this library to understand each release's JSONata API compatibility.  As an example, 2.1.7 should be compliant with 2.1.x jsonata-js tests, but may have fixes specific to this library.  If a patch release for jsonata-js is relevant for this project, it will be included in a patch release that may or may not follow the patch numbers of the upstream project.
 
+This project currently chooses not to implement async, because it has limited value for most of the most common use-cases.  We 
+
 [![Crates.io](https://img.shields.io/crates/v/jsonata-core.svg)](https://crates.io/crates/jsonata-core)
 [![PyPI version](https://badge.fury.io/py/jsonatapy.svg)](https://pypi.org/project/jsonatapy/)
 [![Python versions](https://img.shields.io/pypi/pyversions/jsonatapy.svg)](https://pypi.org/project/jsonatapy/)
@@ -92,7 +99,7 @@ Supports Python 3.10, 3.11, 3.12, 3.13, 3.14 on Linux, macOS (Intel & ARM), and
 
 ## Command-line quick start
 
-Both packages also ship a CLI, `jq`-shaped, with an identical contract:
+Both packages also ship a binary CLI and a Python-based CLI, `jq`-shaped, with an identical contract:
 
 ```bash
 pip install jsonatapy
@@ -102,6 +109,24 @@ echo '{"orders":[{"product":"Laptop","price":1200}]}' | jsonatapy 'orders[price
 
 See [CLI Reference](docs/cli.md) for the full flag/exit-code contract.
 
+## C / C++ quick start
+
+The engine exposes a small C ABI (8 functions, JSON text in/out), usable
+from C, C++, or any language with C interop:
+
+```c
+JsonataExpr *expr = jsonata_compile("$sum(items.price)");
+char *result = jsonata_evaluate(expr, "{\"items\":[{\"price\":2},{\"price\":3}]}");
+// result: "5"
+jsonata_free_string(result);
+jsonata_free_expr(expr);
+```
+
+Build with `cargo build --release --features capi` and include
+[`bindings/c/jsonata.h`](bindings/c/jsonata.h). See the
+[C API guide](bindings/c/README.md) for linking (gcc/clang, Makefile,
+CMake), the memory/threading contract, and error handling.
+
 ---
 
 ## What is JSONata?

jsonatapy-2.2.6/bindings/c/README.md

@@ -0,0 +1,169 @@
+# jsonata-core C API
+
+Use [JSONata](https://jsonata.org) — the JSON query and transformation
+language — from C, C++, or any language with C interop, backed by
+[jsonata-core](https://github.com/txjmb/jsonata-core), a high-performance
+Rust implementation with 100% reference-suite compatibility against
+jsonata-js.
+
+The API is deliberately small: JSON text in, JSON text out, eight
+functions. See [`jsonata.h`](jsonata.h) for the authoritative contract.
+
+```c
+#include "jsonata.h"
+#include <stdio.h>
+
+int main(void) {
+    JsonataExpr *expr = jsonata_compile("$sum(order.items.(price * qty))");
+    if (!expr) {
+        char *err = jsonata_last_error_message();
+        fprintf(stderr, "compile failed: %s\n", err);
+        jsonata_free_string(err);
+        return 1;
+    }
+
+    char *result = jsonata_evaluate(expr,
+        "{\"order\":{\"items\":[{\"price\":9.99,\"qty\":2},{\"price\":5,\"qty\":1}]}}");
+    if (result) {
+        printf("total: %s\n", result);   /* total: 24.98 */
+        jsonata_free_string(result);
+    } else {
+        char *err = jsonata_last_error_message();
+        if (err) {                        /* error */
+            fprintf(stderr, "evaluate failed: %s\n", err);
+            jsonata_free_string(err);
+        } else {                          /* JSONata "undefined" — no match */
+            printf("no result\n");
+        }
+    }
+
+    jsonata_free_expr(expr);
+    return 0;
+}
+```
+
+## Building the shared library
+
+Requires a Rust toolchain (rustc 1.70+, [rustup.rs](https://rustup.rs)):
+
+```sh
+git clone https://github.com/txjmb/jsonata-core
+cd jsonata-core
+cargo build --release --features capi
+```
+
+This produces the shared library in `target/release/`:
+
+| Platform | Library |
+|---|---|
+| Linux | `libjsonata_core.so` |
+| macOS | `libjsonata_core.dylib` |
+| Windows | `jsonata_core.dll` (+ `jsonata_core.dll.lib` import lib) |
+
+The only header you need is `bindings/c/jsonata.h`.
+
+## Compiling and linking
+
+**C** (gcc/clang):
+
+```sh
+gcc -Wall -o myapp myapp.c -I/path/to/jsonata-core/bindings/c \
+    -L/path/to/jsonata-core/target/release -ljsonata_core
+LD_LIBRARY_PATH=/path/to/jsonata-core/target/release ./myapp
+```
+
+**C++**: the header is C++-safe (`extern "C"` guarded); compile and link
+exactly as above with `g++`/`clang++`.
+
+For deployment, install the library somewhere on the loader path (or set
+`rpath`): `-Wl,-rpath,/opt/myapp/lib` at link time avoids
+`LD_LIBRARY_PATH` at run time.
+
+**Makefile snippet:**
+
+```make
+JSONATA_DIR := /path/to/jsonata-core
+CFLAGS  += -I$(JSONATA_DIR)/bindings/c
+LDFLAGS += -L$(JSONATA_DIR)/target/release -Wl,-rpath,$(JSONATA_DIR)/target/release
+LDLIBS  += -ljsonata_core
+
+myapp: myapp.o
+	$(CC) $(LDFLAGS) -o $@ $^ $(LDLIBS)
+```
+
+**CMake snippet:**
+
+```cmake
+set(JSONATA_DIR /path/to/jsonata-core)
+
+add_library(jsonata_core SHARED IMPORTED)
+set_target_properties(jsonata_core PROPERTIES
+    IMPORTED_LOCATION ${JSONATA_DIR}/target/release/libjsonata_core.so
+    INTERFACE_INCLUDE_DIRECTORIES ${JSONATA_DIR}/bindings/c)
+
+target_link_libraries(myapp PRIVATE jsonata_core)
+```
+
+(Optionally wrap the `cargo build` in a CMake `add_custom_command` so the
+Rust library rebuilds with your project.)
+
+## API rules (the short version)
+
+1. **Ownership:** every `char*` the library returns is yours — free it with
+   `jsonata_free_string()`. The single exception is `jsonata_version()`
+   (static; never free). Never free library strings with your own
+   `free()` — allocators may differ.
+2. **NULL from `jsonata_evaluate` is ambiguous by design:** check
+   `jsonata_last_error_message()`. Non-NULL → error. NULL → the JSONata
+   result was *undefined* (a normal outcome — e.g. a path that matched
+   nothing). This mirrors JSONata semantics, where `undefined` and `null`
+   are distinct.
+3. **Error codes:** `jsonata_last_error_code()` returns the JSONata spec
+   code (`"T2002"`, `"S0201"`, `"D3030"`, …) when the failure has one,
+   NULL otherwise. Error source positions are not exposed (the engine
+   does not currently track them).
+4. **Threading:** one `JsonataExpr*` per thread — create, use, and free a
+   handle on the same thread. Handles are cheap; compile per thread rather
+   than sharing. Different threads with their own handles are fine, and
+   the error slot is thread-local.
+5. **Reuse handles:** `jsonata_compile` once, `jsonata_evaluate` many
+   times — the expression is JIT-compiled to bytecode on first evaluation
+   and reused. Compilation is the expensive step.
+6. **Variables:** `jsonata_bind_var(expr, "x", "[1,2,3]")` binds `$x` for
+   all subsequent evaluations on that handle (values are JSON text;
+   re-binding replaces).
+7. **Host functions:** `jsonata_register_fn(expr, "name", fn, user_data)`
+   exposes a C callback to the expression as `$name(...)`. The callback
+   receives its arguments as a JSON array string and returns a JSON result
+   string that jsonata copies (you keep ownership — do not expect jsonata to
+   free it); returning NULL signals an error. A name colliding with a
+   built-in is rejected; `jsonata_register_fn_override` replaces a built-in
+   deliberately (e.g. a frozen `$now`, or a disabled `$eval`). `user_data`
+   must outlive the handle. Registering a host function routes evaluation
+   through the tree-walker, like variable bindings.
+8. **Panics:** internal engine panics are caught at the boundary and
+   surface as errors prefixed `internal error:` — they will not abort
+   your process.
+
+## Smoke test
+
+[`examples/smoke.c`](examples/smoke.c) exercises the full API surface and
+doubles as usage documentation. Build and run it from the repo root:
+
+```sh
+cargo build --release --features capi
+gcc -Wall -Wextra -Werror -o smoke bindings/c/examples/smoke.c \
+    -Ltarget/release -ljsonata_core
+LD_LIBRARY_PATH=target/release ./smoke
+```
+
+CI compiles and runs it (as both C and C++) on every change to the C ABI.
+
+## Related
+
+- [jsonatapy](https://pypi.org/project/jsonatapy/) — the Python binding of
+  this engine (PyPI, zero runtime dependencies).
+- [`jsonata` CLI](../../docs/) — a jq-style command-line interface to the
+  same engine.
+- [jsonata-js](https://github.com/jsonata-js/jsonata) — the reference
+  implementation this engine tracks (1682/1682 reference tests passing).

jsonatapy-2.2.6/bindings/c/examples/smoke.c

@@ -0,0 +1,191 @@
+/*
+ * smoke.c — compile-and-run smoke test for the jsonata-core C ABI.
+ *
+ * Exercises every function in jsonata.h against the real library and exits
+ * non-zero on the first failure. CI builds and runs this on every PR that
+ * touches the C ABI; see bindings/c/README.md for the manual build/run
+ * commands.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "../jsonata.h"
+
+static int failures = 0;
+
+#define CHECK(cond, name)                                                    \
+    do {                                                                     \
+        if (cond) {                                                          \
+            printf("PASS  %s\n", name);                                      \
+        } else {                                                             \
+            printf("FAIL  %s (line %d)\n", name, __LINE__);                  \
+            failures++;                                                      \
+        }                                                                    \
+    } while (0)
+
+static char *take_error(void) { return jsonata_last_error_message(); }
+
+/*
+ * Host function: given the JSON array ["<name>"], returns "hello <name>".
+ * Uses a static buffer — valid until the next call, which is all jsonata needs
+ * (it copies the result before returning to the expression).
+ */
+static char host_buf[256];
+static const char *greet_cb(void *user_data, const char *args_json) {
+    (void)user_data;
+    const char *open = strchr(args_json, '"');
+    if (!open) return NULL;
+    const char *start = open + 1;
+    const char *end = strchr(start, '"');
+    if (!end) return NULL;
+    int len = (int)(end - start);
+    snprintf(host_buf, sizeof(host_buf), "\"hello %.*s\"", len, start);
+    return host_buf;
+}
+
+/* Host override for $now(): a frozen timestamp (static string, always valid). */
+static const char *frozen_now_cb(void *user_data, const char *args_json) {
+    (void)user_data;
+    (void)args_json;
+    return "\"2020-01-01T00:00:00.000Z\"";
+}
+
+int main(void) {
+    /* version */
+    const char *v = jsonata_version();
+    CHECK(v != NULL && strlen(v) > 0, "version non-empty");
+
+    /* simple path */
+    {
+        JsonataExpr *e = jsonata_compile("user.name");
+        CHECK(e != NULL, "compile simple path");
+        char *r = jsonata_evaluate(e, "{\"user\":{\"name\":\"Alice\"}}");
+        CHECK(r != NULL && strcmp(r, "\"Alice\"") == 0, "evaluate simple path");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* object construction + arithmetic */
+    {
+        JsonataExpr *e = jsonata_compile("{\"n\": a + b}");
+        char *r = jsonata_evaluate(e, "{\"a\":1,\"b\":2}");
+        CHECK(r != NULL && strcmp(r, "{\"n\":3}") == 0, "object result");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* undefined result: NULL with EMPTY error slot */
+    {
+        JsonataExpr *e = jsonata_compile("missing.path");
+        char *r = jsonata_evaluate(e, "{\"a\":1}");
+        char *err = take_error();
+        CHECK(r == NULL && err == NULL, "undefined -> NULL + empty error");
+        jsonata_free_string(err);
+        jsonata_free_expr(e);
+    }
+
+    /* parse error: NULL handle + message */
+    {
+        JsonataExpr *e = jsonata_compile("a.b[");
+        char *err = take_error();
+        CHECK(e == NULL && err != NULL && strlen(err) > 0,
+              "parse error -> NULL + message");
+        jsonata_free_string(err);
+    }
+
+    /* coded evaluation error: message + spec code */
+    {
+        JsonataExpr *e = jsonata_compile("$number(b)");
+        char *r = jsonata_evaluate(e, "{\"b\":[1]}");
+        char *err = take_error();
+        char *code = jsonata_last_error_code();
+        CHECK(r == NULL && err != NULL, "eval error -> NULL + message");
+        CHECK(code != NULL && strcmp(code, "D3030") == 0,
+              "eval error -> spec code D3030");
+        jsonata_free_string(err);
+        jsonata_free_string(code);
+        jsonata_free_expr(e);
+    }
+
+    /* variable binding */
+    {
+        JsonataExpr *e = jsonata_compile("$sum($xs) + n");
+        int rc = jsonata_bind_var(e, "$xs", "[1,2,3]");
+        CHECK(rc == 0, "bind_var succeeds");
+        char *r = jsonata_evaluate(e, "{\"n\":10}");
+        CHECK(r != NULL && strcmp(r, "16") == 0, "evaluate with bound var");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* invalid input JSON: NULL + uncoded message */
+    {
+        JsonataExpr *e = jsonata_compile("a");
+        char *r = jsonata_evaluate(e, "{not json");
+        char *err = take_error();
+        char *code = jsonata_last_error_code();
+        CHECK(r == NULL && err != NULL && strstr(err, "invalid input JSON") != NULL,
+              "invalid input JSON -> message");
+        CHECK(code == NULL, "invalid input JSON -> no spec code");
+        jsonata_free_string(err);
+        jsonata_free_string(code);
+        jsonata_free_expr(e);
+    }
+
+    /* multibyte UTF-8 round trip */
+    {
+        JsonataExpr *e = jsonata_compile("$uppercase(name)");
+        char *r = jsonata_evaluate(e, "{\"name\":\"h\xC3\xA9llo \xE2\x9C\x93\"}");
+        CHECK(r != NULL && strcmp(r, "\"H\xC3\x89LLO \xE2\x9C\x93\"") == 0,
+              "multibyte UTF-8 round trip");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* host function registration + call */
+    {
+        JsonataExpr *e = jsonata_compile("$greet(name)");
+        int rc = jsonata_register_fn(e, "greet", greet_cb, NULL);
+        CHECK(rc == 0, "register_fn succeeds");
+        char *r = jsonata_evaluate(e, "{\"name\":\"Ada\"}");
+        CHECK(r != NULL && strcmp(r, "\"hello Ada\"") == 0, "host function call");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* host function override of an impure built-in ($now) */
+    {
+        JsonataExpr *e = jsonata_compile("$now()");
+        int rc = jsonata_register_fn_override(e, "now", frozen_now_cb, NULL);
+        CHECK(rc == 0, "register_fn_override succeeds");
+        char *r = jsonata_evaluate(e, "null");
+        CHECK(r != NULL && strcmp(r, "\"2020-01-01T00:00:00.000Z\"") == 0,
+              "override $now");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* collision with a built-in is rejected */
+    {
+        JsonataExpr *e = jsonata_compile("$sum(x)");
+        int rc = jsonata_register_fn(e, "sum", greet_cb, NULL);
+        char *err = take_error();
+        CHECK(rc == -1 && err != NULL, "register_fn collision rejected");
+        jsonata_free_string(err);
+        jsonata_free_expr(e);
+    }
+
+    /* NULL tolerance of free functions */
+    jsonata_free_expr(NULL);
+    jsonata_free_string(NULL);
+    CHECK(1, "free(NULL) is a no-op");
+
+    if (failures == 0) {
+        printf("SMOKE OK (jsonata-core %s)\n", v);
+        return 0;
+    }
+    printf("SMOKE FAILED: %d failure(s)\n", failures);
+    return 1;
+}