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

# 1.7.1
* Generated names are now stable between compiles. An `:exists` condition binds `?__gen__<condition>_<position>` instead of a gensym. 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. Activation cache keys hold these names, so separately compiled sessions now hit the cache for such rules.
* Rules with the same `:exists` condition on the same parent nodes now share the accumulator node.

# 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 generated names (1.7.1)**: `:exists` bindings are
`?__gen__<condition>_<position>`. 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
43 changes: 26 additions & 17 deletions src/main/clojure/clara/rules/compiler.clj
Original file line number Diff line number Diff line change
Expand Up @@ -649,21 +649,25 @@

It may be possible to replace this conversion with a specialized
ExtractNode in the future, but this transformation is simple
and meets the functional needs."
[conditions]
(for [condition conditions
expanded (if (= :exists (condition-type condition))
and meets the functional needs.

The result binding name comes from the condition-index of the
top-level condition and the position in the conditions. The name
must not change between compiles, because the activation cache
key holds the bindings."
[condition-index conditions]
(map-indexed (fn as-exists
Comment thread
k13gomez marked this conversation as resolved.
Resolved
[i condition]
(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)}])
{:accumulator '(clara.rules.accumulators/exists)
:from (second condition)
:result-binding (keyword (str "?__gen__" condition-index "_" i))}
Comment thread
k13gomez marked this conversation as resolved.
Resolved

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

expanded))
condition))
conditions))

(defn- classify-variables
"Classifies the variables found in the given contraints into 'bound' vs 'free'
Expand Down Expand Up @@ -992,10 +996,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") "__" (gensym)))
Comment thread
k13gomez marked this conversation as resolved.
Resolved

;; Insert the bindings from ancestors that are used in the negation
;; in the NegationResult fact so that the [:not [NegationResult...]]
Expand Down Expand Up @@ -1222,7 +1231,7 @@
(reduce (fn [previous-result conjunctions]
;; Get the complete bindings
(let [;; Convert exists operations to accumulator and test nodes.
exists-extracted (extract-exists conjunctions)
exists-extracted (extract-exists (count previous-conditions) conjunctions)
;; Compute the new bindings with the expressions.
new-result (get-condition-bindings exists-extracted
(:env production)
Expand Down Expand Up @@ -1299,7 +1308,7 @@

;; Get the beta graph, new identifiers, and complete bindings
(let [;; Convert exists operations to accumulator and test nodes.
exists-extracted (extract-exists conjunctions)
exists-extracted (extract-exists (count previous-conditions) conjunctions)

;; Compute the new beta graph, ids, and bindings with the expressions.
new-result (add-conjunctions exists-extracted
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")))
Loading