factbase 0.17.1 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91ef3ed499ea15abb77bc39cfed30eb9af704921e86c3c03c7bdd9b13cb44270
-  data.tar.gz: 3c2e80d00620e0de14ec4be35ff08b28393793c69742dda9bda55c4a5ae01c8f
+  metadata.gz: c20d4add4664149fc5c070ec64321a79c8ac07ef81c69ae2b64bac1e9fd0c4e9
+  data.tar.gz: ff9a8f121d9cfafa6ad97a634c79fc2ec834a07ee0d17042eb3fc5fa8c529501
 SHA512:
-  metadata.gz: 9c6e18a32a5ae773e78672e449cce031a2c7641b1291b9f637ccb28afb6afddc87091955ce06e75c0e35326f4db37b04fac5b827b1cdc203a8b0262c105ca2c3
-  data.tar.gz: 923207d8494313e1af4fae0ecf3068372a5dde28924840edbe1b6d625127afb7e4eb2cf44c9f86a28d9d7fc650336abce9c9b99cd492b3ff29bcbb4cf214c83e
+  metadata.gz: 3f93283308d6f15766fca09f253da85145efc28975e51259ee88f0954cc6a7f584700de2ff604478bd5a48f1c86153243949a6280732a466412a739f38e9a1e2
+  data.tar.gz: e21602f7612821dd2389e831056389900f62a3ef3b1bf998f6ebbe722cfc9684357383c754ad0556a346534cf7a6bc76489706e0f0f58ea23336a918be71b442

data/Gemfile

@@ -12,7 +12,7 @@ gem 'minitest-reporters', '~>1.7', require: false
 gem 'os', '~>1.1', require: false
 gem 'qbash', '~>0.4', require: false
 gem 'rake', '~>13.2', require: false
-gem 'rdoc', '6.16.1', require: false # GPL
+gem 'rdoc', '6.17.0', require: false # GPL
 gem 'rubocop', '~>1.74', require: false
 gem 'rubocop-minitest', '~>0.38', require: false
 gem 'rubocop-performance', '~>1.25', require: false

data/Gemfile.lock

@@ -68,7 +68,7 @@ GEM
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
-    rdoc (6.16.1)
+    rdoc (6.17.0)
       erb
       psych (>= 4.0.0)
       tsort
@@ -126,6 +126,7 @@ PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-24
+  arm64-darwin-25
   x64-mingw-ucrt
   x86_64-darwin-20
   x86_64-darwin-21
@@ -140,7 +141,7 @@ DEPENDENCIES
   os (~> 1.1)
   qbash (~> 0.4)
   rake (~> 13.2)
-  rdoc (= 6.16.1)
+  rdoc (= 6.17.0)
   rubocop (~> 1.74)
   rubocop-minitest (~> 0.38)
   rubocop-performance (~> 1.25)

data/README.md

@@ -210,36 +210,54 @@ This is the result of the benchmark:
 
 <!-- benchmark_begin -->
 ```text
-                                                                   user
-insert 20000 facts                                             0.637574
-export 20000 facts                                             0.019855
-import 410750 bytes (20000 facts)                              0.035065
-insert 10 facts                                                0.044615
-query 10 times w/txn                                           2.455739
-query 10 times w/o txn                                         0.050423
-modify 10 attrs w/txn                                          1.894240
-delete 10 facts w/txn                                          1.043079
-(and (eq what 'issue-was-closed') (exists... -> 200            1.279827
-(and (eq what 'issue-was-closed') (exists... -> 200/txn        1.263302
-(and (eq what 'issue-was-closed') (exists... -> zero           1.253773
-(and (eq what 'issue-was-closed') (exists... -> zero/txn       1.292489
-(gt time '2024-03-23T03:21:43Z')                               0.398074
-(gt cost 50)                                                   0.254020
-(eq title 'Object Thinking 5000')                              0.037238
-(and (eq foo 42.998) (or (gt bar 200) (absent z...             0.047599
-(and (exists foo) (not (exists blue)))                         1.115156
-(eq id (agg (always) (max id)))                                0.711832
-(join "c<=cost,b<=bar" (eq id (agg (always) (ma...             1.393622
-(and (eq what "foo") (join "w<=what" (and (eq i...             7.428505
-delete!                                                        0.272962
-Taped.append() x50000                                          0.020619
-Taped.each() x125                                              1.721876
-Taped.delete_if() x375                                         0.844673
+                                                                       
+query all facts from an empty factbase                             0.00
+insert 20000 facts                                                 0.67
+export 20000 facts                                                 0.02
+import 411032 bytes (20000 facts)                                  0.03
+insert 10 facts                                                    0.04
+query 10 times w/txn                                               2.52
+query 10 times w/o txn                                             0.05
+modify 10 attrs w/txn                                              1.84
+delete 10 facts w/txn                                              2.98
+build index on 5000 facts                                          0.05
+export 5000 facts with index                                       0.03
+import 5000 facts with persisted index                             0.05
+query 5000 facts using persisted index                             0.11
+export 5000 facts without index                                    0.00
+import 5000 facts without index                                    0.04
+query 5000 facts building index on-the-fly                         0.10
+(and (eq what 'issue-was-closed') (exists... -> 200                1.21
+(and (eq what 'issue-was-closed') (exists... -> 200/txn            1.20
+(and (eq what 'issue-was-closed') (exists... -> zero               1.21
+(and (eq what 'issue-was-closed') (exists... -> zero/txn           1.23
+transaction rollback on factbase with 100000 facts                 0.25
+(gt time '2024-03-23T03:21:43Z')                                   0.33
+(gt cost 50)                                                       0.21
+(eq title 'Object Thinking 5000')                                  0.05
+(and (eq foo 42.998) (or (gt bar 200) (absent z...                 0.05
+(and (exists foo) (not (exists blue)))                             1.68
+(eq id (agg (always) (max id)))                                    2.76
+(join "c<=cost,b<=bar" (eq id (agg (always) (ma...                 4.02
+(and (eq what "foo") (join "w<=what" (and (eq i...                 7.68
+delete!                                                            0.56
+(and (eq issue *) (eq repository *) (eq what '*') (eq where '*'))  2.75
+Taped.append() x50000                                              0.16
+Taped.each() x125                                                  1.63
+Taped.delete_if() x375                                             0.84
+50000 facts: read-only txn (no copy needed)                        7.60
+50000 facts: rollback txn (no copy needed)                         7.47
+50000 facts: insert in txn (copy triggered)                        3.64
+50000 facts: modify in txn (copy triggered)                       39.42
+100000 facts: read-only txn (no copy needed)                      15.23
+100000 facts: rollback txn (no copy needed)                       15.17
+100000 facts: insert in txn (copy triggered)                       7.45
+100000 facts: modify in txn (copy triggered)                      73.97
 ```
 
 The results were calculated in [this GHA job][benchmark-gha]
-on 2025-10-15 at 14:53,
+on 2025-12-11 at 13:29,
 on Linux with 4 CPUs.
 <!-- benchmark_end -->
 
-[benchmark-gha]: https://github.com/yegor256/factbase/actions/runs/18533080805
+[benchmark-gha]: https://github.com/yegor256/factbase/actions/runs/20134646978

data/lib/factbase/cached/cached_fact.rb

@@ -6,7 +6,7 @@
 require 'others'
 require_relative '../../factbase'
 
-# A single fact in a factbase, which is sentitive to changes.
+# A single fact in a factbase, which is sensitive to changes.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
@@ -15,9 +15,11 @@ class Factbase::CachedFact
   # Ctor.
   # @param [Factbase::Fact] origin The original fact
   # @param [Hash] cache Cache of queries (to clean it on attribute addition)
-  def initialize(origin, cache)
+  # @param [Boolean] fresh True if this is a newly inserted fact (not yet in cache)
+  def initialize(origin, cache, fresh: false)
     @origin = origin
     @cache = cache
+    @fresh = fresh
   end
 
   def to_s
@@ -26,7 +28,9 @@ class Factbase::CachedFact
 
   # When a method is missing, this method is called.
   others do |*args|
-    @cache.clear if args[0].to_s.end_with?('=')
+    # Only clear cache when modifying properties on existing (non-fresh) facts
+    # Fresh facts are not in the cache yet, so modifications don't affect it
+    @cache.clear if args[0].to_s.end_with?('=') && !@fresh
     @origin.send(*args)
   end
 end

data/lib/factbase/cached/cached_factbase.rb

@@ -31,8 +31,7 @@ class Factbase::CachedFactbase
   # Insert a new fact and return it.
   # @return [Factbase::Fact] The fact just inserted
   def insert
-    @cache.clear
-    Factbase::CachedFact.new(@origin.insert, @cache)
+    Factbase::CachedFact.new(@origin.insert, @cache, fresh: true)
   end
 
   # Convert a query to a term.

data/lib/factbase/indexed/indexed_absent.rb

@@ -13,13 +13,19 @@ class Factbase::IndexedAbsent
   def predict(maps, _fb, _params)
     return nil if @idx.nil?
     key = [maps.object_id, @term.operands.first, @term.op]
-    if @idx[key].nil?
-      @idx[key] = []
+    entry = @idx[key]
+    maps_array = maps.to_a
+    if entry.nil?
+      entry = { facts: [], indexed_count: 0 }
+      @idx[key] = entry
+    end
+    if entry[:indexed_count] < maps_array.size
       prop = @term.operands.first.to_s
-      maps.to_a.each do |m|
-        @idx[key].append(m) if m[prop].nil?
+      maps_array[entry[:indexed_count]..].each do |m|
+        entry[:facts] << m if m[prop].nil?
       end
+      entry[:indexed_count] = maps_array.size
     end
-    (maps & []) | @idx[key]
+    (maps & []) | entry[:facts]
   end
 end

data/lib/factbase/indexed/indexed_and.rb

@@ -18,14 +18,20 @@ class Factbase::IndexedAnd
       && @term.operands.all? { |o| o.operands.first.is_a?(Symbol) && _scalar?(o.operands[1]) }
       props = @term.operands.map { |o| o.operands.first }.sort
       key = [maps.object_id, props, :multi_and_eq]
-      if @idx[key].nil?
-        @idx[key] = {}
-        maps.to_a.each do |m|
+      entry = @idx[key]
+      maps_array = maps.to_a
+      if entry.nil?
+        entry = { index: {}, indexed_count: 0 }
+        @idx[key] = entry
+      end
+      if entry[:indexed_count] < maps_array.size
+        maps_array[entry[:indexed_count]..].each do |m|
           _all_tuples(m, props).each do |t|
-            @idx[key][t] = [] if @idx[key][t].nil?
-            @idx[key][t].append(m)
+            entry[:index][t] ||= []
+            entry[:index][t] << m
           end
         end
+        entry[:indexed_count] = maps_array.size
       end
       tuples = Enumerator.product(
         *@term.operands.sort_by { |o| o.operands.first }.map do |o|
@@ -36,7 +42,7 @@ class Factbase::IndexedAnd
           end
         end
       )
-      j = tuples.map { |t| @idx[key][t] || [] }.reduce(&:|)
+      j = tuples.map { |t| entry[:index][t] || [] }.reduce(&:|)
       r = (maps & []) | j
     else
       @term.operands.each do |o|

data/lib/factbase/indexed/indexed_eq.rb

@@ -14,15 +14,21 @@ class Factbase::IndexedEq
     return nil if @idx.nil?
     key = [maps.object_id, @term.operands.first, @term.op]
     return unless @term.operands.first.is_a?(Symbol) && _scalar?(@term.operands[1])
-    if @idx[key].nil?
-      @idx[key] = {}
+    entry = @idx[key]
+    maps_array = maps.to_a
+    if entry.nil?
+      entry = { index: {}, indexed_count: 0 }
+      @idx[key] = entry
+    end
+    if entry[:indexed_count] < maps_array.size
       prop = @term.operands.first.to_s
-      maps.to_a.each do |m|
+      maps_array[entry[:indexed_count]..].each do |m|
         m[prop]&.each do |v|
-          @idx[key][v] = [] if @idx[key][v].nil?
-          @idx[key][v].append(m)
+          entry[:index][v] ||= []
+          entry[:index][v] << m
         end
       end
+      entry[:indexed_count] = maps_array.size
     end
     vv =
       if @term.operands[1].is_a?(Symbol)
@@ -33,7 +39,7 @@ class Factbase::IndexedEq
     if vv.empty?
       (maps & [])
     else
-      j = vv.map { |v| @idx[key][v] || [] }.reduce(&:|)
+      j = vv.map { |v| entry[:index][v] || [] }.reduce(&:|)
       (maps & []) | j
     end
   end

data/lib/factbase/indexed/indexed_exists.rb

@@ -13,13 +13,19 @@ class Factbase::IndexedExists
   def predict(maps, _fb, _params)
     return nil if @idx.nil?
     key = [maps.object_id, @term.operands.first, @term.op]
-    if @idx[key].nil?
-      @idx[key] = []
+    entry = @idx[key]
+    maps_array = maps.to_a
+    if entry.nil?
+      entry = { facts: [], indexed_count: 0 }
+      @idx[key] = entry
+    end
+    if entry[:indexed_count] < maps_array.size
       prop = @term.operands.first.to_s
-      maps.to_a.each do |m|
-        @idx[key].append(m) unless m[prop].nil?
+      maps_array[entry[:indexed_count]..].each do |m|
+        entry[:facts] << m unless m[prop].nil?
       end
+      entry[:indexed_count] = maps_array.size
     end
-    (maps & []) | @idx[key]
+    (maps & []) | entry[:facts]
   end
 end

data/lib/factbase/indexed/indexed_fact.rb

@@ -6,7 +6,7 @@
 require 'others'
 require_relative '../../factbase'
 
-# A single fact in a factbase, which is sentitive to changes.
+# A single fact in a factbase, which is sensitive to changes.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
@@ -15,9 +15,11 @@ class Factbase::IndexedFact
   # Ctor.
   # @param [Factbase::Fact] origin The original fact
   # @param [Hash] idx The index
-  def initialize(origin, idx)
+  # @param [Boolean] fresh True if this is a newly inserted fact (not yet in index)
+  def initialize(origin, idx, fresh: false)
     @origin = origin
     @idx = idx
+    @fresh = fresh
   end
 
   def to_s
@@ -26,7 +28,9 @@ class Factbase::IndexedFact
 
   # When a method is missing, this method is called.
   others do |*args|
-    @idx.clear if args[0].to_s.end_with?('=')
+    # Only clear index when modifying properties on existing (non-fresh) facts
+    # Fresh facts are not in the index yet, so modifications don't affect it
+    @idx.clear if args[0].to_s.end_with?('=') && !@fresh
     @origin.send(*args)
   end
 end

data/lib/factbase/indexed/indexed_factbase.rb

@@ -31,8 +31,7 @@ class Factbase::IndexedFactbase
   # Insert a new fact and return it.
   # @return [Factbase::Fact] The fact just inserted
   def insert
-    @idx.clear
-    Factbase::IndexedFact.new(@origin.insert, @idx)
+    Factbase::IndexedFact.new(@origin.insert, @idx, fresh: true)
   end
 
   # Convert a query to a term.

data/lib/factbase/indexed/indexed_gt.rb

@@ -15,21 +15,27 @@ class Factbase::IndexedGt
     return unless @term.operands.first.is_a?(Symbol) && _scalar?(@term.operands[1])
     prop = @term.operands.first.to_s
     cache_key = [maps.object_id, @term.operands.first, :sorted]
-    if @idx[cache_key].nil?
-      @idx[cache_key] = []
-      maps.to_a.each do |m|
+    entry = @idx[cache_key]
+    maps_array = maps.to_a
+    if entry.nil?
+      entry = { sorted: [], indexed_count: 0 }
+      @idx[cache_key] = entry
+    end
+    if entry[:indexed_count] < maps_array.size
+      maps_array[entry[:indexed_count]..].each do |m|
         values = m[prop]
         next if values.nil?
         values.each do |v|
-          @idx[cache_key] << [v, m]
+          entry[:sorted] << [v, m]
         end
       end
-      @idx[cache_key].sort_by! { |pair| pair[0] }
+      entry[:sorted].sort_by! { |pair| pair[0] }
+      entry[:indexed_count] = maps_array.size
     end
     threshold = @term.operands[1].is_a?(Symbol) ? params[@term.operands[1].to_s]&.first : @term.operands[1]
     return nil if threshold.nil?
-    i = @idx[cache_key].bsearch_index { |pair| pair[0] > threshold } || @idx[cache_key].size
-    result = @idx[cache_key][i..].map { |pair| pair[1] }.uniq
+    i = entry[:sorted].bsearch_index { |pair| pair[0] > threshold } || entry[:sorted].size
+    result = entry[:sorted][i..].map { |pair| pair[1] }.uniq
     (maps & []) | result
   end
 

data/lib/factbase/indexed/indexed_lt.rb

@@ -15,21 +15,32 @@ class Factbase::IndexedLt
     return unless @term.operands.first.is_a?(Symbol) && _scalar?(@term.operands[1])
     prop = @term.operands.first.to_s
     cache_key = [maps.object_id, @term.operands.first, :sorted]
-    if @idx[cache_key].nil?
-      @idx[cache_key] = []
-      maps.to_a.each do |m|
+    entry = @idx[cache_key]
+    maps_array = maps.to_a
+    if entry.nil?
+      entry = { sorted: [], indexed_count: 0 }
+      @idx[cache_key] = entry
+    end
+    if entry[:indexed_count] < maps_array.size
+      new_pairs = []
+      maps_array[entry[:indexed_count]..].each do |m|
         values = m[prop]
         next if values.nil?
         values.each do |v|
-          @idx[cache_key] << [v, m]
+          new_pairs << [v, m]
         end
       end
-      @idx[cache_key].sort_by! { |pair| pair[0] }
+      unless new_pairs.empty?
+        entry[:sorted].concat(new_pairs)
+        entry[:sorted].sort_by! { |pair| pair[0] }
+      end
+      entry[:indexed_count] = maps_array.size
     end
+
     threshold = @term.operands[1].is_a?(Symbol) ? params[@term.operands[1].to_s]&.first : @term.operands[1]
     return nil if threshold.nil?
-    i = @idx[cache_key].bsearch_index { |pair| pair[0] >= threshold } || @idx[cache_key].size
-    result = @idx[cache_key][0...i].map { |pair| pair[1] }.uniq
+    i = entry[:sorted].bsearch_index { |pair| pair[0] >= threshold } || entry[:sorted].size
+    result = entry[:sorted][0...i].map { |pair| pair[1] }.uniq
     (maps & []) | result
   end
 

data/lib/factbase/indexed/indexed_not.rb

@@ -13,16 +13,25 @@ class Factbase::IndexedNot
   def predict(maps, fb, params)
     return nil if @idx.nil?
     key = [maps.object_id, @term.operands.first, @term.op]
-    if @idx[key].nil?
+    entry = @idx[key]
+    maps_array = maps.to_a
+    if entry.nil?
+      entry = { facts: nil, indexed_count: 0, yes_set: nil }
+      @idx[key] = entry
+    end
+    if entry[:indexed_count] < maps_array.size
       yes = @term.operands.first.predict(maps, fb, params)
       if yes.nil?
-        @idx[key] = { r: nil }
+        entry[:facts] = nil
+        entry[:yes_set] = nil
       else
-        yes = yes.to_a.to_set
-        @idx[key] = { r: maps.to_a.reject { |m| yes.include?(m) } }
+        yes_set = yes.to_a.to_set
+        entry[:yes_set] = yes_set
+        entry[:facts] = maps_array.reject { |m| yes_set.include?(m) }
       end
+      entry[:indexed_count] = maps_array.size
     end
-    r = @idx[key][:r]
+    r = entry[:facts]
     if r.nil?
       nil
     else

data/lib/factbase/indexed/indexed_one.rb

@@ -13,13 +13,19 @@ class Factbase::IndexedOne
   def predict(maps, _fb, _params)
     return nil if @idx.nil?
     key = [maps.object_id, @term.operands.first, @term.op]
-    if @idx[key].nil?
-      @idx[key] = []
+    entry = @idx[key]
+    maps_array = maps.to_a
+    if entry.nil?
+      entry = { facts: [], indexed_count: 0 }
+      @idx[key] = entry
+    end
+    if entry[:indexed_count] < maps_array.size
       prop = @term.operands.first.to_s
-      maps.to_a.each do |m|
-        @idx[key].append(m) if !m[prop].nil? && m[prop].size == 1
+      maps_array[entry[:indexed_count]..].each do |m|
+        entry[:facts] << m if !m[prop].nil? && m[prop].size == 1
       end
+      entry[:indexed_count] = maps_array.size
     end
-    (maps & []) | @idx[key]
+    (maps & []) | entry[:facts]
   end
 end

data/lib/factbase/indexed/indexed_unique.rb

@@ -16,10 +16,19 @@ class Factbase::IndexedUnique
   def predict(maps, _fb, _params)
     return nil if @idx.nil?
     key = [maps.object_id, @term.operands.first, @term.op]
-    if @idx[key].nil?
+    entry = @idx[key]
+    maps_array = maps.to_a
+    if entry.nil?
+      entry = { facts: [], indexed_count: 0 }
+      @idx[key] = entry
+    end
+    if entry[:indexed_count] < maps_array.size
       props = @term.operands.map(&:to_s)
-      @idx[key] = maps.to_a.select { |m| props.all? { |p| !m[p].nil? } }
+      maps_array[entry[:indexed_count]..].each do |m|
+        entry[:facts] << m if props.all? { |p| !m[p].nil? }
+      end
+      entry[:indexed_count] = maps_array.size
     end
-    (maps & []) | @idx[key]
+    (maps & []) | entry[:facts]
   end
 end

data/lib/factbase/lazy_taped.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../factbase'
+require_relative 'taped'
+require_relative 'lazy_taped_hash'
+
+# A lazy decorator of an Array with HashMaps that defers copying until modification.
+class Factbase::LazyTaped
+  def initialize(origin)
+    @origin = origin
+    @copied = false
+    @maps = nil
+    @pairs = nil
+    @inserted = []
+    @deleted = []
+    @added = []
+  end
+
+  # Returns a hash mapping copied maps to their originals.
+  # This is used during transaction commit to identify which original facts
+  # were modified, allowing the factbase to update the correct entries.
+  def pairs
+    return {} unless @pairs
+    result = {}.compare_by_identity
+    @pairs.each { |copied, original| result[copied] = original }
+    result
+  end
+
+  # Returns the unique object IDs of maps that were inserted (newly created).
+  # This is used during transaction commit to identify new facts that need
+  # to be added to the factbase.
+  def inserted
+    @inserted.uniq
+  end
+
+  # Returns the unique object IDs of maps that were deleted.
+  # This is used during transaction commit to identify facts that need
+  # to be removed from the factbase.
+  def deleted
+    @deleted.uniq
+  end
+
+  # Returns the unique object IDs of maps that were modified (properties added).
+  # This is used during transaction commit to track the churn (number of changes).
+  def added
+    @added.uniq
+  end
+
+  def find_by_object_id(oid)
+    (@maps || @origin).find { |m| m.object_id == oid }
+  end
+
+  def size
+    (@maps || @origin).size
+  end
+
+  def empty?
+    (@maps || @origin).empty?
+  end
+
+  def <<(map)
+    ensure_copied
+    @maps << map
+    @inserted.append(map.object_id)
+  end
+
+  def each
+    return to_enum(__method__) unless block_given?
+    if @copied
+      @maps.each do |m|
+        yield Factbase::Taped::TapedHash.new(m, @added)
+      end
+    else
+      @origin.each do |m|
+        yield LazyTapedHash.new(m, self, @added)
+      end
+    end
+  end
+
+  def delete_if
+    ensure_copied
+    @maps.delete_if do |m|
+      r = yield m
+      @deleted.append(@pairs[m].object_id) if r
+      r
+    end
+  end
+
+  def to_a
+    (@maps || @origin).to_a
+  end
+
+  def &(other)
+    if other == [] || (@maps || @origin).empty?
+      return Factbase::Taped.new([], inserted: @inserted, deleted: @deleted, added: @added)
+    end
+    join(other, &:&)
+  end
+
+  def |(other)
+    return Factbase::Taped.new(to_a, inserted: @inserted, deleted: @deleted, added: @added) if other == []
+    if (@maps || @origin).empty?
+      return Factbase::Taped.new(other, inserted: @inserted, deleted: @deleted, added: @added)
+    end
+    join(other, &:|)
+  end
+
+  def ensure_copied
+    return if @copied
+    @pairs = {}.compare_by_identity
+    @maps =
+      @origin.map do |m|
+        n = m.transform_values(&:dup)
+        @pairs[n] = m
+        n
+      end
+    @copied = true
+  end
+
+  def get_copied_map(original_map)
+    ensure_copied
+    @maps.find { |m| @pairs[m].equal?(original_map) }
+  end
+
+  private
+
+  def join(other)
+    n = yield (@maps || @origin).to_a, other.to_a
+    raise 'Cannot join with another Taped' if other.respond_to?(:inserted)
+    raise 'Can only join with array' unless other.is_a?(Array)
+    Factbase::Taped.new(
+      n,
+      inserted: @inserted,
+      deleted: @deleted,
+      added: @added
+    )
+  end
+end

data/lib/factbase/lazy_taped_array.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../factbase'
+
+class Factbase::LazyTaped
+  # Decorator of Array that triggers copy-on-write.
+  # @todo #424:30min Add dedicated unit tests for LazyTapedArray class.
+  #  Currently this class is tested indirectly through LazyTaped tests.
+  #  We should add explicit tests for all public methods including each, [],
+  #  to_a, any?, <<, and uniq! to ensure proper copy-on-write behavior.
+  class LazyTapedArray
+    # Creates a new lazy array wrapper.
+    # @param origin [Array] The original array to wrap
+    # @param key [String] The key in the parent hash where this array is stored
+    # @param taped_hash [LazyTapedHash] The parent hash wrapper that owns this array
+    # @param added [Array] Accumulator for tracking object IDs of modified facts
+    def initialize(origin, key, taped_hash, added)
+      @origin = origin
+      @key = key
+      @taped_hash = taped_hash
+      @added = added
+    end
+
+    def each(&)
+      return to_enum(__method__) unless block_given?
+      current_array.each(&)
+    end
+
+    def [](idx)
+      current_array[idx]
+    end
+
+    def to_a
+      current_array.to_a
+    end
+
+    def any?(pattern = nil, &)
+      pattern ? current_array.any?(pattern) : current_array.any?(&)
+    end
+
+    def <<(item)
+      @taped_hash.ensure_copied_map
+      @added.append(@taped_hash.tracking_id)
+      @taped_hash.get_copied_array(@key) << item
+    end
+
+    def uniq!
+      @taped_hash.ensure_copied_map
+      @added.append(@taped_hash.tracking_id)
+      @taped_hash.get_copied_array(@key).uniq!
+    end
+
+    private
+
+    def current_array
+      @taped_hash.copied? ? @taped_hash.get_copied_array(@key) : @origin
+    end
+  end
+end

data/lib/factbase/lazy_taped_hash.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../factbase'
+require_relative 'lazy_taped_array'
+
+class Factbase::LazyTaped
+  # Decorator of Hash that triggers copy-on-write.
+  # @todo #424:30min Add dedicated unit tests for LazyTapedHash class.
+  #  Currently this class is tested indirectly through LazyTaped tests.
+  #  We should add explicit tests for all public methods including keys, map,
+  #  bracket access, bracket assignment, and the copy-on-write behavior.
+  class LazyTapedHash
+    # Creates a new LazyTapedHash decorator.
+    # @param origin [Hash] The original hash being wrapped (not yet copied)
+    # @param lazy_taped [Factbase::LazyTaped] The parent LazyTaped instance that manages copy-on-write
+    # @param added [Array] Array to track object IDs of maps that have been modified
+    def initialize(origin, lazy_taped, added)
+      @origin = origin
+      @lazy_taped = lazy_taped
+      @added = added
+      @copied_map = nil
+    end
+
+    def keys
+      current_map.keys
+    end
+
+    def map(&)
+      current_map.map(&)
+    end
+
+    def [](key)
+      v = current_map[key]
+      v = LazyTapedArray.new(v, key, self, @added) if v.is_a?(Array)
+      v
+    end
+
+    def []=(key, value)
+      ensure_copied_map
+      @copied_map[key] = value
+      @added.append(@copied_map.object_id)
+    end
+
+    def ensure_copied_map
+      return if @copied_map
+      @copied_map = @lazy_taped.get_copied_map(@origin)
+    end
+
+    def get_copied_array(key)
+      ensure_copied_map
+      @copied_map[key]
+    end
+
+    def tracking_id
+      @copied_map ? @copied_map.object_id : @origin.object_id
+    end
+
+    def copied?
+      !@copied_map.nil?
+    end
+
+    private
+
+    def current_map
+      @copied_map || @origin
+    end
+
+    def method_missing(method, *, &)
+      current_map.send(method, *, &)
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      current_map.respond_to?(method, include_private)
+    end
+  end
+end

data/lib/factbase/term.rb

@@ -86,7 +86,7 @@ require_relative 'terms/max'
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
-class Factbase::Term
+class Factbase::Term < Factbase::TermBase
   # The operator of this term
   # @return [Symbol] The operator
   attr_reader :op
@@ -95,13 +95,11 @@ class Factbase::Term
   # @return [Array] The operands
   attr_reader :operands
 
-  require_relative 'terms/shared'
-  include Factbase::TermShared
-
   # Ctor.
   # @param [Symbol] operator Operator
   # @param [Array] operands Operands
   def initialize(operator, operands)
+    super()
     @op = operator
     @operands = operands
     @terms = {

data/lib/factbase/terms/agg.rb

@@ -26,7 +26,7 @@ class Factbase::Agg < Factbase::TermBase
       raise "A term is expected, but '#{selector}' provided"
     end
     term = @operands[1]
-    unless term.is_a?(Factbase::Term) || selector.is_a?(Factbase::TermBase)
+    unless term.is_a?(Factbase::Term) || term.is_a?(Factbase::TermBase)
       raise "A term is expected, but '#{term}' provided"
     end
     subset = fb.query(selector, maps).each(fb, fact).to_a

data/lib/factbase/terms/base.rb

@@ -10,8 +10,61 @@
 
 # Base class for all terms.
 class Factbase::TermBase
-  require_relative 'shared'
-  include Factbase::TermShared
+  # Turns it into a string.
+  # @return [String] The string of it
+  def to_s
+    @to_s ||=
+      begin
+        items = []
+        items << @op
+        items +=
+          @operands.map do |o|
+            if o.is_a?(String)
+              "'#{o.gsub("'", "\\\\'").gsub('"', '\\\\"')}'"
+            elsif o.is_a?(Time)
+              o.utc.iso8601
+            else
+              o.to_s
+            end
+          end
+        "(#{items.join(' ')})"
+      end
+  end
 
-  protected :assert_args, :_by_symbol, :_values, :to_s
+  private
+
+  def assert_args(num)
+    c = @operands.size
+    raise "Too many (#{c}) operands for '#{@op}' (#{num} expected)" if c > num
+    raise "Too few (#{c}) operands for '#{@op}' (#{num} expected)" if c < num
+  end
+
+  def _by_symbol(pos, fact)
+    o = @operands[pos]
+    raise "A symbol expected at ##{pos}, but '#{o}' (#{o.class}) provided" unless o.is_a?(Symbol)
+    k = o.to_s
+    fact[k]
+  end
+
+  # @return [Array|nil] Either array of values or NIL
+  def _values(pos, fact, maps, fb)
+    v = @operands[pos]
+    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::Term)
+    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::TermBase)
+    v = fact[v.to_s] if v.is_a?(Symbol)
+    return v if v.nil?
+    unless v.is_a?(Array)
+      v =
+        if v.respond_to?(:each)
+          v.to_a
+        else
+          [v]
+        end
+    end
+    raise 'Why not array?' unless v.is_a?(Array)
+    unless v.all? { |i| [Float, Integer, String, Time, TrueClass, FalseClass].any? { |t| i.is_a?(t) } }
+      raise 'Wrong type inside'
+    end
+    v
+  end
 end

data/lib/factbase/version.rb

@@ -9,5 +9,5 @@
 # License:: MIT
 class Factbase
   # Current version of the gem (changed by .rultor.yml on every release)
-  VERSION = '0.17.1' unless const_defined?(:VERSION)
+  VERSION = '0.19.0' unless const_defined?(:VERSION)
 end

data/lib/factbase.rb

@@ -164,17 +164,8 @@ class Factbase
   #
   # @return [Factbase::Churn] How many facts have been changed (zero if rolled back)
   def txn
-    pairs = {}
-    before =
-      @maps.map do |m|
-        n = m.transform_values(&:dup)
-        # rubocop:disable Lint/HashCompareByIdentity
-        pairs[n.object_id] = m.object_id
-        # rubocop:enable Lint/HashCompareByIdentity
-        n
-      end
-    require_relative 'factbase/taped'
-    taped = Factbase::Taped.new(before)
+    require_relative 'factbase/lazy_taped'
+    taped = Factbase::LazyTaped.new(@maps)
     require_relative 'factbase/churn'
     churn = Factbase::Churn.new
     catch :commit do
@@ -188,30 +179,32 @@ class Factbase
     rescue Factbase::Rollback
       return churn
     end
-    seen = []
-    garbage = []
+    seen = {}.compare_by_identity
+    garbage = {}.compare_by_identity
+    pairs = taped.pairs
     taped.deleted.each do |oid|
-      garbage << pairs[oid]
-      seen << oid
+      original = @maps.find { |m| m.object_id == oid }
+      next if original.nil?
+      garbage[original] = true
       churn.append(0, 1, 0)
     end
     taped.inserted.each do |oid|
-      next if seen.include?(oid)
       b = taped.find_by_object_id(oid)
       next if b.nil?
-      seen << oid
+      next if seen.key?(b)
+      seen[b] = true
       @maps << b
       churn.append(1, 0, 0)
     end
     taped.added.each do |oid|
-      next if seen.include?(oid)
       b = taped.find_by_object_id(oid)
       next if b.nil?
-      garbage << pairs[oid]
+      next if seen.key?(b)
+      garbage[pairs[b]] = true
       @maps << b
       churn.append(0, 0, 1)
     end
-    @maps.delete_if { |m| garbage.include?(m.object_id) } unless garbage.empty?
+    @maps.delete_if { |m| garbage.key?(m) } unless garbage.empty?
     churn
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: factbase
 version: !ruby/object:Gem::Version
-  version: 0.17.1
+  version: 0.19.0
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -195,6 +195,9 @@ files:
 - lib/factbase/indexed/indexed_term.rb
 - lib/factbase/indexed/indexed_unique.rb
 - lib/factbase/inv.rb
+- lib/factbase/lazy_taped.rb
+- lib/factbase/lazy_taped_array.rb
+- lib/factbase/lazy_taped_hash.rb
 - lib/factbase/light.rb
 - lib/factbase/logged.rb
 - lib/factbase/pre.rb
@@ -248,7 +251,6 @@ files:
 - lib/factbase/terms/or.rb
 - lib/factbase/terms/plus.rb
 - lib/factbase/terms/prev.rb
-- lib/factbase/terms/shared.rb
 - lib/factbase/terms/simplified.rb
 - lib/factbase/terms/size.rb
 - lib/factbase/terms/sorted.rb

data/lib/factbase/terms/shared.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
-# SPDX-License-Identifier: MIT
-
-# This module provides shared methods for Factbase terms, including argument validation,
-# symbol-based lookups, and handling of operand values.
-# @todo #302:30min Remove this module and move its methods to Factbase::TermBase.
-#  Currently, we use it because we are required to inject all thesse methods into Factbase::Term.
-#  When all the terms will inherit from Factbase::TermBase, we can remove this module.
-module Factbase::TermShared
-  # Turns it into a string.
-  # @return [String] The string of it
-  def to_s
-    @to_s ||=
-      begin
-        items = []
-        items << @op
-        items +=
-          @operands.map do |o|
-            if o.is_a?(String)
-              "'#{o.gsub("'", "\\\\'").gsub('"', '\\\\"')}'"
-            elsif o.is_a?(Time)
-              o.utc.iso8601
-            else
-              o.to_s
-            end
-          end
-        "(#{items.join(' ')})"
-      end
-  end
-
-  private
-
-  def assert_args(num)
-    c = @operands.size
-    raise "Too many (#{c}) operands for '#{@op}' (#{num} expected)" if c > num
-    raise "Too few (#{c}) operands for '#{@op}' (#{num} expected)" if c < num
-  end
-
-  def _by_symbol(pos, fact)
-    o = @operands[pos]
-    raise "A symbol expected at ##{pos}, but '#{o}' (#{o.class}) provided" unless o.is_a?(Symbol)
-    k = o.to_s
-    fact[k]
-  end
-
-  # @return [Array|nil] Either array of values or NIL
-  def _values(pos, fact, maps, fb)
-    v = @operands[pos]
-    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::Term)
-    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::TermBase)
-    v = fact[v.to_s] if v.is_a?(Symbol)
-    return v if v.nil?
-    unless v.is_a?(Array)
-      v =
-        if v.respond_to?(:each)
-          v.to_a
-        else
-          [v]
-        end
-    end
-    raise 'Why not array?' unless v.is_a?(Array)
-    unless v.all? { |i| [Float, Integer, String, Time, TrueClass, FalseClass].any? { |t| i.is_a?(t) } }
-      raise 'Wrong type inside'
-    end
-    v
-  end
-end