rollgeist 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 169d2323578ba1e2e133c2c0baf070eaf1f92d35e2ca062ffef14d365c116522
+  data.tar.gz: 185259990e46f5ae1a3380330b79fb8270701aafcd988ec2bace09c1637d6b61
+SHA512:
+  metadata.gz: 618f2cf0dc83a44c444b7b64a79bc3989961f8d365390870576c381a37b8c80bc696af1e6d2b80506a82f5e3910c63aa6c9ba832d457d9b1e9e1e046f5aae7c3
+  data.tar.gz: 9a517a2906d9bd8271d9cdad5a9f5a2b58eb280a18f1415fbf4b786d2fae73fdc6f7a91ac2e8b3cc8cc573235a2325d34dfd382bcc2c562544a4819055e46b54

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,204 @@
+# Rollgeist
+
+Rollgeist detects Active Record objects whose database writes were
+rolled back while their in-memory attributes remained changed.
+
+```ruby
+user = User.find(1) # plan: "free"
+
+ActiveRecord::Base.transaction do
+  user.update!(plan: "premium")
+  charge!(user) # raises; the transaction rolls back
+rescue ChargeError
+  nil
+end
+
+# The database still says "free", but this object says "premium".
+NotificationMailer.upgraded(user).deliver_later if user.plan == "premium"
+```
+
+The gem marks records after Rails finishes `rolledback!`, then reports risky
+externalization through `as_json`, `serializable_hash`, and `to_global_id`.
+It does not restore attributes or change Rails transaction behavior.
+
+## Installation
+
+Add the gem to the application:
+
+```ruby
+gem "rollgeist", "~> 0.1.0"
+```
+
+Then run `bundle install`.
+
+Rollgeist requires Ruby 3.2 or newer and Active Record 7.1 or newer.
+
+## Configuration
+
+Create `config/initializers/rollgeist.rb`:
+
+```ruby
+Rollgeist.configure do |config|
+  # Defaults to :raise in test and :log elsewhere.
+  # :raise is intentionally restricted to the test environment.
+  config.mode = :log
+
+  config.warn_on_serialization = true
+  config.warn_on_global_id = true
+  config.warn_on_resave = false
+  config.warn_once = true
+  config.max_reports_per_request = 5
+  config.ignore_if = nil
+  config.enabled_environments = %w[development test]
+end
+```
+
+Production is disabled by default because the gem depends on Active Record
+transaction internals and reports application behavior. Enable it only after
+observing the signal quality in development and test:
+
+```ruby
+config.enabled_environments = %w[development test production]
+```
+
+## What is reported
+
+| Operation | Detected after rollback? | Notes |
+|---|---:|---|
+| Successful create/save | Yes | Includes exception-driven rollbacks |
+| Successful update/save | Yes | In-memory changed values are reported |
+| Destroy | Yes | Rails restores destroyed/frozen state first |
+| `requires_new` savepoint | Yes | Mark survives the outer commit |
+| Joined nested `ActiveRecord::Rollback` | No | No database rollback occurs |
+| `update_columns` / `update_column` | No | No transaction record is registered |
+| `touch` | No | Deliberately outside the 0.1 scope |
+| `update_all`, `delete_all`, raw SQL | No | No model transaction record is registered |
+| Ordinary attribute reads | No | Only externalization watchpoints are monitored |
+
+This is a detector for specific unsafe paths, not a proof that an application
+is free of rollback-related stale state.
+
+## Clearing a mark
+
+A mark is cleared when the object is known to agree with the database again:
+
+```ruby
+user.reload # clears after a successful reload
+user.save!  # clears after a successful save
+user.destroy! # clears after a successful destroy
+```
+
+A later rollback attaches a fresh mark. A successful `committed!` is also a
+cleanup point.
+
+## Resave reports are opt-in
+
+`warn_on_resave` defaults to `false`. Rails calls `rolledback!` for deadlocks,
+serialization failures, and other exception-driven rollbacks, so a legitimate
+retry often looks like this:
+
+```ruby
+begin
+  User.transaction { user.save! }
+rescue ActiveRecord::SerializationFailure
+  retry
+end
+```
+
+The successful retry makes the database agree with the object. Reporting it by
+default would be noisy and would flag a normal recovery pattern. Set
+`warn_on_resave = true` only when that stricter signal is useful.
+
+## Suppression and filtering
+
+Suppress a known-safe block:
+
+```ruby
+Rollgeist.suppress do
+  audit_payload = user.as_json
+end
+```
+
+Or filter using the structured report:
+
+```ruby
+config.ignore_if = lambda do |report|
+  report.model_name == "AuditSnapshot" ||
+    report.changed_attributes.all? { |name| name == "updated_at" }
+end
+```
+
+Reports are limited per Rails executor. At the default limit, a request that
+would emit 100 reports logs five reports followed by:
+
+```text
+Rollgeist: +95 more suppressed
+```
+
+Outside an executor, a process-wide one-minute fallback window prevents
+unbounded reporting.
+
+## Notifications and reports
+
+Every emitted report publishes `ghost_access.rollgeist` through
+`ActiveSupport::Notifications`:
+
+```ruby
+ActiveSupport::Notifications.subscribe("ghost_access.rollgeist") do |event|
+  report = event.payload.fetch(:report)
+  ErrorTracker.notify(report.to_h)
+end
+```
+
+Reports contain the model name, id, rollback action, changed attribute names
+and in-memory values, rollback location, and access location. Subscriber,
+filter, and logger failures are reduced to warnings and do not change the
+serialization result. Only configured test `:raise` mode intentionally stops
+the watched operation.
+
+## Supported versions
+
+| Active Record | Ruby 3.2 | Ruby 3.3 | Ruby 3.4 | Ruby 4.0 |
+|---|---:|---:|---:|---:|
+| 7.1 | CI | CI | — | — |
+| 7.2 | CI | CI | CI | — |
+| 8.0 | CI | CI | CI | CI |
+
+Rails main runs in CI as an allowed-failure early-warning job because
+`rolledback!`, `committed!`, and transaction-record registration are internal
+APIs. See [the internal API probe](docs/rails_internals.md) for the fixed
+behavioral assumptions.
+
+## Performance
+
+Records that have never been marked use Active Record's original serialization
+method directly. Rollgeist installs serialization and GlobalID
+watchpoints only on a record after its write is rolled back, then removes them
+when the record is normalized.
+
+A local sample on Ruby 3.4.9, Active Record 8.0.5, and a 14-column model
+measured 140,978 baseline `as_json` calls/s and 140,412 guarded calls/s:
+0.40% overhead, within benchmark error and the +2% target. The benchmark uses
+two unmarked instances of the same class and asserts that both resolve
+`serializable_hash` to Active Record's original method owner.
+
+Reproduce the benchmark with:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile \
+  bundle exec ruby -Ilib benchmark/serialization.rb
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec appraisal rails_7_1 rspec
+bundle exec appraisal rails_7_2 rspec
+bundle exec appraisal rails_8_0 rspec
+gem build rollgeist.gemspec
+```
+
+## License
+
+Rollgeist is available under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/rails_internals.md

@@ -0,0 +1,76 @@
+# Active Record transaction internals
+
+This document fixes the internal API assumptions used by
+`rollgeist` 0.1. Re-run the probe with:
+
+```sh
+bundle exec appraisal rails_7_1 ruby script/rails_internals_probe.rb
+bundle exec appraisal rails_7_2 ruby script/rails_internals_probe.rb
+bundle exec appraisal rails_8_0 ruby script/rails_internals_probe.rb
+```
+
+The results below were captured on Ruby 4.0.0 with Active Record 7.1.6,
+7.2.3, and 8.0.5. The behavioral spec suite repeats the assumptions on every
+supported Appraisal.
+
+## Rollback callbacks
+
+| Scenario | Rails 7.1 | Rails 7.2 | Rails 8.0 |
+|---|---|---|---|
+| Explicit `ActiveRecord::Rollback` | `rolledback!` called | same | same |
+| Exception escaping the transaction | `rolledback!` called | same | same |
+| Outer transaction rollback arguments | `force_restore_state: true`, `should_run_callbacks: true` | same | same |
+| `requires_new` savepoint rollback arguments | `force_restore_state: false`, `should_run_callbacks: true` | same | same |
+| Joined nested `ActiveRecord::Rollback` | no rollback; outer transaction commits | same | same |
+| `after_rollback` ordering | runs inside `rolledback!` before it returns | same | same |
+
+The guard therefore captures dirty metadata before `super` and attaches the
+mark only after `super` returns. Application `after_rollback` callbacks cannot
+observe the mark.
+
+## State restored by `rolledback!`
+
+| Write | Before `super` | After `super` | Attribute values |
+|---|---|---|---|
+| Create | `new_record? == false`, assigned id | `new_record? == true`, id cleared | submitted values remain in memory |
+| Update | persisted, not frozen | persisted, not frozen | updated values remain in memory |
+| Destroy | destroyed and frozen | not destroyed and not frozen | values remain in memory |
+
+For update and create, `saved_changes` still contains the attributes written
+when `rolledback!` starts. `changes_to_save` is already empty. The guard uses
+the former, captured before Rails restores its transaction state.
+
+## Transaction-record registration
+
+| Operation | Added as a transaction record? | v0.1 marking behavior |
+|---|---|---|
+| Successful create/save | yes | marked on rollback |
+| Successful update/save | yes | marked on rollback |
+| Destroy | yes | marked on rollback; a later successful destroy also clears an existing mark |
+| `update_columns` | no | not detected |
+| `touch` | yes | deliberately not marked; direct/timestamp-only writes are outside v0.1 scope |
+| Raw SQL | no model transaction record | not detected |
+
+`touch` registration is an important implementation detail: relying only on
+the presence of a `rolledback!` callback would broaden the documented scope.
+The guard records successful `create_or_update` calls separately so a
+touch-only rollback remains unmarked.
+
+## Commit behavior
+
+A record rolled back by a `requires_new` savepoint is not later passed to
+`committed!` merely because the outer transaction commits. Its mark therefore
+survives the outer commit. Joined nested transactions behave differently:
+swallowing `ActiveRecord::Rollback` does not roll back the joined work, and the
+record receives `committed!` from the outer transaction.
+
+Successful reload, save, or destroy clears a mark. A later `committed!` is an
+additional cleanup point. If that save or destroy is itself rolled back,
+`rolledback!` creates a fresh mark after Rails restores the record.
+
+## Compatibility policy
+
+`rolledback!`, `committed!`, and transaction-record registration are internal
+APIs. The supported Rails matrix is mandatory CI; Rails main runs as an
+allowed-failure compatibility signal so signature or callback-order changes
+are visible before the next release.

data/lib/rollgeist/configuration.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  class Configuration
+    MODES = %i[log raise].freeze
+
+    attr_accessor :enabled_environments,
+      :ignore_if,
+      :logger,
+      :max_reports_per_request,
+      :warn_once,
+      :warn_on_global_id,
+      :warn_on_resave,
+      :warn_on_serialization
+    attr_writer :mode
+
+    def initialize
+      @enabled_environments = %w[development test]
+      @ignore_if = nil
+      @logger = nil
+      @max_reports_per_request = 5
+      @mode = nil
+      @warn_once = true
+      @warn_on_global_id = true
+      @warn_on_resave = false
+      @warn_on_serialization = true
+    end
+
+    def mode
+      @mode || (Rollgeist.environment == "test" ? :raise : :log)
+    end
+
+    def enabled_in?(environment)
+      enabled_environments.map(&:to_s).include?(environment.to_s)
+    end
+
+    def watchpoint_enabled?(watchpoint)
+      case watchpoint
+      when :serialization then warn_on_serialization
+      when :global_id then warn_on_global_id
+      when :resave then warn_on_resave
+      else false
+      end
+    end
+
+    def validate!
+      validate_mode!
+      validate_limit!
+      validate_ignore_predicate!
+      validate_environments!
+      self
+    end
+
+    private
+
+    def validate_mode!
+      unless MODES.include?(mode)
+        raise ConfigurationError, "mode must be one of: #{MODES.join(", ")}"
+      end
+      return unless mode == :raise && Rollgeist.environment != "test"
+
+      raise ConfigurationError, "raise mode is only available in the test environment"
+    end
+
+    def validate_limit!
+      return if max_reports_per_request.is_a?(Integer) && max_reports_per_request.positive?
+
+      raise ConfigurationError, "max_reports_per_request must be a positive Integer"
+    end
+
+    def validate_ignore_predicate!
+      return if ignore_if.nil? || ignore_if.respond_to?(:call)
+
+      raise ConfigurationError, "ignore_if must be callable or nil"
+    end
+
+    def validate_environments!
+      return if enabled_environments.is_a?(Array)
+
+      raise ConfigurationError, "enabled_environments must be an Array"
+    end
+  end
+end

data/lib/rollgeist/errors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class GhostRecordAccess < Error
+    attr_reader :report
+
+    def initialize(report)
+      @report = report
+      super(report.to_s)
+    end
+  end
+end

data/lib/rollgeist/execution_state.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module Rollgeist
+  module ExecutionState
+    COUNTER_KEY = :__rollgeist_execution_counter
+    FALLBACK_WINDOW_SECONDS = 60
+    Counter = Struct.new(:reported, :suppressed, :started_at, keyword_init: true)
+    Decision = Struct.new(:allowed, :suppressed_to_flush, keyword_init: true)
+
+    class << self
+      def install!(executor = ActiveSupport::Executor)
+        @installed_executors ||= {}
+        return if @installed_executors[executor.object_id]
+
+        executor.to_run { Rollgeist::ExecutionState.start! }
+        executor.to_complete { Rollgeist::ExecutionState.complete! }
+        @installed_executors[executor.object_id] = true
+      end
+
+      def start!
+        ActiveSupport::IsolatedExecutionState[COUNTER_KEY] = new_counter
+      end
+
+      def complete!
+        counter = ActiveSupport::IsolatedExecutionState[COUNTER_KEY]
+        ActiveSupport::IsolatedExecutionState[COUNTER_KEY] = nil
+        Notifier.report_suppressed(counter.suppressed) if counter&.suppressed.to_i.positive?
+      end
+
+      def claim(limit)
+        counter = ActiveSupport::IsolatedExecutionState[COUNTER_KEY]
+        return claim_from(counter, limit) if counter
+
+        fallback_claim(limit)
+      end
+
+      def reset!
+        ActiveSupport::IsolatedExecutionState[COUNTER_KEY] = nil
+        fallback_mutex.synchronize { @fallback_counter = new_counter }
+      end
+
+      private
+
+      def claim_from(counter, limit)
+        if counter.reported < limit
+          counter.reported += 1
+          Decision.new(allowed: true)
+        else
+          counter.suppressed += 1
+          Decision.new(allowed: false)
+        end
+      end
+
+      def fallback_claim(limit)
+        fallback_mutex.synchronize do
+          now = monotonic_time
+          counter = fallback_counter
+          suppressed_to_flush = nil
+
+          if now - counter.started_at >= FALLBACK_WINDOW_SECONDS
+            suppressed_to_flush = counter.suppressed if counter.suppressed.positive?
+            counter = @fallback_counter = new_counter(now)
+          end
+
+          decision = claim_from(counter, limit)
+          decision.suppressed_to_flush = suppressed_to_flush
+          decision
+        end
+      end
+
+      def fallback_counter
+        @fallback_counter ||= new_counter
+      end
+
+      def fallback_mutex
+        @fallback_mutex ||= Mutex.new
+      end
+
+      def new_counter(started_at = monotonic_time)
+        Counter.new(reported: 0, suppressed: 0, started_at: started_at)
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/rollgeist/formatter.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  class Formatter
+    ACCESS_DESCRIPTIONS = {
+      global_id: "was converted to a GlobalID",
+      resave: "was saved or destroyed again",
+      serialization: "was serialized"
+    }.freeze
+    ACTION_DESCRIPTIONS = {
+      create: "creation",
+      destroy: "destruction",
+      update: "update"
+    }.freeze
+
+    def initialize(report)
+      @report = report
+    end
+
+    def to_s
+      <<~MESSAGE.chomp
+        Rollgeist::GhostRecordAccess
+
+        #{record_label} #{ACCESS_DESCRIPTIONS.fetch(report.watchpoint)} after its #{ACTION_DESCRIPTIONS.fetch(report.action)} was rolled back.
+
+        The in-memory object still carries:
+        #{formatted_values}
+
+        Rolled back at:
+          #{report.rollback_location || "(location unavailable)"}  (#{formatted_age} ago)
+
+        Accessed at:
+          #{report.access_location || "(location unavailable)"}
+
+        Call `record.reload` before using this object,
+        or move the usage inside the transaction.
+      MESSAGE
+    end
+
+    private
+
+    attr_reader :report
+
+    def record_label
+      identifier = report.record_id.nil? ? "new" : report.record_id
+      "#{report.model_name}##{identifier}"
+    end
+
+    def formatted_values
+      return "  (no attribute changes captured)" if report.values.empty?
+
+      report.values.map do |attribute, value|
+        "  #{attribute}: #{value.inspect}        (database: rolled back)"
+      end.join("\n")
+    end
+
+    def formatted_age
+      seconds = report.accessed_at - report.rolled_back_at
+      format("%.1fs", [seconds, 0].max)
+    end
+  end
+end

data/lib/rollgeist/mark.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  class Mark
+    ACTIONS = %i[create update destroy].freeze
+
+    attr_reader :action, :changed_attributes, :rollback_location, :rolled_back_at
+
+    def initialize(action:, changed_attributes:, rollback_location:, rolled_back_at:)
+      raise ArgumentError, "unsupported rollback action: #{action}" unless ACTIONS.include?(action)
+
+      @action = action
+      @changed_attributes = changed_attributes.map(&:to_s).uniq.freeze
+      @rollback_location = rollback_location
+      @rolled_back_at = rolled_back_at
+      freeze
+    end
+  end
+end

data/lib/rollgeist/notifier.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  module Notifier
+    EVENT_NAME = "ghost_access.rollgeist"
+    WATCHPOINT_BITS = {
+      serialization: 1,
+      global_id: 2,
+      resave: 4
+    }.freeze
+
+    class << self
+      def notify(record, watchpoint)
+        return unless Rollgeist.enabled?
+        return if Rollgeist.suppressed?
+
+        configuration = Rollgeist.configuration
+        return unless configuration.watchpoint_enabled?(watchpoint)
+
+        mark = Rollgeist.mark_for(record)
+        return unless mark
+
+        report = Report.build(record: record, mark: mark, watchpoint: watchpoint)
+        return if ignored?(configuration, report)
+        return if configuration.warn_once && !claim_watchpoint(record, watchpoint)
+
+        decision = ExecutionState.claim(configuration.max_reports_per_request)
+        report_suppressed(decision.suppressed_to_flush) if decision.suppressed_to_flush
+        return unless decision.allowed
+
+        emit(report, configuration)
+      rescue GhostRecordAccess
+        raise
+      rescue StandardError => error
+        warn_safely("Rollgeist notifier failure: #{error.class}: #{error.message}")
+      end
+
+      def report_suppressed(count)
+        return unless count.to_i.positive?
+
+        log_safely("Rollgeist: +#{count} more suppressed")
+      end
+
+      private
+
+      def ignored?(configuration, report)
+        configuration.ignore_if&.call(report)
+      rescue StandardError => error
+        warn_safely("Rollgeist ignore_if failure: #{error.class}: #{error.message}")
+        false
+      end
+
+      def claim_watchpoint(record, watchpoint)
+        bit = WATCHPOINT_BITS.fetch(watchpoint)
+        reported = if record.instance_variable_defined?(REPORTED_IVAR)
+          record.instance_variable_get(REPORTED_IVAR)
+        else
+          0
+        end
+        return false unless (reported & bit).zero?
+
+        record.instance_variable_set(REPORTED_IVAR, reported | bit)
+        true
+      end
+
+      def emit(report, configuration)
+        instrument_safely(report)
+
+        if configuration.mode == :raise
+          raise GhostRecordAccess, report
+        end
+
+        log_safely(report.to_s)
+      end
+
+      def instrument_safely(report)
+        ActiveSupport::Notifications.instrument(EVENT_NAME, report: report)
+      rescue StandardError => error
+        warn_safely("Rollgeist notification failure: #{error.class}: #{error.message}")
+      end
+
+      def log_safely(message)
+        logger = Rollgeist.configuration.logger
+        logger ||= Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+        logger ? logger.warn(message) : Kernel.warn(message)
+      rescue StandardError => error
+        warn_safely("Rollgeist logger failure: #{error.class}: #{error.message}")
+      end
+
+      def warn_safely(message)
+        Kernel.warn(message)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/rollgeist/patches/persistence.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  module Patches
+    module Persistence
+      def reload(...)
+        result = super
+        Rollgeist.clear_mark!(self)
+        result
+      end
+
+      def destroy(...)
+        return super unless defined?(@__rollgeist_mark)
+
+        Rollgeist::Notifier.notify(self, :resave)
+        mark = instance_variable_get(MARK_IVAR)
+        reported = instance_variable_get(REPORTED_IVAR) if instance_variable_defined?(REPORTED_IVAR)
+        Rollgeist.clear_mark!(self)
+        result = super
+        restore_mark(mark, reported) unless result
+        result
+      rescue Exception # rubocop:disable Lint/RescueException
+        restore_mark(mark, reported) if mark && !frozen?
+        raise
+      end
+
+      private
+
+      def create_or_update(...)
+        if defined?(@__rollgeist_mark)
+          Rollgeist::Notifier.notify(self, :resave)
+        end
+
+        result = super
+        if result
+          Rollgeist.clear_mark!(self)
+          Rollgeist.mark_saved!(self)
+        end
+        result
+      end
+
+      def restore_mark(mark, reported)
+        instance_variable_set(MARK_IVAR, mark)
+        instance_variable_set(REPORTED_IVAR, reported) if reported
+        Rollgeist::RecordWatchpoints.install!(self)
+      rescue StandardError => error
+        Rollgeist.tracking_failure("mark restoration", error)
+      end
+    end
+  end
+end

data/lib/rollgeist/patches/transactions.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  module Patches
+    module Transactions
+      def committed!(*args, **kwargs)
+        result = super
+        Rollgeist.clear_record_state!(self)
+        result
+      end
+
+      def rolledback!(*args, **kwargs)
+        snapshot = Rollgeist.rollback_snapshot(self)
+        result = super
+
+        if snapshot
+          Rollgeist.attach_mark!(self, snapshot)
+        else
+          Rollgeist.clear_transaction_write_state!(self)
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/rollgeist/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  class Railtie < Rails::Railtie
+    initializer "rollgeist.executor" do |application|
+      ExecutionState.install!(application.executor)
+    end
+  end
+end

data/lib/rollgeist/record_watchpoints.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  module RecordWatchpoints
+    INSTALLED_IVAR = :@__rollgeist_watchpoints
+    SERIALIZATION_BIT = 1
+    GLOBAL_ID_BIT = 2
+
+    SERIALIZATION_ALIAS = :__rollgeist_original_serializable_hash
+    SERIALIZATION_STATE = :@__rollgeist_serialization_visibility
+    GLOBAL_ID_ALIAS = :__rollgeist_original_to_global_id
+    GLOBAL_ID_STATE = :@__rollgeist_global_id_visibility
+    INHERITED = :inherited
+
+    class << self
+      def install!(record)
+        return if record.instance_variable_defined?(INSTALLED_IVAR)
+
+        mask = install_serialization(record)
+        mask |= install_global_id(record)
+        record.instance_variable_set(INSTALLED_IVAR, mask)
+      rescue StandardError
+        uninstall_mask(record, mask.to_i)
+        raise
+      end
+
+      def uninstall!(record)
+        return unless record.instance_variable_defined?(INSTALLED_IVAR)
+
+        mask = record.instance_variable_get(INSTALLED_IVAR)
+        uninstall_mask(record, mask)
+        record.remove_instance_variable(INSTALLED_IVAR)
+      end
+
+      private
+
+      def install_serialization(record)
+        return 0 unless record.respond_to?(:serializable_hash, true)
+
+        install_method(
+          record,
+          :serializable_hash,
+          SERIALIZATION_ALIAS,
+          SERIALIZATION_STATE,
+          :serialization
+        )
+        SERIALIZATION_BIT
+      end
+
+      def install_global_id(record)
+        return 0 unless record.respond_to?(:to_global_id, true)
+
+        install_method(
+          record,
+          :to_global_id,
+          GLOBAL_ID_ALIAS,
+          GLOBAL_ID_STATE,
+          :global_id
+        )
+        GLOBAL_ID_BIT
+      end
+
+      def install_method(record, method_name, alias_name, state_ivar, watchpoint)
+        singleton_class = record.singleton_class
+        ensure_alias_available!(singleton_class, alias_name)
+        original_visibility = own_visibility(singleton_class, method_name)
+        inherited_visibility = visibility(singleton_class, method_name)
+
+        preserve_original(singleton_class, method_name, alias_name) if original_visibility
+        singleton_class.instance_variable_set(state_ivar, original_visibility || INHERITED)
+        define_watchpoint(singleton_class, method_name, alias_name, state_ivar, watchpoint)
+        singleton_class.send(inherited_visibility, method_name)
+      end
+
+      def define_watchpoint(singleton_class, method_name, alias_name, state_ivar, watchpoint)
+        singleton_class.define_method(method_name) do |*args, **kwargs, &block|
+          Rollgeist::Notifier.notify(self, watchpoint) if defined?(@__rollgeist_mark)
+          state = self.singleton_class.instance_variable_get(state_ivar)
+
+          if state == INHERITED
+            kwargs.empty? ? super(*args, &block) : super(*args, **kwargs, &block)
+          elsif kwargs.empty?
+            __send__(alias_name, *args, &block)
+          else
+            __send__(alias_name, *args, **kwargs, &block)
+          end
+        end
+      end
+
+      def preserve_original(singleton_class, method_name, alias_name)
+        singleton_class.alias_method(alias_name, method_name)
+        singleton_class.send(:private, alias_name)
+      end
+
+      def uninstall_mask(record, mask)
+        singleton_class = record.singleton_class
+        uninstall_method(
+          singleton_class,
+          :to_global_id,
+          GLOBAL_ID_ALIAS,
+          GLOBAL_ID_STATE
+        ) if (mask & GLOBAL_ID_BIT).positive?
+        uninstall_method(
+          singleton_class,
+          :serializable_hash,
+          SERIALIZATION_ALIAS,
+          SERIALIZATION_STATE
+        ) if (mask & SERIALIZATION_BIT).positive?
+      end
+
+      def uninstall_method(singleton_class, method_name, alias_name, state_ivar)
+        original_visibility = singleton_class.instance_variable_get(state_ivar)
+        singleton_class.remove_method(method_name)
+
+        unless original_visibility == INHERITED
+          singleton_class.alias_method(method_name, alias_name)
+          singleton_class.send(original_visibility, method_name)
+          singleton_class.remove_method(alias_name)
+        end
+
+        singleton_class.remove_instance_variable(state_ivar)
+      end
+
+      def ensure_alias_available!(singleton_class, alias_name)
+        return unless own_visibility(singleton_class, alias_name)
+
+        raise Error, "record already defines reserved method #{alias_name}"
+      end
+
+      def own_visibility(singleton_class, method_name)
+        return :public if singleton_class.public_instance_methods(false).include?(method_name)
+        return :protected if singleton_class.protected_instance_methods(false).include?(method_name)
+        return :private if singleton_class.private_instance_methods(false).include?(method_name)
+      end
+
+      def visibility(singleton_class, method_name)
+        return :public if singleton_class.public_method_defined?(method_name)
+        return :protected if singleton_class.protected_method_defined?(method_name)
+        return :private if singleton_class.private_method_defined?(method_name)
+
+        raise Error, "record does not define #{method_name}"
+      end
+    end
+  end
+end

data/lib/rollgeist/report.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  class Report
+    attr_reader :access_location,
+      :accessed_at,
+      :action,
+      :changed_attributes,
+      :model_name,
+      :record_id,
+      :rollback_location,
+      :rolled_back_at,
+      :values,
+      :watchpoint
+
+    def self.build(record:, mark:, watchpoint:)
+      changed_attributes = mark.changed_attributes
+      values = changed_attributes.to_h do |attribute|
+        [attribute, safely_read(record, attribute)]
+      end
+
+      new(
+        access_location: Rollgeist.capture_location,
+        accessed_at: Time.now,
+        action: mark.action,
+        changed_attributes: changed_attributes,
+        model_name: record.class.name || record.class.to_s,
+        record_id: record.id,
+        rollback_location: mark.rollback_location,
+        rolled_back_at: mark.rolled_back_at,
+        values: values,
+        watchpoint: watchpoint
+      )
+    end
+
+    def self.safely_read(record, attribute)
+      record.read_attribute_for_serialization(attribute)
+    rescue StandardError => error
+      "<unavailable: #{error.class}>"
+    end
+    private_class_method :safely_read
+
+    def initialize(
+      access_location:,
+      accessed_at:,
+      action:,
+      changed_attributes:,
+      model_name:,
+      record_id:,
+      rollback_location:,
+      rolled_back_at:,
+      values:,
+      watchpoint:
+    )
+      @access_location = access_location
+      @accessed_at = accessed_at
+      @action = action
+      @changed_attributes = changed_attributes
+      @model_name = model_name
+      @record_id = record_id
+      @rollback_location = rollback_location
+      @rolled_back_at = rolled_back_at
+      @values = values
+      @watchpoint = watchpoint
+      freeze
+    end
+
+    def to_h
+      {
+        access_location: access_location,
+        accessed_at: accessed_at,
+        action: action,
+        changed_attributes: changed_attributes,
+        model_name: model_name,
+        record_id: record_id,
+        rollback_location: rollback_location,
+        rolled_back_at: rolled_back_at,
+        values: values,
+        watchpoint: watchpoint
+      }
+    end
+
+    def to_s
+      Formatter.new(self).to_s
+    end
+  end
+end

data/lib/rollgeist/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rollgeist
+  VERSION = "0.1.0"
+end

data/lib/rollgeist.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/executor"
+require "active_support/isolated_execution_state"
+require "active_support/lazy_load_hooks"
+require "active_support/notifications"
+
+require_relative "rollgeist/version"
+require_relative "rollgeist/configuration"
+require_relative "rollgeist/errors"
+require_relative "rollgeist/execution_state"
+require_relative "rollgeist/formatter"
+require_relative "rollgeist/mark"
+require_relative "rollgeist/notifier"
+require_relative "rollgeist/record_watchpoints"
+require_relative "rollgeist/report"
+require_relative "rollgeist/patches/persistence"
+require_relative "rollgeist/patches/transactions"
+
+module Rollgeist
+  MARK_IVAR = :@__rollgeist_mark
+  REPORTED_IVAR = :@__rollgeist_reported
+  SAVED_IVAR = :@__rollgeist_saved
+  SUPPRESSION_KEY = :__rollgeist_suppression_depth
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration.validate!
+      configuration
+    end
+
+    def reset!
+      @configuration = Configuration.new
+      ExecutionState.reset!
+    end
+
+    def environment
+      return Rails.env.to_s if defined?(Rails) && Rails.respond_to?(:env)
+
+      ENV.fetch("RAILS_ENV", ENV.fetch("RACK_ENV", "development"))
+    end
+
+    def enabled?
+      configuration.enabled_in?(environment)
+    end
+
+    def suppress
+      previous_depth = ActiveSupport::IsolatedExecutionState[SUPPRESSION_KEY]
+      ActiveSupport::IsolatedExecutionState[SUPPRESSION_KEY] = previous_depth.to_i + 1
+      yield
+    ensure
+      ActiveSupport::IsolatedExecutionState[SUPPRESSION_KEY] = previous_depth
+    end
+
+    def suppressed?
+      ActiveSupport::IsolatedExecutionState[SUPPRESSION_KEY].to_i.positive?
+    end
+
+    def install!(active_record_base)
+      active_record_base.prepend(Patches::Transactions) unless active_record_base < Patches::Transactions
+      active_record_base.prepend(Patches::Persistence) unless active_record_base < Patches::Persistence
+      ExecutionState.install!
+    end
+
+    def mark_for(record)
+      record.instance_variable_get(MARK_IVAR)
+    end
+
+    def mark_saved!(record)
+      record.instance_variable_set(SAVED_IVAR, true) if enabled?
+    rescue StandardError => error
+      tracking_failure("save tracking", error)
+    end
+
+    def rollback_snapshot(record)
+      return unless enabled?
+
+      action = rollback_action(record)
+      return unless action
+
+      {
+        action: action,
+        changed_attributes: rollback_changed_attributes(record, action),
+        rolled_back_at: Time.now,
+        rollback_location: capture_location
+      }
+    rescue StandardError => error
+      tracking_failure("rollback snapshot", error)
+      nil
+    end
+
+    def attach_mark!(record, attributes)
+      mark = Mark.new(**attributes)
+      RecordWatchpoints.install!(record)
+      record.instance_variable_set(MARK_IVAR, mark)
+      remove_ivar(record, REPORTED_IVAR)
+      clear_transaction_write_state!(record)
+    rescue StandardError => error
+      tracking_failure("mark attachment", error)
+    end
+
+    def clear_mark!(record)
+      RecordWatchpoints.uninstall!(record)
+      remove_ivar(record, MARK_IVAR)
+      remove_ivar(record, REPORTED_IVAR)
+    rescue StandardError => error
+      tracking_failure("mark cleanup", error)
+    end
+
+    def clear_record_state!(record)
+      clear_mark!(record)
+      clear_transaction_write_state!(record)
+    end
+
+    def clear_transaction_write_state!(record)
+      remove_ivar(record, SAVED_IVAR)
+    rescue StandardError => error
+      tracking_failure("transaction-state cleanup", error)
+    end
+
+    def capture_location
+      location = caller_locations(2, 50).find do |candidate|
+        application_location?(candidate.path)
+      end
+      location && "#{location.path}:#{location.lineno}"
+    end
+
+    def tracking_failure(context, error)
+      Kernel.warn("Rollgeist #{context} failure: #{error.class}: #{error.message}")
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def rollback_action(record)
+      return :destroy if record.destroyed?
+      return unless record.instance_variable_defined?(SAVED_IVAR)
+
+      record.previously_new_record? ? :create : :update
+    end
+
+    def rollback_changed_attributes(record, action)
+      attributes = if action == :destroy
+        record.changes_to_save.keys
+      else
+        record.saved_changes.keys
+      end
+
+      attributes.map(&:to_s).uniq
+    end
+
+    def application_location?(path)
+      return false unless path
+      return false if path.start_with?(__dir__)
+      return false if path.include?("/active_record/")
+      return false if path.include?("/active_support/")
+
+      true
+    end
+
+    def remove_ivar(record, ivar)
+      return unless record.instance_variable_defined?(ivar)
+
+      record.remove_instance_variable(ivar)
+    end
+  end
+end
+
+begin
+  require "global_id"
+rescue LoadError
+  nil
+end
+
+ActiveSupport.on_load(:active_record) do
+  Rollgeist.install!(self)
+end
+
+begin
+  require "rails/railtie"
+rescue LoadError
+  nil
+end
+
+require_relative "rollgeist/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: rollgeist
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Marks Active Record instances whose writes were rolled back and reports
+  unsafe serialization, GlobalID conversion, or optional resave attempts.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/rails_internals.md
+- lib/rollgeist.rb
+- lib/rollgeist/configuration.rb
+- lib/rollgeist/errors.rb
+- lib/rollgeist/execution_state.rb
+- lib/rollgeist/formatter.rb
+- lib/rollgeist/mark.rb
+- lib/rollgeist/notifier.rb
+- lib/rollgeist/patches/persistence.rb
+- lib/rollgeist/patches/transactions.rb
+- lib/rollgeist/railtie.rb
+- lib/rollgeist/record_watchpoints.rb
+- lib/rollgeist/report.rb
+- lib/rollgeist/version.rb
+homepage: https://github.com/ydah/rollgeist
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://rubygems.org/gems/rollgeist
+  source_code_uri: https://github.com/ydah/rollgeist
+  changelog_uri: https://github.com/ydah/rollgeist/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Detect Active Record objects left stale after a transaction rollback
+test_files: []