Skip to content
Merged
Show file tree
Hide file tree
Changes from all 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
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
This is a history of changes to gateless/clara-rules.

# 1.7.1
* An `:exists` condition no longer adds a generated `?__gen__` binding to the token. Activation cache keys hold the token bindings, so separately compiled sessions now hit the cache for such rules.
* Generated complex negation rule names are now stable between compiles. A complex negation in a named rule generates a rule named `<rule>__gen__COMPLEX_NEGATION_<condition>`. A nested complex negation appends `_<condition>` to that name.
* Rules with the same `:exists` condition on the same parent nodes now share the accumulator node.
* Condition exception messages no longer throw a `NullPointerException` for an accumulator written without `<-` a result binding.

# 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
13 changes: 12 additions & 1 deletion CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ since it diverged from upstream cerner/clara-rules, as of 2026-05-01.
- **Read-only and query-only sessions.** New session types and durability options
for fast deserialization when only queries or inspection are needed.
- **Pluggable caching.** Session and expression compilation are both backed by
`core.cache` `CacheProtocol` instances and can be swapped or cleared.
`core.cache` `CacheProtocol` instances and can be swapped or cleared. An
opt-in `:activation-cache` replays rule RHS output across sessions.
- **`ham-fisted` performance rewrite.** Working memory, beta graph, update caches,
and Fressian durability use ham-fisted mutable collections.
- **DSL additions.** `defhierarchy` macro, namespace-level rule properties,
Expand Down Expand Up @@ -67,6 +68,16 @@ since it diverged from upstream cerner/clara-rules, as of 2026-05-01.
compilation; default is a soft-reference cache.
- Public helpers `clear-session-cache!` and `clear-compiler-cache!`.
- New `:hash-expr-fn` option for deterministic, MD5-based cache keying.
- **Activation cache (1.7.0)**: a rule opts in with the `:cache` prop. The
caller passes `:activation-cache` to `fire-rules`/`fire-rules-async`. A hit
replays the stored RHS output and skips the RHS. `:activation-cache-key-fn`
overrides the key. `:default-rule-props` on `mk-session` sets props for all
rules.
- **Stable activation cache keys (1.7.1)**: `:exists` no longer adds a
generated `?__gen__` binding to the token. Generated complex negation rules
are `<rule>__gen__COMPLEX_NEGATION_<condition>`, with `_<condition>` appended
for each nested level. Activation cache keys therefore match across
separately compiled sessions.

## 4. ham-fisted-based performance rewrite
- `ham-fisted` introduced as a core dep (currently 3.006). Used pervasively in:
Expand Down
4 changes: 2 additions & 2 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@
<groupId>com.github.gateless</groupId>
<artifactId>clara-rules</artifactId>
<name>clara-rules</name>
<version>1.7.0</version>
<version>1.7.1</version>
<scm>
<tag>1.7.0</tag>
<tag>1.7.1</tag>
<url>https://github.com/gateless/clara-rules</url>
<connection>scm:git:git://github.com/gateless/clara-rules.git</connection>
<developerConnection>scm:git:ssh://git@github.com/gateless/clara-rules.git</developerConnection>
Expand Down
33 changes: 16 additions & 17 deletions src/main/clojure/clara/rules/compiler.clj
Original file line number Diff line number Diff line change
Expand Up @@ -628,7 +628,6 @@
(let [is-negation (= :not (first condition))
is-exists (= :exists (first condition))
accumulator (:accumulator condition)
result-binding (:result-binding condition) ; Get the optional result binding used by accumulators.
condition (cond
is-negation (second condition)
accumulator (:from condition)
Expand All @@ -651,19 +650,14 @@
ExtractNode in the future, but this transformation is simple
and meets the functional needs."
[conditions]
(for [condition conditions
expanded (if (= :exists (condition-type condition))
;; This is an :exists condition, so expand it
;; into an accumulator and a test.
(let [exists-count (gensym "?__gen__")]
[{:accumulator '(clara.rules.accumulators/exists)
:from (second condition)
:result-binding (keyword exists-count)}])

;; This is not an :exists condition, so do not change it.
[condition])]
(for [condition conditions]
(if (= :exists (condition-type condition))
;; This is an :exists condition, so expand it into an accumulator
{:accumulator '(clara.rules.accumulators/exists)
:from (second condition)}

expanded))
;; This is not an :exists condition, so do not change it.
condition)))

(defn- classify-variables
"Classifies the variables found in the given contraints into 'bound' vs 'free'
Expand Down Expand Up @@ -992,10 +986,15 @@

;; Dealing with a compound negation, so extract it out.
(let [negation-expr (second expression)
gen-rule-name (str (or (:name production)
(gensym "gen-rule"))
"__"
(gensym))
condition-index (count previous-expressions)
;;; generated rule names are deterministic based on the production name and negation index
;;; or for productions without names, a generated name is used so it remains unique.
gen-rule-name (if-let [production-name (:name production)]
(if (= :extracted-negation
(get-in production [:props :clara-rules/internal-salience]))
(str production-name "_" condition-index)
(str production-name "__gen__COMPLEX_NEGATION_" condition-index))
(str (gensym "gen-rule__COMPLEX_NEGATION") "__" (gensym)))

;; Insert the bindings from ancestors that are used in the negation
;; in the NegationResult fact so that the [:not [NegationResult...]]
Expand Down
16 changes: 11 additions & 5 deletions src/main/clojure/clara/rules/engine.clj
Original file line number Diff line number Diff line change
Expand Up @@ -1017,6 +1017,14 @@
(send-tokens transport memory listener (:children node)
[(->Token (conj (:matches token) [converted-result (:id node)]) new-bindings)]))))

(defn- accum-condition-description
"Describes an accumulator condition for condition exceptions and tracing."
[result-binding accumulator condition]
;; :exists, or an accumulator without <-, has no result binding.
(if result-binding
[(symbol (name result-binding)) '<- accumulator :from condition]
[accumulator :from condition]))

;; The AccumulateNode hosts Accumulators, a Rete extension described above, in the Rete network.
;; It behaves similarly to a JoinNode, but performs an accumulation function on the incoming
;; working-memory elements before sending a new token to its descendents.
Expand Down Expand Up @@ -1364,9 +1372,8 @@
(get-condition-description [this]
(let [{:keys [accumulator from]} accum-condition
{:keys [type constraints]} from
condition (into [type] constraints)
result-symbol (symbol (name result-binding))]
[result-symbol '<- accumulator :from condition]))
condition (into [type] constraints)]
(accum-condition-description result-binding accumulator condition)))

IAccumInspect
(token->matching-elements [this memory token]
Expand Down Expand Up @@ -1709,12 +1716,11 @@
(get-condition-description [this]
(let [{:keys [accumulator from]} accum-condition
{:keys [type constraints original-constraints]} from
result-symbol (symbol (name result-binding))
full-constraints (if (seq original-constraints)
original-constraints
constraints)
condition (into [type] full-constraints)]
[result-symbol '<- accumulator :from condition]))
(accum-condition-description result-binding accumulator condition)))

;; The explanation of the implementation of token->matching-elements on AccumulateNode applies here as well.
;; Note that since we store all facts propagated from the alpha network to this condition in the accum memory,
Expand Down
98 changes: 98 additions & 0 deletions src/test/clojure/clara/test_activation_cache.clj
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
fire-rules fire-rules-async query insert!
insert-unconditional! retract retract!]]
[clara.rules.activation-cache.core :as ac]
[clara.rules.accumulators]
[clara.tools.tracing :as t]
[clojure.core.cache.wrapped :as cache]
[clojure.data.fressian :as fres]
Expand Down Expand Up @@ -359,3 +360,100 @@
[hit-event] (fire-activation-events (run))]
(is (not (contains? (:activation miss-event) :cache)) "a miss (live RHS) activation has no :cache flag")
(is (true? (:cache (:activation hit-event))) "a hit activation is marked :cache true")))))

;; ---------------------------------------------------------------------------
;; Stable generated names across compiles
;; ---------------------------------------------------------------------------

(def exists-runs (atom 0))

(defrule exists-rule
"An :exists condition must not add a binding that changes between compiles.
It adds no binding today. Token bindings are part of the activation cache
key, so the test fails if a future change adds an unstable one."
{:cache true}
[:exists [Temperature (< temperature 20)]]
=>
(swap! exists-runs inc))

(defrule complex-negation-rule
"A complex negation compiles to a generated rule that copies these props, so
the generated rule is cached too. Its name is part of its cache key."
{:cache true}
[Temperature (= ?t temperature)]
[:not [:or [Hot (= ?t temperature)] [Cold (= ?t temperature)]]]
=>
(insert! (->Hot 0)))

(defn- fire-in-separate-sessions
"Fires the facts in two separately compiled sessions that share the given
activation cache. Returns the cache entry count after each session."
[productions facts ca]
(let [run (fn []
(-> (mk-session productions
:cache false
:compiler-cache (cache/basic-cache-factory {}))
(insert-all facts)
(fire-rules {:activation-cache ca}))
(count @ca))]
[(run) (run)]))

(deftest test-exists-binding-stable-across-compiles
(reset! exists-runs 0)
(let [ca (fresh-cache)
[after-s1 after-s2] (fire-in-separate-sessions [exists-rule]
[(->Temperature 10 "MCI")]
ca)]
(is (= 1 @exists-runs)
"the second compile has the same token bindings, so the activation hits")
(is (= after-s1 after-s2) "the second session adds no cache entries")))

(deftest test-complex-negation-rule-name-stable-across-compiles
(let [ca (fresh-cache)
[after-s1 after-s2] (fire-in-separate-sessions [complex-negation-rule]
[(->Temperature 10 "MCI")
(->Hot 10)
(->Cold 10)]
ca)]
(is (pos? after-s1) "the generated negation rule fires and is cached")
(is (= after-s1 after-s2)
"the second compile has the same generated rule name, so its activations hit")))

(def nested-negation-runs (atom 0))

(defrule nested-negation-rule
"The inner negation sits in an :and, so the generated negation rule has a
complex negation of its own. That gives a nested generated rule."
{:cache true}
[Temperature (= ?t temperature)]
[:not [:and
[Hot (= ?t temperature)]
[:not [:or [Cold (= ?t temperature)] [Temperature (> temperature 100)]]]]]
=>
(swap! nested-negation-runs inc))

(deftest test-nested-negation-rule-names-stable-across-compiles
;; A generated rule is cached only when it fires. The nested rule fires for
;; ?t 10 (Hot and Cold), which blocks its parent for 10. Its parent fires for
;; ?t 20 (Hot, no Cold).
(reset! nested-negation-runs 0)
(let [ca (fresh-cache)
[after-s1 after-s2] (fire-in-separate-sessions [nested-negation-rule]
[(->Temperature 10 "MCI")
(->Hot 10)
(->Cold 10)
(->Temperature 20 "MCI")
(->Hot 20)]
ca)
names (set (map :name (keys @ca)))
rule-name "clara.test-activation-cache/nested-negation-rule"
generated? (fn [suffix-re]
(some #(re-matches (re-pattern (str "\\Q" rule-name "\\E" suffix-re)) %)
names))]
(is (generated? "__gen__COMPLEX_NEGATION_\\d+")
"the first generated negation rule has the marker and one index")
(is (generated? "__gen__COMPLEX_NEGATION_\\d+_\\d+")
"the nested generated negation rule appends one more index")
(is (= 1 @nested-negation-runs) "the rule fires for ?t 10 once and hits in session 2")
(is (= after-s1 after-s2)
"the second compile has the same generated rule names, so all activations hit")))
41 changes: 40 additions & 1 deletion src/test/clojure/clara/test_exists.clj
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
(ns clara.test-exists
(:require [clara.tools.testing-utils :refer [def-rules-test] :as tu]
[clara.rules :refer [fire-rules
mk-session
insert
insert-all
insert-unconditional!
Expand All @@ -11,9 +12,13 @@
[clara.rules.testfacts :refer [->Temperature ->Cold ->WindSpeed
->ColdAndWindy]]
[clojure.test :refer [is deftest run-tests testing use-fixtures]]
[clara.rules.dsl :as dsl]
[clara.rules.engine :as eng]
[clara.rules.accumulators]
[clara.tools.tracing :as t]
[schema.test :as st])
(:import [clara.rules.testfacts
(:import [clara.rules.engine AccumulateNode AccumulateWithJoinFilterNode]
[clara.rules.testfacts
Temperature
Cold
WindSpeed
Expand Down Expand Up @@ -167,3 +172,37 @@
(insert (->Temperature -10 "INV"))
fire-rules
(query cold-query)))))

;; An :exists accumulator has no result binding. Condition descriptions must
;; still work for it, because condition exceptions and tracing build them.
(deftest test-condition-exception-inside-exists
(let [rule (dsl/parse-rule [[:exists [Temperature (= 1 (/ 1 (- temperature 10)))]]]
(insert! (->Cold 0)))
e (try
(-> (mk-session [rule] :cache false)
(insert (->Temperature 10 "MCI"))
(fire-rules))
nil
(catch Exception e e))]
(is (instance? clojure.lang.ExceptionInfo e))
(is (.startsWith (str (ex-message e)) "Condition exception raised."))
(is (instance? ArithmeticException (ex-cause e))
"the original error is the cause")))

(deftest test-ranked-productions-with-exists
(let [plain (dsl/parse-rule [[:exists [Temperature (< temperature 20)]]]
(insert! (->Cold 0)))
;; The non-equality join gives an accumulate node with a join filter.
join-filter (dsl/parse-rule [[Temperature (= ?t temperature)]
[:exists [Cold (< temperature ?t)]]]
(insert! (->Cold -1)))
session (-> (mk-session [plain join-filter] :cache false)
t/with-tracing
(insert (->Temperature 10 "MCI"))
(fire-rules))]
(is (map? (t/ranked-productions session)))
(let [accum-nodes (->> session eng/components :rulebase :id-to-node vals
(filter #(or (instance? AccumulateNode %)
(instance? AccumulateWithJoinFilterNode %))))]
(is (= #{AccumulateNode AccumulateWithJoinFilterNode} (set (map type accum-nodes)))
"both accumulate node types are present"))))
Loading