jsonatapy 2.2.12__tar.gz → 2.2.13__tar.gz

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/CHANGELOG.md

@@ -19,6 +19,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+## [2.2.13] - 2026-10-24
+
+**Upgrade notes**
+
+- **Breaking for Rust code that builds `EvaluatorOptions` field by field.** `EvaluatorOptions`
+  has a new public `cancel` field (see Added), so a struct literal that lists every field
+  without `..Default::default()` no longer compiles. Add `cancel: None`, or end the literal with
+  `..Default::default()`. Strict semver would call this a major change. It ships in a patch
+  release because jsonata-core's version tracks the jsonata-js version it targets (2.2), and
+  code that uses `..Default::default()` is unaffected. The Python and C APIs are unchanged.
+- **`jsonatapy[mcp]` now needs fastmcp 4.1.2 or later**, which brings `mcp` 2.x (see Changed).
+
+### Added
+
+- **An evaluation can be cancelled from another thread.** `EvaluatorOptions` has a new
+  `cancel` field that takes a `CancelToken`. Calling `cancel()` on any clone of the token
+  stops the evaluation with `U1003: Evaluation cancelled` wherever `timeout_ms` is checked:
+  each node evaluated, each element a higher-order builtin hands its callback, each match
+  `$replace` hands its replacement function, and each pass of a tail-call loop. A single
+  builtin call over a large input finishes first, as it does under `timeout_ms`, and if it is
+  the last step the evaluation returns its result. jsonata-js has no cancellation, so the
+  code is in the `U` series. This is a Rust API only. See the upgrade notes above for the
+  `EvaluatorOptions` source break. (#264) Thanks to @jonking-ajar for the design, the
+  implementation and its tests.
+
+### Changed
+
+- **The `mcp` extra now needs fastmcp 4.1.2 or later** (was 3.0). fastmcp 4 brings `mcp` 2.x
+  and replaces `httpx` with `httpx2`, so an environment that pins `mcp<2` or depends on
+  `httpx` alongside `jsonatapy[mcp]` may need updating. The `jsonatapy mcp` server itself is
+  unchanged. 4.1.2 is also the first 4.x release with the fix for GHSA-7xgj-8392-5q4r.
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+- **`timeout_ms` now stops `$map`, `$filter`, `$reduce`, `$single`, `$sift`, `$each` and
+  `$sort` when their callback is a builtin, host or partial function, and `$replace` when its
+  replacement function is one.** Their loops over such a function had no checkpoint, because
+  the call evaluates no node, so `$map(items, $string)` over a large array ran to the end past
+  its timeout. A lambda callback was already stopped, since its body is checked like any node.
+  An expression with `timeout_ms` set that used to finish late in one of these loops and
+  return a result now fails with D1012 instead. (#264) Thanks to @jonking-ajar, who found and
+  fixed this alongside the cancellation work.
+
+### Security
+
 ## [2.2.12] "Gymkata" - 2026-10-20
 
 ### Added

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/Cargo.lock

@@ -620,7 +620,7 @@ dependencies = [
 
 [[package]]
 name = "jsonata-core"
-version = "2.2.12"
+version = "2.2.13"
 dependencies = [
  "assert_cmd",
  "base64",

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jsonata-core"
-version = "2.2.12"
+version = "2.2.13"
 edition = "2021"
 authors = ["txjmb <txjmb@users.noreply.github.com>"]
 description = "High-performance Rust implementation of JSONata query and transformation language"

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jsonatapy
-Version: 2.2.12
+Version: 2.2.13
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -24,12 +24,12 @@ Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
 Requires-Dist: ruff>=0.3.0 ; extra == 'dev'
 Requires-Dist: mypy>=1.0 ; extra == 'dev'
 Requires-Dist: maturin>=1.0 ; extra == 'dev'
-Requires-Dist: fastmcp>=3.0 ; extra == 'dev'
+Requires-Dist: fastmcp>=4.1.2 ; extra == 'dev'
 Requires-Dist: mkdocs>=1.5 ; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.0 ; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.24 ; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.0 ; extra == 'docs'
-Requires-Dist: fastmcp>=3.0 ; extra == 'mcp'
+Requires-Dist: fastmcp>=4.1.2 ; extra == 'mcp'
 Provides-Extra: bench
 Provides-Extra: dev
 Provides-Extra: docs
@@ -75,13 +75,13 @@ Project-URL: Repository, https://github.com/txjmb/jsonata-core
     <source media="(prefers-color-scheme: dark)"
             srcset="https://raw.githubusercontent.com/txjmb/jsonata-core/main/docs/assets/realistic-workload-dark.svg">
     <img width="880"
-         alt="Realistic-workload benchmark on a 100-product dataset, lower is better: jsonatapy is 8.7x faster than the jsonata-js reference on the geometric mean of 5 e-commerce queries, and the pure-Rust jsonata-core engine is faster still."
+         alt="Realistic-workload benchmark on a 100-product dataset, lower is better: jsonatapy is 8.1x faster than the jsonata-js reference on the geometric mean of 5 e-commerce queries, and the pure-Rust jsonata-core engine is faster still."
          src="https://raw.githubusercontent.com/txjmb/jsonata-core/main/docs/assets/realistic-workload-light.svg">
   </picture>
 </a>
 
 *Click the chart for the full category-by-category tables, including jsonata-python
-and jsonata-rs, which are left off the chart because at 68 ms–9 s they would
+and jsonata-rs, which are left off the chart because at 67 ms–9 s they would
 flatten everything else into a sliver.*
 <!-- END generated performance chart -->
 
@@ -156,10 +156,10 @@ let result = Evaluator::new().evaluate(&ast, &data)?;
 ```toml
 # Cargo.toml
 [dependencies]
-jsonata-core = "2.2.12"          # pure Rust, no Python dependency
+jsonata-core = "2.2.13"          # pure Rust, no Python dependency
 
 # Optional: disable SIMD for constrained targets
-jsonata-core = { version = "2.2.12", default-features = false }
+jsonata-core = { version = "2.2.13", default-features = false }
 ```
 
 ---

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/README.md

@@ -26,13 +26,13 @@
     <source media="(prefers-color-scheme: dark)"
             srcset="https://raw.githubusercontent.com/txjmb/jsonata-core/main/docs/assets/realistic-workload-dark.svg">
     <img width="880"
-         alt="Realistic-workload benchmark on a 100-product dataset, lower is better: jsonatapy is 8.7x faster than the jsonata-js reference on the geometric mean of 5 e-commerce queries, and the pure-Rust jsonata-core engine is faster still."
+         alt="Realistic-workload benchmark on a 100-product dataset, lower is better: jsonatapy is 8.1x faster than the jsonata-js reference on the geometric mean of 5 e-commerce queries, and the pure-Rust jsonata-core engine is faster still."
          src="https://raw.githubusercontent.com/txjmb/jsonata-core/main/docs/assets/realistic-workload-light.svg">
   </picture>
 </a>
 
 *Click the chart for the full category-by-category tables, including jsonata-python
-and jsonata-rs, which are left off the chart because at 68 ms–9 s they would
+and jsonata-rs, which are left off the chart because at 67 ms–9 s they would
 flatten everything else into a sliver.*
 <!-- END generated performance chart -->
 
@@ -107,10 +107,10 @@ let result = Evaluator::new().evaluate(&ast, &data)?;
 ```toml
 # Cargo.toml
 [dependencies]
-jsonata-core = "2.2.12"          # pure Rust, no Python dependency
+jsonata-core = "2.2.13"          # pure Rust, no Python dependency
 
 # Optional: disable SIMD for constrained targets
-jsonata-core = { version = "2.2.12", default-features = false }
+jsonata-core = { version = "2.2.13", default-features = false }
 ```
 
 ---

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "jsonatapy"
-version = "2.2.12"
+version = "2.2.13"
 description = "High-performance Python/Rust implementation of JSONata query and transformation language"
 authors = [
     {name = "txjmb", email = "txjmb@users.noreply.github.com"}
@@ -42,10 +42,10 @@ dev = [
     "ruff>=0.3.0",        # Linting and formatting
     "mypy>=1.0",
     "maturin>=1.0",
-    "fastmcp>=3.0",       # So `dev` installs can run the full test suite (Task 9)
+    "fastmcp>=4.1.2",     # So `dev` installs can run the full test suite (Task 9)
 ]
 mcp = [
-    "fastmcp>=3.0",
+    "fastmcp>=4.1.2",
 ]
 bench = [
     "jsonata>=0.2.0",     # jsonata-python for benchmarking
@@ -82,7 +82,7 @@ dev = [
     "ruff>=0.3.0",
     "mypy>=1.0",
     "maturin>=1.0",
-    "fastmcp>=3.0",
+    "fastmcp>=4.1.2",
 ]
 
 [tool.ruff]

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/src/capi.rs

@@ -491,6 +491,7 @@ pub unsafe extern "C" fn jsonata_set_limits(
         timeout_ms: (timeout_ms > 0).then_some(timeout_ms),
         max_stack_depth: (max_stack_depth > 0).then_some(max_stack_depth as usize),
         max_sequence_length: (max_sequence_length > 0).then_some(max_sequence_length as usize),
+        cancel: None,
     };
     clear_error();
     0

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/src/evaluator.rs

@@ -3691,12 +3691,76 @@ impl TupleKeyBindings {
     }
 }
 
+/// A handle that stops an evaluation from another thread.
+///
+/// Clones share one flag. Put a clone in [`EvaluatorOptions::cancel`] and call
+/// [`CancelToken::cancel`] on another, and the evaluation raises U1003 at its
+/// next checkpoint: each node it evaluates, each element a higher-order
+/// builtin (`$map`, `$filter`, `$reduce`, `$single`, `$sift`, `$each`,
+/// `$sort`) hands its callback, each match `$replace` hands its replacement
+/// function, and each pass of a tail-call loop. These are the places
+/// `timeout_ms` is checked.
+///
+/// A single builtin call over a large input, such as `$string` of a long
+/// array, finishes before the flag is seen. If that call is the last step,
+/// the evaluation returns its result even though the token was cancelled, so
+/// check [`CancelToken::is_cancelled`] after it returns when that matters.
+///
+/// An [`Evaluator`] keeps its options, so one built with a cancelled token
+/// fails every later evaluation. Pass a fresh token with each call, as below,
+/// or build a new `Evaluator`.
+///
+/// ```
+/// use jsonata_core::evaluator::{CancelToken, EvaluatorOptions};
+/// use jsonata_core::value::JValue;
+/// use jsonata_core::Expression;
+///
+/// let expr = Expression::compile("($inf := function(){ $inf() }; $inf())")?;
+///
+/// let token = CancelToken::new();
+/// let canceller = token.clone();
+/// std::thread::spawn(move || {
+///     std::thread::sleep(std::time::Duration::from_millis(10));
+///     canceller.cancel();
+/// });
+/// let options = EvaluatorOptions {
+///     cancel: Some(token),
+///     ..Default::default()
+/// };
+/// let err = expr.evaluate_with_options(&JValue::Null, options).unwrap_err();
+/// assert!(err.to_string().contains("U1003"));
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+#[derive(Clone, Debug, Default)]
+pub struct CancelToken(std::sync::Arc<std::sync::atomic::AtomicBool>);
+
+impl CancelToken {
+    /// A token that has not been cancelled.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Stop every evaluation that holds a clone of this token. It cannot be
+    /// reset.
+    pub fn cancel(&self) {
+        self.0.store(true, std::sync::atomic::Ordering::Relaxed);
+    }
+
+    /// Whether [`CancelToken::cancel`] has been called on any clone.
+    pub fn is_cancelled(&self) -> bool {
+        self.0.load(std::sync::atomic::Ordering::Relaxed)
+    }
+}
+
 /// Resource-limit guardrails, mirroring jsonata-js 2.2.1's `timeout`/`stack`/`sequence`
 /// evaluator options. All fields default to `None` = unlimited (current behavior).
 #[derive(Default, Clone, Debug)]
 pub struct EvaluatorOptions {
     /// Maximum wall-clock evaluation time in milliseconds. Exceeding it raises D1012.
     pub timeout_ms: Option<u64>,
+    /// Stops the evaluation with U1003 once the token is cancelled, from any
+    /// thread. jsonata-js has no equivalent; see [`CancelToken`].
+    pub cancel: Option<CancelToken>,
     /// Maximum evaluation stack depth, like jsonata-js's `stack` option. Exceeding
     /// it raises D1011. Without it, evaluation may nest up to the built-in
     /// `MAX_EVAL_DEPTH` (30,000 levels, about 10,000 non-tail recursive calls),
@@ -4262,14 +4326,29 @@ pub(crate) fn check_sequence_length(
     Ok(())
 }
 
-/// Per-iteration D1012 check for loop-based compiled/VM constructs (map/filter/
-/// reduce element loops, FilterByBytecode) that don't pass through
-/// `evaluate_internal`'s per-node checkpoint and would otherwise run untimed.
+/// U1003 once the caller has cancelled the evaluation. jsonata-js has no
+/// cancellation and so no code for it; like U1001 and U1002 this one is ours.
+#[inline(always)]
+pub(crate) fn check_cancelled(options: &EvaluatorOptions) -> Result<(), EvaluatorError> {
+    match &options.cancel {
+        Some(token) if token.is_cancelled() => Err(EvaluatorError::EvaluationError(
+            "U1003: Evaluation cancelled".to_string(),
+        )),
+        _ => Ok(()),
+    }
+}
+
+/// Per-iteration D1012 and U1003 check for loops that don't pass through
+/// `evaluate_internal`'s per-node checkpoint and would otherwise run untimed:
+/// compiled map/filter/reduce element loops, FilterByBytecode, the tail-call
+/// trampoline, and the higher-order builtins' loops over a builtin, host or
+/// partial callback, whose call evaluates no node.
 #[inline]
 pub(crate) fn check_loop_timeout(
     options: &EvaluatorOptions,
     start_time: Option<Instant>,
 ) -> Result<(), EvaluatorError> {
+    check_cancelled(options)?;
     if let Some(timeout_ms) = options.timeout_ms {
         if let Some(start) = start_time {
             if start.elapsed().as_millis() as u64 > timeout_ms {
@@ -4915,6 +4994,7 @@ impl Evaluator {
             } else {
                 // Unexpected param count - fall back to generic path
                 while i < left.len() && j < right.len() {
+                    check_loop_timeout(&self.options, self.start_time)?;
                     let cmp_result = self.apply_function(
                         comparator,
                         &[left[i].clone(), right[j].clone()],
@@ -4932,6 +5012,7 @@ impl Evaluator {
         } else {
             // Non-lambda comparator: use generic apply_function path
             while i < left.len() && j < right.len() {
+                check_loop_timeout(&self.options, self.start_time)?;
                 let cmp_result =
                     self.apply_function(comparator, &[left[i].clone(), right[j].clone()], data)?;
                 if js_truthy(&cmp_result) {
@@ -5111,9 +5192,9 @@ impl Evaluator {
         self.with_checkpoint(|ev| ev.evaluate_internal_impl(node, data))
     }
 
-    /// Run one level of evaluation under the recursion-depth, timeout and
-    /// native-stack checks every node evaluation makes. Inlined so the hot
-    /// node-evaluation path pays no extra call frame for it. The trampoline's
+    /// Run one level of evaluation under the recursion-depth, cancellation,
+    /// timeout and native-stack checks every node evaluation makes. Inlined so
+    /// the hot node-evaluation path pays no extra call frame for it. The trampoline's
     /// own recursion paths that bypass `evaluate_internal` (a tail call of a
     /// higher-order builtin or of a composition) run under it too, so no
     /// recursion cycle grows the native stack unchecked (#191).
@@ -5152,6 +5233,11 @@ impl Evaluator {
             ));
         }
 
+        if let Err(e) = check_cancelled(&self.options) {
+            self.recursion_depth -= 1;
+            return Err(e);
+        }
+
         // Check evaluation timeout (D1012). `start_time` is only set (in
         // `evaluate()`) when `options.timeout_ms` is configured, so this is a
         // single `is_none()` branch of overhead when no timeout is set.
@@ -8347,6 +8433,7 @@ impl Evaluator {
                         let call_args =
                             hof_object_call_args(value, key, obj_value.as_ref(), param_count);
 
+                        check_loop_timeout(&evaluator.options, evaluator.start_time)?;
                         let pred_result =
                             evaluator.apply_function(func_node, &call_args, context_data)?;
                         if evaluator.is_truthy(&pred_result) {
@@ -8549,6 +8636,7 @@ impl Evaluator {
                             let call_args =
                                 hof_array_call_args(item, index, arr_value.as_ref(), param_count);
 
+                            check_loop_timeout(&self.options, self.start_time)?;
                             let mapped = self.apply_function(&args[1], &call_args, data)?;
                             // Filter out undefined results but keep explicit null (JSONata map semantics)
                             // undefined comes from missing else clause, null is explicit
@@ -8686,6 +8774,7 @@ impl Evaluator {
                     let call_args =
                         hof_array_call_args(item, index, arr_value.as_ref(), param_count);
 
+                    check_loop_timeout(&self.options, self.start_time)?;
                     let predicate_result = self.apply_function(&args[1], &call_args, data)?;
                     if self.is_truthy(&predicate_result) {
                         result.push(item.clone());
@@ -8848,6 +8937,7 @@ impl Evaluator {
                         ],
                     };
 
+                    check_loop_timeout(&self.options, self.start_time)?;
                     accumulator = self.apply_function(&args[1], &call_args, data)?;
                 }
 
@@ -8908,6 +8998,7 @@ impl Evaluator {
                         // hofFuncArgs shaping (see hof_array_call_args)
                         let call_args =
                             hof_array_call_args(item, index, arr_value.as_ref(), param_count);
+                        check_loop_timeout(&self.options, self.start_time)?;
                         let predicate_result = self.apply_function(&args[1], &call_args, data)?;
                         if self.is_truthy(&predicate_result) {
                             matches.push(item.clone());
@@ -8960,6 +9051,7 @@ impl Evaluator {
                             let call_args =
                                 hof_object_call_args(value, key, obj_whole.as_ref(), param_count);
 
+                            check_loop_timeout(&self.options, self.start_time)?;
                             let fn_result = self.apply_function(func_arg, &call_args, data)?;
                             // Skip undefined results only. jsonata-js guards
                             // this push with `typeof val !== 'undefined'`, so an
@@ -10223,6 +10315,7 @@ impl Evaluator {
                 group,
             );
         }
+        check_loop_timeout(&self.options, self.start_time)?;
         match self.as_callback(|ev| ev.call_function_value(replacement, &[match_object()], data))? {
             JValue::String(replaced) => {
                 out.push_str(&replaced);

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/src/lib.rs

@@ -343,6 +343,7 @@ impl JsonataExpression {
             timeout_ms: timeout.or(self.default_options.timeout_ms),
             max_stack_depth: max_stack_depth.or(self.default_options.max_stack_depth),
             max_sequence_length: max_sequence_length.or(self.default_options.max_sequence_length),
+            cancel: self.default_options.cancel.clone(),
         }
     }
 
@@ -792,6 +793,7 @@ fn build_evaluator_options(
         timeout_ms: timeout,
         max_stack_depth,
         max_sequence_length,
+        cancel: None,
     }
 }
 

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/src/vm.rs

@@ -199,6 +199,7 @@ impl<'prog> Vm<'prog> {
         data: &JValue,
         vars: Option<&HashMap<&str, &JValue>>,
     ) -> Result<JValue, EvaluatorError> {
+        crate::evaluator::check_cancelled(&self.options)?;
         let data = &data.clone().into_outer_wrapper();
         let start_time = if self.options.timeout_ms.is_some() {
             Some(std::time::Instant::now())
@@ -830,4 +831,23 @@ mod tests {
             .expect_err("expected D1012");
         assert!(err.to_string().contains("D1012"), "got: {err}");
     }
+
+    #[test]
+    fn test_filter_by_bytecode_raises_u1003_when_cancelled() {
+        let data: JValue = serde_json::json!({
+            "items": (0..1000).collect::<Vec<i32>>()
+        })
+        .into();
+        let prog = compile_and_assert_uses_filter_by_bytecode("items[$ >= 0]");
+        let token = crate::evaluator::CancelToken::new();
+        token.cancel();
+        let options = EvaluatorOptions {
+            cancel: Some(token),
+            ..Default::default()
+        };
+        let err = Vm::with_options(&prog, options)
+            .run(&data, None)
+            .expect_err("expected U1003");
+        assert!(err.to_string().contains("U1003"), "got: {err}");
+    }
 }

{jsonatapy-2.2.12 → jsonatapy-2.2.13}/tests/integration_test.rs

@@ -4,7 +4,7 @@
 // to process complete JSONata expressions.
 
 use jsonata_core::{
-    evaluator::{Context, Evaluator, EvaluatorOptions},
+    evaluator::{CancelToken, Context, Evaluator, EvaluatorOptions},
     parser::parse,
     value::JValue,
 };
@@ -1022,6 +1022,161 @@ fn test_no_timeout_configured_never_raises_d1012() {
     assert!(result.is_ok(), "expected Ok, got: {result:?}");
 }
 
+/// Options carrying `token`, with a 10 s timeout so a cancel that is never
+/// seen fails with D1012 instead of hanging the test run.
+fn cancellable(token: &CancelToken) -> EvaluatorOptions {
+    EvaluatorOptions {
+        cancel: Some(token.clone()),
+        timeout_ms: Some(10_000),
+        ..Default::default()
+    }
+}
+
+/// Evaluates `expr_str` with a host function `$tick` that cancels the
+/// evaluation on its `cancel_on`th call. It returns `"x"`, since a string suits
+/// every callback slot and a `$replace` replacement must return one. Returns
+/// the error and how many times `$tick` ran.
+fn evaluate_cancelled_on_call(
+    expr_str: &str,
+    cancel_on: usize,
+) -> (jsonata_core::evaluator::EvaluatorError, usize) {
+    let ast = parse(expr_str).unwrap();
+    let token = CancelToken::new();
+    let calls = std::rc::Rc::new(std::cell::Cell::new(0));
+    let mut evaluator = Evaluator::with_options(Context::new(), cancellable(&token));
+    let (tick_token, tick_calls) = (token.clone(), calls.clone());
+    evaluator
+        .register_fn("tick", move |_args: &[JValue]| {
+            tick_calls.set(tick_calls.get() + 1);
+            if tick_calls.get() == cancel_on {
+                tick_token.cancel();
+            }
+            Ok(JValue::string("x"))
+        })
+        .unwrap();
+    let err = evaluator
+        .evaluate(&ast, &JValue::Null)
+        .expect_err("expected a U1003 cancellation");
+    (err, calls.get())
+}
+
+/// A token cancelled before evaluation starts stops it at the first node.
+#[test]
+fn test_cancel_before_evaluation_raises_u1003() {
+    let ast = parse("$sum([1..10])").unwrap();
+    let token = CancelToken::new();
+    token.cancel();
+    let err = Evaluator::with_options(Context::new(), cancellable(&token))
+        .evaluate(&ast, &JValue::Null)
+        .expect_err("expected U1003");
+    assert!(
+        err.to_string().contains("U1003"),
+        "expected U1003, got: {err}"
+    );
+}
+
+/// A token cancelled before the run stops a compiled `Expression` too, whose
+/// simple expressions run on the bytecode VM rather than the tree-walker.
+#[test]
+fn test_cancel_before_evaluation_raises_u1003_on_compiled_expression() {
+    let token = CancelToken::new();
+    token.cancel();
+    let data = JValue::from(json!({"a": 1}));
+    for expr_str in ["a + 1", "a", "$sum([a, 2])"] {
+        let expr =
+            jsonata_core::Expression::compile_with_options(expr_str, cancellable(&token)).unwrap();
+        let err = expr.evaluate(&data).expect_err("expected U1003");
+        assert!(
+            err.to_string().contains("U1003"),
+            "{expr_str}: expected U1003, got: {err}"
+        );
+    }
+}
+
+/// A runaway tail-recursive loop, which has no iteration cap, stops once
+/// another thread cancels it. The trampoline checks on every pass.
+#[test]
+fn test_cancel_from_another_thread_stops_tail_recursion() {
+    let ast = parse("($inf := function(){$inf()}; $inf())").unwrap();
+    let token = CancelToken::new();
+    let canceller = token.clone();
+    let cancel_thread = std::thread::spawn(move || {
+        std::thread::sleep(std::time::Duration::from_millis(20));
+        canceller.cancel();
+    });
+    let err = Evaluator::with_options(Context::new(), cancellable(&token))
+        .evaluate(&ast, &JValue::Null)
+        .expect_err("expected U1003");
+    cancel_thread.join().unwrap();
+    assert!(
+        err.to_string().contains("U1003"),
+        "expected U1003, got: {err}"
+    );
+}
+
+/// A cancel stops a higher-order builtin between elements, whether its
+/// callback is a lambda, whose body is checked like any node, or a host
+/// function, whose call evaluates no node and is checked by the loop.
+#[test]
+fn test_cancel_stops_higher_order_builtins_between_elements() {
+    let cases = [
+        "$map([1..2000], function($x){ $tick($x) })",
+        "$map([1..2000], $tick)",
+        "$filter([1..2000], $tick)",
+        "$reduce([1..2000], $tick)",
+        "$single([1..2000], $tick)",
+        "$sift($merge([1..2000].{$string($): $}), $tick)",
+        "$each($merge([1..2000].{$string($): $}), $tick)",
+        "$sort([1..2000], $tick)",
+        "$replace($pad('', 2000, 'a'), /a/, $tick)",
+    ];
+    for expr_str in cases {
+        let (err, calls) = evaluate_cancelled_on_call(expr_str, 100);
+        assert!(
+            err.to_string().contains("U1003"),
+            "{expr_str}: expected U1003, got: {err}"
+        );
+        assert_eq!(calls, 100, "{expr_str}: $tick ran {calls} times");
+    }
+}
+
+/// `timeout_ms` stops `$map` over a host callback too. The loop had no
+/// check, so a slow callback ran past the deadline to the end of the array.
+#[test]
+fn test_timeout_stops_map_over_a_host_callback() {
+    let ast = parse("$map([1..1000], $slow)").unwrap();
+    let options = EvaluatorOptions {
+        timeout_ms: Some(50),
+        ..Default::default()
+    };
+    let mut evaluator = Evaluator::with_options(Context::new(), options);
+    evaluator
+        .register_fn("slow", |args: &[JValue]| {
+            std::thread::sleep(std::time::Duration::from_millis(1));
+            Ok(args.first().cloned().unwrap_or(JValue::Null))
+        })
+        .unwrap();
+    let err = evaluator
+        .evaluate(&ast, &JValue::Null)
+        .expect_err("expected D1012");
+    assert!(
+        err.to_string().contains("D1012"),
+        "expected D1012, got: {err}"
+    );
+}
+
+/// A token that is never cancelled changes no result.
+#[test]
+fn test_uncancelled_token_changes_nothing() {
+    let ast = parse("$map([1..1000], function($x){$x*2})").unwrap();
+    let token = CancelToken::new();
+    let with_token = Evaluator::with_options(Context::new(), cancellable(&token))
+        .evaluate(&ast, &JValue::Null)
+        .unwrap();
+    let without = Evaluator::new().evaluate(&ast, &JValue::Null).unwrap();
+    assert_eq!(with_token, without);
+}
+
 /// jsonata-js's own canonical guardrails-documentation example: an infinite
 /// tail-recursive call. `invoke_lambda_with_tco`'s trampoline loop previously
 /// had no timeout check at all -- only a hardcoded 100,000-iteration cap,