datahike-browser-tests 1.0.0

package/src/datahike/lru.cljc

@@ -0,0 +1,146 @@
+(ns ^:no-doc datahike.lru
+  (:require [#?(:clj clojure.core.cache :cljs cljs.cache) :refer [defcache CacheProtocol]]
+            #?(:clj clojure.data.priority-map
+               :cljs tailrecursion.priority-map)))
+
+(declare assoc-lru cleanup-lru)
+
+#?(:cljs
+   (deftype LRU [key-value gen-key key-gen gen limit]
+     IAssociative
+     (-assoc [this k v] (assoc-lru this k v))
+     (-contains-key? [_ k] (-contains-key? key-value k))
+     ILookup
+     (-lookup [_ k]    (-lookup key-value k nil))
+     (-lookup [_ k nf] (-lookup key-value k nf))
+     IPrintWithWriter
+     (-pr-writer [_ writer opts]
+       (-pr-writer (persistent! key-value) writer opts)))
+   :clj
+   (deftype LRU [^clojure.lang.Associative key-value gen-key key-gen gen limit]
+     clojure.lang.ILookup
+     (valAt [_ k]           (.valAt key-value k))
+     (valAt [_ k not-found] (.valAt key-value k not-found))
+     clojure.lang.Associative
+     (containsKey [_ k] (.containsKey key-value k))
+     (entryAt [_ k]     (.entryAt key-value k))
+     (assoc [this k v]  (assoc-lru this k v))))
+
+(defn assoc-lru [^LRU lru k v]
+  (let [key-value (.-key-value lru)
+        gen-key   (.-gen-key lru)
+        key-gen   (.-key-gen lru)
+        gen       (.-gen lru)
+        limit     (.-limit lru)]
+    (if-let [g (key-gen k nil)]
+      (->LRU key-value
+             (-> gen-key
+                 (dissoc g)
+                 (assoc gen k))
+             (assoc key-gen k gen)
+             (inc gen)
+             limit)
+      (cleanup-lru
+       (->LRU (assoc key-value k v)
+              (assoc gen-key gen k)
+              (assoc key-gen k gen)
+              (inc gen)
+              limit)))))
+
+(defn cleanup-lru [^LRU lru]
+  (if (> (count (.-key-value lru)) (.-limit lru))
+    (let [key-value (.-key-value lru)
+          gen-key   (.-gen-key lru)
+          key-gen   (.-key-gen lru)
+          gen       (.-gen lru)
+          limit     (.-limit lru)
+          [g k]     (first gen-key)]
+      (->LRU (dissoc key-value k)
+             (dissoc gen-key g)
+             (dissoc key-gen k)
+             gen
+             limit))
+    lru))
+
+(defn lru [limit]
+  (->LRU {} (sorted-map) {} 0 limit))
+
+(defcache LRUDatomCache [cache lru counts n-total-datoms tick datom-limit]
+  CacheProtocol
+  (lookup [_ item]
+          (get cache item))
+  (lookup [_ item not-found]
+          (get cache item not-found))
+  (has? [_ item]
+        (contains? cache item))
+  (hit [_ item]
+       (let [tick+ (inc tick)]
+         (LRUDatomCache. cache
+                         (if (contains? cache item)
+                           (assoc lru item tick+)
+                           lru)
+                         counts
+                         n-total-datoms
+                         tick+
+                         datom-limit)))
+  (miss [this item result]
+        (let [tick+ (inc tick)
+              n-new-datoms (count result)
+              new-size (+ n-total-datoms n-new-datoms)
+              [c l n s] (if (contains? lru item)
+                          [(dissoc cache item)
+                           (dissoc lru item)
+                           (dissoc counts item)
+                           (- new-size (get counts item))]
+                          [cache lru counts new-size])
+              [c l n s] (loop [c c l l n n s s]
+                          (if (> s datom-limit)
+                            (let [k (first (peek lru))]
+                              (if-let [x (get n k)]
+                                (recur (dissoc c k)
+                                       (dissoc l k)
+                                       (dissoc n k)
+                                       (- s x))
+                                [c l n s]))
+                            [c l n s]))]
+          (LRUDatomCache. (assoc c item result)
+                          (assoc l item tick+)
+                          (assoc n item n-new-datoms)
+                          s
+                          tick+
+                          datom-limit)))
+  (evict [this key]
+         (if (contains? cache key)
+           (LRUDatomCache. (dissoc cache key)
+                           (dissoc lru key)
+                           (dissoc counts key)
+                           (- n-total-datoms (get counts key))
+                           (inc tick)
+                           datom-limit)
+           this))
+  (seed [_ base]
+        (LRUDatomCache. base
+                        (into #?(:clj (clojure.data.priority-map/priority-map)
+                                 :cljs (tailrecursion.priority-map/priority-map))
+                              (map #(vector % 0)
+                                   (keys base)))
+                        (into {}
+                              (map #(vector % (count (get base %)))
+                                   (keys base)))
+                        0
+                        0
+                        datom-limit))
+  Object
+  (toString [_]
+            (str cache \, \space lru \, \space counts \, \space n-total-datoms \, \space tick \, \space datom-limit)))
+
+(defn lru-datom-cache-factory
+  "Returns an LRU cache with the cache and usage-table initialied to `base` --
+   each entry is initialized with the same usage value.
+   This function takes an optional `:threshold` argument that defines the maximum number
+   of elements in the cache before the LRU semantics apply (default is 32)."
+  [base & {threshold :threshold :or {threshold 32}}]
+  {:pre [(number? threshold) (< 0 threshold)
+         (map? base)]}
+  #?(:clj (atom (clojure.core.cache/seed (LRUDatomCache. {} (clojure.data.priority-map/priority-map) {} 0 0 threshold) base))
+     :cljs (atom (cljs.cache/seed (LRUDatomCache. {} (tailrecursion.priority-map/priority-map) {} 0 0 threshold) base))))

package/src/datahike/migrate.clj

@@ -0,0 +1,39 @@
+(ns ^:no-doc datahike.migrate
+  (:require [datahike.api :as api]
+            [datahike.constants :as c]
+            [datahike.datom :as d]
+            [datahike.db :as db]
+            [clj-cbor.core :as cbor]))
+
+(defn export-db
+  "Export the database in a flat-file of datoms at path.
+  Intended as a temporary solution, pending developments in Wanderung."
+  [conn path]
+  (let [db @conn
+        cfg (:config db)]
+    (cbor/spit-all path (cond->> (sort-by
+                                  (juxt d/datom-tx :e)
+                                  (api/datoms (if (:keep-history? cfg) (api/history db) db) :eavt))
+                          (:attribute-refs? cfg) (remove #(= (d/datom-tx %) c/tx0))
+                          true (map seq)))))
+
+(defn update-max-tx
+  "Find bigest tx in datoms and update max-tx of db.
+  Note: the last tx might not be the biggest if the db
+  has been imported before."
+  [db datoms]
+  (assoc db :max-tx (reduce #(max %1 (nth %2 3)) 0 datoms)))
+
+(defn- instance-to-date [v]
+  (if (instance? java.time.Instant v) (java.util.Date/from v) v))
+
+(defn import-db
+  "Import a flat-file of datoms at path into your database.
+  Intended as a temporary solution, pending developments in Wanderung."
+  [conn path]
+  (println "Preparing import of" path "in batches of 1000")
+  (let [datoms (->> (cbor/slurp-all path)
+                    (map #(-> (apply d/datom %) (update :v instance-to-date))))]
+    (swap! conn update-max-tx datoms)
+    (print "Importing ")
+    (api/transact conn (vec datoms))))

package/src/datahike/norm/norm.clj

@@ -0,0 +1,245 @@
+(ns datahike.norm.norm
+  (:require
+   [clojure.java.io :as io]
+   [clojure.string :as string]
+   [clojure.pprint :as pp]
+   [clojure.data :as data]
+   [clojure.edn :as edn]
+   [clojure.spec.alpha :as s]
+   [taoensso.timbre :as log]
+   [hasch.core :as h]
+   [hasch.platform :as hp]
+   [datahike.api :as d]
+   [datahike.tools :as dt])
+  (:import
+   [java.io File]
+   [java.util.jar JarFile JarEntry]
+   [java.net URL]))
+
+(def checksums-file "checksums.edn")
+
+(defn- attribute-installed? [conn attr]
+  (some? (d/entity @conn [:db/ident attr])))
+
+(defn- ensure-norm-attribute! [conn]
+  (if-not (attribute-installed? conn :tx/norm)
+    (:db-after (d/transact conn {:tx-data [{:db/ident       :tx/norm
+                                            :db/valueType   :db.type/keyword
+                                            :db/cardinality :db.cardinality/one}]}))
+    @conn))
+
+(defn- norm-installed? [db norm]
+  (->> {:query '[:find (count ?t) .
+                 :in $ ?tn
+                 :where
+                 [_ :tx/norm ?tn ?t]]
+        :args  [db norm]}
+       d/q
+       some?))
+
+(defn- get-jar [resource]
+  (-> (.getPath resource)
+      (string/split #"!" 2)
+      first
+      (subs 5)
+      JarFile.))
+
+(defmulti ^:private retrieve-file-list
+  (fn [file-or-resource] (type file-or-resource)))
+
+(defmethod ^:private retrieve-file-list File [file]
+  (if (.exists file)
+    (let [migration-files (file-seq file)
+          xf (comp
+              (filter #(.isFile %))
+              (filter #(string/ends-with? (.getPath %) ".edn")))]
+      (into [] xf migration-files))
+    (dt/raise (format "Norms folder %s does not exist." (str file)) {:folder file})))
+
+(defmethod ^:private retrieve-file-list URL [resource]
+  (if resource
+    (let [abs-path (.getPath resource)
+          last-path-segment (-> abs-path (string/split #"/") peek)]
+      (if (string/starts-with? abs-path "file:")
+        (->> (get-jar resource)
+             .entries
+             enumeration-seq
+             (filter #(and (string/starts-with? (.getName %) last-path-segment)
+                           (not (.isDirectory %))
+                           (string/ends-with? % ".edn"))))
+        (->> (file-seq (io/file abs-path))
+             (filter #(not (.isDirectory %))))))
+    (dt/raise "Resource does not exist." {:resource (str resource)})))
+
+(defmethod ^:private retrieve-file-list :default [arg]
+  (dt/raise "Can only read a File or a URL (resource)" {:arg arg :type (type arg)}))
+
+(defn- filter-file-list [file-list]
+  (filter #(and (string/ends-with? % ".edn")
+                (not (string/ends-with? (.getName %) checksums-file)))
+          file-list))
+
+(defn filename->keyword [filename]
+  (-> filename
+      (string/replace #" " "-")
+      (keyword)))
+
+(defmulti ^:private read-edn-file
+  (fn [file-or-entry _file-or-resource] (type file-or-entry)))
+
+(defmethod ^:private read-edn-file File [f _file]
+  (when (not (.exists f))
+    (dt/raise "Failed reading file because it does not exist" {:filename (str f)}))
+  [(-> (slurp f)
+       edn/read-string)
+   {:name (.getName f)
+    :norm (filename->keyword (.getName f))}])
+
+(defmethod ^:private read-edn-file JarEntry [entry resource]
+  (when (nil? resource)
+    (dt/raise "Failed reading resource because it does not exist" {:resource (str resource)}))
+  (let [file-name (-> (.getName entry)
+                      (string/split #"/")
+                      peek)]
+    [(-> (get-jar resource)
+         (.getInputStream entry)
+         slurp
+         edn/read-string)
+     {:name file-name
+      :norm (filename->keyword file-name)}]))
+
+(defmethod ^:private read-edn-file :default [t _]
+  (dt/raise "Can not handle argument" {:type (type t) :arg t}))
+
+(defn- read-norm-files [norm-list file-or-resource]
+  (->> norm-list
+       (map (fn [f]
+              (let [[content metadata] (read-edn-file f file-or-resource)]
+                (merge content metadata))))
+       (sort-by :norm)))
+
+(defn- compute-checksums [norm-files]
+  (->> norm-files
+       (reduce (fn [m {:keys [norm] :as content}]
+                 (assoc m
+                        norm
+                        (-> (select-keys content [:tx-data :tx-fn])
+                            h/edn-hash
+                            hp/hash->str)))
+               {})))
+
+(s/def ::tx-data vector?)
+(s/def ::tx-fn symbol?)
+(s/def ::norm-map (s/keys :opt-un [::tx-data ::tx-fn]))
+(defn- validate-norm [norm]
+  (if (s/valid? ::norm-map norm)
+    (log/debug "Norm validated" {:norm-map norm})
+    (let [res (s/explain-data ::norm-map norm)]
+      (dt/raise "Invalid norm" {:validation-error res}))))
+
+(defn- neutral-fn [_] [])
+
+(defn- transact-norms [conn norm-list]
+  (let [db (ensure-norm-attribute! conn)]
+    (log/info "Checking migrations ...")
+    (doseq [{:keys [norm tx-data tx-fn]
+             :as   norm-map
+             :or   {tx-data []
+                    tx-fn   'datahike.norm.norm/neutral-fn}}
+            norm-list]
+      (log/info "Checking migration" norm)
+      (validate-norm norm-map)
+      (when-not (norm-installed? db norm)
+        (log/info "Running migration")
+        (d/transact conn {:tx-data (vec (concat [{:tx/norm norm}]
+                                                tx-data
+                                                ((var-get (requiring-resolve tx-fn)) conn)))})
+        (log/info "Done")))))
+
+(defn- diff-checksums [checksums edn-content]
+  (let [diff (data/diff checksums edn-content)]
+    (when-not (every? nil? (butlast diff))
+      (dt/raise "Deviation of the checksums found. Migration aborted." {:diff diff}))))
+
+(defmulti verify-checksums
+  (fn [file-or-resource] (type file-or-resource)))
+
+(defmethod verify-checksums File [file]
+  (let [norm-list (-> (retrieve-file-list file)
+                      filter-file-list
+                      (read-norm-files file))
+        edn-content (-> (io/file (io/file file) checksums-file)
+                        (read-edn-file file)
+                        first)]
+    (diff-checksums (compute-checksums norm-list)
+                    edn-content)))
+
+(defmethod verify-checksums URL [resource]
+  (let [file-list (retrieve-file-list resource)
+        norm-list (-> (filter-file-list file-list)
+                      (read-norm-files resource))
+        edn-content (-> (->> file-list
+                             (filter #(-> (.getName %) (string/ends-with? checksums-file)))
+                             first)
+                        (read-edn-file resource)
+                        first)]
+    (diff-checksums (compute-checksums norm-list)
+                    edn-content)))
+
+(defmulti ^:private ensure-norms
+  (fn [_conn file-or-resource] (type file-or-resource)))
+
+(defmethod ^:private ensure-norms File [conn file]
+  (let [norm-list (-> (retrieve-file-list file)
+                      filter-file-list
+                      (read-norm-files file))]
+    (transact-norms conn norm-list)))
+
+(defmethod ^:private ensure-norms URL [conn resource]
+  (let [file-list (retrieve-file-list resource)
+        norm-list (-> (filter-file-list file-list)
+                      (read-norm-files resource))]
+    (transact-norms conn norm-list)))
+
+(defn ensure-norms!
+  "Takes Datahike-connection and optional a java.io.File object
+   or java.net.URL to specify the location of your norms.
+   Defaults to the resource `migrations`.
+   Returns nil when successful and throws exception when not.
+
+   Ensures your norms are present on your Datahike database.
+   All the edn-files in this folder and its subfolders are
+   considered migration-files aka norms and will be transacted
+   ordered by their names into your database. All norms that
+   are successfully transacted will have an attribute that
+   marks them as migrated and they will not be applied twice."
+  ([conn]
+   (ensure-norms! conn (io/resource "migrations")))
+  ([conn file-or-resource]
+   (ensure-norms conn file-or-resource)))
+
+(defn update-checksums!
+  "Optionally takes a folder as string. Defaults to the
+   folder `resources/migrations`.
+   Returns nil when successful and throws exception when not.
+
+   All the edn-files in the folder and its subfolders are
+   considered migration-files aka norms. For each of
+   these norms a checksum will be computed and written to
+   the file `checksums.edn`. Each time this fn is run,
+   the `checksums.edn` will be overwritten with the current
+   values.
+   This prevents inadvertent migrations of your database
+   when used in conjunction with a VCS. A merge-conflict
+   should be raised when trying to merge a checksums.edn
+   with stale data."
+  ([]
+   (update-checksums! "resources/migrations"))
+  ([^String norms-folder]
+   (let [file (io/file norms-folder)]
+     (-> (retrieve-file-list file)
+         filter-file-list
+         (read-norm-files file)
+         compute-checksums
+         (#(spit (io/file norms-folder checksums-file)
+                 (with-out-str (pp/pprint %))))))))

package/src/datahike/online_gc.cljc

@@ -0,0 +1,252 @@
+(ns datahike.online-gc
+  "Online garbage collection for freed index nodes.
+
+   Runs incrementally during transaction commits with configurable grace period.
+   Addresses are marked as freed during transient operations (PSS mutations),
+   then deleted after a grace period to ensure concurrent readers don't crash.
+
+   Usage:
+     ;; In datahike config
+     {:online-gc {:enabled? true
+                  :grace-period-ms 60000    ;; 1 minute default
+                  :max-batch 1000}}         ;; Max addresses per GC run
+
+     ;; For bulk imports (no concurrent readers)
+     {:online-gc {:enabled? true
+                  :grace-period-ms 0        ;; No grace period
+                  :max-batch 10000}}
+
+     ;; Background GC (optional)
+     (def stop-ch (start-background-gc! store {...opts...}))
+     ;; Later: (async/close! stop-ch)"
+  (:require [konserve.core :as k]
+            [konserve.utils :refer [multi-key-capable?]]
+            #?@(:clj  [[clojure.core.cache.wrapped :as wrapped]]
+                :cljs [[cljs.cache.wrapped :as wrapped]])
+            [taoensso.timbre :refer [debug trace warn]]
+            [clojure.core.async :as async]
+            [superv.async #?(:clj :refer :cljs :refer-macros) [go-try- <?-]]
+            #?(:cljs [clojure.core.async :refer-macros [go]]))
+  #?(:clj (:import [java.util Date])))
+
+(defn get-time [d]
+  #?(:clj (.getTime ^Date d)
+     :cljs (.getTime d)))
+
+(defn get-and-clear-eligible-freed!
+  "Get ALL freed addresses eligible for deletion based on grace period.
+
+   Arguments:
+     store - The datahike store
+     grace-period-ms - Minimum age before deletion (milliseconds)
+
+   Returns: [addresses-to-delete remaining-freed]
+     - addresses-to-delete: vector of all addresses ready to delete
+     - remaining-freed: vector of [addr ts] pairs still in grace period"
+  [store grace-period-ms]
+  (let [freed-atom (-> store :storage :freed-addresses)
+        freed-set-atom (-> store :storage :freed-set)
+        now #?(:clj (Date.) :cljs (js/Date.))
+        cutoff-time (- (get-time now) grace-period-ms)]
+    (if freed-atom
+      (let [result (atom nil)]
+        (swap! freed-atom
+               (fn [freed-pairs]
+                 (let [eligible (filterv (fn [[_addr ts]]
+                                           (<= (get-time ts) cutoff-time))
+                                         freed-pairs)
+                       remaining (filterv (fn [[_addr ts]]
+                                            (> (get-time ts) cutoff-time))
+                                          freed-pairs)]
+                   (reset! result [(mapv first eligible) remaining])
+                   remaining)))
+        ;; Also clear the freed-set and freed-stacks of eligible addresses
+        (when freed-set-atom
+          (let [[eligible _] @result]
+            (swap! freed-set-atom #(reduce disj % eligible))
+            (when-let [freed-stacks-atom (-> store :storage :freed-stacks)]
+              (swap! freed-stacks-atom #(reduce dissoc % eligible)))))
+        @result)
+      ;; No freed-addresses atom (shouldn't happen with CachedStorage)
+      [[] []])))
+
+(defn recycle-freed-addresses!
+  "Add freed addresses to the storage freelist for reuse instead of deleting.
+   Evicts addresses from cache to prevent stale reads.
+   The actual LMDB entries are overwritten when the address is reused.
+
+   Arguments:
+     store - The datahike store
+     addresses - Vector of addresses to recycle
+
+   Returns: Number of addresses recycled"
+  [store addresses]
+  (if (empty? addresses)
+    0
+    (let [cache (-> store :storage :cache)
+          freelist (-> store :storage :freelist)]
+      (trace "Recycling" (count addresses) "freed addresses to freelist")
+      ;; Evict from cache to prevent stale reads
+      (doseq [addr addresses]
+        (wrapped/evict cache addr))
+      ;; Add all addresses to the freelist for reuse
+      (swap! freelist into addresses)
+      (count addresses))))
+
+(defn delete-freed-addresses!
+  "Delete freed addresses from store and cache.
+   Used as fallback when freelist is not available.
+
+   Arguments:
+     store - The datahike store
+     addresses - Vector of addresses to delete
+     max-batch - Chunk size for multi-dissoc calls
+     sync? - Whether to perform synchronous deletion
+
+   Returns: Number of addresses deleted (async channel or sync value)"
+  [store addresses max-batch sync?]
+  (if (empty? addresses)
+    (if sync? 0 (go-try- 0))
+    (let [cache (-> store :storage :cache)]
+      (trace "Deleting" (count addresses) "freed addresses")
+      ;; Evict from cache first
+      (doseq [addr addresses]
+        (wrapped/evict cache addr))
+      ;; Batch delete from store, chunked by max-batch
+      (if (multi-key-capable? store)
+        (if sync?
+          (do
+            (doseq [chunk (partition-all max-batch addresses)]
+              (k/multi-dissoc store (vec chunk) {:sync? true}))
+            (count addresses))
+          (go-try-
+           (doseq [chunk (partition-all max-batch addresses)]
+             (<?- (k/multi-dissoc store (vec chunk) {:sync? false})))
+           (count addresses)))
+        ;; Fallback to individual deletes for stores without multi-key support
+        (if sync?
+          (do
+            (doseq [addr addresses]
+              (k/dissoc store addr {:sync? true}))
+            (count addresses))
+          (go-try-
+           (doseq [addr addresses]
+             (<?- (k/dissoc store addr {:sync? false})))
+           (count addresses)))))))
+
+(defn online-gc!
+  "Perform online GC during commit.
+   Clears ALL eligible freed addresses each cycle.
+
+   CRITICAL SAFETY WARNINGS:
+   - Online GC is ONLY safe for single-branch databases
+   - Multi-branch databases SKIP online GC entirely (returns 0)
+     Reason: Freed nodes from one branch may still be referenced by other branches
+     through structural sharing. Only offline GC can safely handle multi-branch
+     cleanup via full reachability analysis.
+   - Long-lived readers can be corrupted if grace period is too short
+   - For bulk imports with no readers, set :grace-period-ms 0
+
+   When freelist recycling is available (non-crypto-hash mode, single branch),
+   addresses are added to a freelist for reuse instead of being deleted from
+   the store. This eliminates LMDB delete operations, converting O(freed_nodes)
+   deletes to O(1) append.
+
+   MULTI-BRANCH LIMITATION:
+   Online GC is completely disabled when multiple branches exist. Freed addresses
+   remain in the freed-addresses tracking for offline GC (d/gc-storage) to handle
+   safely through full reachability analysis.
+
+   Options:
+     :grace-period-ms - Minimum age before deletion (default 60000 = 1 minute)
+     :max-batch - Chunk size for store deletion batches (default 10000, only for delete mode)
+     :enabled? - Enable online GC (default false for safety)
+     :sync? - Synchronous deletion (default true, only for delete mode)
+
+   Returns: Number of addresses recycled/deleted (or async channel with count)"
+  [store {:keys [grace-period-ms max-batch enabled? sync?]
+          :or {grace-period-ms 60000
+               max-batch 10000
+               enabled? false
+               sync? true}}]
+  (if-not enabled?
+    (if sync? 0 (go-try- 0))
+    (if sync?
+      ;; Synchronous mode
+      (let [branches (k/get store :branches nil {:sync? true})
+            multi-branch? (> (count branches) 1)]
+        (if multi-branch?
+          (do
+            (debug "Online GC: skipped (multi-branch detected - use offline GC instead)")
+            0)
+          (let [[to-recycle _remaining] (get-and-clear-eligible-freed! store grace-period-ms)]
+            (if (seq to-recycle)
+              (let [freelist (-> store :storage :freelist)
+                    crypto-hash? (-> store :storage :config :crypto-hash?)]
+                (if (and freelist (not crypto-hash?))
+                  (do
+                    (debug "Online GC: recycling" (count to-recycle) "addresses to freelist")
+                    (recycle-freed-addresses! store to-recycle))
+                  (do
+                    (debug "Online GC: deleting" (count to-recycle) "addresses")
+                    (delete-freed-addresses! store to-recycle max-batch true))))
+              0))))
+      ;; Asynchronous mode
+      (go-try-
+       (let [branches (<?- (k/get store :branches nil {:sync? false}))
+             multi-branch? (> (count branches) 1)]
+         (if multi-branch?
+           (do
+             (debug "Online GC: skipped (multi-branch detected - use offline GC instead)")
+             0)
+           (let [[to-recycle _remaining] (get-and-clear-eligible-freed! store grace-period-ms)]
+             (if (seq to-recycle)
+               (let [freelist (-> store :storage :freelist)
+                     crypto-hash? (-> store :storage :config :crypto-hash?)]
+                 (if (and freelist (not crypto-hash?))
+                   (do
+                     (debug "Online GC: recycling" (count to-recycle) "addresses to freelist")
+                     (recycle-freed-addresses! store to-recycle))
+                   (do
+                     (debug "Online GC: deleting" (count to-recycle) "addresses")
+                     (<?- (delete-freed-addresses! store to-recycle max-batch false)))))
+               0))))))))
+
+(defn start-background-gc!
+  "Start a background process that periodically runs online GC.
+
+   Arguments:
+     store - The datahike store
+     options - GC configuration map
+       :grace-period-ms - Minimum age before deletion (default 60000 = 1 minute)
+       :interval-ms - How often to run GC (default 10000 = 10 seconds)
+       :max-batch - Maximum addresses to delete per run (default 1000)
+
+   Returns: A channel that can be closed to stop the background GC
+
+   Example:
+     (def stop-ch (start-background-gc! store {:grace-period-ms 60000
+                                               :interval-ms 10000
+                                               :max-batch 1000}))
+     ;; Later, to stop:
+     (async/close! stop-ch)"
+  [store {:keys [grace-period-ms interval-ms max-batch]
+          :or {grace-period-ms 60000
+               interval-ms 10000
+               max-batch 1000}}]
+  (let [stop-ch (async/chan)]
+    (async/go-loop []
+      (let [[_ ch] (async/alts! [stop-ch (async/timeout interval-ms)])]
+        (when-not (= ch stop-ch)
+          ;; Run GC asynchronously
+          (try
+            (let [deleted (async/<! (online-gc! store {:grace-period-ms grace-period-ms
+                                                       :max-batch max-batch
+                                                       :enabled? true
+                                                       :sync? false}))]
+              (when (and deleted (pos? deleted))
+                (debug "Background GC deleted" deleted "addresses")))
+            (catch #?(:clj Exception :cljs js/Error) e
+              (warn "Background GC error:" e)))
+          (recur))))
+    stop-ch))