glib-web 6.8.1 → 6.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a632657e59d940a2691d9793e2f9859c423b9ea344fa5b1f67f47d66c4a28c8
-  data.tar.gz: 44f187b5d84c31e7727b838dfddfe0ba654171d0375973042313c4f53b310f85
+  metadata.gz: 3bed80d7507f4438018d07a12e8222c4fadc6b518e2e857db8d315845c65cace
+  data.tar.gz: 971c2518cd4ed3b39fcbf8f03b8076ca16c61ba6af2ba92a226efd99d3ac379f
 SHA512:
-  metadata.gz: aea444e0d5996db47728356004ad47fea27fd945e446edafa01de8332f4d92ed618c4b9cf29cd01212854d88b13d71ee0aa21958304e39a28d7bb2ef49616a2a
-  data.tar.gz: 2e89f1c25abc1760d65beb70eb89d1b1a5562d4b286922e6c5b9fd97817b008f16d2e5f8c6658cefad32d1b0c9e430733102ee87024f0199dace2f5561cc6a5e
+  metadata.gz: fe7febf0f24cc8e05140fc6a2905ed1998ad5427a3d0316daab114edf4652e0b5002e732da4043d6c3a9e62e2d22cf88eb79bfb7ae4544d66a9eec88280f3c8e
+  data.tar.gz: d0f2705eb05a5977eba46d8327d47999a01b71cd3740e5bff0e7db536229fa26b5de1601d2efdfeecc8a0b1abad7a994e35e2aa43e4d2531faa040c2261f05b8

data/app/jobs/glib/purge_unattached_job.rb

@@ -0,0 +1,28 @@
+module Glib
+  # Daily cleanup for ActiveStorage blobs that have no attachments. Excludes blobs referenced by
+  # any `SnapshotBlobReference` row, so old file versions that still appear in some snapshot's
+  # timeline (i.e. a previous version of an attached file) survive the purge.
+  #
+  # Opt-in: if the host app has not run the gem's `create_snapshot_blob_references` migration,
+  # `SnapshotBlobReference.table_exists?` is false and the exclusion subquery short-circuits —
+  # the job then behaves identically to Rails' built-in unattached-blob cleanup, just delayed
+  # by 8 hours to give upload flows time to attach.
+  #
+  # Schedule from the host app (e.g. via sidekiq-cron):
+  #   Glib::PurgeUnattachedJob.perform_later
+  class PurgeUnattachedJob < ApplicationJob
+    queue_as :cleanup
+
+    def perform(*_args)
+      scope = ActiveStorage::Blob
+        .unattached
+        .where('active_storage_blobs.created_at < ?', 8.hours.ago)
+
+      if SnapshotBlobReference.table_exists?
+        scope = scope.where.not(id: SnapshotBlobReference.select(:blob_id))
+      end
+
+      scope.find_each(&:purge_later)
+    end
+  end
+end

data/app/models/concerns/glib/snapshot_v2.rb

@@ -0,0 +1,462 @@
+require 'active_snapshot'
+require 'hashdiff'
+
+# V2 snapshot concern adapted from mapping-web. Promotes action/version/diff/source from the
+# monolithic `metadata` JSON to real columns, enabling indexed JSONB queries and a `source`
+# attribution concept. Defaults to unlimited retention (max_snapshots nil).
+#
+# Patches applied on top of mapping-web's SnapshotV2:
+#   1. ActiveStorage support in check_snapshot_changed (ported from V1 gem).
+#   2. Nil has_one safe-nav in check_snapshot_changed.
+#   3. has_one wrapping in diff_associations (V2 only tested with has_many in mapping-web).
+#   4. ActiveStorage in diff_associations (convert Attached::One/Many to attachment records).
+#
+# To get all records of a model, you can use the following query:
+# MyModel.joins(:snapshots).distinct
+module Glib
+  module SnapshotV2
+    extend ActiveSupport::Concern
+
+    # The CRUD backbone covers most flows; the approval-gate admin actions are distinct
+    # audit events (request_changes / approve / undo_approve) that the timeline UI labels
+    # off the action string, so they earn their own slots here rather than being collapsed
+    # into :update (which would lose the "what happened" signal in the audit trail).
+    KNOWN_ACTIONS = [:create, :update, :destroy, :request_changes, :approve, :undo_approve].freeze
+
+    included do
+      include ::ActiveSnapshot
+
+      attr_accessor :snapshot_changed
+      attr_accessor :attributes_before_save
+
+      # Save-boundary state capture for the snapshot diff engine -- not a hidden side
+      # effect. Records the pre-save DB state into `attributes_before_save` and
+      # computes `snapshot_changed` so the diff (see `diff` / `same_as_before?`) has a
+      # "before" to compare against. `attributes_in_database` is only readable inside
+      # the save boundary, and this is a generic concern mixed into many models, so it
+      # can't be hoisted to an individual save site the way notification callbacks were.
+      # It only sets instance state (no writes, no notifications) -- the actual snapshot
+      # row is written by the explicit, call-site-visible `save_with_snapshot` /
+      # `glib_create_snapshot!` paths, which is where the acting user is known.
+      before_save do # rubocop:disable DevDoc/Rails/AvoidRailsCallbacks
+        # Only set snapshot_changed if not already set (handles case where before_save
+        # is called multiple times - e.g., when associated records are saved before parent)
+        if snapshot_changed.nil?
+          self.attributes_before_save = attributes_in_database
+          self.snapshot_changed = check_snapshot_changed
+        end
+      end
+    end
+
+    def check_snapshot_changed
+      return true if changed?
+
+      associations_for_snapshot.each do |association_name|
+        association = self.class.reflect_on_association(association_name)
+        association_value = public_send(association_name)
+
+        # ActiveStorage associations (has_one_attached / has_many_attached) are not
+        # reflected as standard AR macros; handle them before the case block.
+        if active_storage_association?(association, association_value)
+          active_storage_records(association_value).each do |record|
+            return true if record.changed?
+          end
+          next
+        end
+
+        raise "Invalid association: #{association_name}" if association.nil?
+
+        case association.macro
+        when :has_many
+          records = association_value
+          records.each do |record|
+            return true if record.changed?
+          end
+          if new_record? && records.count > 0
+            return true
+          end
+        when :has_one, :belongs_to
+          return true if association_value&.changed?
+        else
+          raise "Unexpected association macro: #{association.macro}"
+        end
+      end
+
+      false
+    end
+
+    # information need to be store:
+    # - action: create, update, destroy
+    # - track changes
+    def glib_create_snapshot!(action, source, user: nil)
+      action_sym = action.to_sym
+      raise "unknown action: #{action}" unless KNOWN_ACTIONS.include?(action_sym)
+      raise 'source must be present' if source.blank?
+      raise 'user must be present when source is "user"' if source == 'user' && user.nil?
+
+      # Lock is required to prevent race conditions when calculating version number.
+      if (result =
+            with_lock do
+              version = last_version + 1
+              calculated_diff = diff
+
+              snapshot_obj = {
+                identifier: snapshot_identifier(version),
+                user: user,
+                metadata: {} # Keep for potential future use, but main data in columns
+              }
+
+              # Don't create version if same as before
+              unless same_as_before?
+                # No nil guard: active_snapshot's `create_snapshot!` raises on failure and
+                # always returns the snapshot.
+                snapshot = create_snapshot!(**snapshot_obj)
+                # update_columns is the second half of the insert, not a domain update: the
+                # gem's create_snapshot! signature can't set these V2-promoted columns, and
+                # no validation/callback (gem or initializer) concerns them. Runs inside
+                # with_lock's transaction, so no half-written row ever commits.
+                snapshot.update_columns( # rubocop:disable DevDoc/Rails/AvoidBypassingValidation
+                  action: action.to_s,
+                  version: version,
+                  diff: calculated_diff,
+                  source: source
+                )
+                record_blob_references(snapshot, calculated_diff)
+                snapshot
+              end
+            end)
+        # Cleanup operations - run outside lock and transaction
+        remove_old_snapshot
+      end
+
+      result
+    end
+
+    def glib_revert_snapshot!(version)
+      snapshot = snapshots.find_by!(identifier: snapshot_identifier(version))
+      snapshot.restore!
+    end
+
+    def snapshot_identifier(version)
+      "#{self.class.to_s.underscore}_#{id}_version_#{version}"
+    end
+
+    def interval_from_prev_version
+      return nil if snapshot_prev.nil?
+
+      updated_at - snapshot_prev.created_at
+    end
+
+    def diff(snapshot = snapshot_prev)
+      default_ignored_keys = ['updated_at', 'created_at']
+      ignore_keys = build_ignore_keys(default_ignored_keys)
+
+      item, associations = fetch_snapshot_items(snapshot)
+
+      {
+        'item' => ::Hashdiff.diff(
+          normalize_attributes_for_diff(item.attributes.except(*ignore_keys)),
+          normalize_attributes_for_diff(attributes.except(*ignore_keys))
+        ),
+        'associations' => diff_associations(associations, default_ignored_keys)
+      }
+    end
+
+    def snapshot_prev
+      snapshots.order(version: :desc).first
+    end
+
+    def same_as_before?
+      return !snapshot_changed if snapshot_prev.blank?
+
+      computed_diff = diff
+      item_unchanged = computed_diff['item'].blank?
+      assoc_diff = computed_diff['associations']
+      associations_unchanged = assoc_diff.nil? || assoc_diff.values.all?(&:blank?)
+
+      item_unchanged && associations_unchanged
+    end
+
+    def last_version
+      max_version = snapshots.maximum(:version)
+      return 0 if max_version.blank?
+
+      max_version
+    end
+
+    def remove_old_snapshot
+      return if max_snapshots.nil?
+
+      newest_ids = snapshots.order(version: :desc, id: :desc).limit(max_snapshots).ids
+      return unless newest_ids.size >= max_snapshots
+
+      snapshots.where.not(id: newest_ids).destroy_all
+    end
+
+    def watched_keys_for_snapshot
+      raise NotImplementedError, "please add method 'watched_keys_for_snapshot' to #{self.class}"
+    end
+
+    def associations_for_snapshot
+      children_to_snapshot.keys.filter { |key| respond_to?(key) }
+    end
+
+    def max_snapshots
+      nil
+    end
+
+    # Return number of days to retain snapshot content, or nil for unlimited.
+    def content_retention_days
+      nil
+    end
+
+    private
+      # Truncate Time/TimeWithZone values to the JSON encoding precision so that
+      # reified (JSON-round-tripped) attributes compare equal to live DB values
+      # that carry microsecond precision. Without this, Hashdiff reports a
+      # spurious change for every datetime field on every re-snapshot.
+      #
+      # The divisor is derived from ActiveSupport::JSON::Encoding.time_precision so a consumer who
+      # raises it above the Rails default of 3 (ms) is not over-truncated — mirrors V1's
+      # Glib::Snapshot#normalize_attributes / snapshot_time_divisor exactly. no-op when the
+      # precision is already 6 (microseconds).
+      def normalize_attributes_for_diff(attrs)
+        divisor = snapshot_time_divisor
+        attrs.transform_values do |v|
+          if (v.is_a?(Time) || v.is_a?(ActiveSupport::TimeWithZone)) && divisor > 1
+            v.change(usec: v.usec - v.usec % divisor)
+          else
+            v
+          end
+        end
+      end
+
+      def snapshot_time_divisor
+        10 ** (6 - ActiveSupport::JSON::Encoding.time_precision)
+      end
+
+      def build_ignore_keys(default_ignored_keys)
+        ignore_keys = default_ignored_keys
+
+        unless watched_keys_for_snapshot.nil?
+          ignored_keys_for_snapshot = attributes.except(*watched_keys_for_snapshot.map(&:to_s)).keys
+          ignore_keys = (default_ignored_keys + ignored_keys_for_snapshot.map(&:to_s)).uniq
+        end
+
+        ignore_keys
+      end
+
+      def fetch_snapshot_items(snapshot)
+        if snapshot.present?
+          snapshot.fetch_reified_items
+        else
+          [OpenStruct.new(attributes: attributes_before_save || {}), {}]
+        end
+      end
+
+      def diff_associations(associations, default_ignored_keys)
+        associations_for_snapshot.reduce({}) do |prev, association_name|
+          before_records = associations[association_name] || []
+
+          records = send(association_name)
+
+          # ActiveStorage: convert Attached::One/Many to their underlying attachment records.
+          association = self.class.reflect_on_association(association_name)
+          if active_storage_association?(association, records)
+            records = active_storage_records(records)
+          end
+
+          # has_one wrapping: V2 tested only with has_many in mapping-web; a has_one returns
+          # a single record (or nil), not a collection. Wrap it so the diff logic below works.
+          unless records.respond_to?(:each)
+            records = [records].compact
+          end
+
+          # id is the universal snapshot identity here: the diff below matches records
+          # by id (index_by(&:id)), so this order only pins stable diff-path indices.
+          # created_at isn't guaranteed across every association this generic concern
+          # snapshots (ActiveStorage, through-tables) and can be backdated, so id — not
+          # created_at — is the right deterministic key. Generic engine, hence the disable.
+          now_records = records.respond_to?(:order) ? records.order(id: :asc) : records.to_a.sort_by { |r| r.id.to_i } # rubocop:disable DevDoc/Rails/AvoidOrderingById
+
+          association_diff = diff_single_association(
+            association_name,
+            before_records,
+            now_records,
+            default_ignored_keys
+          )
+
+          prev.merge(association_name.to_s => association_diff)
+        end
+      end
+
+      def diff_single_association(_association_name, before_records, now_records, default_ignored_keys)
+        association_ignored_keys = build_association_ignore_keys(now_records.first, default_ignored_keys)
+
+        if before_records.blank?
+          return ::Hashdiff.diff([], now_records.map { |record| normalize_attributes_for_diff(record.attributes.except(*association_ignored_keys)) })
+        end
+
+        # Create hash lookups to avoid N+1 queries
+        now_records_by_id = now_records.index_by(&:id)
+        before_records_by_id = before_records.index_by(&:id)
+
+        # Detect deleted and updated records
+        deleted_or_updated = before_records.map.with_index do |record_before, index|
+          record_now = now_records_by_id[record_before.id]
+          if record_now.blank?
+            ['-', "[#{index}]", normalize_attributes_for_diff(record_before.attributes.except(*association_ignored_keys))]
+          else
+            before_attrs = normalize_attributes_for_diff(record_before.attributes.except(*association_ignored_keys))
+            now_attrs = normalize_attributes_for_diff(record_now.attributes.except(*association_ignored_keys))
+            next if Hashdiff.diff(before_attrs, now_attrs).blank?
+
+            ['~', "[#{index}]", before_attrs, now_attrs]
+          end
+        end.compact_blank
+
+        # Detect added records
+        added = now_records.map.with_index do |record_now, index|
+          record_before = before_records_by_id[record_now.id]
+          if record_before.blank?
+            ['+', "[#{index}]", normalize_attributes_for_diff(record_now.attributes.except(*association_ignored_keys))]
+          end
+        end.compact_blank
+
+        deleted_or_updated + added
+      end
+
+      def build_association_ignore_keys(first_record, default_ignored_keys)
+        if first_record.present? && !active_storage_record?(first_record) && !first_record.respond_to?(:watched_keys_for_snapshot)
+          raise NotImplementedError, "please add method 'watched_keys_for_snapshot' to #{first_record.class}"
+        end
+
+        if active_storage_record?(first_record)
+          default_ignored_keys
+        elsif first_record.try(:watched_keys_for_snapshot).nil?
+          default_ignored_keys
+        else
+          assoc_ignore_keys = first_record.attributes.except(*first_record.watched_keys_for_snapshot.map(&:to_s)).keys.map(&:to_s)
+          (default_ignored_keys + assoc_ignore_keys).uniq
+        end
+      end
+
+      # --- Blob reference tracking ---
+      #
+      # When a snapshot diff includes attachment changes, extract the blob_ids and persist them as
+      # SnapshotBlobReference records. This prevents Glib::PurgeUnattachedJob from deleting old file
+      # versions that are still visible in the snapshot timeline.
+      #
+      # Opt-in: the host app must run the gem's `create_snapshot_blob_references` migration. The
+      # `table_exists?` guard makes this a silent no-op for consumers that skip the migration, so
+      # `include Glib::SnapshotV2` never crashes a model whose owner only wants the diff/timeline
+      # half.
+      #
+      # Only file-bearing associations are processed — see `file_bearing_association?`. This avoids
+      # the over-eager extraction the original code shipped with (it grabbed `id` from *every*
+      # association's payload, rescued only by a downstream existence filter that masks the mistake
+      # until a non-file record's PK happens to collide with a real blob PK, at which point a
+      # spurious reference silently "protects" an unrelated blob from purge).
+      def record_blob_references(snapshot, calculated_diff)
+        return unless SnapshotBlobReference.table_exists?
+
+        associations = calculated_diff['associations']
+        return if associations.blank?
+
+        blob_ids = Set.new
+        associations.each do |assoc_name, changes|
+          next if changes.blank?
+          next unless file_bearing_association?(assoc_name.to_s)
+
+          changes.each do |tuple|
+            # tuple format: [op, index, payload] or [op, index, from, to]
+            extract_blob_ids_from_payload(tuple[2], blob_ids)
+            to_payload = tuple[3]
+            extract_blob_ids_from_payload(to_payload, blob_ids) if to_payload
+          end
+        end
+
+        return if blob_ids.empty?
+
+        # Belt-and-suspenders: file_bearing_association? is the primary defense (non-file
+        # associations never reach here), but a blob could still be purged between diff-compute
+        # and reference-write inside the with_lock block. Filter to existing blobs to avoid an
+        # FK violation on snapshot_blob_references.blob_id. :: prefix — see
+        # file_bearing_association? for the Glib::ActiveStorage shadowing rationale.
+        existing_blob_ids = ::ActiveStorage::Blob.where(id: blob_ids.to_a).pluck(:id)
+        existing_blob_ids.each do |blob_id|
+          SnapshotBlobReference.create!(snapshot: snapshot, blob_id: blob_id)
+        rescue ActiveRecord::RecordNotUnique
+          # Already referenced (e.g. same blob_id in both from and to of an update) — safe to skip.
+        end
+      end
+
+      # An association is "file-bearing" if its diff payloads carry ActiveStorage blob/attachment
+      # row data. Two shapes:
+      #   1. Direct ActiveStorage macros: has_one_attached / has_many_attached
+      #      (e.g. OrganizationDocument#file, V2Post#photos). NOTE: these create NO AR reflection
+      #      under their own name — they're detected by their value type (Attached::One/Many),
+      #      the same value-based detection check_snapshot_changed and diff_associations use
+      #      (active_storage_association?).
+      #   2. Through associations whose terminal klass is ActiveStorage::Blob or ::Attachment
+      #      (e.g. Submission's snapshot_document_blobs: has_many ..., through: ..., source: :blob).
+      #      These have real reflections with a blob/attachment klass.
+      # Non-file associations (has_many :comments, has_one :profile, etc.) are skipped so their
+      # record PKs never enter the blob-id extraction path.
+      #
+      # The :: prefix on ActiveStorage constants is REQUIRED: inside `module Glib`, a bare
+      # `ActiveStorage` resolves lexically to Glib::ActiveStorage (the gem's dynamic-text mirror
+      # subclass of ::ActiveStorage::Blob), and class equality against it would always be false.
+      def file_bearing_association?(assoc_name)
+        reflection = self.class.reflect_on_association(assoc_name)
+        association_value = public_send(assoc_name)
+
+        return true if active_storage_association?(reflection, association_value)
+
+        klass = reflection&.klass
+        klass && [::ActiveStorage::Blob, ::ActiveStorage::Attachment].include?(klass)
+      end
+
+      def extract_blob_ids_from_payload(payload, blob_ids)
+        return unless payload.is_a?(Hash)
+
+        # Old snapshots diff ActiveStorage::Attachment rows (blob_id key);
+        # new snapshots diff ActiveStorage::Blob rows directly (id key = Blob PK).
+        blob_id = payload['blob_id'] || payload[:blob_id] || payload['id'] || payload[:id]
+        blob_ids.add(blob_id) if blob_id.present?
+      end
+
+      # --- ActiveStorage helpers (ported from V1 gem) ---
+
+      def active_storage_association?(association, association_value)
+        macro = association&.macro
+        return true if [:has_many_attached, :has_one_attached].include?(macro)
+        return false if association_value.nil?
+
+        # :: prefix — see file_bearing_association? for the Glib::ActiveStorage shadowing
+        # rationale. Without it, `defined?(Glib::ActiveStorage::Attached)` is nil and the
+        # is_a? checks below silently never run (the respond_to? fallback masked this).
+        if defined?(::ActiveStorage::Attached)
+          return true if association_value.is_a?(::ActiveStorage::Attached::Many) || association_value.is_a?(::ActiveStorage::Attached::One)
+        end
+
+        association_value.respond_to?(:attachments) || association_value.respond_to?(:attachment)
+      end
+
+      def active_storage_records(value)
+        if value.respond_to?(:attachments)
+          value.attachments
+        elsif value.respond_to?(:attachment)
+          Array(value.attachment).compact
+        else
+          []
+        end
+      end
+
+      def active_storage_record?(record)
+        return false if record.nil?
+
+        record.class.name.start_with?('ActiveStorage::')
+      end
+  end
+end

data/app/models/snapshot_blob_reference.rb

@@ -0,0 +1,20 @@
+# Top-level (NOT namespaced under Glib::) by design — see issue #960's hard constraint:
+#
+#   The gem's SnapshotBlobReference must stay a top-level model on table
+#   `snapshot_blob_references` — not namespaced. Drop-in compatibility holds only
+#   because `isolate_namespace` is off in lib/glib/engine.rb. Namespacing it (e.g.
+#   Glib::SnapshotBlobReference → table `glib_snapshot_blob_references`) or enabling
+#   isolate_namespace orphans every existing consumer's table + rows and forces a
+#   rename/data migration.
+#
+# This file lives at `app/models/snapshot_blob_reference.rb` (not under `app/models/glib/`)
+# so the Rails autoloader resolves the constant as top-level `SnapshotBlobReference`, which
+# in turn maps to the un-prefixed table name `snapshot_blob_references`. The host app's
+# existing `SnapshotBlobReference` model can be deleted verbatim when it bumps the gem.
+#
+# Inherits from the host's `ApplicationRecord` (the standard since Rails 5.0) so the model
+# shares the primary DB connection — same pattern as every other top-level host model.
+class SnapshotBlobReference < ApplicationRecord
+  belongs_to :snapshot, class_name: 'ActiveSnapshot::Snapshot'
+  belongs_to :blob, class_name: 'ActiveStorage::Blob'
+end

data/lib/generators/glib/snapshot_v2_generator.rb

@@ -0,0 +1,54 @@
+module Glib
+  module Generators
+    # Installs the Glib::SnapshotV2 database prerequisites. Two opt-in pieces, each produced
+    # only when the corresponding flag is passed:
+    #
+    #   `rails g glib:snapshot_v2`                        # adds V2 columns only (required for V2)
+    #   `rails g glib:snapshot_v2 --with-blob-references` # also creates the blob-reference table
+    #
+    # Deliberately separate from `glib:install`: that generator overwrites `config/database.yml`
+    # and writes dynamic-text migrations to the non-standard `db/dynamic_text_migrate/` path,
+    # neither of which a snapshot adopter wants re-run on their app. Snapshot tables live in the
+    # primary DB and use the standard `db/migrate/` path.
+    #
+    # The V2 columns migration adds `action` / `version` / `diff` (jsonb) / `source` plus the
+    # two composite indexes Glib::SnapshotV2's queries rely on. It does NOT backfill — adopters
+    # who need to migrate legacy V1 snapshots (stored under metadata) own that one-way data
+    # conversion themselves. See issue #960.
+    class SnapshotV2Generator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('../templates/snapshot_v2', __dir__)
+
+      class_option :with_blob_references, type: :boolean, default: false,
+                                          desc: 'Also create the snapshot_blob_references table (required to version attached files)'
+
+      def copy_v2_columns_migration
+        migration_template 'add_snapshot_v2_columns.rb',
+                           'db/migrate/add_snapshot_v2_columns.rb'
+      end
+
+      def copy_blob_references_migration
+        return unless options[:with_blob_references]
+
+        migration_template 'create_snapshot_blob_references.rb',
+                           'db/migrate/create_snapshot_blob_references.rb'
+      end
+
+      private
+        # Rails::Generators::Migration requires this class method. Returns the UTC timestamp for
+        # the next migration filename. The mutex + @last_number pair guarantees the second template
+        # (create_snapshot_blob_references) lands strictly AFTER the first (add_snapshot_v2_columns)
+        # within a single invocation — otherwise both share the same timestamp and load order is
+        # non-deterministic.
+        @@migration_mutex = Mutex.new
+
+        def self.next_migration_number(_dirname)
+          @@migration_mutex.synchronize do
+            @last_snapshot_v2_number ||= (Time.now.utc - 1.second).strftime('%Y%m%d%H%M%S')
+            @last_snapshot_v2_number = (@last_snapshot_v2_number.to_i + 1).to_s
+          end
+        end
+    end
+  end
+end

data/lib/generators/templates/snapshot_v2/add_snapshot_v2_columns.rb

@@ -0,0 +1,18 @@
+class AddSnapshotV2Columns < ActiveRecord::Migration[8.0]
+  def change
+    # PostgreSQL has jsonb (binary, indexable); SQLite (used by glib-web's dummy-app) and MySQL
+    # only have json. Pick the richest type the adapter supports so consumers on PG get indexable
+    # diffs while greenfield adopters on SQLite/MySQL still work without edits.
+    diff_type = connection.adapter_name.match?(/PostgreSQL/i) ? :jsonb : :json
+
+    change_table :snapshots, bulk: true do |t|
+      t.string  :action
+      t.integer :version
+      t.column  :diff, diff_type
+      t.string  :source
+    end
+
+    add_index :snapshots, [:action, :item_type, :item_id]
+    add_index :snapshots, [:item_type, :item_id, :version]
+  end
+end

data/lib/generators/templates/snapshot_v2/create_snapshot_blob_references.rb

@@ -0,0 +1,10 @@
+class CreateSnapshotBlobReferences < ActiveRecord::Migration[8.0]
+  def change
+    create_table :snapshot_blob_references do |t|
+      t.belongs_to :snapshot, null: false, foreign_key: { to_table: :snapshots }
+      t.belongs_to :blob, null: false, foreign_key: { to_table: :active_storage_blobs }
+      t.timestamps
+    end
+    add_index :snapshot_blob_references, [:snapshot_id, :blob_id], unique: true
+  end
+end

data/lib/glib/engine.rb

@@ -22,6 +22,25 @@ module Glib
             scope :created_desc, -> { order(created_at: :desc, id: :desc) }
           end
 
+          # Cascade-destroy blob references when a snapshot is destroyed (e.g. by max_snapshots
+          # retention in Glib::SnapshotV2#remove_old_snapshot). Without this, the FK on
+          # snapshot_blob_references would raise PG::ForeignKeyViolation.
+          #
+          # Opt-in: only consumers who run the gem's `create_snapshot_blob_references` migration
+          # have the table. The connection+table_exists? guard (wrapped in a rescue for boot
+          # sequences with no DB yet — `rails db:create`, parallel test setup) makes this a no-op
+          # for everyone else, so a bare `include Glib::SnapshotV2` never crashes a boot.
+          unless respond_to?(:snapshot_blob_references)
+            begin
+              if connection.table_exists?(:snapshot_blob_references)
+                has_many :snapshot_blob_references, dependent: :destroy
+              end
+            rescue ActiveRecord::NoDatabaseError, ActiveRecord::StatementInvalid
+              # Boot before the DB exists (e.g. `rails db:create`). The association gets re-registered
+              # on the next successful boot that finds the table.
+            end
+          end
+
           # Parses the stored diff into a flat hash of Change structs:
           #   { 'item' => [Change, ...], 'association_name' => [Change, ...], ... }
           # Returns an empty structure if no diff exists (e.g. the first snapshot).
@@ -93,7 +112,13 @@ module Glib
 
           private
             # Item-level change: from/to are scalar column values. Cast each to the column's real type.
+            #
+            # `index` is normalized to a Symbol so consumers compare against symbol literals
+            # (matching AR attribute keys, e.g. `change.index == :title`). Association-level
+            # changes are NOT symbolized — their index is a collection position from a path like
+            # "[0]", a positional digit, not a name.
             def cast_item_change(change, root)
+              change.index = change.index.to_sym
               change.from = cast_column_value(root, change.index, change.from)
               change.to   = cast_column_value(root, change.index, change.to)
               change

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glib-web
 version: !ruby/object:Gem::Version
-  version: 6.8.1
+  version: 6.9.0
 platform: ruby
 authors:
 - ''
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-22 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: pundit
   requirement: !ruby/object:Gem::Requirement
@@ -251,9 +265,11 @@ files:
 - app/helpers/glib/json_ui/view_builder/multimedia.rb
 - app/helpers/glib/json_ui/view_builder/panels.rb
 - app/helpers/glib/urls_helper.rb
+- app/jobs/glib/purge_unattached_job.rb
 - app/models/concerns/glib/enum_humanization.rb
 - app/models/concerns/glib/enum_symbolization.rb
 - app/models/concerns/glib/nilify_blanks.rb
+- app/models/concerns/glib/snapshot_v2.rb
 - app/models/concerns/glib/soft_deletable.rb
 - app/models/glib/active_storage/attachment.rb
 - app/models/glib/active_storage/blob.rb
@@ -263,6 +279,7 @@ files:
 - app/models/glib/dynamic_text_record.rb
 - app/models/glib/state_list.rb
 - app/models/glib/text.rb
+- app/models/snapshot_blob_reference.rb
 - app/policies/glib/application_policy.rb
 - app/validators/email_typo_validator.rb
 - app/validators/email_validator.rb
@@ -534,12 +551,15 @@ files:
 - config/routes.rb
 - lib/active_storage/service/glib_s3_service.rb
 - lib/generators/glib/install_generator.rb
+- lib/generators/glib/snapshot_v2_generator.rb
 - lib/generators/templates/20191017062519_create_texts.rb
 - lib/generators/templates/20191024063257_add_scope_to_texts.rb
 - lib/generators/templates/20191112095018_add_lang_to_texts.rb
 - lib/generators/templates/20191126071051_create_active_storage_tables.active_storage.rb
 - lib/generators/templates/database.yml
 - lib/generators/templates/dynamic_text.rb
+- lib/generators/templates/snapshot_v2/add_snapshot_v2_columns.rb
+- lib/generators/templates/snapshot_v2/create_snapshot_blob_references.rb
 - lib/glib-web.rb
 - lib/glib/all_helpers.rb
 - lib/glib/crypt/utils.rb