hardbyte · hardbyte · May 12, 2026 · May 12, 2026 · May 12, 2026 · May 12, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Updated
+
+- Updated cel-rust from 0.12.0 to 0.13.0.
+
+### Added
+
+- `Context.set_variable_resolver(callback)` exposes cel 0.13's `VariableResolver` trait to Python. The callback receives a variable name and returns the value (or `None` to fall through to variables registered with `add_variable`). Useful for backing a CEL context with on-demand sources (database lookups, lazily-loaded config files, etc.) without materializing the full set of variables upfront. Exceptions raised by the resolver are logged and treated as "not handled".
+- Idiomatic Python exception mapping for several CEL runtime errors that previously fell through to `ValueError`:
+  - Arithmetic overflow → `OverflowError` (e.g. `9223372036854775807 + 1`, including the new overflow-safe int math in cel 0.13).
+  - Division by zero / modulo by zero → `ZeroDivisionError`.
+  - List index out of bounds → `IndexError`.
+  - Missing map key (e.g. `{"a": 1}.b`) → `KeyError`.
+
+### Changed
+
+- **Behaviour change** (cel 0.13): bytes concatenation with `+` now works per the CEL spec (`b'hello' + b'world'` returns `b'helloworld'`). Previously raised `TypeError`.
+- **Behaviour change** (cel 0.13): logical `&&` and `||` are now "err-resilient" per CEL spec — `X && false` short-circuits to `false` and `X || true` short-circuits to `true` even when `X` is not a boolean. Conversely, `false || X` and `true && X` now raise `TypeError` when `X` is not boolean (previously `false || X` returned `X`).
+- **Error mapping**: more operations now route through CEL's `NoSuchOverload` (e.g. `1 + 2u`, `1 * 2u`, indexing into a string). These map to `TypeError` with a generic message listing common causes and conversion functions (`int(x)`, `uint(x)`, `double(x)`). The previous type-specific messages (e.g. "Cannot mix signed and unsigned integers") are still produced for the operand orderings cel-rust dispatches via `UnsupportedBinaryOperator`. Tests asserting on specific message text may need updating.
+- **Behaviour change** (cel 0.13): no implicit type coercion on map index access; indexing into a string now raises `TypeError` (`NoSuchOverload`) per CEL spec.
+- **Behaviour change** (cel 0.13): integer arithmetic overflow now raises `OverflowError` instead of silently wrapping. Affects `+`, `-`, `*` on both `int` and `uint` at the type's bounds.
+
+### Performance
+
+- Microbenchmarks comparing cel 0.13 vs 0.12 (release build, taking the min of 3 runs per scenario):
+
+  | Scenario              | compile  | compiled execute | evaluate |
+  |-----------------------|---------:|-----------------:|---------:|
+  | `x + y * 2`           |   +2.8%  |          +8.4%   |   +3.3%  |
+  | `greet + ' ' + name`  |  +23.0%  |          +4.3%   |   +0.5%  |
+  | `size(items)` (1k)    |   ~0%    |         +63.4%   |  +53.2%  |
+  | map field access      |   −7.1%  |          +8.3%   |   +6.5%  |
+  | custom Python fn      |   +1.4%  |          +6.7%   |   −1.9%  |
+
+  Most scenarios are within ~10% of 0.12; the `size(items)` regression on a 1000-element list is cel 0.13's dyn-Val refactor adding per-element boxing overhead at the Python→CEL boundary. Smaller lists are not noticeably affected.
+
 ## [0.5.6] - 2026-02-07
 
 ### Fixed

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -10,7 +10,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 pyo3 = { version = "0.27", features = ["chrono", "py-clone"]}
-cel = { version = "0.12.0", features = ["chrono", "json", "regex", "bytes"] }
+cel = { version = "0.13.0", features = ["chrono", "json", "regex", "bytes"] }
 log = "0.4.27"
 pyo3-log = { git = "https://github.com/a1phyr/pyo3-log.git", branch = "pyo3_0.27" }
 chrono = { version = "0.4.42", features = ["serde"] }
diff --git a/README.md b/README.md
@@ -179,7 +179,7 @@ uv run pytest
 ## Contributing
 
 Contributions are welcome! Please see our [documentation](https://python-common-expression-language.readthedocs.io/) for:
-- [CEL compliance status](docs/reference/cel-compliance.md)
+- [CHANGELOG](CHANGELOG.md) — release notes and behaviour changes
 - Development setup and guidelines
 - Areas where help is needed
 

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -59,16 +59,9 @@ uv sync --dev
 
 # Build the Rust extension
 uv run maturin develop
-# → 🔗 Found pyo3 bindings
-# → 📦 Built wheel for CPython 3.11 to target/wheels/common_expression_language-0.11.0-cp311-cp311-linux_x86_64.whl
-# → 📦 Installed common-expression-language-0.11.0
 
 # Run tests to verify setup
 uv run pytest
-# → ========================= test session starts =========================
-# → collected 300+ items
-# → tests/test_basics.py ........ [ 95%]
-# → ========================= 300 passed in 2.34s =========================
 ```
 
 ### Code Organization
@@ -152,7 +145,7 @@ def test_lower_ascii_not_implemented(self):
         cel.evaluate('"HELLO".lowerAscii()')
         # → RuntimeError: Undefined variable or function 'lowerAscii'
 
-@pytest.mark.xfail(reason="String utilities not implemented in cel v0.11.1", strict=False)
+@pytest.mark.xfail(reason="String utility not implemented upstream yet", strict=False)
 def test_lower_ascii_expected_behavior(self):
     """This test will pass when upstream implements lowerAscii()."""
     result = cel.evaluate('"HELLO".lowerAscii()')
@@ -266,16 +259,10 @@ See https://pyo3.rs/main/type-stub to opt-in to the automated types when impleme
 ```bash
 # Clean rebuild
 uv run maturin develop --release
-# → 🔗 Found pyo3 bindings
-# → 📦 Built wheel for CPython 3.11 to target/wheels/common_expression_language-0.11.0-cp311-cp311-linux_x86_64.whl
-# → 📦 Installed common-expression-language-0.11.0
 
 # Check Rust toolchain
 rustc --version
-# → rustc 1.75.0 (82e1608df 2023-12-21)
-
 cargo --version
-# → cargo 1.75.0 (1d8b05cdd 2023-11-20)
 ```
 
 **Test Failures:**

diff --git a/docs/cookbook.md b/docs/cookbook.md
@@ -325,7 +325,7 @@ print(result)  # → True (cached on subsequent calls)
 > - Never trust user-provided expressions without sandboxing
 > - Monitor expression performance for DoS protection
 
-**→ [Full Production Guide](how-to-guides/production-patterns-best-practices.md) | [API Reference](reference/python-api.md)**
+**→ [API Reference](reference/python-api.md) | [Error Handling](how-to-guides/error-handling.md)**
 
 ---
 
@@ -337,8 +337,7 @@ print(result)  # → True (cached on subsequent calls)
 2. **Learn Fundamentals**: [CEL Language Basics](tutorials/cel-language-basics.md) - Master the syntax
 3. **Practice**: [CLI Recipes](#cli-recipes) - Get comfortable with the tools
 4. **Build**: [Business Logic](#data-transformation) - Implement your first real use case
-5. **Secure**: [Error Handling](#error-handling) - Make it production-ready
-6. **Scale**: [Production Patterns](#production-patterns) - Deploy with confidence
+5. **Handle errors**: [Error Handling](#error-handling) - Make it production-ready
 
 ## 💡 Can't Find What You're Looking For?
 

diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -13,27 +13,20 @@ Getting Python CEL up and running is quick and easy.
 
     ```bash
     uv add common-expression-language
-    # → Adding common-expression-language to dependencies
-    # → Resolved 15 packages in 1.23s
-    # → Installed common-expression-language-0.11.0
     ```
 
 === "uv tool (CLI only)"
 
     Install the CLI tool globally:
-    
+
     ```bash
     uv tool install common-expression-language
-    # → Installed common-expression-language 0.11.0
-    # → Installed executables: cel
     ```
 
 === "pip"
 
     ```bash
     pip install common-expression-language
-    # → Collecting common-expression-language
-    # → Successfully installed common-expression-language-0.11.0
     ```
 
 
@@ -56,8 +49,6 @@ print("✓ Basic evaluation working correctly")
 
 ```bash
 cel --version
-# → cel 0.11.0
-
 cel '1 + 2'
 # → 3
 ```
@@ -81,17 +72,10 @@ cd python-common-expression-language
 
 # Install in development mode
 pip install maturin
-# → Successfully installed maturin-1.4.0
-
 maturin develop
-# → 🔗 Found pyo3 bindings
-# → 📦 Built wheel for CPython 3.11 to target/wheels/
-# → 📦 Installed common-expression-language-0.11.0
 
 # Or with uv
 uv run maturin develop
-# → 🔗 Found pyo3 bindings
-# → 📦 Built wheel and installed successfully
 ```
 
 ## Troubleshooting

diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
@@ -345,12 +345,12 @@ def evaluate_expression(expression: str, context: dict = None):
     """Evaluate expression with proper exception handling."""
     return evaluate(expression, context or {})
 
-# For cases where you need fallback values  
+# For cases where you need fallback values
 def evaluate_with_default(expression: str, context: dict = None, default = None):
     """Evaluate with fallback value on errors."""
     try:
         return evaluate(expression, context or {})
-    except (ValueError, TypeError, RuntimeError):
+    except (ValueError, TypeError, RuntimeError, KeyError, IndexError):
         return default
 
 # Result-like pattern for detailed error information
@@ -406,7 +406,7 @@ def validate_user_rules(rules: list[str], user_context: dict) -> dict[str, bool]
     for rule in rules:
         try:
             results[rule] = bool(evaluate_expression(rule, user_context))
-        except (ValueError, TypeError, RuntimeError):
+        except (ValueError, TypeError, RuntimeError, KeyError, IndexError):
             results[rule] = False  # Invalid rules are considered failed
     return results
 
@@ -444,7 +444,7 @@ Congratulations! You've mastered basic CEL evaluation with dictionary context. N
 **🏢 Jump to Specific Applications:**
 - **[Access Control Policies](../how-to-guides/access-control-policies.md)** - Build permission systems (requires Context knowledge)
 - **[Business Logic & Data Transformation](../how-to-guides/business-logic-data-transformation.md)** - Implement business rules
-- **[Production Patterns & Best Practices](../how-to-guides/production-patterns-best-practices.md)** - Deploy CEL safely
+- **[Error Handling](../how-to-guides/error-handling.md)** - Exception types and safe-evaluation patterns
 
 **💡 Recommended Learning Path:**