Skip to content
Open
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why metadata instead of first class data on the data structure?

* 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`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this sentence to be confusing. Why is it holding this key still and why does it get a class-cast exception?

* `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.

# 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.
Expand Down
18 changes: 12 additions & 6 deletions src/main/clojure/clara/rules.clj
Original file line number Diff line number Diff line change
Expand Up @@ -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__ {}))

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mrrodriguez this is the fix we had discussed yesterday

@mrrodriguez mrrodriguez Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is OK, but you could also just do (first rule-args) to avoid the need to have to know what it actually is and not get it wrong again.

([~@rule-args]
~@rule-body))))

Expand All @@ -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
Expand Down
160 changes: 121 additions & 39 deletions src/main/clojure/clara/rules/compiler.clj

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions src/main/clojure/clara/rules/durability.clj
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
2 changes: 1 addition & 1 deletion src/main/clojure/clara/rules/engine.clj
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a little bit weird because if the query actually has changed, it could even have different parameters now. However, you would be resolving it to whatever it used to be. So the call one would not really align anymore.

(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 #{}
Expand Down
5 changes: 3 additions & 2 deletions src/main/clojure/clara/rules/schema.clj
Original file line number Diff line number Diff line change
Expand Up @@ -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}})

Expand Down Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions src/test/clojure/clara/test_common.clj
Original file line number Diff line number Diff line change
Expand Up @@ -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)])

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does Query no longer has name somantically for what it is doing. Why was the equals changed here?


(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"
Expand Down
45 changes: 43 additions & 2 deletions src/test/clojure/clara/test_durability.clj
Original file line number Diff line number Diff line change
Expand Up @@ -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]))

Expand Down Expand Up @@ -506,3 +506,44 @@
{: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)))))))

(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)))))))
155 changes: 155 additions & 0 deletions src/test/clojure/clara/test_lhs_exprs.clj
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
(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-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}]
(-> (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)))))))
Loading