From 08414b47d93dc20e143d0ecce4d36df4ebe1d188 Mon Sep 17 00:00:00 2001 From: Jose Gomez Date: Tue, 20 Oct 2026 13:25:33 -0500 Subject: [PATCH 1/4] feat: implement lhs eager expr compilation at defrule time --- CHANGELOG.md | 8 ++ src/main/clojure/clara/rules.clj | 18 ++- src/main/clojure/clara/rules/compiler.clj | 125 +++++++++++----- src/main/clojure/clara/rules/durability.clj | 4 +- src/main/clojure/clara/rules/schema.clj | 5 +- src/test/clojure/clara/test_common.clj | 6 +- src/test/clojure/clara/test_lhs_exprs.clj | 149 ++++++++++++++++++++ 7 files changed, 267 insertions(+), 48 deletions(-) create mode 100644 src/test/clojure/clara/test_lhs_exprs.clj diff --git a/CHANGELOG.md b/CHANGELOG.md index 178683e..ceec84d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ This is a history of changes to gateless/clara-rules. +# 1.8.0 +* `defrule` and `defquery` now compile their left-hand-side (LHS) expressions when the form is evaluated. An LHS that does not compile now fails at load time, not at `mk-session`. +* The compiled LHS fns are stored in the `:clara.rules/exprs` metadata of the rule or query var. `mk-session` uses them in place of `eval`. A node that several rules share uses one fn. +* A fn is matched by the condition data that its expression is built from. Rules built at runtime still use `eval`. A complex negation still uses `eval` for its generated condition. +* A `defquery` with params that its LHS does not bind now fails at load time. +* A `defquery` query map now has a `:handler` symbol that points to its var, as a rule map does. +* Precompiled fns are now used when `:compiler-cache` is `false`. Before, the precompiled RHS handler was used only when the compiler cache was enabled. + # 1.7.0 * Add opt-in caching of rule right-hand-side (RHS) output across sessions. A rule opts in with a `:cache` prop; the caller passes a cache atom (any `clojure.core.cache/CacheProtocol`) as the `:activation-cache` option to `fire-rules`/`fire-rules-async`. On a cache hit the stored RHS output is replayed and the RHS is skipped; on a miss the RHS runs and its output is recorded. Firing without a cache is unchanged. Cache policy (TTL, eviction, hit/miss metrics) is the caller's responsibility. * Add a `:activation-cache-key-fn` option to `fire-rules`/`fire-rules-async` that overrides the default activation cache key (`clara.rules.activation-cache.core/build-cache-key`). It receives the activation map (`{:node :token}`) and returns the key, or nil to skip caching for that activation (the RHS runs uncached). Only consulted when `:activation-cache` is supplied and the rule opted in; choosing a sound key is the caller's responsibility. diff --git a/src/main/clojure/clara/rules.clj b/src/main/clojure/clara/rules.clj index 2319e74..99f4b54 100644 --- a/src/main/clojure/clara/rules.clj +++ b/src/main/clojure/clara/rules.clj @@ -298,13 +298,15 @@ (:rhs production) &env) [rule-args & rule-body] (drop 2 rule-handler) - name-with-meta (vary-meta rule-name assoc :rule true :doc doc) + lhs-exprs (into {} (map (fn [[k form]] [(list 'quote k) form])) + (com/build-lhs-exprs rule-action)) ;;; The compiled LHS + name-with-meta (vary-meta rule-name assoc :rule true :doc doc :clara.rules/exprs lhs-exprs) handler-name (symbol (name (ns-name *ns*)) (name rule-name))] ;;; The compiled RHS `(defn ~name-with-meta ([] (assoc ~rule :handler '~handler-name)) ([~@(take 1 rule-args)] - (~rule-name '?__token__ {})) + (~rule-name ~'?__token__ {})) ([~@rule-args] ~@rule-body)))) @@ -318,10 +320,14 @@ [?issue <- ValidationError]) See the [query authoring documentation](http://www.clara-rules.org/docs/queries/) for details." - [name & body] - (let [doc (if (string? (first body)) (first body) nil)] - `(def ~(vary-meta name assoc :query true :doc doc) - ~(dsl/build-query name body &env (meta &form))))) + [query-name & body] + (let [doc (if (string? (first body)) (first body) nil) + query (dsl/build-query query-name body &env (meta &form)) + lhs-exprs (into {} (map (fn [[k form]] [(list 'quote k) form])) + (com/build-lhs-exprs (update query :lhs second))) + handler-name (symbol (name (ns-name *ns*)) (name query-name))] + `(def ~(vary-meta query-name assoc :query true :doc doc :clara.rules/exprs lhs-exprs) + ~(assoc query :handler `'~handler-name)))) (defmacro defhierarchy "Defines a hierarchy and stores it in the given var. For instance, a simple hierarchy that adds diff --git a/src/main/clojure/clara/rules/compiler.clj b/src/main/clojure/clara/rules/compiler.clj index d96352b..58c85e2 100644 --- a/src/main/clojure/clara/rules/compiler.clj +++ b/src/main/clojure/clara/rules/compiler.clj @@ -3,6 +3,7 @@ This is the Clara rules compiler, translating raw data structures into compiled versions and functions. Most users should use only the clara.rules namespace." (:require [clara.rules.engine :as eng] + [clara.rules.accumulators] ;;; for exists [clara.rules.schema :as schema] [clara.rules.platform :refer [jeq-wrap] :as platform] [clojure.core.cache.wrapped :as cache] @@ -1370,6 +1371,21 @@ node-id :- sc/Int] (= #{0} (get backward-edges node-id))) +(defn- env-keys + "Only the env keys change an LHS form. The values are symbols at macro time and runtime values in a session." + [env] + (set (keys env))) + +(defn- join-filter-lhs-expr-key + "Returns the :compile-ctx :expr-key of a join filter, made of the inputs that compile-join-filter reads." + [node-type beta-node] + [:join-filter-expr + node-type + (:join-filter-expressions beta-node) + (:join-filter-join-bindings beta-node) + (:new-bindings beta-node) + (env-keys (:env beta-node))]) + (sc/defn extract-exprs :- schema/NodeExprLookup "Walks the Alpha and Beta graphs and extracts the expressions that will be used in the construction of the final network. The extracted expressions are stored by their key, [ ], this allows for the function to be retrieved @@ -1381,12 +1397,12 @@ [beta-graph :- schema/BetaGraph alpha-graph :- [schema/AlphaNode]] (let [backward-edges (:backward-edges beta-graph) - handle-expr (fn [id->expr s-expr id expr-key compilation-ctx] + handle-expr (fn [id->expr s-expr id expr-node-type compilation-ctx] ;; clj-kondo 2026.08.04 infers a numeric key from ham-fisted's assoc!, so ignore it. #_{:clj-kondo/ignore [:type-mismatch]} (hf/assoc! id->expr - [id expr-key] - [s-expr (assoc compilation-ctx expr-key s-expr)]) + [id expr-node-type] + [s-expr (assoc compilation-ctx expr-node-type s-expr)]) id->expr) id->expr (reduce (fn add-alpha-nodes @@ -1405,7 +1421,8 @@ id :alpha-expr {:file (or (:file cmeta) *file*) - :compile-ctx {:condition condition + :compile-ctx {:expr-key [:alpha-expr condition (env-keys env)] + :condition condition :env env :msg "compiling alpha node"}}))) (hf/mut-map) @@ -1459,7 +1476,8 @@ (:env beta-node)) id :join-filter-expr - {:compile-ctx {:condition condition + {:compile-ctx {:expr-key (join-filter-lhs-expr-key "ExpressionJoinNode" beta-node) + :condition condition :join-filter-expressions (:join-filter-expressions beta-node) :env (:env beta-node) :msg "compiling expression join node"}})) @@ -1473,7 +1491,8 @@ (:env beta-node)) id :join-filter-expr - {:compile-ctx {:condition condition + {:compile-ctx {:expr-key (join-filter-lhs-expr-key "NegationWithJoinFilterNode" beta-node) + :condition condition :join-filter-expressions (:join-filter-expressions beta-node) :env (:env beta-node) :msg "compiling negation with join filter node"}}) @@ -1482,22 +1501,28 @@ (compile-test id (:constraints condition) (:env beta-node)) id :test-expr - {:compile-ctx {:condition condition + {:compile-ctx {:expr-key [:test-expr (:constraints condition) (env-keys (:env beta-node))] + :condition condition :env (:env beta-node) :msg "compiling test node"}}) - :accumulator (cond-> (handle-expr prev - (compile-accum id - (if (:join-filter-expressions beta-node) - "AccumulateWithJoinFilterNode" - "AccumulateNode") - (:accumulator beta-node) - (:env beta-node)) - id - :accum-expr - {:compile-ctx {:condition condition - :accumulator (:accumulator beta-node) - :env (:env beta-node) - :msg "compiling accumulator"}}) + :accumulator (cond-> (let [node-type (if (:join-filter-expressions beta-node) + "AccumulateWithJoinFilterNode" + "AccumulateNode")] + (handle-expr prev + (compile-accum id + node-type + (:accumulator beta-node) + (:env beta-node)) + id + :accum-expr + {:compile-ctx {:expr-key [:accum-expr + node-type + (:accumulator beta-node) + (env-keys (:env beta-node))] + :condition condition + :accumulator (:accumulator beta-node) + :env (:env beta-node) + :msg "compiling accumulator"}})) (:join-filter-expressions beta-node) (handle-expr (compile-join-filter id @@ -1508,7 +1533,8 @@ (:env beta-node)) id :join-filter-expr - {:compile-ctx {:condition condition + {:compile-ctx {:expr-key (join-filter-lhs-expr-key "AccumulateWithJoinFilterNode" beta-node) + :condition condition :join-filter-expressions (:join-filter-expressions beta-node) :env (:env beta-node) :msg "compiling accumulate with join filter node"}})) @@ -1565,21 +1591,29 @@ forms-per-eval-default) hash-expr-fn (or (:hash-expr-fn options) hash) + lhs-exprs (::lhs-exprs options {}) prepare-expr (fn do-prepare-expr - [[expr-key [expr compilation-ctx]]] - (if read-only? ;;; read-only expressions cannot be cached and are replaced by a read-only-expr - [:compiled [expr-key [read-only-expr compilation-ctx]]] - (if expr-cache + [[expr-node-type [expr compilation-ctx]]] + (let [precompiled (or (some-> compilation-ctx :compile-ctx :production :handler resolve) + (get lhs-exprs (-> compilation-ctx :compile-ctx :expr-key)))] + (cond + read-only? ;;; read-only expressions cannot be cached and are replaced by a read-only-expr + [:compiled [expr-node-type [read-only-expr compilation-ctx]]] + + precompiled + [:compiled [expr-node-type [precompiled compilation-ctx]]] + + expr-cache (let [cache-key [(hash-expr-fn expr) (hash-expr-fn compilation-ctx)] compilation-ctx (assoc compilation-ctx :cache-key cache-key) - compiled-handler (some-> compilation-ctx :compile-ctx :production :handler resolve) - compiled-expr (or compiled-handler - (cache/lookup expr-cache cache-key))] + compiled-expr (cache/lookup expr-cache cache-key)] (if compiled-expr - [:compiled [expr-key [compiled-expr compilation-ctx]]] - [:prepared [expr-key [expr compilation-ctx]]])) - [:prepared [expr-key [expr compilation-ctx]]]))) + [:compiled [expr-node-type [compiled-expr compilation-ctx]]] + [:prepared [expr-node-type [expr compilation-ctx]]])) + + :else + [:prepared [expr-node-type [expr compilation-ctx]]]))) batching-try-eval (fn do-compile-exprs [exprs compilation-ctxs] ;; Try to evaluate all of the expressions as a batch. If they fail the batch eval then we @@ -1619,15 +1653,15 @@ (for [[nspace ns-expr-group] (sort-by key (group-by (comp :ns second val) key->expr)) ;; Partitioning the number of forms to be evaluated, Java has a limit to the size of methods if we were ;; evaluate all expressions at once it would likely exceed this limit and throw an exception. - expr-batch (partition-all forms-per-eval ns-expr-group) ;;;; [ [ ]] + expr-batch (partition-all forms-per-eval ns-expr-group) ;;;; [ [ ]] :let [grouped-exprs (->> (mapv prepare-expr expr-batch) (group-by first)) prepared-exprs (map second (:prepared grouped-exprs)) - node-expr-keys (mapv first prepared-exprs) + expr-node-types (mapv first prepared-exprs) exprs (mapv (comp first second) prepared-exprs) compilation-ctxs (mapv (comp second second) prepared-exprs) prev-compiled-exprs (map second (:compiled grouped-exprs)) - next-compiled-exprs (mapv vector node-expr-keys + next-compiled-exprs (mapv vector expr-node-types (with-bindings (if (and nspace (not read-only?)) {#'*ns* (the-ns nspace)} @@ -1870,6 +1904,21 @@ :beta-children (distinct node-ids)} (seq env) (assoc :env env)))))) +(defn build-lhs-exprs + "Returns a map of :compile-ctx :expr-key to LHS fn form for one production, as extract-exprs builds them for a session. + defrule and defquery compile these forms at load time. + mk-session finds the compiled fns by that key, which is made of condition data." + [production] + (let [id-counter (atom 0) + create-id-fn (fn [] (swap! id-counter inc)) + beta-graph (to-beta-graph #{production} create-id-fn) + alpha-graph (to-alpha-graph beta-graph create-id-fn)] + (into {} + (keep (fn [[[_ expr-node-type] [expr ctx]]] + (when-not (= :action-expr expr-node-type) + [(-> ctx :compile-ctx :expr-key) expr]))) + (extract-exprs beta-graph alpha-graph)))) + (sc/defn compile-alpha-nodes :- [{:id sc/Int :type sc/Any :alpha-fn schema/Function @@ -2087,7 +2136,13 @@ ;; Extract the expressions from the graphs and evaluate them in a batch manner. ;; This is a performance optimization, see Issue 381 for more information. - exprs (compile-exprs (extract-exprs beta-graph alpha-graph) options) + ;; defrule and defquery store their compiled LHS fns on the var, keyed by condition data. + ;; Equal keys from different productions collapse to one entry here. + lhs-exprs (into {} (mapcat (fn get-exprs + [production] + (some-> production :handler resolve meta :clara.rules/exprs))) productions) + exprs (compile-exprs (extract-exprs beta-graph alpha-graph) + (assoc options ::lhs-exprs lhs-exprs)) ;; If we have made it to this point, it means that we have succeeded in compiling all expressions ;; thus we can free the :compile-ctx used for troubleshooting compilation failures. diff --git a/src/main/clojure/clara/rules/durability.clj b/src/main/clojure/clara/rules/durability.clj index f0ae475..1f94380 100644 --- a/src/main/clojure/clara/rules/durability.clj +++ b/src/main/clojure/clara/rules/durability.clj @@ -38,10 +38,10 @@ rulebase is deserialized the nodes will reference this cache to repopulate their fns." nil) -(defn- add-node-fn [node fn-key expr-key] +(defn- add-node-fn [node fn-key expr-node-type] (assoc node fn-key - (first (get *node-fn-cache* [(:id node) expr-key])))) + (first (get *node-fn-cache* [(:id node) expr-node-type])))) (defn add-rhs-fn [node] (add-node-fn node :rhs :action-expr)) diff --git a/src/main/clojure/clara/rules/schema.clj b/src/main/clojure/clara/rules/schema.clj index bb63e13..3537b16 100644 --- a/src/main/clojure/clara/rules/schema.clj +++ b/src/main/clojure/clara/rules/schema.clj @@ -80,6 +80,7 @@ (s/optional-key :doc) s/Str (s/optional-key :props) {s/Keyword s/Any} (s/optional-key :env) {s/Keyword s/Any} + (s/optional-key :handler) (s/maybe Function) :lhs [Condition] :params #{s/Keyword}}) @@ -174,8 +175,8 @@ (def NodeCompilationValue (s/constrained {s/Keyword s/Any} (fn [compilation] - (let [expr-keys #{:alpha-expr :action-expr :join-filter-expr :test-expr :accum-expr}] - (some expr-keys (keys compilation)))) + (let [expr-node-types #{:alpha-expr :action-expr :join-filter-expr :test-expr :accum-expr}] + (some expr-node-types (keys compilation)))) "node-compilation-value")) (def NodeCompilationContext diff --git a/src/test/clojure/clara/test_common.clj b/src/test/clojure/clara/test_common.clj index 83ed03a..a2d9c1c 100644 --- a/src/test/clojure/clara/test_common.clj +++ b/src/test/clojure/clara/test_common.clj @@ -96,15 +96,15 @@ (defquery temperature-below-value-using-symbol-arg [?value] - [:temperature [{value :value}] (< value ?value)]) + [:temperature [{value :value}] (= ?value value)]) (defquery temperature-below-value-using-keyword-arg [:?value] - [:temperature [{value :value}] (< value ?value)]) + [:temperature [{value :value}] (= ?value value)]) (deftest test-query-definition-bindings-args (testing "can define queries using symbol or keyword arguments" - (is (= (dissoc temperature-below-value-using-symbol-arg :name) (dissoc temperature-below-value-using-keyword-arg :name))))) + (is (= (dissoc temperature-below-value-using-symbol-arg :name :handler) (dissoc temperature-below-value-using-keyword-arg :name :handler))))) (deftest test-query-param-args (testing "noop query-params using keyword arguments" diff --git a/src/test/clojure/clara/test_lhs_exprs.clj b/src/test/clojure/clara/test_lhs_exprs.clj new file mode 100644 index 0000000..e1e00fb --- /dev/null +++ b/src/test/clojure/clara/test_lhs_exprs.clj @@ -0,0 +1,149 @@ +(ns clara.test-lhs-exprs + "Tests for LHS expressions that defrule and defquery compile at load time. + Each var holds its compiled LHS fns in :clara.rules/exprs, keyed by condition data. + mk-session uses these fns in place of eval, and equal condition data shares one fn." + (:require [clara.rules :refer [defrule defquery mk-session insert insert! fire-rules query]] + [clara.rules.accumulators :as acc] + [clara.rules.dsl :as dsl] + [clara.rules.engine :as eng] + [clara.rules.testfacts :refer [->Temperature ->WindSpeed ->Cold]] + [clojure.set :as set] + [clojure.test :refer [deftest is testing]]) + (:import [clara.rules.testfacts Temperature WindSpeed Cold])) + +(defrule cold-rule + [Temperature (< temperature 0) (= ?t temperature)] + => + (insert! (->Cold ?t))) + +(defrule cold-and-windy-rule + [Temperature (< temperature 0) (= ?t temperature)] + [WindSpeed (< ?t windspeed)] + [:test (some? ?t)] + => + (insert! (->Cold (dec ?t)))) + +(defrule exists-rule + [:exists [Temperature (< temperature 0)]] + [WindSpeed (= ?w windspeed)] + => + (insert! (->Cold ?w))) + +(defquery cold-count-query + [] + [?n <- (acc/count) :from [Cold]]) + +(defrule complex-negation-rule + [Temperature (= ?t temperature)] + [:not [:or [WindSpeed (= ?t windspeed)] + [Cold (= ?t temperature)]]] + => + (insert! (->Cold (* 10 ?t)))) + +(defquery cold-query + [] + [Cold (= ?t temperature)]) + +(defrule temperature-and-cold-rule + [Temperature (= ?t temperature)] + [Cold (= ?t temperature)] + => + nil) + +(defquery temperature-query + [] + [Temperature (= ?t temperature)]) + +(defn- precompiled-fns + [& vars] + (set (mapcat (comp vals :clara.rules/exprs meta) vars))) + +(defn- expr-fns + "Returns {expr-node-type #{fn}} for the compiled expressions of a session." + [session] + (reduce-kv (fn [m [_ expr-node-type] [f]] + (update m expr-node-type (fnil conj #{}) f)) + {} + (-> session eng/components :rulebase :node-expr-fn-lookup))) + +(defn- eval-in-scratch-ns + [form] + (binding [*ns* (create-ns 'clara.test-lhs-exprs.scratch)] + (refer-clojure) + (eval form))) + +(deftest test-lhs-error-at-load-time + (testing "an LHS that does not compile fails when defrule is evaluated" + (is (thrown? Exception + (eval-in-scratch-ns + '(clara.rules/defrule bad-rule + [clara.rules.testfacts.Temperature (= ?t (no-such-fn temperature))] + => + nil))))) + (testing "an LHS that does not compile fails when defquery is evaluated" + (is (thrown? Exception + (eval-in-scratch-ns + '(clara.rules/defquery bad-query + [] + [clara.rules.testfacts.Temperature (= ?t (no-such-fn temperature))])))))) + +(deftest test-precompiled-lhs-fns-are-used + (let [session (mk-session [cold-rule cold-and-windy-rule exists-rule cold-count-query] + :cache false + :compiler-cache false) + precompiled (precompiled-fns #'cold-rule #'cold-and-windy-rule #'exists-rule #'cold-count-query) + fns (expr-fns session)] + (testing "every expression type of these productions is present" + (is (= #{:alpha-expr :join-filter-expr :test-expr :accum-expr :action-expr} + (set (keys fns))))) + (testing "each LHS fn is a precompiled fn, even with the compiler cache disabled" + (doseq [expr-node-type [:alpha-expr :join-filter-expr :test-expr :accum-expr] + f (get fns expr-node-type)] + (is (contains? precompiled f) (str expr-node-type " was not precompiled")))) + (testing "each RHS fn is the rule var, even with the compiler cache disabled" + (is (set/subset? #{#'cold-rule #'cold-and-windy-rule #'exists-rule} + (:action-expr fns)))) + (testing "the session gives the expected results" + (is (= [{:?n 3}] + (-> session + (insert (->Temperature -5 "MCI") (->WindSpeed 10 "MCI")) + (fire-rules) + (query cold-count-query))))))) + +(deftest test-shared-condition-uses-one-fn + (let [session (mk-session [cold-rule cold-and-windy-rule] :cache false) + temperature-alphas (-> session eng/components :rulebase :alpha-roots (get Temperature))] + (testing "both rules share the alpha node of the Temperature condition" + (is (= 1 (count temperature-alphas)))) + (testing "the shared node uses the precompiled fn of one of the rules" + (is (contains? (precompiled-fns #'cold-rule #'cold-and-windy-rule) + (:activation (first temperature-alphas))))))) + +(deftest test-fact-type-is-part-of-the-key + (testing "one rule keeps a fn for each fact type when the constraints are equal" + (let [precompiled (precompiled-fns #'temperature-and-cold-rule) + alpha-fns (:alpha-expr (expr-fns (mk-session [temperature-and-cold-rule] :cache false)))] + (is (= 2 (count precompiled) (count alpha-fns))) + (is (every? precompiled alpha-fns)))) + (testing "conditions that differ only in the fact type keep their own fns" + (let [session (-> (mk-session [cold-query temperature-query] :cache false) + (insert (->Cold 1) (->Temperature 2 "MCI")) + (fire-rules))] + (is (= [{:?t 1}] (query session cold-query))) + (is (= [{:?t 2}] (query session temperature-query)))))) + +(deftest test-fallback-to-eval + (testing "a complex negation still compiles and fires" + (is (= [{:?t 30}] + (-> (mk-session [complex-negation-rule cold-query] :cache false) + (insert (->Temperature 3 "MCI")) + (fire-rules) + (query cold-query))))) + (testing "a rule built at runtime has no var and still compiles and fires" + (let [rule (dsl/parse-rule [[Temperature (= ?t temperature)]] + (insert! (->Cold ?t)))] + (is (= [{:?t 7}] + (-> (mk-session [rule cold-query] :cache false) + (insert (->Temperature 7 "MCI")) + (fire-rules) + (query cold-query))))))) From 030c1c4f9ffd070b5ebc2f498452ffc7bd621072 Mon Sep 17 00:00:00 2001 From: Jose Gomez Date: Tue, 20 Oct 2026 13:56:40 -0500 Subject: [PATCH 2/4] chore: add serde support for compiled expressions --- CHANGELOG.md | 3 + src/main/clojure/clara/rules/compiler.clj | 131 +++++++++++++-------- src/test/clojure/clara/test_durability.clj | 36 +++++- src/test/clojure/clara/test_lhs_exprs.clj | 6 + 4 files changed, 122 insertions(+), 54 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ceec84d..68210c3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,9 @@ This is a history of changes to gateless/clara-rules. * `defrule` and `defquery` now compile their left-hand-side (LHS) expressions when the form is evaluated. An LHS that does not compile now fails at load time, not at `mk-session`. * The compiled LHS fns are stored in the `:clara.rules/exprs` metadata of the rule or query var. `mk-session` uses them in place of `eval`. A node that several rules share uses one fn. * A fn is matched by the condition data that its expression is built from. Rules built at runtime still use `eval`. A complex negation still uses `eval` for its generated condition. +* Deserialization of a rulebase uses the precompiled LHS and RHS fns when the rule namespaces are on the classpath. It loads those namespaces when needed. Otherwise it uses `eval`, as before. +* The serialized expression data now holds the `:handler` var symbol and the `:expr-key` of each precompiled expression. A rulebase serialized by an earlier version still deserializes with `eval`. +* Fix deserialization with `:compiler-cache false` when an expression still needs `eval`. Before, a `:cache-key` stored in the serialized data made it throw a `ClassCastException`. * A `defquery` with params that its LHS does not bind now fails at load time. * A `defquery` query map now has a `:handler` symbol that points to its var, as a rule map does. * Precompiled fns are now used when `:compiler-cache` is `false`. Before, the precompiled RHS handler was used only when the compiler cache was enabled. diff --git a/src/main/clojure/clara/rules/compiler.clj b/src/main/clojure/clara/rules/compiler.clj index 58c85e2..f3b9c35 100644 --- a/src/main/clojure/clara/rules/compiler.clj +++ b/src/main/clojure/clara/rules/compiler.clj @@ -1376,15 +1376,26 @@ [env] (set (keys env))) +(defn- expr-key + "Returns an :expr-key made of the given condition data. + Each Class becomes its name symbol. A serialized key then reads back before the fact classes are loaded." + [& parts] + (walk/postwalk (fn safe-key + [x] + (if (class? x) + (symbol (.getName ^Class x)) + x)) + (vec parts))) + (defn- join-filter-lhs-expr-key - "Returns the :compile-ctx :expr-key of a join filter, made of the inputs that compile-join-filter reads." + "Returns the :expr-key of a join filter, made of the inputs that compile-join-filter reads." [node-type beta-node] - [:join-filter-expr - node-type - (:join-filter-expressions beta-node) - (:join-filter-join-bindings beta-node) - (:new-bindings beta-node) - (env-keys (:env beta-node))]) + (expr-key :join-filter-expr + node-type + (:join-filter-expressions beta-node) + (:join-filter-join-bindings beta-node) + (:new-bindings beta-node) + (env-keys (:env beta-node)))) (sc/defn extract-exprs :- schema/NodeExprLookup "Walks the Alpha and Beta graphs and extracts the expressions that will be used in the construction of the final network. @@ -1420,9 +1431,9 @@ (select-keys cmeta [:line :file])) id :alpha-expr - {:file (or (:file cmeta) *file*) - :compile-ctx {:expr-key [:alpha-expr condition (env-keys env)] - :condition condition + {:expr-key (expr-key :alpha-expr condition (env-keys env)) + :file (or (:file cmeta) *file*) + :compile-ctx {:condition condition :env env :msg "compiling alpha node"}}))) (hf/mut-map) @@ -1476,8 +1487,8 @@ (:env beta-node)) id :join-filter-expr - {:compile-ctx {:expr-key (join-filter-lhs-expr-key "ExpressionJoinNode" beta-node) - :condition condition + {:expr-key (join-filter-lhs-expr-key "ExpressionJoinNode" beta-node) + :compile-ctx {:condition condition :join-filter-expressions (:join-filter-expressions beta-node) :env (:env beta-node) :msg "compiling expression join node"}})) @@ -1491,8 +1502,8 @@ (:env beta-node)) id :join-filter-expr - {:compile-ctx {:expr-key (join-filter-lhs-expr-key "NegationWithJoinFilterNode" beta-node) - :condition condition + {:expr-key (join-filter-lhs-expr-key "NegationWithJoinFilterNode" beta-node) + :compile-ctx {:condition condition :join-filter-expressions (:join-filter-expressions beta-node) :env (:env beta-node) :msg "compiling negation with join filter node"}}) @@ -1501,8 +1512,8 @@ (compile-test id (:constraints condition) (:env beta-node)) id :test-expr - {:compile-ctx {:expr-key [:test-expr (:constraints condition) (env-keys (:env beta-node))] - :condition condition + {:expr-key (expr-key :test-expr (:constraints condition) (env-keys (:env beta-node))) + :compile-ctx {:condition condition :env (:env beta-node) :msg "compiling test node"}}) :accumulator (cond-> (let [node-type (if (:join-filter-expressions beta-node) @@ -1515,11 +1526,11 @@ (:env beta-node)) id :accum-expr - {:compile-ctx {:expr-key [:accum-expr - node-type - (:accumulator beta-node) - (env-keys (:env beta-node))] - :condition condition + {:expr-key (expr-key :accum-expr + node-type + (:accumulator beta-node) + (env-keys (:env beta-node))) + :compile-ctx {:condition condition :accumulator (:accumulator beta-node) :env (:env beta-node) :msg "compiling accumulator"}})) @@ -1533,8 +1544,8 @@ (:env beta-node)) id :join-filter-expr - {:compile-ctx {:expr-key (join-filter-lhs-expr-key "AccumulateWithJoinFilterNode" beta-node) - :condition condition + {:expr-key (join-filter-lhs-expr-key "AccumulateWithJoinFilterNode" beta-node) + :compile-ctx {:condition condition :join-filter-expressions (:join-filter-expressions beta-node) :env (:env beta-node) :msg "compiling accumulate with join filter node"}})) @@ -1548,6 +1559,15 @@ (:id-to-condition-node beta-graph))] (persistent! id->expr))) +(defn- resolve-precompiled + "Returns the precompiled fn of an expression, or nil when it is not available. + The rule or query var holds the fns. requiring-resolve loads its namespace from the classpath when needed." + [expr-type handler expr-key] + (when-let [v (try (requiring-resolve handler) (catch Exception _ nil))] + (if (= :action-expr expr-type) + v + (get (:clara.rules/exprs (meta v)) expr-key)))) + (def forms-per-eval-default "The default max number of forms that will be evaluated together as a single batch. 5000 is chosen here due to the way that clojure will evaluate the vector of forms extracted from the nodes. @@ -1591,29 +1611,33 @@ forms-per-eval-default) hash-expr-fn (or (:hash-expr-fn options) hash) - lhs-exprs (::lhs-exprs options {}) + lhs-handlers (::lhs-handlers options {}) prepare-expr (fn do-prepare-expr [[expr-node-type [expr compilation-ctx]]] - (let [precompiled (or (some-> compilation-ctx :compile-ctx :production :handler resolve) - (get lhs-exprs (-> compilation-ctx :compile-ctx :expr-key)))] - (cond - read-only? ;;; read-only expressions cannot be cached and are replaced by a read-only-expr - [:compiled [expr-node-type [read-only-expr compilation-ctx]]] - - precompiled - [:compiled [expr-node-type [precompiled compilation-ctx]]] - - expr-cache - (let [cache-key [(hash-expr-fn expr) - (hash-expr-fn compilation-ctx)] - compilation-ctx (assoc compilation-ctx :cache-key cache-key) - compiled-expr (cache/lookup expr-cache cache-key)] - (if compiled-expr - [:compiled [expr-node-type [compiled-expr compilation-ctx]]] - [:prepared [expr-node-type [expr compilation-ctx]]])) - - :else - [:prepared [expr-node-type [expr compilation-ctx]]]))) + (if read-only? ;;; read-only expressions cannot be cached and are replaced by a read-only-expr + [:compiled [expr-node-type [read-only-expr compilation-ctx]]] + (let [;; A deserialized ctx holds :handler. In mk-session it comes from the production. + handler (or (:handler compilation-ctx) + (some-> compilation-ctx :compile-ctx :production :handler) + (get lhs-handlers (:expr-key compilation-ctx))) + precompiled (when handler + (resolve-precompiled (nth expr-node-type 1) handler (:expr-key compilation-ctx)))] + (cond + ;; :handler stays in the ctx, so serialization keeps the pointer to the precompiled fn. + precompiled + [:compiled [expr-node-type [precompiled (assoc compilation-ctx :handler handler)]]] + + expr-cache + (let [cache-key [(hash-expr-fn expr) + (hash-expr-fn compilation-ctx)] + compilation-ctx (assoc compilation-ctx :cache-key cache-key) + compiled-expr (cache/lookup expr-cache cache-key)] + (if compiled-expr + [:compiled [expr-node-type [compiled-expr compilation-ctx]]] + [:prepared [expr-node-type [expr compilation-ctx]]])) + + :else + [:prepared [expr-node-type [expr compilation-ctx]]])))) batching-try-eval (fn do-compile-exprs [exprs compilation-ctxs] ;; Try to evaluate all of the expressions as a batch. If they fail the batch eval then we @@ -1623,7 +1647,8 @@ (mapv (fn do-cache-expr [compiled-expr compilation-ctx] - (when-let [cache-key (:cache-key compilation-ctx)] + ;; A deserialized ctx can hold the :cache-key of the session that wrote it, even when caching is off now. + (when-let [cache-key (and expr-cache (:cache-key compilation-ctx))] (cache/miss expr-cache cache-key compiled-expr)) [compiled-expr compilation-ctx]) (eval exprs) compilation-ctxs) @@ -1905,7 +1930,7 @@ (seq env) (assoc :env env)))))) (defn build-lhs-exprs - "Returns a map of :compile-ctx :expr-key to LHS fn form for one production, as extract-exprs builds them for a session. + "Returns a map of :expr-key to LHS fn form for one production, as extract-exprs builds them for a session. defrule and defquery compile these forms at load time. mk-session finds the compiled fns by that key, which is made of condition data." [production] @@ -1916,7 +1941,7 @@ (into {} (keep (fn [[[_ expr-node-type] [expr ctx]]] (when-not (= :action-expr expr-node-type) - [(-> ctx :compile-ctx :expr-key) expr]))) + [(:expr-key ctx) expr]))) (extract-exprs beta-graph alpha-graph)))) (sc/defn compile-alpha-nodes :- [{:id sc/Int @@ -2137,12 +2162,14 @@ ;; Extract the expressions from the graphs and evaluate them in a batch manner. ;; This is a performance optimization, see Issue 381 for more information. ;; defrule and defquery store their compiled LHS fns on the var, keyed by condition data. - ;; Equal keys from different productions collapse to one entry here. - lhs-exprs (into {} (mapcat (fn get-exprs - [production] - (some-> production :handler resolve meta :clara.rules/exprs))) productions) + ;; This maps each key to the var symbol. Equal keys from different productions collapse to one entry here. + lhs-handlers (into {} (mapcat (fn get-handlers + [{:keys [handler]}] + (for [expr-key (some-> handler resolve meta :clara.rules/exprs keys)] + [expr-key handler]))) + productions) exprs (compile-exprs (extract-exprs beta-graph alpha-graph) - (assoc options ::lhs-exprs lhs-exprs)) + (assoc options ::lhs-handlers lhs-handlers)) ;; If we have made it to this point, it means that we have succeeded in compiling all expressions ;; thus we can free the :compile-ctx used for troubleshooting compilation failures. diff --git a/src/test/clojure/clara/test_durability.clj b/src/test/clojure/clara/test_durability.clj index c60d6c7..1862cd2 100644 --- a/src/test/clojure/clara/test_durability.clj +++ b/src/test/clojure/clara/test_durability.clj @@ -12,8 +12,8 @@ [clojure.test :refer :all] [clara.rules.compiler :as com] [clara.tools.testing-utils :as tu]) - (:import [clara.rules.testfacts Temperature] - [clara.rules.engine TestNode] + (:import [clara.rules.testfacts Temperature Cold] + [clara.rules.engine TestNode ProductionNode] [clara.rules.engine ReadOnlyLocalSession] [java.io ByteArrayInputStream ByteArrayOutputStream])) @@ -506,3 +506,35 @@ {:type Long :constraints ['(== this clara.test-durability/test-compilation-ctx-var)]}) (tu/get-all-ex-data e))))))) + +(deftest test-deserialize-uses-precompiled-fns + (let [s (mk-session 'clara.durability-rules :cache false :compiler-cache false) + restored-rb (rb-serde s {:compiler-cache false}) + rule-vars (->> (ns-interns 'clara.durability-rules) vals (filter (comp :rule meta)) set) + precompiled (->> (ns-interns 'clara.durability-rules) vals (mapcat (comp vals :clara.rules/exprs meta)) set)] + (testing "each LHS fn is a precompiled fn, with the compiler cache disabled" + (doseq [[[_ expr-node-type :as node-key] [f]] (:node-expr-fn-lookup restored-rb) + :when (not= :action-expr expr-node-type)] + (is (contains? precompiled f) (str node-key " was not precompiled")))) + (testing "each RHS fn of a production node is its rule var" + (doseq [[[id expr-node-type :as node-key] [f]] (:node-expr-fn-lookup restored-rb) + :when (and (= :action-expr expr-node-type) + (instance? ProductionNode (get (:id-to-node restored-rb) id)))] + (is (contains? rule-vars f) (str node-key " was not precompiled")))) + (testing "the restored session gives the same query results" + (is (= (:query-results (session-test s)) + (:query-results (session-test (d/assemble-restored-session restored-rb {})))))))) + +(deftest test-deserialize-without-compiler-cache + (testing "a serialized :cache-key does not break deserialization when the compiler cache is off" + (let [rule (dsl/parse-rule [[Temperature (< temperature 20) (= ?t temperature)]] + (insert! (->Cold ?t))) + cold-query (dsl/parse-query [] [[?c <- Cold]]) + ;; The default compiler cache adds a :cache-key to the ctx of the eval'd rule. + s (com/mk-session [[rule cold-query] :cache false]) + restored (d/assemble-restored-session (rb-serde s {:compiler-cache false}) {})] + (is (= [{:?c (->Cold 10)}] + (-> restored + (insert (->Temperature 10 "MCI")) + (fire-rules) + (query cold-query))))))) diff --git a/src/test/clojure/clara/test_lhs_exprs.clj b/src/test/clojure/clara/test_lhs_exprs.clj index e1e00fb..02a4109 100644 --- a/src/test/clojure/clara/test_lhs_exprs.clj +++ b/src/test/clojure/clara/test_lhs_exprs.clj @@ -132,6 +132,12 @@ (is (= [{:?t 1}] (query session cold-query))) (is (= [{:?t 2}] (query session temperature-query)))))) +(deftest test-expr-keys-hold-no-classes + (testing "a key holds class names, so it reads back from serialized data before the fact classes are loaded" + (is (not-any? class? + (mapcat #(tree-seq coll? seq %) + (keys (:clara.rules/exprs (meta #'cold-and-windy-rule)))))))) + (deftest test-fallback-to-eval (testing "a complex negation still compiles and fires" (is (= [{:?t 30}] From 982dc1e2aac3e10cff70ca1816978ff305bcafb9 Mon Sep 17 00:00:00 2001 From: Jose Gomez Date: Tue, 20 Oct 2026 14:56:01 -0500 Subject: [PATCH 3/4] chore: query tidy up --- CHANGELOG.md | 1 + src/main/clojure/clara/rules/engine.clj | 2 +- src/test/clojure/clara/test_durability.clj | 9 +++++++++ 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 68210c3..a3f4524 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ This is a history of changes to gateless/clara-rules. * Deserialization of a rulebase uses the precompiled LHS and RHS fns when the rule namespaces are on the classpath. It loads those namespaces when needed. Otherwise it uses `eval`, as before. * The serialized expression data now holds the `:handler` var symbol and the `:expr-key` of each precompiled expression. A rulebase serialized by an earlier version still deserializes with `eval`. * Fix deserialization with `:compiler-cache false` when an expression still needs `eval`. Before, a `:cache-key` stored in the serialized data made it throw a `ClassCastException`. +* `query` looks up a query that has a name by that name. A query var now works with a rulebase serialized by an earlier version, where the query map can differ. * A `defquery` with params that its LHS does not bind now fails at load time. * A `defquery` query map now has a `:handler` symbol that points to its var, as a rule map does. * Precompiled fns are now used when `:compiler-cache` is `false`. Before, the precompiled RHS handler was used only when the compiler cache was enabled. diff --git a/src/main/clojure/clara/rules/engine.clj b/src/main/clojure/clara/rules/engine.clj index 555c2c2..ce47b8a 100644 --- a/src/main/clojure/clara/rules/engine.clj +++ b/src/main/clojure/clara/rules/engine.clj @@ -2128,7 +2128,7 @@ (defn- query* [rulebase memory query params] - (let [query-node (get-in rulebase [:query-nodes query])] + (let [query-node (get-in rulebase [:query-nodes (or (:name query) query)])] ;;; lookup by name or value (when (= nil query-node) (platform/throw-error (str "The query " query " is invalid or not included in the rule base."))) (when-not (= (into #{} (keys params)) ;; nil params should be equivalent to #{} diff --git a/src/test/clojure/clara/test_durability.clj b/src/test/clojure/clara/test_durability.clj index 1862cd2..ac133e9 100644 --- a/src/test/clojure/clara/test_durability.clj +++ b/src/test/clojure/clara/test_durability.clj @@ -538,3 +538,12 @@ (insert (->Temperature 10 "MCI")) (fire-rules) (query cold-query))))))) + +(deftest test-query-by-name-after-deserialization + (testing "a named query is found by its name when its map differs from the one in the rulebase" + (let [restored (d/assemble-restored-session (rb-serde (mk-session 'clara.durability-rules) nil) {}) + {:keys [fired-session]} (session-test restored) + expected (query fired-session dr/cold-temp)] + (is (seq expected)) + (is (= expected (query fired-session (assoc dr/cold-temp :extra true)))) + (is (= expected (query fired-session (dissoc dr/cold-temp :handler))))))) From 8a25c93ae496f7e8a2dccaee46718491dd6939da Mon Sep 17 00:00:00 2001 From: Jose Gomez Date: Tue, 20 Oct 2026 15:17:58 -0500 Subject: [PATCH 4/4] chore: schema fixes --- src/main/clojure/clara/rules/schema.clj | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/main/clojure/clara/rules/schema.clj b/src/main/clojure/clara/rules/schema.clj index 3537b16..e9e4bbf 100644 --- a/src/main/clojure/clara/rules/schema.clj +++ b/src/main/clojure/clara/rules/schema.clj @@ -71,7 +71,7 @@ (s/optional-key :doc) s/Str (s/optional-key :props) {s/Keyword s/Any} (s/optional-key :env) {s/Keyword s/Any} - (s/optional-key :handler) (s/maybe Function) + (s/optional-key :handler) (s/maybe s/Symbol) :lhs [Condition] :rhs s/Any}) @@ -80,7 +80,7 @@ (s/optional-key :doc) s/Str (s/optional-key :props) {s/Keyword s/Any} (s/optional-key :env) {s/Keyword s/Any} - (s/optional-key :handler) (s/maybe Function) + (s/optional-key :handler) (s/maybe s/Symbol) :lhs [Condition] :params #{s/Keyword}})