historiographer 4.1.16 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de76c8aaf1054da7a45d6ee7b8d8dd8a7671558ff4b0789726c97295e4f24c53
-  data.tar.gz: dc5af5d7b25378009cec12c092f19618685e692604bd7f9fc47210c967d5880e
+  metadata.gz: e095861ef6cd8df461a227897f73a7f0055c1ed1cc337ec6025be60fa3755a91
+  data.tar.gz: dc5272631bc5cf63cc55495842cc3a4407a59729b011499ca34e4248fc75d10d
 SHA512:
-  metadata.gz: 698b99835d996003cf895707bc543d6149b39c057db6e4f86535495b8ea6a581a75b500c84487ea5acc3df0493a905e13e2ceb35e94784a6732c7be730df18db
-  data.tar.gz: d4c85721df30cdd16992ba8043afe2a6e9eca34fe8cad77d9360bc0f03a122b526d1aec5d7c727275d788afbf59098255564ae041fa65f8eb08d27237ca031f0
+  metadata.gz: d165aa2cc4f216c3abb3c30cf0b456fc517d3ea4ce9aed12afb109f0ecc01e95a8ab2affb374602b2d6fec9ed9983d1d28831365f768c64c3e785903c5a455a5
+  data.tar.gz: 8a6a3a0ecae45fe220d99f8644a925103aaf686c2048ca8c75cb26e3d785f939affb72fb732c7997346bd1d4ed7cf1029f293178b61c5ef1c7f677850859a140

data/README.md

@@ -130,174 +130,6 @@ This can be useful when:
 - You're versioning training data for machine learning models
 - You need to maintain immutable audit trails at specific checkpoints
 
-## Single Table Inheritance (STI)
-
-Historiographer fully supports Single Table Inheritance, both with the default `type` column and with custom inheritance columns.
-
-### Default STI with `type` column
-
-```ruby
-class Post < ActiveRecord::Base
-  include Historiographer
-end
-
-class PrivatePost < Post
-end
-
-# The history classes follow the same inheritance pattern:
-class PostHistory < ActiveRecord::Base
-  include Historiographer::History
-end
-
-class PrivatePostHistory < PostHistory
-end
-```
-
-History records automatically maintain the correct STI type:
-
-```ruby
-private_post = PrivatePost.create(title: "Secret", history_user_id: current_user.id)
-private_post.snapshot
-
-# History records are the correct subclass
-history = PostHistory.last
-history.is_a?(PrivatePostHistory) #=> true
-history.type #=> "PrivatePostHistory"
-```
-
-### Custom Inheritance Columns
-
-You can also use a custom column for STI instead of the default `type`:
-
-```ruby
-class MLModel < ActiveRecord::Base
-  self.inheritance_column = :model_type
-  include Historiographer
-end
-
-class XGBoost < MLModel
-  self.table_name = "ml_models"
-end
-
-# History classes use the same custom column
-class MLModelHistory < MLModel
-  self.inheritance_column = :model_type
-  self.table_name = "ml_model_histories"
-end
-
-class XGBoostHistory < MLModelHistory
-end
-```
-
-Migration for custom inheritance column:
-
-```ruby
-create_table :ml_models do |t|
-  t.string :name
-  t.string :model_type  # Custom inheritance column
-  t.jsonb :parameters
-  t.timestamps
-
-  t.index :model_type
-end
-
-create_table :ml_model_histories do |t|
-  t.histories  # Includes all columns from parent table
-end
-```
-
-The custom inheritance column works just like the default `type`:
-
-```ruby
-model = XGBoost.create(name: "My Model", history_user_id: current_user.id)
-model.snapshot
-
-# History records maintain the correct subclass
-history = MLModelHistory.last
-history.is_a?(XGBoostHistory) #=> true
-history.model_type #=> "XGBoostHistory"
-```
-
-### STI and Snapshots: Perfect for Model Versioning
-
-Single Table Inheritance combined with Historiographer's snapshot feature is particularly powerful for versioning machine learning models and other complex systems that need immutable historical records. Here's why:
-
-1. **Type-Safe History**: When you snapshot an ML model, both the model and its parameters are preserved with their exact implementation type. This ensures that when you retrieve historical versions, you get back exactly the right subclass with its specific behavior:
-
-```ruby
-# Create and configure an XGBoost model
-model = XGBoost.create(
-  name: "Customer Churn Predictor v1",
-  parameters: { max_depth: 3, eta: 0.1 },
-  history_user_id: current_user.id
-)
-
-# Take a snapshot before training
-model.snapshot
-
-# Update the model after training
-model.update(
-  name: "Customer Churn Predictor v2",
-  parameters: { max_depth: 5, eta: 0.2 },
-  history_user_id: current_user.id
-)
-
-# Later, retrieve the exact pre-training version
-historical_model = MLModel.latest_snapshot
-historical_model.is_a?(XGBoostHistory) #=> true
-historical_model.parameters #=> { max_depth: 3, eta: 0.1 }
-```
-
-2. **Implementation Versioning**: Different model types often have different parameters, preprocessing steps, or scoring methods. STI ensures these differences are preserved in history:
-
-```ruby
-class XGBoost < MLModel
-  def predict(data)
-    # XGBoost-specific prediction logic
-  end
-end
-
-class RandomForest < MLModel
-  def predict(data)
-    # RandomForest-specific prediction logic
-  end
-end
-
-# Your historical records maintain these implementation differences
-old_model = MLModel.latest_snapshot
-old_model.predict(data) # Uses the exact prediction logic from that point in time
-```
-
-3. **Reproducibility**: Essential for ML workflows where you need to reproduce results or audit model behavior:
-
-```ruby
-# Create model and snapshot at each significant stage
-model = XGBoost.create(name: "Risk Scorer v1", history_user_id: current_user.id)
-
-# Snapshot after initial configuration
-model.snapshot(metadata: { stage: "configuration" })
-
-# Snapshot after training
-model.update(parameters: trained_parameters)
-model.snapshot(metadata: { stage: "post_training" })
-
-# Snapshot after validation
-model.update(parameters: validated_parameters)
-model.snapshot(metadata: { stage: "validated" })
-
-# Later, you can retrieve any version to reproduce results
-initial_version = model.histories.find_by(metadata: { stage: "configuration" })
-trained_version = model.histories.find_by(metadata: { stage: "post_training" })
-```
-
-This combination of STI and snapshots is particularly valuable for:
-
-- Model governance and compliance
-- A/B testing different model types
-- Debugging model behavior
-- Reproducing historical predictions
-- Maintaining audit trails for regulatory requirements
-
 ## Namespaced Models
 
 When using namespaced models, Rails handles foreign key naming differently than with non-namespaced models. For example, if you have a model namespaced like this:

data/VERSION

@@ -1 +1 @@
-4.1.16
+4.4.0

data/historiographer.gemspec

@@ -2,11 +2,11 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: historiographer 4.1.16 ruby lib
+# stub: historiographer 4.4.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "historiographer".freeze
-  s.version = "4.1.16"
+  s.version = "4.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -33,6 +33,7 @@ Gem::Specification.new do |s|
     "historiographer-4.1.12.gem",
     "historiographer-4.1.13.gem",
     "historiographer-4.1.14.gem",
+    "historiographer-4.3.0.gem",
     "historiographer.gemspec",
     "init.rb",
     "instructions/implementation.md",
@@ -63,31 +64,26 @@ Gem::Specification.new do |s|
     "spec/db/migrate/20221018204255_create_silent_post_histories.rb",
     "spec/db/migrate/20241109182017_create_comments.rb",
     "spec/db/migrate/20241109182020_create_comment_histories.rb",
-    "spec/db/migrate/20241118000000_add_type_to_posts.rb",
-    "spec/db/migrate/20241118000001_add_type_to_post_histories.rb",
-    "spec/db/migrate/20241118000002_create_ml_models.rb",
-    "spec/db/migrate/20241118000003_create_easy_ml_columns.rb",
     "spec/db/migrate/20241119000000_create_datasets.rb",
+    "spec/db/migrate/2025082100000_create_projects.rb",
+    "spec/db/migrate/2025082100001_create_project_files.rb",
     "spec/db/schema.rb",
     "spec/factories/post.rb",
+    "spec/foreign_key_spec.rb",
     "spec/historiographer_spec.rb",
     "spec/models/application_record.rb",
     "spec/models/author.rb",
     "spec/models/author_history.rb",
     "spec/models/comment.rb",
     "spec/models/comment_history.rb",
-    "spec/models/dataset.rb",
-    "spec/models/dataset_history.rb",
     "spec/models/easy_ml/column.rb",
     "spec/models/easy_ml/column_history.rb",
-    "spec/models/easy_ml/encrypted_column.rb",
-    "spec/models/easy_ml/encrypted_column_history.rb",
-    "spec/models/ml_model.rb",
-    "spec/models/ml_model_history.rb",
     "spec/models/post.rb",
     "spec/models/post_history.rb",
-    "spec/models/private_post.rb",
-    "spec/models/private_post_history.rb",
+    "spec/models/project.rb",
+    "spec/models/project_file.rb",
+    "spec/models/project_file_history.rb",
+    "spec/models/project_history.rb",
     "spec/models/safe_post.rb",
     "spec/models/safe_post_history.rb",
     "spec/models/silent_post.rb",
@@ -96,8 +92,6 @@ Gem::Specification.new do |s|
     "spec/models/thing_with_compound_index_history.rb",
     "spec/models/thing_without_history.rb",
     "spec/models/user.rb",
-    "spec/models/xgboost.rb",
-    "spec/models/xgboost_history.rb",
     "spec/spec_helper.rb"
   ]
   s.homepage = "http://github.com/brettshollenberger/historiographer".freeze

data/lib/historiographer/history.rb

@@ -179,11 +179,6 @@ module Historiographer
         belongs_to association_name, class_name: foreign_class_name
       end
 
-      # Enable STI for history classes
-      if foreign_class.sti_enabled?
-        self.inheritance_column = 'type'
-      end
-
       # Ensure we can't destroy history records
       before_destroy { |record| raise "Cannot destroy history records" }
 
@@ -235,6 +230,9 @@ module Historiographer
           .order('snapshot_id, history_started_at DESC, id DESC')
       }
 
+      # Track custom association methods
+      base.class_variable_set(:@@history_association_methods, [])
+      
       # Dynamically define associations on the history class
       foreign_class.reflect_on_all_associations.each do |association|
         define_history_association(association)
@@ -286,20 +284,64 @@ module Historiographer
         assoc_class = assoc_history_class_name.safe_constantize || OpenStruct.new(name: association.class_name)
         assoc_class_name = assoc_class.name
 
-        # Define the scope to filter by snapshot_id for history associations
-        scope = if assoc_class_name.match?(/History/)
-                  ->(history_instance) { where(snapshot_id: history_instance.snapshot_id) }
-                else
-                  ->(history_instance) { all }
-                end
-
         case association.macro
         when :belongs_to
-          belongs_to assoc_name, scope, class_name: assoc_class_name, foreign_key: assoc_foreign_key, primary_key: assoc_foreign_key
+          # For belongs_to associations, if the target is a history class, we need special handling
+          if assoc_class_name.match?(/History/)
+            # Override the association method to filter by snapshot_id
+            # The history class uses <model>_id as the foreign key (e.g., author_id for AuthorHistory)
+            history_fk = association.class_name.gsub(/History$/, '').underscore + '_id'
+            
+            # Track this custom method
+            methods_list = class_variable_get(:@@history_association_methods) rescue []
+            methods_list << assoc_name
+            class_variable_set(:@@history_association_methods, methods_list)
+            
+            define_method(assoc_name) do
+              return nil unless self[assoc_foreign_key]
+              assoc_class.where(
+                history_fk => self[assoc_foreign_key],
+                snapshot_id: self.snapshot_id
+              ).first
+            end
+          else
+            belongs_to assoc_name, class_name: assoc_class_name, foreign_key: assoc_foreign_key
+          end
         when :has_one
-          has_one assoc_name, scope, class_name: assoc_class_name, foreign_key: assoc_foreign_key, primary_key: history_foreign_key
+          if assoc_class_name.match?(/History/)
+            hfk = history_foreign_key
+            
+            # Track this custom method
+            methods_list = class_variable_get(:@@history_association_methods) rescue []
+            methods_list << assoc_name
+            class_variable_set(:@@history_association_methods, methods_list)
+            
+            define_method(assoc_name) do
+              assoc_class.where(
+                assoc_foreign_key => self[hfk],
+                snapshot_id: self.snapshot_id
+              ).first
+            end
+          else
+            has_one assoc_name, class_name: assoc_class_name, foreign_key: assoc_foreign_key, primary_key: history_foreign_key
+          end
         when :has_many
-          has_many assoc_name, scope, class_name: assoc_class_name, foreign_key: assoc_foreign_key, primary_key: history_foreign_key
+          if assoc_class_name.match?(/History/)
+            hfk = history_foreign_key
+            # Track this custom method
+            methods_list = class_variable_get(:@@history_association_methods) rescue []
+            methods_list << assoc_name
+            class_variable_set(:@@history_association_methods, methods_list)
+            
+            define_method(assoc_name) do
+              assoc_class.where(
+                assoc_foreign_key => self[hfk],
+                snapshot_id: self.snapshot_id
+              )
+            end
+          else
+            has_many assoc_name, class_name: assoc_class_name, foreign_key: assoc_foreign_key, primary_key: history_foreign_key
+          end
         end
       end
 
@@ -312,13 +354,9 @@ module Historiographer
         return @history_foreign_key if @history_foreign_key
 
         # CAN THIS BE TABLE OR MODEL?
-        @history_foreign_key = sti_base_class.name.singularize.foreign_key
+        @history_foreign_key = original_class.base_class.name.singularize.foreign_key
       end
 
-      def sti_base_class
-        return @sti_base_class if @sti_base_class
-        @sti_base_class = original_class.base_class
-      end
     end
 
     def original_class
@@ -337,10 +375,6 @@ module Historiographer
       attrs = attributes.clone
       # attrs[original_class.primary_key] = attrs[self.class.history_foreign_key]
 
-      if original_class.sti_enabled?
-        # Remove History suffix from type if present
-        attrs[original_class.inheritance_column] = attrs[original_class.inheritance_column]&.gsub(/History$/, '')
-      end
 
       # Manually handle creating instance WITHOUT running find or initialize callbacks
       # We will manually run callbacks below
@@ -373,13 +407,19 @@ module Historiographer
         end
       end
 
-      # For each association in the history class
-      self.class.reflect_on_all_associations.each do |reflection|
+      # For each association in the history class (including custom methods)
+      associations_to_forward = self.class.reflect_on_all_associations.map(&:name)
+      
+      # Add custom association methods
+      custom_methods = self.class.class_variable_get(:@@history_association_methods) rescue []
+      associations_to_forward += custom_methods
+      
+      associations_to_forward.uniq.each do |assoc_name|
         # Define a method that forwards to the history association
         instance.singleton_class.class_eval do
-          define_method(reflection.name) do |*args, &block|
-            history_instance = instance.instance_variable_get(:@_history_instance)
-            history_instance.send(reflection.name, *args, &block)
+          define_method(assoc_name) do |*args, &block|
+            history_instance = instance_variable_get(:@_history_instance)
+            history_instance.send(assoc_name, *args, &block)
           end
         end
       end

data/lib/historiographer.rb

@@ -78,6 +78,7 @@ module Historiographer
   extend ActiveSupport::Concern
 
   class HistoryUserIdMissingError < StandardError; end
+  class HistoryInsertionError < StandardError; end
 
   UTC = Time.now.in_time_zone('UTC').time_zone
 
@@ -190,9 +191,6 @@ module Historiographer
       
       history_class_initializer = Class.new(ActiveRecord::Base) do
         self.table_name = "#{base_table}_histories"
-        
-        # Handle STI properly
-        self.inheritance_column = base.inheritance_column if base.sti_enabled?
       end
 
       # Split the class name into module parts and the actual class name
@@ -295,10 +293,11 @@ module Historiographer
         existing_snapshot = history_class.where(foreign_key => attrs[primary_key], snapshot_id: snapshot_id)
         return if existing_snapshot.present?
 
-        null_snapshot = history_class.where(foreign_key => attrs[primary_key], snapshot_id: nil)
+        null_snapshot = history_class.where(foreign_key => attrs[primary_key], snapshot_id: nil).first
         snapshot = nil
         if null_snapshot.present?
-          snapshot = null_snapshot.update(snapshot_id: snapshot_id)
+          null_snapshot.update(snapshot_id: snapshot_id)
+          snapshot = null_snapshot
         else
           snapshot = record_history(snapshot_id: snapshot_id)
         end
@@ -344,12 +343,6 @@ module Historiographer
       attrs.merge!(foreign_key => attrs['id'], history_started_at: now, history_user_id: history_user_id)
       attrs.merge!(snapshot_id: snapshot_id) if snapshot_id.present?
 
-      # For STI, ensure we use the correct history class type
-      if self.class.sti_enabled?
-        type_column = self.class.inheritance_column
-        attrs[type_column] = "#{self.class.name}History"
-      end
-
       attrs = attrs.except('id')
       attrs.stringify_keys!
 
@@ -385,6 +378,29 @@ module Historiographer
 
       if history_class.history_foreign_key.present? && history_class.present?
         result = history_class.insert_all([attrs])
+        
+        # Check if the insertion was successful
+        if result.rows.empty?
+          # insert_all returned empty rows, likely due to a duplicate/conflict
+          # Try to find the existing record that prevented insertion
+          foreign_key = history_class.history_foreign_key
+          existing_history = history_class.where(
+            foreign_key => attrs[foreign_key],
+            history_started_at: attrs['history_started_at']
+          ).first
+          
+          if existing_history
+            # A duplicate history already exists (race condition or retry)
+            # This is acceptable - return the existing history
+            Rails.logger.warn("Duplicate history detected for #{self.class.name} ##{id} at #{attrs['history_started_at']}. Using existing history record ##{existing_history.id}.") if Rails.logger
+            current_history.update_columns(history_ended_at: now) if current_history.present?
+            return existing_history
+          else
+            # No rows inserted and can't find an existing record - this is unexpected
+            raise HistoryInsertionError, "Failed to insert history record for #{self.class.name} ##{id}, and no existing history was found. This may indicate a database constraint preventing insertion."
+          end
+        end
+        
         inserted_id = result.rows.first.first if history_class.primary_key == 'id'
         instance = history_class.find(inserted_id)
         current_history.update_columns(history_ended_at: now) if current_history.present?
@@ -434,9 +450,6 @@ module Historiographer
       @historiographer_mode || Historiographer::Configuration.mode
     end
 
-    def sti_enabled?
-      columns.map(&:name).include?(inheritance_column)
-    end
   end
 
   def is_history_class?

data/spec/db/migrate/2025082100000_create_projects.rb

@@ -0,0 +1,14 @@
+require 'historiographer/postgres_migration'
+
+class CreateProjects < ActiveRecord::Migration[7.1]
+  def change
+    create_table :projects do |t|
+      t.string :name, null: false
+      t.timestamps
+    end
+
+    create_table :project_histories do |t|
+      t.histories
+    end
+  end
+end

data/spec/db/migrate/2025082100001_create_project_files.rb

@@ -0,0 +1,18 @@
+
+require 'historiographer/postgres_migration'
+
+class CreateProjectFiles < ActiveRecord::Migration[7.1]
+  def change
+    create_table :project_files do |t|
+      t.bigint :project_id
+      t.string :name, null: false
+      t.string :content
+      t.timestamps
+      t.index :project_id
+    end
+
+    create_table :project_file_histories do |t|
+      t.histories
+    end
+  end
+end

data/spec/db/schema.rb

@@ -195,6 +195,50 @@ ActiveRecord::Schema[7.1].define(version: 2024_11_19_000000) do
     t.index ["type"], name: "index_posts_on_type"
   end
 
+  create_table "project_file_histories", force: :cascade do |t|
+    t.integer "project_file_id", null: false
+    t.string "name", null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.datetime "history_started_at", null: false
+    t.datetime "history_ended_at"
+    t.integer "history_user_id"
+    t.string "snapshot_id"
+    t.index ["history_ended_at"], name: "index_project_file_histories_on_history_ended_at"
+    t.index ["history_started_at"], name: "index_project_file_histories_on_history_started_at"
+    t.index ["history_user_id"], name: "index_project_file_histories_on_history_user_id"
+    t.index ["project_file_id"], name: "index_project_file_histories_on_project_file_id"
+    t.index ["snapshot_id"], name: "index_project_file_histories_on_snapshot_id"
+  end
+
+  create_table "project_files", force: :cascade do |t|
+    t.string "name", null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+  end
+
+  create_table "project_histories", force: :cascade do |t|
+    t.integer "project_id", null: false
+    t.string "name", null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.datetime "history_started_at", null: false
+    t.datetime "history_ended_at"
+    t.integer "history_user_id"
+    t.string "snapshot_id"
+    t.index ["history_ended_at"], name: "index_project_histories_on_history_ended_at"
+    t.index ["history_started_at"], name: "index_project_histories_on_history_started_at"
+    t.index ["history_user_id"], name: "index_project_histories_on_history_user_id"
+    t.index ["project_id"], name: "index_project_histories_on_project_id"
+    t.index ["snapshot_id"], name: "index_project_histories_on_snapshot_id"
+  end
+
+  create_table "projects", force: :cascade do |t|
+    t.string "name", null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+  end
+
   create_table "safe_post_histories", force: :cascade do |t|
     t.integer "safe_post_id", null: false
     t.string "title", null: false

data/spec/foreign_key_spec.rb

@@ -0,0 +1,189 @@
+require 'spec_helper'
+
+RSpec.describe 'Foreign key handling for belongs_to associations' do
+  before(:all) do
+    @original_stdout = $stdout
+    $stdout = StringIO.new
+    
+    ActiveRecord::Base.connection.create_table :test_users, force: true do |t|
+      t.string :name
+      t.timestamps
+    end
+    
+    ActiveRecord::Base.connection.create_table :test_websites, force: true do |t|
+      t.string :name
+      t.integer :user_id
+      t.timestamps
+    end
+    
+    ActiveRecord::Base.connection.create_table :test_website_histories, force: true do |t|
+      t.integer :test_website_id, null: false
+      t.string :name
+      t.integer :user_id
+      t.timestamps
+      t.datetime :history_started_at, null: false
+      t.datetime :history_ended_at
+      t.integer :history_user_id
+      t.string :snapshot_id
+      
+      t.index :test_website_id
+      t.index :history_started_at
+      t.index :history_ended_at
+      t.index :snapshot_id
+    end
+    
+    ActiveRecord::Base.connection.create_table :test_user_histories, force: true do |t|
+      t.integer :test_user_id, null: false
+      t.string :name
+      t.timestamps
+      t.datetime :history_started_at, null: false
+      t.datetime :history_ended_at
+      t.integer :history_user_id
+      t.string :snapshot_id
+      
+      t.index :test_user_id
+      t.index :history_started_at
+      t.index :history_ended_at
+      t.index :snapshot_id
+    end
+    
+    class TestUser < ActiveRecord::Base
+      include Historiographer
+      has_many :test_websites, foreign_key: 'user_id'
+    end
+    
+    class TestWebsite < ActiveRecord::Base
+      include Historiographer
+      belongs_to :user, class_name: 'TestUser', foreign_key: 'user_id', optional: true
+    end
+    
+    class TestWebsiteHistory < ActiveRecord::Base
+      include Historiographer::History
+    end
+    
+    class TestUserHistory < ActiveRecord::Base
+      include Historiographer::History
+    end
+  end
+  
+  after(:all) do
+    $stdout = @original_stdout
+    ActiveRecord::Base.connection.drop_table :test_website_histories
+    ActiveRecord::Base.connection.drop_table :test_websites
+    ActiveRecord::Base.connection.drop_table :test_user_histories
+    ActiveRecord::Base.connection.drop_table :test_users
+    Object.send(:remove_const, :TestWebsite) if Object.const_defined?(:TestWebsite)
+    Object.send(:remove_const, :TestWebsiteHistory) if Object.const_defined?(:TestWebsiteHistory)
+    Object.send(:remove_const, :TestUser) if Object.const_defined?(:TestUser)
+    Object.send(:remove_const, :TestUserHistory) if Object.const_defined?(:TestUserHistory)
+  end
+  
+  describe 'belongs_to association on history models' do
+    it 'does not raise error about wrong column when accessing belongs_to associations' do
+      # This is the core issue: when a history model has a belongs_to association,
+      # it should not use the foreign key as the primary key for lookups
+      
+      # Create a user
+      user = TestUser.create!(name: 'Test User', history_user_id: 1)
+      
+      # Create a website belonging to the user
+      website = TestWebsite.create!(
+        name: 'Test Website',
+        user_id: user.id,
+        history_user_id: 1
+      )
+      
+      # Get the website history
+      website_history = TestWebsiteHistory.last
+      
+      # The history should have the correct user_id
+      expect(website_history.user_id).to eq(user.id)
+      
+      # The belongs_to association should work without errors
+      # Previously this would fail with "column users.user_id does not exist"
+      # because it was using primary_key: :user_id instead of the default :id
+      expect { website_history.user }.not_to raise_error
+    end
+    
+    it 'allows direct creation of history records with foreign keys' do
+      user = TestUser.create!(name: 'Another User', history_user_id: 1)
+      
+      # Create history attributes like in the original error case
+      attrs = {
+        "name" => "test.example",
+        "user_id" => user.id,
+        "created_at" => Time.now,
+        "updated_at" => Time.now,
+        "test_website_id" => 100,
+        "history_started_at" => Time.now,
+        "history_user_id" => 1,
+        "snapshot_id" => SecureRandom.uuid
+      }
+      
+      # This should not raise an error about test_users.user_id not existing
+      # The original bug was that it would look for test_users.user_id instead of test_users.id
+      expect { TestWebsiteHistory.create!(attrs) }.not_to raise_error
+      
+      history = TestWebsiteHistory.last
+      expect(history.user_id).to eq(user.id)
+    end
+  end
+  
+  describe 'snapshot associations with history models' do
+    it 'correctly filters associations by snapshot_id when using custom association methods' do
+      # First create regular history records
+      user = TestUser.create!(name: 'User One', history_user_id: 1)
+      website = TestWebsite.create!(
+        name: 'Website One',
+        user_id: user.id,
+        history_user_id: 1
+      )
+      
+      # Check that regular histories were created
+      expect(TestUserHistory.count).to eq(1)
+      expect(TestWebsiteHistory.count).to eq(1)
+      
+      # Now create snapshot histories directly (simulating what snapshot would do)
+      snapshot_id = SecureRandom.uuid
+      
+      # Create user history with snapshot
+      user_snapshot = TestUserHistory.create!(
+        test_user_id: user.id,
+        name: user.name,
+        created_at: user.created_at,
+        updated_at: user.updated_at,
+        history_started_at: Time.now,
+        history_user_id: 1,
+        snapshot_id: snapshot_id
+      )
+      
+      # Create website history with snapshot
+      website_snapshot = TestWebsiteHistory.create!(
+        test_website_id: website.id,
+        name: website.name,
+        user_id: user.id,
+        created_at: website.created_at,
+        updated_at: website.updated_at,
+        history_started_at: Time.now,
+        history_user_id: 1,
+        snapshot_id: snapshot_id
+      )
+      
+      # Now test that the association filtering works
+      # The website history's user association should find the user history with the same snapshot_id
+      user_from_association = website_snapshot.user
+      
+      # Since user association points to history when snapshots are involved,
+      # it should return the TestUserHistory with matching snapshot_id
+      if user_from_association.is_a?(TestUserHistory)
+        expect(user_from_association.snapshot_id).to eq(snapshot_id)
+        expect(user_from_association.name).to eq('User One')
+      else
+        # If it returns the regular TestUser (non-history), that's also acceptable
+        # as long as it doesn't error
+        expect(user_from_association).to be_a(TestUser)
+        expect(user_from_association.name).to eq('User One')
+      end
+    end
+  end
+end

data/spec/historiographer_spec.rb

@@ -397,20 +397,6 @@ describe Historiographer do
     end
   end
 
-  describe 'Method stubbing' do
-    it 'handles adding method appropriately' do
-      post = PrivatePost.create(title: 'Post 1', body: "Hello", author_id: 1, history_user_id: 1)
-      expect(post.formatted_title).to eq("Private — You cannot see!")
-      
-      allow_any_instance_of(PrivatePost).to receive(:formatted_title).and_return("New Title")
-      expect(post.formatted_title).to eq("New Title")
-      
-      # Ensure history still works
-      post.update(title: 'Updated Title', history_user_id: user.id)
-      expect(post.histories.count).to eq(2)
-      expect(post.histories.first.class).to eq(PrivatePostHistory)  # Verify correct history class
-    end
-  end
 
   describe 'Scopes' do
     it 'finds current histories' do
@@ -517,6 +503,118 @@ describe Historiographer do
     end
   end
 
+  describe 'Empty insertion handling' do
+    it 'handles duplicate history gracefully by returning existing record' do
+      # Create post without history tracking to avoid initial history
+      post = Post.new(
+        title: 'Post 1',
+        body: 'Great post',
+        author_id: 1,
+        history_user_id: user.id
+      )
+      post.save_without_history
+      
+      # Freeze time to ensure same timestamp
+      Timecop.freeze do
+        # Create a history record with current timestamp
+        now = Historiographer::UTC.now
+        attrs = post.send(:history_attrs, now: now)
+        existing_history = PostHistory.create!(attrs)
+        
+        # Mock insert_all to return empty result (simulating duplicate constraint)
+        empty_result = double('result')
+        allow(empty_result).to receive(:rows).and_return([])
+        
+        allow(PostHistory).to receive(:insert_all).and_return(empty_result)
+        
+        # The method should find and return the existing history
+        allow(Rails.logger).to receive(:warn).with(/Duplicate history detected/) if Rails.logger
+        result = post.send(:record_history)
+        expect(result.id).to eq(existing_history.id)
+        expect(result.post_id).to eq(post.id)
+      end
+    end
+    
+    it 'raises error when insert fails and no existing record found' do
+      post = create_post
+      
+      # Mock insert_all to return an empty result
+      empty_result = double('result')
+      allow(empty_result).to receive(:rows).and_return([])
+      
+      allow(PostHistory).to receive(:insert_all).and_return(empty_result)
+      
+      # Mock the where clause for finding existing history to return nothing
+      # We need to be specific about the where clause we're mocking
+      original_where = PostHistory.method(:where)
+      allow(PostHistory).to receive(:where) do |*args|
+        # Check if this is the specific query for finding duplicates
+        # The foreign key is "post_id" (string) and we're checking for history_started_at
+        if args.first.is_a?(Hash) && args.first.keys.include?("post_id") && args.first.keys.include?(:history_started_at)
+          # Return a double that returns nil when .first is called
+          double('where').tap { |d| allow(d).to receive(:first).and_return(nil) }
+        else
+          # For all other queries, use the original behavior
+          original_where.call(*args)
+        end
+      end
+      
+      # This should raise a meaningful error
+      expect {
+        post.send(:record_history)
+      }.to raise_error(Historiographer::HistoryInsertionError, /Failed to insert history record.*no existing history was found/)
+    end
+
+    it 'provides meaningful error when insertion fails' do
+      post = create_post
+      
+      # Mock insert_all to simulate a database-level failure
+      # This could happen due to various reasons:
+      # - Database is read-only
+      # - Connection issues
+      # - Constraint violations that prevent insertion
+      allow(PostHistory).to receive(:insert_all).and_raise(ActiveRecord::StatementInvalid, "PG::ReadOnlySqlTransaction: ERROR: cannot execute INSERT in a read-only transaction")
+      
+      expect {
+        post.send(:record_history)
+      }.to raise_error(ActiveRecord::StatementInvalid)
+    end
+    
+    it 'successfully inserts history when everything is valid' do
+      post = create_post
+      
+      # Clear existing histories
+      PostHistory.where(post_id: post.id).destroy_all
+      
+      # Record a new history
+      history = post.send(:record_history)
+      
+      expect(history).to be_a(PostHistory)
+      expect(history).to be_persisted
+      expect(history.post_id).to eq(post.id)
+      expect(history.title).to eq(post.title)
+      expect(history.body).to eq(post.body)
+    end
+    
+    it 'handles race conditions by returning existing history' do
+      post = create_post
+      
+      # Simulate a race condition where the same history_started_at timestamp is used
+      now = Time.now
+      allow(Historiographer::UTC).to receive(:now).and_return(now)
+      
+      # First process creates history
+      history1 = post.histories.last
+      
+      # Second process tries to create history with same timestamp
+      # This would normally cause insert_all to return empty rows
+      history2 = post.send(:record_history)
+      
+      # Should handle gracefully
+      expect(history2).to be_a(PostHistory)
+    end
+  end
+
   describe 'Scopes' do
     it 'finds current' do
       post = create_post
@@ -724,102 +822,24 @@ describe Historiographer do
       expect(post.comment_count).to eq 2
       expect(post.latest_snapshot.comment_count).to eq 1
     end
-  end
 
-  describe 'Single Table Inheritance' do
-    let(:user) { User.create(name: 'Test User') }
-    let(:private_post) do 
-      PrivatePost.create(
-        title: 'Private Post',
-        body: 'Test',
-        history_user_id: user.id,
-        author_id: 1
-      )
-    end
+    it "doesn't explode" do
+      project = Project.create(name: "test_project")
+      project_file = ProjectFile.create(project: project, name: "test_file", content: "Hello world")
 
-    it 'maintains original class type on create' do
-      post_history = private_post.histories.first
-      expect(post_history.original_class).to eq(PrivatePost)
-    end
+      original_snapshot = project.snapshot
 
-    it 'maintains original class in history records' do
-      post_history = private_post.histories.first
-      expect(post_history.original_class).to eq(PrivatePost)
-      expect(post_history.title).to eq('Private — You cannot see!')
-    end
+      project_file.update(content: "Goodnight moon")
+      new_snapshot = project.snapshot
 
-    it 'maintains original class behavior when updating' do
-      private_post.update(title: 'Updated Private Post', history_user_id: user.id)
-      new_history = private_post.histories.current&.first
-      expect(new_history.original_class).to eq(PrivatePost)
-      expect(new_history.title).to eq('Private — You cannot see!')
-    end
+      expect(original_snapshot.files.map(&:class)).to eq [ProjectFileHistory]
+      expect(new_snapshot.files.map(&:class)).to eq [ProjectFileHistory]
 
-    it 'maintains original class behavior when reifying' do
-      private_post.update(title: 'Updated Private Post', history_user_id: user.id)
-      old_history = private_post.histories.first
-      reified = old_history
-      expect(reified.title).to eq('Private — You cannot see!')
-      expect(reified.original_class).to eq(PrivatePost)
+      expect(new_snapshot.files.first.content).to eq "Goodnight moon"
+      expect(original_snapshot.files.first.content).to eq "Hello world"
     end
   end
 
-  describe 'Single Table Inheritance with Associations' do
-    let(:user) { User.create(name: 'Test User') }
-
-    it 'inherits associations in history classes' do
-      dataset = Dataset.create(name: "test_dataset", history_user_id: user.id)
-      model = XGBoost.create(name: "test_model", dataset: dataset, history_user_id: user.id)
-      model.snapshot
-
-      dataset.update(name: "new_dataset", history_user_id: user.id)
-      
-      expect(dataset.ml_model).to eq model # This is still a live model
-      expect(model.dataset).to eq(dataset)
-      expect(model.histories.first).to respond_to(:dataset)
-      expect(model.histories.first.dataset).to be_a(DatasetHistory)
-
-      model_history = model.latest_snapshot
-      expect(model_history.dataset.name).to eq "test_dataset"
-    end
-  end
-
-  describe 'Single Table Inheritance with custom inheritance column' do
-    let(:user) { User.create(name: 'Test User') }
-    let(:xgboost) do
-      XGBoost.create(
-        name: 'My XGBoost Model',
-        parameters: { max_depth: 3, eta: 0.1 },
-        history_user_id: user.id
-      )
-    end
-
-    it 'creates history records with correct inheritance' do
-      model = xgboost
-      expect(model.model_name).to eq('XGBoost')
-      expect(model.current_history).to be_a(XGBoostHistory)
-      expect(model.current_history.model_name).to eq('XGBoostHistory')
-    end
-
-    it 'maintains inheritance through updates' do
-      model = xgboost
-      model.update(name: 'Updated XGBoost Model', history_user_id: user.id)
-      
-      expect(model.histories.count).to eq(2)
-      expect(model.histories.all? { |h| h.is_a?(XGBoostHistory) }).to be true
-    end
-
-    it 'reifies with correct class' do
-      model = xgboost
-      original_name = model.name
-      model.update(name: 'Updated XGBoost Model', history_user_id: user.id)
-      model.snapshot
-      
-      reified = model.latest_snapshot
-      expect(reified).to be_a(XGBoostHistory)
-      expect(reified.name).to eq("Updated XGBoost Model")
-    end
-  end
 
   describe 'Class-level mode setting' do
     before(:each) do
@@ -882,24 +902,6 @@ describe Historiographer do
       expect(col_history).to be_a(EasyML::ColumnHistory)
     end
 
-    it 'establishes correct associations for child classes' do
-      encrypted_col = EasyML::Column.create(
-        name: 'secret_feature',
-        data_type: 'numeric',
-        history_user_id: user.id,
-        column_type: "EasyML::EncryptedColumn"
-      )
-      
-      # Verify the base record
-      expect(encrypted_col).to be_a(EasyML::EncryptedColumn)
-      expect(encrypted_col.encrypted?).to be true
-      
-      # Verify history record
-      col_history = encrypted_col.histories.last
-      expect(col_history).to be_a(EasyML::EncryptedColumnHistory)
-      expect(col_history.class.history_foreign_key).to eq('column_id')
-      expect(col_history.encrypted?).to be true
-    end
 
     it 'uses correct table names' do
       expect(EasyML::Column.table_name).to eq('easy_ml_columns')

data/spec/models/easy_ml/column.rb

@@ -1,7 +1,6 @@
 module EasyML
   class Column < ActiveRecord::Base
     self.table_name = "easy_ml_columns"
-    self.inheritance_column = "column_type"
     include Historiographer
   end
 end

data/spec/models/project.rb

@@ -0,0 +1,4 @@
+class Project < ApplicationRecord
+  include Historiographer::Safe
+  has_many :files, class_name: "ProjectFile"
+end

data/spec/models/project_file.rb

@@ -0,0 +1,5 @@
+class ProjectFile < ApplicationRecord
+  include Historiographer::Safe
+
+  belongs_to :project
+end

data/spec/models/project_file_history.rb

@@ -0,0 +1,4 @@
+class ProjectFileHistory < ActiveRecord::Base
+  self.table_name = "project_file_histories"
+  include Historiographer::History
+end

data/spec/models/project_history.rb

@@ -0,0 +1,4 @@
+class ProjectHistory < ActiveRecord::Base
+  self.table_name = "project_histories"
+  include Historiographer::History
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: historiographer
 version: !ruby/object:Gem::Version
-  version: 4.1.16
+  version: 4.4.0
 platform: ruby
 authors:
 - brettshollenberger
@@ -228,6 +228,7 @@ files:
 - historiographer-4.1.12.gem
 - historiographer-4.1.13.gem
 - historiographer-4.1.14.gem
+- historiographer-4.3.0.gem
 - historiographer.gemspec
 - init.rb
 - instructions/implementation.md
@@ -258,31 +259,26 @@ files:
 - spec/db/migrate/20221018204255_create_silent_post_histories.rb
 - spec/db/migrate/20241109182017_create_comments.rb
 - spec/db/migrate/20241109182020_create_comment_histories.rb
-- spec/db/migrate/20241118000000_add_type_to_posts.rb
-- spec/db/migrate/20241118000001_add_type_to_post_histories.rb
-- spec/db/migrate/20241118000002_create_ml_models.rb
-- spec/db/migrate/20241118000003_create_easy_ml_columns.rb
 - spec/db/migrate/20241119000000_create_datasets.rb
+- spec/db/migrate/2025082100000_create_projects.rb
+- spec/db/migrate/2025082100001_create_project_files.rb
 - spec/db/schema.rb
 - spec/factories/post.rb
+- spec/foreign_key_spec.rb
 - spec/historiographer_spec.rb
 - spec/models/application_record.rb
 - spec/models/author.rb
 - spec/models/author_history.rb
 - spec/models/comment.rb
 - spec/models/comment_history.rb
-- spec/models/dataset.rb
-- spec/models/dataset_history.rb
 - spec/models/easy_ml/column.rb
 - spec/models/easy_ml/column_history.rb
-- spec/models/easy_ml/encrypted_column.rb
-- spec/models/easy_ml/encrypted_column_history.rb
-- spec/models/ml_model.rb
-- spec/models/ml_model_history.rb
 - spec/models/post.rb
 - spec/models/post_history.rb
-- spec/models/private_post.rb
-- spec/models/private_post_history.rb
+- spec/models/project.rb
+- spec/models/project_file.rb
+- spec/models/project_file_history.rb
+- spec/models/project_history.rb
 - spec/models/safe_post.rb
 - spec/models/safe_post_history.rb
 - spec/models/silent_post.rb
@@ -291,8 +287,6 @@ files:
 - spec/models/thing_with_compound_index_history.rb
 - spec/models/thing_without_history.rb
 - spec/models/user.rb
-- spec/models/xgboost.rb
-- spec/models/xgboost_history.rb
 - spec/spec_helper.rb
 homepage: http://github.com/brettshollenberger/historiographer
 licenses:

data/spec/db/migrate/20241118000000_add_type_to_posts.rb

@@ -1,6 +0,0 @@
-class AddTypeToPosts < ActiveRecord::Migration[7.1]
-  def change
-    add_column :posts, :type, :string
-    add_index :posts, :type
-  end
-end

data/spec/db/migrate/20241118000001_add_type_to_post_histories.rb

@@ -1,5 +0,0 @@
-class AddTypeToPostHistories < ActiveRecord::Migration[7.0]
-  def change
-    add_column :post_histories, :type, :string
-  end
-end

data/spec/db/migrate/20241118000002_create_ml_models.rb

@@ -1,19 +0,0 @@
-require "historiographer/postgres_migration"
-require "historiographer/mysql_migration"
-
-class CreateMlModels < ActiveRecord::Migration[7.0]
-  def change
-    create_table :ml_models do |t|
-      t.string :name
-      t.string :model_type
-      t.jsonb :parameters
-      t.timestamps
-
-      t.index :model_type
-    end
-
-    create_table :ml_model_histories do |t|
-      t.histories
-    end
-  end
-end

data/spec/db/migrate/20241118000003_create_easy_ml_columns.rb

@@ -1,17 +0,0 @@
-require "historiographer/postgres_migration"
-require "historiographer/mysql_migration"
-
-class CreateEasyMlColumns < ActiveRecord::Migration[7.1]
-  def change
-    create_table :easy_ml_columns do |t|
-      t.string :name, null: false
-      t.string :data_type, null: false
-      t.string :column_type
-      t.timestamps
-    end
-
-    create_table :easy_ml_column_histories do |t|
-      t.histories(foreign_key: :column_id)
-    end
-  end
-end

data/spec/models/dataset.rb

@@ -1,6 +0,0 @@
-class Dataset < ActiveRecord::Base
-  include Historiographer
-  self.table_name = "datasets"
-
-  belongs_to :ml_model, class_name: "MLModel"
-end

data/spec/models/dataset_history.rb

@@ -1,4 +0,0 @@
-class DatasetHistory < ActiveRecord::Base
-  include Historiographer::History
-  self.table_name = "dataset_histories"
-end

data/spec/models/easy_ml/encrypted_column.rb

@@ -1,10 +0,0 @@
-module EasyML
-  class EncryptedColumn < Column
-    self.inheritance_column = "column_type"
-    include Historiographer
-
-    def encrypted?
-      true
-    end
-  end
-end

data/spec/models/easy_ml/encrypted_column_history.rb

@@ -1,6 +0,0 @@
-module EasyML
-  class EncryptedColumnHistory < ActiveRecord::Base
-    self.table_name = "easy_ml_column_histories"
-    include Historiographer::History
-  end
-end

data/spec/models/ml_model.rb

@@ -1,6 +0,0 @@
-class MLModel < ActiveRecord::Base
-  self.inheritance_column = "model_type"
-  include Historiographer
-
-  has_one :dataset
-end

data/spec/models/ml_model_history.rb

@@ -1,4 +0,0 @@
-class MLModelHistory < ActiveRecord::Base
-  include Historiographer::History
-  self.table_name = "ml_model_histories"
-end

data/spec/models/private_post.rb

@@ -1,12 +0,0 @@
-class PrivatePost < Post
-  self.table_name = "posts"
-  include Historiographer
-
-  def title
-    "Private — You cannot see!"
-  end
-
-  def formatted_title
-    "Private — You cannot see!"
-  end
-end

data/spec/models/private_post_history.rb

@@ -1,4 +0,0 @@
-class PrivatePostHistory < ActiveRecord::Base
-  self.table_name = "post_histories"
-  include Historiographer::History
-end

data/spec/models/xgboost.rb

@@ -1,10 +0,0 @@
-class XGBoost < MLModel
-  self.table_name = "ml_models"
-  self.inheritance_column = "model_type"
-  include Historiographer
-  after_initialize :set_defaults
-
-  def set_defaults
-    write_attribute(:model_type, "XGBoost")
-  end
-end

data/spec/models/xgboost_history.rb

@@ -1,4 +0,0 @@
-class XGBoostHistory < ActiveRecord::Base
-  include Historiographer::History
-  self.table_name = "ml_model_histories"
-end