glib-web 7.0.0.beta1 → 7.0.0

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

@@ -0,0 +1,514 @@
+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).
+#   5. same_as_before? derives from the computed diff instead of the instance-local
+#      `snapshot_changed` flag (mapping-web's flag-gating silently dropped a target's
+#      snapshot when taken after the owner's -- see "Snapshot ordering" below, issue #481),
+#      with the flag re-entering as a NEGATIVE signal for first snapshots only (see
+#      `same_as_before?` for why an empty association baseline cannot decide those).
+#
+# ## Snapshot ordering: owner vs association targets
+#
+# Owner and association-target snapshots may be taken in ANY order within a request.
+# `same_as_before?` decides from persisted state, so a target snapshotted after its owner
+# (through the replaced association target) still records its version.
+#
+# The one residual ordering caveat: `diff` compares against the instance's IN-MEMORY
+# attributes, so unsaved changes live only on the instance that holds them. If a target is
+# modified in memory without saving, snapshot it via a local captured BEFORE the owner's
+# `glib_create_snapshot!` (whose `with_lock` reload replaces the association targets) --
+# reading the target back through the association snapshots the persisted state instead.
+#
+# `snapshot_changed` / `attributes_before_save` remain writable instance accessors for
+# call-site use; `snapshot_changed` is consulted by the skip decision only as a NEGATIVE
+# signal on first snapshots (see `same_as_before?`).
+#
+# 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?
+          # For a save with no pending change `attributes_in_database` is empty -- an
+          # unchanged persisted record has no database-side delta -- which would make a
+          # first snapshot diff every attribute as an addition. Capture the full
+          # persisted state instead, so an unchanged save yields an empty item diff and
+          # the nil-guard keeps that baseline stable for later changes on the same
+          # instance. New records keep `attributes_in_database` (their all-nil
+          # originals): that non-empty baseline is exactly why a create's version 1
+          # records the full initial state. `unless` keeps the accessor nil, never
+          # `false`, for call-site nil-safety.
+          self.attributes_before_save = attributes_in_database.presence || (attributes unless new_record?)
+          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. Reuses `calculated_diff` instead of
+              # recomputing it inside `same_as_before?`. `version == 1` (no previous
+              # version exists) tells `same_as_before?` this is a FIRST snapshot, where the
+              # association baseline is empty and the flag carries decision weight.
+              unless same_as_before?(calculated_diff, first_snapshot: version == 1)
+                # 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
+
+    # Decides whether `glib_create_snapshot!` should skip the version write. Derived from
+    # the computed diff (persisted state), not from the instance-local `snapshot_changed`
+    # flag: the flag dies with its instance, and an owner's snapshot replaces association
+    # targets with fresh instances (`with_lock`'s reload clears the association cache, then
+    # the diff walk re-reads the targets), so flag-gating used to silently drop a target's
+    # follow-up snapshot taken through the association (issue #481).
+    #
+    # The one place the flag still decides: a FIRST snapshot whose association diff is
+    # meaningless. With no previous version, `fetch_snapshot_items(nil)` returns `{}`
+    # for associations, so every pre-existing child row reads as `+` and the diff alone
+    # can never prove a no-op — any never-snapshotted record with children would mint a
+    # version on every snapshot call (observed as spurious "Edited" audit entries on
+    # routine re-saves). There the flag is consulted as a NEGATIVE signal:
+    #   - `false` — this instance crossed the before_save boundary and
+    #     `check_snapshot_changed` found no item or child change, and the item diff is
+    #     net-zero against `attributes_before_save` => skip;
+    #   - `nil` — no save boundary on this instance (an owner-triggered snapshot of a
+    #     replaced association target, issue #481) => mint;
+    #   - `true` — a change was detected at the save boundary; falls through to the
+    #     diff-based decision (a reverted change still no-ops).
+    def same_as_before?(computed_diff = diff, first_snapshot: false)
+      return true if first_snapshot && snapshot_changed == false && computed_diff['item'].blank?
+
+      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/glib/model.rb

@@ -0,0 +1,40 @@
+module Glib
+  # Base class for table-less FORM-BACKED domain objects — the ActiveModel
+  # counterpart of Glib::ApplicationRecord. Apps inherit through a thin
+  # `ApplicationModel < Glib::Model` root (parallel to ApplicationRecord), so
+  # app code always reads `< ApplicationModel`.
+  #
+  # Choosing a base for a class under app/models (the three-way rule; see
+  # dev-doc best_practices/backend/en/03_model.md item 9):
+  #
+  #   ApplicationRecord — the class is persisted (it has a table).
+  #   ApplicationModel  — table-less, but it BACKS A FORM/REQUEST: it is built
+  #                       from params (`assign_attributes(create_params)`),
+  #                       validates one user transaction, reports errors back
+  #                       to the dialog, and pairs by name with a controller
+  #                       and policy. (This class.)
+  #   PlainModel        — neither: plain domain logic with no framework
+  #                       machinery — catalogs, derivations, tallies,
+  #                       write-orchestration helpers (see Glib::PlainModel).
+  #
+  # If you are reaching for a bare `include ActiveModel::Model`, you want
+  # ApplicationModel instead — the shared mechanics live here.
+  class Model
+    include ActiveModel::Model
+
+    # Declares multi-select id-list attributes: a reader plus a normalizing
+    # writer that drops the blank entries browsers submit for empty
+    # multi-selects and coerces the surviving ids to integers.
+    #
+    #   attr_id_list :member_ids, :assignee_group_ids
+    def self.attr_id_list(*attr_names)
+      attr_names.each do |attr_name|
+        attr_reader attr_name
+
+        define_method("#{attr_name}=") do |ids|
+          instance_variable_set("@#{attr_name}", Array(ids).map(&:presence).compact.map(&:to_i))
+        end
+      end
+    end
+  end
+end

data/app/models/glib/plain_model.rb

@@ -0,0 +1,23 @@
+module Glib
+  # Marker base for PLAIN domain objects: domain logic under app/models that
+  # neither persists (no table — not ApplicationRecord) nor backs a form or
+  # request (no params/validations/errors — not ApplicationModel). Catalogs,
+  # derivations, tallies, write-orchestration helpers. Apps inherit through a
+  # thin `PlainModel < Glib::PlainModel` root; the base-choosing guide lives on
+  # Glib::Model.
+  #
+  # Deliberately empty: what plain domain objects share is a CONTRACT, not
+  # mechanics —
+  #   - domain logic only: no external I/O (HTTP clients and provider SDKs
+  #     belong in app/services adapters);
+  #   - no enqueues (`perform_later`/`deliver_later` are the calling
+  #     controller's or job's trigger);
+  #   - writes, when any, go through the ActiveRecord models whose invariants
+  #     they are.
+  # Inheriting this class is the author's declaration that the contract holds.
+  # The moment a subclass wants shared BEHAVIOR from here, that behavior
+  # belongs in Glib::Model or a concern instead — this base stays a
+  # classification, so that inheriting it keeps meaning exactly one thing.
+  class PlainModel
+  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/app/views/json_ui/garage/tables/bulk_edit.json.jbuilder

@@ -37,17 +37,17 @@ page.scroll childViews: ->(scroll) do
         displayed: false
     end
 
-    wres.panels_bulkEdit2 \
+    wres.panels_bulkEdit3 \
       id: 'import_table',
       width: 'matchParent',
       paramNameForRowId: 'row_id',
       import: { submitUrl: json_ui_garage_url(path: 'forms/bulk_edit_post2'), paramName: 'user' },
       viewHeaders: [
-        { text: 'Month', id: 'month', importable: true, tooltip: { text: 'Month', placement: 'top' } },
-        { text: 'Electricity usage', id: 'electricity_usage', importable: true },
-        { text: 'Gas usage', id: 'gas_usage', importable: true },
-        { text: 'Sources', id: 'sources', importable: true },
-        { text: 'Compliant', id: 'compliant', importable: true }
+        { text: 'Month', id: 'month', tooltip: { text: 'Month', placement: 'top' } },
+        { text: 'Electricity usage', id: 'electricity_usage' },
+        { text: 'Gas usage', id: 'gas_usage' },
+        { text: 'Sources', id: 'sources' },
+        { text: 'Compliant', id: 'compliant' }
       ],
       viewCells: [
         ->(view) do

data/app/views/json_ui/garage/test_page/_header.json.jbuilder

@@ -37,6 +37,7 @@ nav_groups = {
     'fields_stripeExternalAccount',
     'fields_creditCard',
     'fields_timer',
+    'fields_change_trigger',
     'fields_upload',
     'fields_url_fragment',
     'fields_captcha',
@@ -55,7 +56,6 @@ nav_groups = {
     'flow',
     'grid',
     'horizontal',
-    'panels_bulkEdit2',
     'pagination',
     'responsive',
     'scroll',

data/app/views/json_ui/garage/test_page/dialog.json.jbuilder

@@ -89,6 +89,27 @@ page.body(
           end
         )
         res.spacer height: 4
+        res.button(
+          text: 'Dialog alert onClose',
+          onClick: ->(action) do
+            action.dialogs_alert(
+              message: 'Close me',
+              onClose: ->(subaction) do
+                subaction.dialogs_show(
+                  content: ->(dialog) do
+                    dialog.body(
+                      padding: glib_json_padding_body,
+                      childViews: ->(sbody) do
+                        sbody.h1 text: 'onClose fired'
+                      end
+                    )
+                  end
+                )
+              end
+            )
+          end
+        )
+        res.spacer height: 4
         res.button(
           text: 'Dialog notification',
           onClick: ->(action) do