active_version 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f1b2d07a134e66e4e4330b9d195b32d831d3a2ce0599c324bed86157eb2e3fc
-  data.tar.gz: f612e466b59f335183016fc5d9d601005a4b66b07efa6276b54c1260bbd08736
+  metadata.gz: d52287aa8ea68e0c77baff3065a3140d397c2e638460967880b0b0dbc904b42c
+  data.tar.gz: aff296230f04d04d90bafe26e12fe0876fc2cd292cd07e6083d71a595a9ea6f6
 SHA512:
-  metadata.gz: '068727dace361f83992e6b6e92b25e2dcb50cc5128e5cbb80114cfd4d48fa7f4f406f0fe216de0518becbe75f9186ab18637211452ce2a98b66825ea513172f7'
-  data.tar.gz: 6d09e28cbb0b651a4aaa89fb879a48e978bb9d9fcde7d3c312226ca256963ed119b9aba9e016eaddbe6a0a613d2e10140c5474f280d545f318fdb80282007930
+  metadata.gz: 35c7b1c96056c61e5c36a72166d2be067504da0fa922fd439ad4a6b1a09a7630ae80734fb2ad8e97dfb81fd3302c75ed168cb92adb22669f222e5cd6aa363a90
+  data.tar.gz: db6759859ffd1139a818c45a23ae486e819e035553b32762f586465cbef3a2597507a80ea424036ecc0718fe6a9dbf25cb11fe5c8e4e6c7556d27e124e13704f

data/CHANGELOG.md

@@ -1,9 +1,25 @@
 # CHANGELOG
 
+## 2.0.0 (2026-08-21)
+
+- BREAKING: Require Active Support and Active Record `>= 7.2.3.2` and `< 9.0`.
+- Retry unique version collisions so a revision snapshot or audit still writes after a concurrent insert, including inside an open PostgreSQL transaction.
+- Add `rfcs/` starter pack: process (RFC 0001), positioning (RFC 0002), and Standards Track design RFCs 0003–0006 for translations, revisions, audits, and generators.
+
+## 1.4.0 (2026-07-13)
+
+- Add `revision_error_behavior` configuration (`:exception`, `:log`, `:silent`) and per-model `has_revisions error_behavior:` override for revision snapshot failures.
+- Skip post-update revision bookkeeping when snapshot creation returns nil under `:log` or `:silent` revision error handling.
+- Route audit warning output through `ActiveVersion.logger` so non-Rails apps and custom log sinks receive audit write failures consistently.
+- Align audit writer fallback error behavior with the configuration default (`:exception`) when neither per-model nor global audit error behavior is set.
+- Fix audit combining to refresh the cached audits association instead of reloading the auditable record, and bound combiner queries with COUNT and LIMIT instead of loading the full audit history each iteration.
+- Fix thread-local audited options reader installation on Rails 6.1 models with delegated class methods.
+- Log debug detail for deferred audit setup, instrumentation probes, and unparseable audit payloads when `ActiveVersion.logger` supports debug output.
+
 ## 1.3.0 (2026-04-15)
 
-- Add `polyrun` `~> 1.2.0` development dependency; `bin/polyrun`, `bin/rspec`, `polyrun.yml`, and `config/polyrun_coverage.yml` for parallel RSpec and merged coverage.
-- Add `script/create_postgres_shard_databases.sh` for CI and local Postgres shard databases; document in `POLYRUN.md`; set job-level `DATABASE_URL` in GitHub Actions test workflow.
+- Add `polyrun` `~> 1.3.0` development dependency; `bin/polyrun`, `bin/rspec`, `polyrun.yml`, and `config/polyrun_coverage.yml` for parallel RSpec and merged coverage.
+- Add `script/create_postgres_shard_databases.sh` for CI and local Postgres shard databases; document in `spec/README.md`; set job-level `DATABASE_URL` in GitHub Actions test workflow.
 - Add internal library logger.
 - Fix audits, Sequel foreign keys, revision debounce, and versions walk edge cases.
 - Adjust RSpec and RuboCop test configuration; update spec coverage.

data/README.md

@@ -1,9 +1,11 @@
 # ActiveVersion
 
-[![Gem Version](https://badge.fury.io/rb/active_version.svg)](https://badge.fury.io/rb/active_version) [![Test Status](https://github.com/amkisko/active_version.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/active_version.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/active_version.rb/graph/badge.svg?token=2U6NXJOVVM)](https://codecov.io/gh/amkisko/active_version.rb)
+[![Gem Version](https://badge.fury.io/rb/active_version.svg)](https://badge.fury.io/rb/active_version) [![Test Status](https://github.com/amkisko/active_version.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/active_version.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/active_version.rb/graph/badge.svg?token=2U6NXJOVVM)](https://app.codecov.io/github/amkisko/active_version.rb)
 
 A unified versioning library for ActiveRecord that handles translations, revisions, and audits in a single, extensible architecture.
 
+Design changes go through `rfcs/` (RFC 0001).
+
 ## Features
 
 - Translations: Locale-based versioning with automatic value copying
@@ -305,6 +307,8 @@ rails g active_version:triggers Post --type=audit
 rails g active_version:triggers Post --type=revision
 ```
 
+PostgreSQL audit triggers capture the full row as JSON. They do not apply Ruby-side `only`, `except`, or `redacted` filters from `has_audits`. Use triggers only when you want complete row snapshots at the database layer, or generate custom trigger SQL that matches your column policy.
+
 ### Infrastructure Ownership
 
 ```ruby
@@ -500,14 +504,27 @@ Environment knobs:
 ## Requirements
 
 - Ruby >= 3.0.0
-- ActiveRecord >= 6.0.0 (default runtime)
+- ActiveRecord >= 7.2.3.2 and < 9.0 (default runtime)
 - SQLite or MySQL or PostgreSQL (optional, for triggers and JSONB support)
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/amkisko/active_version.rb.
 
-Development dependencies include [polyrun](https://rubygems.org/gems/polyrun) **`~> 1.2.0`** (declared in `active_version.gemspec`) for **parallel RSpec** (`./bin/polyrun`), coverage, and CI report formats—see [POLYRUN.md](POLYRUN.md).
+Development dependencies include [polyrun](https://rubygems.org/gems/polyrun) (declared in `active_version.gemspec`) for **parallel RSpec** (`./bin/polyrun`), coverage, and CI report formats—see [spec/README.md](spec/README.md).
+
+## Links
+
+- [GitHub](https://github.com/amkisko/active_version.rb)
+- [GitLab](https://gitlab.com/amkisko/active_version.rb)
+- [RubyGems](https://rubygems.org/gems/active_version)
+- [Versions Atom](https://rubygems.org/gems/active_version/versions.atom) (feed id `10668858017926`)
+- [libraries.io](https://libraries.io/rubygems/active_version)
+- [Deps.dev](https://deps.dev/rubygems/active_version)
+- [SonarCloud](https://sonarcloud.io/project/overview?id=amkisko_active_version.rb)
+- [Snyk](https://snyk.io/test/github/amkisko/active_version.rb)
+- [Codecov](https://app.codecov.io/github/amkisko/active_version.rb)
+- [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/amkisko/active_version.rb)
 
 ## License
 

data/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Reporting a Vulnerability
 
-Do NOT open a public GitHub issue for security vulnerabilities.
+Do not open a public issue for security vulnerabilities.
 
 Email security details to: security@kiskolabs.com
 
@@ -23,7 +23,5 @@ Include: description, steps to reproduce, potential impact, and suggested fix (i
 
 ## Automation Security
 
-* Context Isolation: It is strictly forbidden to include production credentials, API keys, or Personally Identifiable Information (PII) in prompts sent to third-party LLMs or automation services.
-
-* Supply Chain: All automated dependencies must be verified.
-
+- Context Isolation: It is strictly forbidden to include production credentials, API keys, or Personally Identifiable Information (PII) in prompts sent to third-party LLMs or automation services.
+- Supply Chain: All automated dependencies must be verified.

data/lib/active_version/adapters/active_record/audits.rb

@@ -11,7 +11,7 @@ module ActiveVersion
         module ClassMethods
           # Declare that a model has audits
           def has_audits(options = {})
-            include ActiveVersion::Audits::HasAudits unless included_modules.include?(ActiveVersion::Audits::HasAudits)
+            include ActiveVersion::Audits::HasAudits unless include?(ActiveVersion::Audits::HasAudits)
 
             # Call the HasAudits implementation once included
             ActiveVersion::Audits::HasAudits::ClassMethods.instance_method(:has_audits)
@@ -30,7 +30,7 @@ end
 
 # If ActiveRecord::Base is already loaded, include immediately
 if defined?(ActiveRecord::Base) && ActiveRecord::Base.respond_to?(:include)
-  unless ActiveRecord::Base.included_modules.include?(ActiveVersion::Adapters::ActiveRecord::Audits)
+  unless ActiveRecord::Base.include?(ActiveVersion::Adapters::ActiveRecord::Audits)
     ActiveSupport.on_load(:active_record) { include ActiveVersion::Adapters::ActiveRecord::Audits }
   end
 end

data/lib/active_version/adapters/active_record/revisions.rb

@@ -43,7 +43,7 @@ end
 
 # If ActiveRecord::Base is already loaded, include immediately
 if defined?(ActiveRecord::Base) && ActiveRecord::Base.respond_to?(:include)
-  unless ActiveRecord::Base.included_modules.include?(ActiveVersion::Adapters::ActiveRecord::Revisions)
+  unless ActiveRecord::Base.include?(ActiveVersion::Adapters::ActiveRecord::Revisions)
     ActiveSupport.on_load(:active_record) { include ActiveVersion::Adapters::ActiveRecord::Revisions }
   end
 end

data/lib/active_version/adapters/active_record/translations.rb

@@ -39,7 +39,7 @@ end
 
 # If ActiveRecord::Base is already loaded, include immediately
 if defined?(ActiveRecord::Base) && ActiveRecord::Base.respond_to?(:include)
-  unless ActiveRecord::Base.included_modules.include?(ActiveVersion::Adapters::ActiveRecord::Translations)
+  unless ActiveRecord::Base.include?(ActiveVersion::Adapters::ActiveRecord::Translations)
     ActiveSupport.on_load(:active_record) { include ActiveVersion::Adapters::ActiveRecord::Translations }
   end
 end

data/lib/active_version/audits/audit_record/serializers.rb

@@ -16,7 +16,10 @@ module ActiveVersion
             return value unless value.is_a?(String)
 
             JSON.parse(value)
-          rescue JSON::ParserError
+          rescue JSON::ParserError => error
+            ActiveVersion.log_debug(
+              "[ActiveVersion::Audits::AuditRecord::Serializers::Json] failed to parse audit payload: #{error.message}"
+            )
             value
           end
 
@@ -35,7 +38,10 @@ module ActiveVersion
             return value unless value.is_a?(String)
 
             YAML.safe_load(value, permitted_classes: PERMITTED_CLASSES, aliases: false)
-          rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::AliasesNotEnabled, ArgumentError
+          rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::AliasesNotEnabled, ArgumentError => error
+            ActiveVersion.log_debug(
+              "[ActiveVersion::Audits::AuditRecord::Serializers::Yaml] failed to parse audit payload: #{error.message}"
+            )
             value
           end
 

data/lib/active_version/audits/audit_record.rb

@@ -125,10 +125,10 @@ module ActiveVersion
               attribute changes_column, :text unless attribute_names.include?(changes_column.to_s)
               attribute context_column, :text unless attribute_names.include?(context_column.to_s)
             end
-          rescue *ActiveVersion::Runtime.active_record_connection_errors => e
-            if defined?(Rails) && Rails.respond_to?(:logger)
-              Rails.logger&.debug("[ActiveVersion] Deferred audit attribute setup for #{name}: #{e.class}: #{e.message}")
-            end
+          rescue *ActiveVersion::Runtime.active_record_connection_errors => error
+            ActiveVersion.log_debug(
+              "[ActiveVersion] Deferred audit attribute setup for #{name}: #{error.class}: #{error.message}"
+            )
           end
 
           begin
@@ -156,10 +156,10 @@ module ActiveVersion
             end
           rescue NameError
             # Source class not yet defined, will be set up later
-          rescue *ActiveVersion::Runtime.active_record_connection_errors => e
-            if defined?(Rails) && Rails.respond_to?(:logger)
-              Rails.logger&.debug("[ActiveVersion] Deferred audit association setup for #{name}: #{e.class}: #{e.message}")
-            end
+          rescue *ActiveVersion::Runtime.active_record_connection_errors => error
+            ActiveVersion.log_debug(
+              "[ActiveVersion] Deferred audit association setup for #{name}: #{error.class}: #{error.message}"
+            )
           end
         end
 

data/lib/active_version/audits/has_audits/audit_combiner.rb

@@ -24,54 +24,27 @@ module ActiveVersion
             iteration += 1
             break if iteration > max_iterations
 
-            # Force reload from database to see any updates
-            if persisted?
-              reload
-            end
-
-            # Clear association cache to ensure we get fresh data from database.
-            # Avoid calling audits reader directly here to prevent AR 6.1
-            # delegation edge cases on dynamic models.
+            # Clear association cache so the direct audit query below sees SQL updates
+            # from prior combine rounds without reloading the auditable record.
             if respond_to?(:association) && association_cached?(:audits)
               association(:audits).reset
             end
 
-            # Get all audits fresh from database (not from cache)
-            # Query directly to ensure we get updated values after SQL updates
             auditable_type = audited_options[:class_name] || self.class.name
             auditable_column = ActiveVersion.column_mapper.column_for(self.class, :audits, :auditable)
             version_column = ActiveVersion.column_mapper.column_for(self.class, :audits, :version)
-            audit_klass =
-              if self.class.reflect_on_association(:audits)
-                association(:audits).klass
-              else
-                self.class.audit_class
-              end
-            if audit_klass.nil? && self.class.respond_to?(:resolve_audit_class_option, true)
-              audit_klass = self.class.send(:resolve_audit_class_option, audited_options[:as])
-            end
+            audit_klass = combiner_audit_klass
             break unless audit_klass
-            all_audits = audit_klass.where({"#{auditable_column}_type" => auditable_type}.merge(active_version_audit_identity_map))
-              .order(version_column => :asc)
-              .to_a
 
-            # Filter out combined audits (those with empty changes)
-            # Check raw column value first (before JSON parsing) for "{}" string
-            active_audits = all_audits.reject do |audit|
-              # Check raw column value first - combined audits have "{}" as string
-              raw_changes = audit.read_attribute(changes_column)
-
-              # If raw value is exactly "{}", it's a combined audit
-              if raw_changes.is_a?(String) && raw_changes.strip == "{}"
-                true
-              else
-                # Otherwise check parsed value
-                changes = audit.audited_changes
-                changes.nil? || (changes.is_a?(Hash) && changes.empty?) || (changes.is_a?(String) && changes.strip.empty?)
-              end
-            end
+            active_scope = active_audits_scope_for_combiner(
+              audit_klass,
+              auditable_type,
+              auditable_column,
+              version_column,
+              changes_column
+            )
 
-            audits_count = active_audits.length
+            audits_count = active_scope.count
             break if audits_count <= max_audits
 
             # Calculate how many extra audits we have
@@ -79,7 +52,11 @@ module ActiveVersion
 
             # Get the oldest active audits to combine (first extra_count + 1)
             # The +1 is because we'll merge into the last one in this set
-            audits_to_combine = active_audits.first(extra_count + 1)
+            audits_to_combine = active_scope
+              .limit(extra_count + 1)
+              .to_a
+              .reject { |audit| combined_audit_record?(audit, changes_column) }
+              .first(extra_count + 1)
 
             # Safety check to prevent infinite loops
             break if audits_to_combine.empty? || audits_to_combine.length <= 1
@@ -89,6 +66,39 @@ module ActiveVersion
           end
         end
 
+        def combiner_audit_klass
+          audit_klass =
+            if self.class.reflect_on_association(:audits)
+              association(:audits).klass
+            else
+              self.class.audit_class
+            end
+          if audit_klass.nil? && self.class.respond_to?(:resolve_audit_class_option, true)
+            audit_klass = self.class.send(:resolve_audit_class_option, audited_options[:as])
+          end
+          audit_klass
+        end
+
+        def active_audits_scope_for_combiner(audit_klass, auditable_type, auditable_column, version_column, changes_column)
+          audit_klass
+            .where({"#{auditable_column}_type" => auditable_type}.merge(active_version_audit_identity_map))
+            .where.not(changes_column => nil)
+            .where.not(changes_column => "")
+            .where.not(changes_column => "{}")
+            .order(version_column => :asc)
+        end
+
+        def combined_audit_record?(audit, changes_column)
+          raw_changes = audit.read_attribute(changes_column)
+
+          if raw_changes.is_a?(String) && raw_changes.strip == "{}"
+            true
+          else
+            changes = audit.audited_changes
+            changes.nil? || (changes.is_a?(Hash) && changes.empty?) || (changes.is_a?(String) && changes.strip.empty?)
+          end
+        end
+
         def evaluate_max_audits
           max_audits = case (option = audited_options[:max_audits])
           when Proc then option.call

data/lib/active_version/audits/has_audits/audit_writer.rb

@@ -187,48 +187,52 @@ module ActiveVersion
                 return nil
               end
 
-              begin
-                audit_class.create!(insert_attrs)
-                combine_audits_if_needed if attrs[:action] != "create"
-                association(:audits).reset if association_cached?(:audits)
-                nil
-              rescue ActiveRecord::RecordNotUnique => e
-                # Handle unique constraint violation (likely version conflict)
-                # Retry once with recalculated version
-                if e.message.include?("version") && attrs[:action] != "create"
-                  # Recalculate version and retry
-                  # Use class_name from options if provided (for dynamically created classes)
-                  auditable_type_for_query = audited_options[:class_name] || self.class.name
-                  if auditable_type_for_query.nil?
-                    raise ConfigurationError, "Cannot determine class name for dynamically created class. Please specify class_name option in has_audits"
-                  end
-                  max_version = audit_class.where({"#{auditable_column}_type" => auditable_type_for_query}.merge(active_version_audit_identity_map))
-                    .maximum(version_column) || 0
-                  insert_attrs[version_column] = max_version + 1
-                  begin
-                    audit_class.create!(insert_attrs)
-                    combine_audits_if_needed if attrs[:action] != "create"
-                    association(:audits).reset if association_cached?(:audits)
-                    nil
-                  rescue => retry_error
-                    handle_audit_errors(retry_error, attrs[:action])
-                    nil
-                  end
-                else
-                  handle_audit_errors(e, attrs[:action])
-                  nil
-                end
-              rescue => e
-                handle_audit_errors(e, attrs[:action])
-                nil
-              end
+              create_audit_record_with_version_retry!(
+                insert_attrs,
+                version_column: version_column,
+                auditable_column: auditable_column,
+                action: attrs[:action]
+              )
+            end
+          end
+        end
+
+        # One retry on unique (version) collision. Each insert uses a savepoint so
+        # PostgreSQL can continue the outer update/lock transaction after a unique violation.
+        def create_audit_record_with_version_retry!(insert_attrs, version_column:, auditable_column:, action:)
+          attempt = 0
+          begin
+            attempt += 1
+            self.class.transaction(requires_new: true) do
+              audit_class.create!(insert_attrs)
+            end
+            combine_audits_if_needed if action != "create"
+            association(:audits).reset if association_cached?(:audits)
+            nil
+          rescue => error
+            unless ActiveVersion::UniqueVersionCollision.match?(error, version_column: version_column) &&
+                action != "create" && attempt < 2
+              handle_audit_errors(error, action)
+              return nil
+            end
+
+            auditable_type_for_query = audited_options[:class_name] || self.class.name
+            if auditable_type_for_query.nil?
+              raise ConfigurationError, "Cannot determine class name for dynamically created class. Please specify class_name option in has_audits"
+            end
+
+            max_version = audit_class.uncached do
+              audit_class.where({"#{auditable_column}_type" => auditable_type_for_query}.merge(active_version_audit_identity_map))
+                .maximum(version_column) || 0
             end
+            insert_attrs[version_column] = max_version + 1
+            retry
           end
         end
 
         def handle_audit_errors(error, action)
           ActiveVersion::Instrumentation.instrument_audit_write_failed(self, error: error, action: action)
-          behavior = audited_options[:error_behavior] || ActiveVersion.config.audit_error_behavior || :log
+          behavior = audited_options[:error_behavior] || ActiveVersion.config.audit_error_behavior || :exception
 
           case behavior
           when :log
@@ -241,7 +245,7 @@ module ActiveVersion
         end
 
         def log_audit_errors(error, action)
-          Rails.logger&.warn(
+          ActiveVersion.logger.warn(
             "Unable to create audit for #{action} of #{self.class.name}" \
             "##{id}: #{error.message}"
           )

data/lib/active_version/audits/has_audits.rb

@@ -419,7 +419,7 @@ module ActiveVersion
         private
 
         def install_thread_local_audited_options_reader!
-          unless singleton_class.instance_methods(false).include?(:audited_options_without_thread_local)
+          unless singleton_class.method_defined?(:audited_options_without_thread_local, false)
             singleton_class.alias_method :audited_options_without_thread_local, :audited_options
           end
 

data/lib/active_version/instrumentation.rb

@@ -217,9 +217,7 @@ module ActiveVersion
       end
 
       def log_debug(message)
-        if defined?(Rails) && Rails.respond_to?(:logger)
-          Rails.logger&.debug("[ActiveVersion::Instrumentation] #{message}")
-        end
+        ActiveVersion.log_debug("[ActiveVersion::Instrumentation] #{message}")
       end
     end
   end

data/lib/active_version/revisions/has_revisions/revision_manipulation.rb

@@ -113,30 +113,25 @@ module ActiveVersion
             pseudo.define_singleton_method(:persisted?) { true }
             pseudo
           else
-
-            # Use create! instead of build + save to get better error messages
             begin
               revision = create_revision_record_with_version_retry!(revision_attrs, version_column_sym)
-            rescue ActiveRecord::RecordInvalid => e
-              ActiveVersion::Instrumentation.instrument_revision_write_failed(self, error: e)
-              error_msg = "Failed to create revision: #{e.class}"
-              error_msg += "\nRevision attribute keys: #{revision_attrs.keys.map(&:to_s).sort.join(", ")}"
-              error_msg += "\nIdentity keys: #{active_version_revision_identity_map.keys.map(&:to_s).sort.join(", ")}"
-              error_msg += "\nVersion column: #{version_column_sym}, New version: #{new_version}"
-              error_msg += "\nRevision class: #{self.class.revision_class.name}"
-              error_msg += "\nSource class: #{self.class.name}"
-              if e.record
-                error_msg += "\nRecord error fields: #{e.record.errors.attribute_names.map(&:to_s).uniq.sort.join(", ")}"
-                error_msg += "\nRecord valid?: #{e.record.valid?}"
-              end
-              raise error_msg
-            rescue => e
-              ActiveVersion::Instrumentation.instrument_revision_write_failed(self, error: e)
-              error_msg = "Failed to create revision: #{e.class}"
-              error_msg += "\nRevision attribute keys: #{revision_attrs.keys.map(&:to_s).sort.join(", ")}"
-              error_msg += "\nIdentity keys: #{active_version_revision_identity_map.keys.map(&:to_s).sort.join(", ")}"
-              error_msg += "\nVersion column: #{version_column_sym}, New version: #{new_version}"
-              raise error_msg
+            rescue ActiveRecord::RecordInvalid => error
+              revision = handle_revision_errors(
+                error,
+                revision_attrs: revision_attrs,
+                version_column_sym: version_column_sym,
+                new_version: new_version,
+                invalid_record: error.record
+              )
+              return revision unless revision
+            rescue => error
+              revision = handle_revision_errors(
+                error,
+                revision_attrs: revision_attrs,
+                version_column_sym: version_column_sym,
+                new_version: new_version
+              )
+              return revision unless revision
             end
 
             # Force reload association to ensure it's visible
@@ -426,21 +421,70 @@ module ActiveVersion
           revisions.reset
         end
 
-        # One retry on unique (version) violation, matching audit_writer behavior when a DB unique index exists.
+        # One retry on unique (version) collision. Each insert uses a savepoint so
+        # PostgreSQL can continue the outer update/lock transaction after a unique violation.
         def create_revision_record_with_version_retry!(revision_attrs, version_column_sym)
           attempt = 0
           begin
             attempt += 1
-            revisions.create!(revision_attrs)
-          rescue ActiveRecord::RecordNotUnique => e
-            raise e if attempt >= 2
+            self.class.transaction(requires_new: true) do
+              revisions.create!(revision_attrs)
+            end
+          rescue => error
+            raise error unless ActiveVersion::UniqueVersionCollision.match?(error, version_column: version_column_sym)
+            raise error if attempt >= 2
 
-            max_version = revisions_scope.maximum(version_column_sym) || 0
+            max_version = revisions_scope.uncached { revisions_scope.maximum(version_column_sym) } || 0
             revision_attrs[version_column_sym] = max_version + 1
             retry
           end
         end
-        private :create_revision_record_with_version_retry!
+
+        def handle_revision_errors(error, revision_attrs:, version_column_sym:, new_version:, invalid_record: nil)
+          ActiveVersion::Instrumentation.instrument_revision_write_failed(self, error: error)
+          behavior = self.class.revision_options&.dig(:error_behavior) ||
+            ActiveVersion.config.revision_error_behavior ||
+            :exception
+
+          case behavior
+          when :exception
+            raise build_revision_error_message(
+              error,
+              revision_attrs: revision_attrs,
+              version_column_sym: version_column_sym,
+              new_version: new_version,
+              invalid_record: invalid_record
+            )
+          when :log
+            ActiveVersion.logger.warn(
+              build_revision_error_message(
+                error,
+                revision_attrs: revision_attrs,
+                version_column_sym: version_column_sym,
+                new_version: new_version,
+                invalid_record: invalid_record
+              )
+            )
+            nil
+          when :silent
+            nil
+          end
+        end
+
+        def build_revision_error_message(error, revision_attrs:, version_column_sym:, new_version:, invalid_record: nil)
+          message = "Failed to create revision: #{error.class}"
+          message += "\nRevision attribute keys: #{revision_attrs.keys.map(&:to_s).sort.join(", ")}"
+          message += "\nIdentity keys: #{active_version_revision_identity_map.keys.map(&:to_s).sort.join(", ")}"
+          message += "\nVersion column: #{version_column_sym}, New version: #{new_version}"
+          if invalid_record
+            message += "\nRevision class: #{self.class.revision_class.name}"
+            message += "\nSource class: #{self.class.name}"
+            message += "\nRecord error fields: #{invalid_record.errors.attribute_names.map(&:to_s).uniq.sort.join(", ")}"
+            message += "\nRecord valid?: #{invalid_record.valid?}"
+          end
+          message
+        end
+        private :create_revision_record_with_version_retry!, :handle_revision_errors, :build_revision_error_message
 
         def refreshable_column_names
           @refreshable_column_names ||=

data/lib/active_version/revisions/has_revisions.rb

@@ -113,9 +113,6 @@ module ActiveVersion
 
           # Set up callbacks based on options
           setup_revision_callbacks(revision_options)
-
-          # Register with version registry (idempotent)
-          ActiveVersion.registry.register(self, :revisions, revision_options)
         end
 
         # Check if model has revisions configured
@@ -134,7 +131,8 @@ module ActiveVersion
             except: Array.wrap(options[:except] || []).map(&:to_s),
             foreign_key: normalize_identity_columns(options[:foreign_key]),
             identity_resolver: options[:identity_resolver],
-            table_name: options[:table_name]
+            table_name: options[:table_name],
+            error_behavior: options[:error_behavior]
           }
         end
 
@@ -409,6 +407,7 @@ module ActiveVersion
         return if truncated_forward_history && latest_revision_matches_current_state?
 
         result = create_snapshot!(use_old_values: true)
+        return unless result
 
         # Ensure revision is persisted and visible in association
         unless result.persisted?

data/lib/active_version/unique_version_collision.rb

@@ -0,0 +1,38 @@
+module ActiveVersion
+  module UniqueVersionCollision
+    module_function
+
+    def match?(error, version_column: nil)
+      return true if version_uniqueness_invalid?(error, version_column)
+
+      unique_constraint_names_version?(error, version_column)
+    end
+
+    def version_uniqueness_invalid?(error, version_column)
+      return false unless error.is_a?(ActiveRecord::RecordInvalid)
+      return false if version_column.nil?
+
+      details = error.record&.errors&.details
+      return false unless details
+
+      Array(details[version_column.to_sym]).any? { |detail| detail[:error] == :taken }
+    end
+
+    def unique_constraint_names_version?(error, version_column)
+      needle = version_column.to_s
+      return false if needle.empty?
+      return false unless unique_constraint_error?(error)
+
+      [error.message, error.cause&.message].compact.any? { |text| text.include?(needle) }
+    end
+
+    def unique_constraint_error?(error)
+      return true if error.is_a?(ActiveRecord::RecordNotUnique)
+      return false unless defined?(PG)
+
+      error.is_a?(ActiveRecord::StatementInvalid) && error.cause.is_a?(PG::UniqueViolation)
+    end
+
+    private_class_method :version_uniqueness_invalid?, :unique_constraint_names_version?, :unique_constraint_error?
+  end
+end

data/lib/active_version/version.rb

@@ -1,3 +1,3 @@
 module ActiveVersion
-  VERSION = "1.3.0"
+  VERSION = "2.0.0"
 end

data/lib/active_version.rb

@@ -12,6 +12,7 @@ require "active_version/column_mapper"
 require "active_version/version_registry"
 require "active_version/instrumentation"
 require "active_version/runtime"
+require "active_version/unique_version_collision"
 
 # Main entry point for ActiveVersion
 module ActiveVersion
@@ -338,6 +339,13 @@ module ActiveVersion
       @logger = default_logger
     end
 
+    def log_debug(message)
+      logger = self.logger
+      return if logger.nil?
+
+      logger.debug(message) if logger.respond_to?(:debug)
+    end
+
     def default_logger
       l = Logger.new($stderr)
       l.level = Logger::WARN

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_version
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Andrei Makarov
@@ -15,14 +15,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: 7.2.3.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: 7.2.3.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -43,14 +49,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: 7.2.3.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.0
+        version: 7.2.3.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -85,14 +97,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: 2.9.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: 2.9.5
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -137,18 +149,32 @@ dependencies:
         version: '0.4'
 - !ruby/object:Gem::Dependency
   name: polyrun
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+- !ruby/object:Gem::Dependency
+  name: prosopite
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -239,14 +265,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: rubocop-thread_safety
   requirement: !ruby/object:Gem::Requirement
@@ -275,6 +301,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: rbs
   requirement: !ruby/object:Gem::Requirement
@@ -289,6 +329,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
+- !ruby/object:Gem::Dependency
+  name: parallel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.26'
 description: 'ActiveVersion is a language-agnostic versioning library that unifies
   three core use cases: translations (locale-based), revisions/drafts (workflow snapshots),
   and audits (change tracking).'
@@ -345,6 +399,7 @@ files:
 - lib/active_version/translations.rb
 - lib/active_version/translations/has_translations.rb
 - lib/active_version/translations/translation_record.rb
+- lib/active_version/unique_version_collision.rb
 - lib/active_version/version.rb
 - lib/active_version/version_registry.rb
 - lib/generators/active_version/audits/audits_generator.rb
@@ -395,7 +450,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Unified versioning library for translations, revisions, and audits
 test_files: []