Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 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 and `clara.tools.tracing/ranked-productions` now support accumulators without a result binding. This includes `:exists` and accumulators written without `<-`. Previously they threw a `NullPointerException`.

# 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
14 changes: 9 additions & 5 deletions src/main/clojure/clara/rules/engine.clj
Original file line number Diff line number Diff line change
Expand Up @@ -1364,9 +1364,11 @@
(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)]
;; :exists, or an accumulator without <-, has no result binding.
(if result-binding
[(symbol (name result-binding)) '<- accumulator :from condition]
[accumulator :from condition])))

IAccumInspect
(token->matching-elements [this memory token]
Expand Down Expand Up @@ -1709,12 +1711,14 @@
(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]))
;; :exists, or an accumulator without <-, has no result binding.
(if result-binding
[(symbol (name result-binding)) '<- accumulator :from condition]
[accumulator :from 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
97 changes: 97 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,99 @@
[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 compiles to an accumulator with a generated result
binding. That binding is part of the activation cache key."
{: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 :exists binding name, 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")))
32 changes: 32 additions & 0 deletions 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,7 +12,9 @@
[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.accumulators]
[clara.tools.tracing :as t]
[schema.test :as st])
(:import [clara.rules.testfacts
Temperature
Expand Down Expand Up @@ -167,3 +170,32 @@
(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)))))
Loading