active_chronicle 0.1.0

data/lib/chronicle/datalog/compiler.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Chronicle
+  module Datalog
+    class Compiler
+      attr_reader :relation, :model
+
+      def self.compile(relation)
+        new(relation).compile
+      end
+
+      def initialize(relation)
+        @relation = relation
+        @model = relation.klass
+        @find_clause = [:find, '?e']
+        @in_clause = [:in, '$']
+        @where_clause = []
+        @bindings = []
+        @var_counter = 0
+      end
+
+      def compile
+        namespace = model.table_name.singularize
+
+        # 1. Process custom select / projections if specified
+        process_projections(namespace)
+
+        # 2. Fetch model attributes for hydration when no custom projection is requested
+        process_model_attributes(namespace)
+
+        # 3. Process includes / eager_load for preloading associations via Datomic pull
+        process_includes(namespace)
+
+        # 4. Process predicates in relation
+        process_where_clause(namespace)
+
+        if @where_clause.empty? && model.respond_to?(:datomic_attributes) && model.datomic_attributes.any?
+          attribute = model.datomic_attributes.keys.first
+          @where_clause << ['?e', :":#{namespace}/#{attribute}", '?value']
+        end
+
+        # 5. Fetch attributes needed to honor Active Record ordering
+        process_ordering(namespace)
+
+        # 6. Assemble Datalog data structure
+        datalog_query = @find_clause + @in_clause + [:where] + @where_clause
+
+        {
+          query: datalog_query,
+          bindings: @bindings,
+          find_vars: @find_clause[1..],
+          pull_spec: @pull_spec
+        }
+      end
+
+      private
+
+      def process_includes(namespace)
+        includes_list = []
+        includes_list += relation.includes_values if relation.respond_to?(:includes_values) && relation.includes_values.present?
+        includes_list += relation.eager_load_values if relation.respond_to?(:eager_load_values) && relation.eager_load_values.present?
+
+        return if includes_list.blank?
+
+        @pull_spec = build_pull_spec(includes_list, namespace)
+        @find_clause = [:find, [:pull, '?e', @pull_spec]]
+      end
+
+      def build_pull_spec(includes_list, namespace)
+        spec = ['*']
+        includes_list.flatten.compact.each do |item|
+          case item
+          when Symbol, String
+            ident = ":#{namespace}/#{item}"
+            spec << { ident => ['*'] }
+          when Hash
+            item.each do |parent_key, child_item|
+              parent_ident = ":#{namespace}/#{parent_key}"
+              child_ns = parent_key.to_s.singularize
+              child_spec = build_pull_spec([child_item], child_ns)
+              spec << { parent_ident => child_spec }
+            end
+          end
+        end
+        spec
+      end
+
+      def process_projections(namespace)
+        select_values = relation.select_values if relation.respond_to?(:select_values)
+        return unless select_values.present? && select_values.none? { |s| s.to_s == '*' }
+
+        find_vars = select_values.map do |col|
+          col_name = col.is_a?(Arel::Nodes::Node) ? col.name : col.to_s
+          var_name = "?#{col_name}"
+          # Add attribute pattern to retrieve attribute value
+          @where_clause << ['?e', :":#{namespace}/#{col_name}", var_name]
+          var_name
+        end
+        @find_clause = [:find] + find_vars
+      end
+
+      def process_model_attributes(namespace)
+        return if relation.select_values.present? || !model.respond_to?(:datomic_attributes)
+        return if model.datomic_attributes.empty?
+
+        @find_clause = [:find, [:pull, '?e', ['*']]]
+        attribute = model.datomic_attributes.keys.first
+        @where_clause << ['?e', :":#{namespace}/#{attribute}", '?value']
+      end
+
+      def process_where_clause(namespace)
+        where_predicates = extract_predicates
+
+        where_predicates.each do |pred|
+          process_predicate(pred, namespace)
+        end
+      end
+
+      def process_ordering(namespace)
+        return unless relation.respond_to?(:order_values)
+        return if @find_clause[1].is_a?(Array)
+
+        relation.order_values.each do |order|
+          expression = order.respond_to?(:expr) ? order.expr : order
+          next unless expression.respond_to?(:name)
+
+          attribute = expression.name.to_s
+          next if attribute == 'id' || !model.datomic_attributes.key?(attribute.to_sym)
+
+          variable = "?#{attribute}"
+          next if @find_clause.include?(variable)
+
+          @find_clause << variable
+          @where_clause << ['?e', :":#{namespace}/#{attribute}", variable]
+        end
+      end
+
+      def extract_predicates
+        if relation.respond_to?(:where_clause)
+          relation.where_clause.send(:predicates)
+        else
+          []
+        end
+      end
+
+      def process_predicate(pred, namespace)
+        case pred
+        when Arel::Nodes::Equality
+          attr_name = pred.left.name
+          val = unwrap_value(pred.right)
+          param_var = "?param_#{next_var_id}"
+
+          if attr_name.to_s == 'id'
+            @where_clause << [[:'=', '?e', param_var]]
+            @in_clause << param_var
+            @bindings << val
+            return
+          end
+
+          @where_clause << ['?e', :":#{namespace}/#{attr_name}", param_var]
+          @in_clause << param_var
+          @bindings << val
+
+        when Arel::Nodes::GreaterThan
+          attr_name = pred.left.name
+          val = unwrap_value(pred.right)
+          var_name = "?var_#{attr_name}"
+
+          @where_clause << ['?e', :":#{namespace}/#{attr_name}", var_name]
+          @where_clause << [[:>, var_name, val]]
+
+        when Arel::Nodes::GreaterThanOrEqual
+          attr_name = pred.left.name
+          val = unwrap_value(pred.right)
+          var_name = "?var_#{attr_name}"
+
+          @where_clause << ['?e', :":#{namespace}/#{attr_name}", var_name]
+          @where_clause << [[:>=, var_name, val]]
+
+        when Arel::Nodes::LessThan
+          attr_name = pred.left.name
+          val = unwrap_value(pred.right)
+          var_name = "?var_#{attr_name}"
+
+          @where_clause << ['?e', :":#{namespace}/#{attr_name}", var_name]
+          @where_clause << [[:<, var_name, val]]
+
+        when Arel::Nodes::LessThanOrEqual
+          attr_name = pred.left.name
+          val = unwrap_value(pred.right)
+          var_name = "?var_#{attr_name}"
+
+          @where_clause << ['?e', :":#{namespace}/#{attr_name}", var_name]
+          @where_clause << [[:<=, var_name, val]]
+
+        when Arel::Nodes::NotEqual
+          attr_name = pred.left.name
+          val = unwrap_value(pred.right)
+          param_var = "?param_#{next_var_id}"
+          var_name = "?var_#{attr_name}"
+
+          @where_clause << ['?e', :":#{namespace}/#{attr_name}", var_name]
+          @where_clause << [[:!=, var_name, param_var]]
+          @in_clause << param_var
+          @bindings << val
+
+        when Arel::Nodes::In
+          attr_name = pred.left.name
+          values = unwrap_value(pred.right).map { |v| unwrap_value(v) }
+          param_var = "?in_vec_#{next_var_id}"
+          val_var = "?var_#{attr_name}"
+
+          @where_clause << ['?e', :":#{namespace}/#{attr_name}", val_var]
+          @where_clause << [val_var, param_var]
+          @in_clause << [param_var, '...']
+          @bindings << values
+
+        when Arel::Nodes::HomogeneousIn
+          attr_name = pred.attribute.name
+          values = pred.values.map { |value| unwrap_value(value) }
+          param_var = "?in_vec_#{next_var_id}"
+          val_var = "?var_#{attr_name}"
+
+          @where_clause << ['?e', :":#{namespace}/#{attr_name}", val_var]
+          @where_clause << [val_var, param_var]
+          @in_clause << [param_var, '...']
+          @bindings << values
+
+        when String
+          @where_clause << pred
+        end
+      end
+
+      def unwrap_value(val)
+        if val.respond_to?(:value)
+          val.value
+        else
+          val
+        end
+      end
+
+      def next_var_id
+        @var_counter += 1
+      end
+    end
+  end
+end

data/lib/chronicle/datalog/optimizer.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Chronicle
+  module Datalog
+    class Optimizer
+      class << self
+        def optimize(compiled_query, model = nil)
+          new(compiled_query, model).optimize
+        end
+      end
+
+      attr_reader :query, :bindings, :find_vars, :model
+
+      def initialize(compiled_query, model = nil)
+        @query = compiled_query[:query]
+        @bindings = compiled_query[:bindings]
+        @find_vars = compiled_query[:find_vars]
+        @model = model
+      end
+
+      def optimize
+        # Extract clauses
+        find_idx = query.index(:find)
+        in_idx = query.index(:in)
+        where_idx = query.index(:where)
+
+        find_part = query[find_idx...in_idx]
+        in_part = query[in_idx...where_idx]
+        where_part = query[(where_idx + 1)..]
+
+        # Reorder where clauses for optimal AVET/EAVT index performance
+        optimized_where = reorder_where_clauses(where_part)
+
+        # Assemble optimized query
+        optimized_query = find_part + in_part + [:where] + optimized_where
+
+        {
+          query: optimized_query,
+          bindings:,
+          find_vars:,
+          optimized: true
+        }
+      end
+
+      private
+
+      def reorder_where_clauses(clauses)
+        # Separate pattern triples [?e :attr ?val] from predicate expressions [[> ?var val]]
+        patterns = []
+        predicates = []
+
+        clauses.each do |c|
+          if c.is_a?(Array) && c.first.is_a?(Array)
+            # Predicate expression like [[:>, "?var_age", 21]] or [[":!=", ...]]
+            predicates << c
+          else
+            patterns << c
+          end
+        end
+
+        # Sort patterns: indexed/unique attributes first (AVET seek), then general attributes
+        sorted_patterns = patterns.sort_by do |pat|
+          attr_sym = pat[1]
+          if unique_or_indexed_attribute?(attr_sym)
+            0 # Highest priority for AVET index seek
+          else
+            1
+          end
+        end
+
+        # Patterns executed first to narrow candidate set, then predicates filter
+        sorted_patterns + predicates
+      end
+
+      def unique_or_indexed_attribute?(attr_sym)
+        return false unless model.respond_to?(:datomic_attributes)
+
+        attr_name = attr_sym.to_s.split('/').last&.to_sym
+        return false unless attr_name
+
+        meta = model.datomic_attributes[attr_name]
+        return false unless meta
+
+        opts = meta[:options] || {}
+        opts[:unique].present? || opts[:index] == true
+      end
+    end
+  end
+end

data/lib/chronicle/hydrator.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/keys'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/string/inflections'
+
+module Chronicle
+  class Hydrator
+    class << self
+      # Main entry point for hydrating raw Datomic query or pull results into Active Record instances
+      #
+      # @param klass [Class] The Active Record model class
+      # @param raw_results [Array] Results returned from Datomic transport #q or #pull
+      # @param compiled_meta [Hash] Options/metadata from Datalog compiler (e.g. find_vars, pluck)
+      # @return [Array<ActiveRecord::Base>, Array] Hydrated model instances or raw scalar values
+      def hydrate(klass, raw_results, compiled_meta = {})
+        return [] if raw_results.blank?
+
+        return hydrate_pluck(raw_results, compiled_meta) if compiled_meta[:pluck]
+
+        find_vars = compiled_meta[:find_vars] || ['?e']
+
+        raw_results.map do |row|
+          attributes, associations = extract_attributes_and_associations(klass, row, find_vars)
+          record = instantiate_model(klass, attributes)
+          hydrate_associations(record, associations) if record && associations.present?
+          record
+        end
+      end
+
+      private
+
+      def hydrate_pluck(raw_results, compiled_meta)
+        find_vars = compiled_meta[:find_vars] || []
+        if find_vars.size == 1
+          raw_results.map { |row| row.is_a?(Array) ? row.first : row }
+        else
+          raw_results.map { |row| row.is_a?(Array) ? row : [row] }
+        end
+      end
+
+      def extract_attributes_and_associations(klass, row, find_vars)
+        attributes = {}
+        associations = {}
+
+        row = row.first if row.is_a?(Array) && row.size == 1 && row.first.is_a?(Hash)
+
+        if row.is_a?(Hash)
+          # Datomic Entity Map (from pull query or entity map)
+          row.each do |key, val|
+            clean_key = normalize_key(key, klass)
+            next unless clean_key
+
+            if val.is_a?(Hash) || (val.is_a?(Array) && val.first.is_a?(Hash))
+              # Nested entity reference (association)
+              associations[clean_key] = val
+              reflection = klass.reflect_on_association(clean_key.to_sym) if klass.respond_to?(:reflect_on_association)
+              if reflection.respond_to?(:foreign_key) && val.is_a?(Hash)
+                child_id = val[':db/id'] || val['db/id'] || val['id']
+                attributes[reflection.foreign_key] = child_id if child_id
+              end
+            else
+              attributes[clean_key] = val
+            end
+          end
+        elsif row.is_a?(Array)
+          # Tuple result corresponding to find_vars
+          find_vars.each_with_index do |var_name, idx|
+            attr_name = var_name.to_s.sub(/^\?/, '')
+            if attr_name == 'e'
+              attributes['id'] = row[idx]
+            else
+              val = row[idx]
+              if val.is_a?(Hash) || (val.is_a?(Array) && val.first.is_a?(Hash))
+                associations[attr_name] = val
+              else
+                attributes[attr_name] = val
+              end
+            end
+          end
+        else
+          # Single scalar (e.g. entity ID integer)
+          attributes['id'] = row
+        end
+
+        [attributes, associations]
+      end
+
+      def normalize_key(key, _klass)
+        str_key = key.to_s.sub(/^:/, '')
+
+        if ['db/id', 'id'].include?(str_key)
+          'id'
+        elsif str_key.include?('/')
+          # Namespace attribute like "user/name" -> "name"
+          parts = str_key.split('/')
+          parts.last.tr('-', '_')
+        else
+          str_key.tr('-', '_')
+        end
+      end
+
+      def instantiate_model(klass, attributes)
+        string_attributes = attributes.stringify_keys
+
+        if klass.respond_to?(:instantiate)
+          record = klass.instantiate(string_attributes)
+          ensure_dirty_tracking_clean(record)
+        else
+          record = klass.allocate
+          if record.respond_to?(:init_with)
+            record.init_with('attributes' => string_attributes, 'new_record' => false)
+          else
+            string_attributes.each do |k, v|
+              setter = "#{k}="
+              record.public_send(setter, v) if record.respond_to?(setter)
+            end
+          end
+        end
+        record
+      end
+
+      def hydrate_associations(record, associations)
+        associations.each do |assoc_name, val|
+          reflection = (record.class.reflect_on_association(assoc_name.to_sym) if record.class.respond_to?(:reflect_on_association))
+
+          target_klass = reflection ? reflection.klass : assoc_name.to_s.classify.safe_constantize
+
+          next unless target_klass
+
+          if val.is_a?(Array)
+            child_records = val.map { |child_hash| hydrate(target_klass, [child_hash]).first }.compact
+            set_association_target(record, reflection, assoc_name, child_records, is_collection: true)
+          else
+            child_record = hydrate(target_klass, [val]).first
+            set_association_target(record, reflection, assoc_name, child_record, is_collection: false)
+          end
+        end
+      end
+
+      def set_association_target(record, reflection, assoc_name, target, is_collection:)
+        if reflection && record.respond_to?(:association)
+          if !is_collection && reflection.respond_to?(:foreign_key) && target.respond_to?(:id)
+            foreign_key = reflection.foreign_key
+            record._write_attribute(foreign_key, target.id) if record.has_attribute?(foreign_key)
+          end
+
+          assoc = record.association(reflection.name)
+          assoc.target = target
+          assoc.loaded!
+        end
+        record.instance_variable_set("@#{assoc_name}", target)
+      end
+
+      def ensure_dirty_tracking_clean(record)
+        if record.respond_to?(:clear_changes_information)
+          record.clear_changes_information
+        elsif record.respond_to?(:changes_applied)
+          record.changes_applied
+        end
+      end
+    end
+  end
+end

data/lib/chronicle/model.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Chronicle
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :datomic_attributes, default: {}
+    end
+
+    module ClassMethods
+      def all(all_queries: nil)
+        super.extending(Relation)
+      end
+
+      def find(*ids)
+        return super unless connection.respond_to?(:transport)
+        return ids.map { |id| find(id) } if ids.size > 1
+
+        record = all.to_a.find { |item| item.id.to_s == ids.first.to_s }
+        return record if record
+
+        raise ActiveRecord::RecordNotFound, "Couldn't find #{name} with 'id'=#{ids.first}"
+      end
+
+      def datomic_attribute(name, type = :string, options = {})
+        self.datomic_attributes = datomic_attributes.merge(name.to_sym => { type:, options: })
+
+        define_method(name) do
+          read_attribute(name)
+        end
+
+        define_method("#{name}=") do |val|
+          write_attribute(name, val)
+        end
+      end
+
+      def as_of(time_or_t)
+        all.extending(TimeTravelExtension).spawn.tap do |rel|
+          rel.time_travel_options = { as_of: time_or_t }
+        end
+      end
+
+      def since(time_or_t)
+        all.extending(TimeTravelExtension).spawn.tap do |rel|
+          rel.time_travel_options = { since: time_or_t }
+        end
+      end
+
+      def chronicle_transport
+        adapter = connection
+        return adapter.transport if adapter.respond_to?(:transport)
+
+        Chronicle::Transport.client
+      end
+    end
+
+    module TimeTravelExtension
+      include Relation
+
+      attr_accessor :time_travel_options
+    end
+
+    def datomic_entity_id
+      read_attribute(:id)
+    end
+
+    def to_datoms
+      datoms = []
+      self.class.datomic_attributes.each_key do |attr_name|
+        val = public_send(attr_name)
+        next if val.nil?
+
+        attr_ident = :":#{self.class.table_name.singularize}/#{attr_name}"
+        datoms << [:'db/add', datomic_entity_id || 'chronicle_temp_id', attr_ident, val]
+      end
+      datoms
+    end
+  end
+end

data/lib/chronicle/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Chronicle
+  class Railtie < Rails::Railtie
+    initializer 'chronicle.register_adapter' do
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::ConnectionAdapters.register(
+          'datomic',
+          'ActiveRecord::ConnectionAdapters::DatomicAdapter',
+          'chronicle/connection_adapters/datomic_adapter'
+        )
+      end
+    end
+  end
+end

data/lib/chronicle/relation.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Chronicle
+  module Relation
+    attr_accessor :time_travel_options
+
+    def as_of(timestamp_or_tx)
+      spawn.tap do |r|
+        r.time_travel_options = (r.time_travel_options || {}).merge(as_of: timestamp_or_tx)
+      end
+    end
+
+    def since(timestamp_or_tx)
+      spawn.tap do |r|
+        r.time_travel_options = (r.time_travel_options || {}).merge(since: timestamp_or_tx)
+      end
+    end
+
+    def to_datalog
+      Datalog::Compiler.compile(self)
+    end
+
+    def exec_queries
+      return @records if loaded?
+
+      # Compile Active Record relation into Datomic Datalog AST
+      compiled = Datalog::Compiler.compile(self)
+
+      # Obtain transport adapter and database snapshot
+      adapter = klass.respond_to?(:chronicle_transport) ? klass.chronicle_transport : Chronicle::Transport.client
+      klass.connection.ensure_model_schema(klass) if klass.connection.respond_to?(:ensure_model_schema)
+      db_snapshot = adapter.db(
+        as_of: time_travel_options&.dig(:as_of),
+        since: time_travel_options&.dig(:since)
+      )
+
+      # Query Datomic endpoint
+      raw_results = if adapter.respond_to?(:pull) && compiled[:query][1].is_a?(Array) && compiled[:query][1].first == :pull
+                      id_query = compiled[:query].dup
+                      id_query[id_query.index(:find) + 1] = '?e'
+                      entity_ids = adapter.q(id_query, db_snapshot, *compiled[:bindings]).map do |row|
+                        row.is_a?(Array) ? row.first : row
+                      end
+                      entity_ids.map { |entity_id| adapter.pull(entity_id, db_snapshot) }
+                    else
+                      adapter.q(compiled[:query], db_snapshot, *compiled[:bindings])
+                    end
+
+      # Map raw Datoms/tuples back into Active Record model instances using Hydrator
+      @records = order_records(Hydrator.hydrate(klass, raw_results, compiled))
+      @loaded = true
+      @records
+    end
+
+    def size
+      records.length
+    end
+
+    private
+
+    def order_records(records)
+      orderings = order_values.filter_map do |order|
+        direction = order.is_a?(Arel::Nodes::Descending) ? -1 : 1
+        expression = order.respond_to?(:expr) ? order.expr : order
+        attribute = expression.name if expression.respond_to?(:name)
+        [attribute.to_s, direction] if attribute && (attribute.to_s == 'id' || klass.datomic_attributes.key?(attribute.to_sym))
+      end
+      return records if orderings.empty?
+
+      records.sort do |left, right|
+        comparison = 0
+        orderings.each do |attribute, direction|
+          left_value = left.read_attribute(attribute)
+          right_value = right.read_attribute(attribute)
+          comparison = compare_order_values(left_value, right_value, direction)
+          break unless comparison.zero?
+        end
+        comparison
+      end
+    end
+
+    def compare_order_values(left, right, direction)
+      return 0 if left.nil? && right.nil?
+      return (left.nil? ? -1 : 1) * direction if left.nil? || right.nil?
+
+      (left <=> right || 0) * direction
+    end
+  end
+end