permission_forge 0.14.1

data/lib/permission_forge/concerns/permissions_per_context.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # Which permission hash the request context selects for a user with
+    # conditional permission sets (PermissionForge::ConditionalSets): the
+    # base entry, or the variant of the conditional sets that pass — on a
+    # read (PermissionCacheAccessor#permissions_hash), on a rebuild
+    # (regenerate_permissions) — and how each entry, base or variant, is
+    # built. (What an invalidation removes is Cache::UserKeys; the variants
+    # go on erasure and cache:clear, Cache::VariantRemoval.) A user without
+    # conditional sets costs it nothing: one nil check.
+    #
+    # @api private
+    module PermissionsPerContext
+      # What a read produced: the hash, what selected it (nil without
+      # conditional sets), the open transaction it was built in (nil when it
+      # was read from the store, or built outside one), and how it came
+      # about — nil: read from the store; :base — regenerate_permissions
+      # built it, which bumped the version; :variant — a variant built
+      # read-through for a base entry read from the store, which did not;
+      # :reentrant — asked by the build itself, {} for that call alone. And
+      # when the soonest of the user's assignments that went into it ends
+      # (epoch seconds, nil for none: EXPIRY_KEY).
+      #
+      # @api private
+      Selected = Data.define(:permissions, :served, :transaction, :rebuilt, :expires_at) do
+        def initialize(expires_at: nil, **)
+          super
+        end
+
+        # What a memo holds, as a base rebuilt by regenerate_permissions.
+        def self.of_memo(memo)
+          new(permissions: memo.permissions, served: memo.served, transaction: nil, rebuilt: :base, expires_at: memo.expires_at)
+        end
+
+        # @return [PermissionsMemo::Memo] the memo of this hash, good for `version`
+        def memo(key, version)
+          PermissionsMemo::Memo.new(key: key, version: version, transaction: transaction, permissions: permissions, served: served,
+                                    expires_at: expires_at)
+        end
+      end
+
+      REENTRANT = Selected.new(permissions: {}.freeze, served: nil, transaction: nil, rebuilt: :reentrant)
+
+      # The fiber-local ExecutionState slot of the builds (and request-context
+      # resolutions) running on this fiber, by permission cache key.
+      BUILDING_KEY = :pf_building_permission_keys
+
+      # Where the stored base entry of a user with an assignment that ends
+      # (PermissionSetUser#expires_at) carries when the soonest one ends, in
+      # epoch seconds — as it carries the conditional sets: taken off on
+      # every read, never part of the hash. The memo of the hash is retired
+      # then (PermissionsMemo::Memo#serves?): an instance kept across
+      # requests stops granting what the assignment granted when it ends,
+      # as the store entry (whose TTL is clamped to it) does.
+      EXPIRY_KEY = :assignments_expire_at
+
+      private
+
+      # The memoized hash, while the request context still selects what it
+      # was built for. For a user without conditional sets: always. With
+      # them: when the context is the one that selected it (its signature,
+      # cheap), or another one that selects the same variant — remembered
+      # as such, so the next call is cheap again. nil when the context now
+      # selects another variant: the base entry is read again.
+      #
+      # @return [Hash, nil]
+      def pf_memoized_permissions_for_context(key, memo)
+        again = memo.for_context { pf_resolve_request_context(key) }
+        return unless again
+
+        pf_memoize_permissions(again) unless again.equal?(memo)
+        again.permissions
+      end
+
+      # What a base entry read from the store serves in the current request
+      # context: itself — or, when the context selects conditional sets, the
+      # variant for them, read from the store (when its slot holds the
+      # variant of this base entry and selection:
+      # ConditionalSets.variant_hash) or built read-through.
+      #
+      # @return [Selected, nil] nil for an entry that cannot be used (its
+      #   conditional sets cannot be read): a miss
+      def pf_select_shared_permissions(key, entry)
+        hash, conditional, expires_at = pf_split_base_entry(entry)
+        return unless hash
+        return pf_read_permissions(hash, nil, expires_at) unless conditional
+
+        served = conditional.serve(pf_resolve_request_context(key))
+        variant = served.variant
+        return pf_read_permissions(hash, served, expires_at) unless variant
+
+        # a variant that is never stored (ConditionalSets::MAX_CACHED_SETS) is not looked for
+        stored = pf_read_shared_permissions(served.store_key(key)) if variant.cached
+        cached = PermissionForge::ConditionalSets.variant_hash(stored, variant)
+        return pf_read_permissions(cached, served, expires_at) if cached
+
+        pf_rebuild_variant_read_through(key, served, expires_at)
+      end
+
+      def pf_read_permissions(hash, served, expires_at)
+        Selected.new(permissions: hash, served: served, transaction: nil, rebuilt: nil, expires_at: expires_at)
+      end
+
+      # A stored base entry taken apart: the hash in the public format, the
+      # conditional sets it carries (ConditionalSets.split) and when the
+      # soonest assignment that went into it ends (EXPIRY_KEY).
+      #
+      # @return [Array(Hash, ConditionalSets|nil, Integer|nil), nil] nil for
+      #   an entry that cannot be used
+      def pf_split_base_entry(entry)
+        expires_at = entry[EXPIRY_KEY]
+        hash, conditional = PermissionForge::ConditionalSets.split(expires_at ? entry.except(EXPIRY_KEY) : entry)
+        [hash, conditional, (expires_at if expires_at.is_a?(Integer))] if hash
+      end
+
+      # Builds the variant `served` names on a cache miss, under the same
+      # guard as a read-through rebuild of the base (the build reads this
+      # user's attributes too), and stores it unless it is withheld.
+      #
+      # @return [Selected]
+      def pf_rebuild_variant_read_through(key, served, expires_at)
+        outcome = pf_guarding_permission_build(key) do
+          transaction = PermissionForge::OpenTransaction.withholding
+          permissions = pf_rebuild_variant(key, transaction, served)
+          Selected.new(permissions: permissions, served: served, transaction: transaction, rebuilt: :variant, expires_at: expires_at)
+        end
+        outcome == :reentrant ? REENTRANT : outcome
+      end
+
+      # Builds the base entry and — when the request context selects
+      # conditional sets — the variant for them; stores each unless it is
+      # withheld inside a transaction (regenerate_permissions).
+      #
+      # @return [Selected] the hash that applies to the context, and what
+      #   selected it (nil when the user holds no conditional set), as a
+      #   base rebuilt
+      def pf_rebuild_permissions(key, transaction)
+        hash, conditional, expires_at = pf_split_base_entry(pf_rebuild_permission_entry(key, transaction))
+        served = conditional&.serve(pf_resolve_request_context(key))
+        hash = pf_rebuild_variant(key, transaction, served) if served&.variant
+        Selected.new(permissions: hash, served: served, transaction: transaction, rebuilt: :base, expires_at: expires_at)
+      end
+
+      # Builds one entry — the base under `key` (served nil), or the variant
+      # `served` selects — and, unless it is withheld inside a transaction
+      # or not cached at all (Variant#cached), stores it, verified against
+      # the user's invalidation stamp. A variant is written only after its
+      # index entry (#pf_variant_indexed?), which is written after the
+      # stamp was read. The WithheldNotice counts permission rebuilds only
+      # (Cache::Rebuild also builds the managed-actions index).
+      #
+      # @param key [String] the user's base key
+      # @param served [ConditionalSets::Served, nil] what selected a variant
+      # @return [Hash] the entry as built, with symbol keys like one read
+      #   from the store (a variant's: #pf_rebuild_variant)
+      def pf_rebuild_permission_entry(key, transaction, served = nil)
+        variant = served&.variant
+        rebuild = PermissionForge::Cache::Rebuild.new(
+          key: served ? served.store_key(key) : key, stamp_key: pf_invalidation_stamp_key, user_id: id,
+          build: -> { pf_build_permission_entry(variant) }
+        )
+        notice = PermissionForge::Cache::WithheldNotice
+        transaction ? notice.withheld : notice.not_withheld
+        withheld = transaction || (variant && !variant.cached)
+        (withheld ? rebuild.withhold : pf_store_rebuild(rebuild, key, served)).deep_symbolize_keys
+      end
+
+      # Runs a rebuild that is stored: a variant's after its index entry.
+      #
+      # @return [Hash] the entry as built
+      def pf_store_rebuild(rebuild, key, served)
+        return rebuild.call.first unless served&.variant
+
+        rebuild.call { pf_variant_indexed?(key) }.first
+      end
+
+      # The hash a variant's rebuild built, without what its entry carries
+      # (ConditionalSets.variant_entry; nothing for a variant that is never
+      # stored).
+      def pf_rebuild_variant(key, transaction, served)
+        variant = served.variant
+        entry = pf_rebuild_permission_entry(key, transaction, served)
+        variant.cached ? PermissionForge::ConditionalSets.variant_hash(entry, variant) : entry
+      end
+
+      # Writes the index entry by which the enumerated cache:clear finds the
+      # variants of the base at `key` (Cache::VariantRemoval; erasure removes
+      # every slot without it) — after the variant's rebuild read the stamp,
+      # before the variant is written. A variant whose rebuild read the stamp
+      # before an invalidation is either verified before it, its index entry
+      # already there for the removal that follows the invalidation, or
+      # discarded by its verification. A variant whose index entry was not
+      # written is not stored: the clear would not find it. The entry
+      # outlives every variant written after it
+      # (ConditionalSets::INDEX_TTL_MARGIN).
+      #
+      # @return [Boolean] whether the store took the index entry
+      def pf_variant_indexed?(key)
+        sets = PermissionForge::ConditionalSets
+        ttl = PermissionForge.configuration.cache_ttl
+        PermissionForge.cache.write(sets.index_key(key), sets::INDEX, ttl: ttl && (ttl + sets::INDEX_TTL_MARGIN)) ? true : false
+      end
+
+      # Everything a build reads is read outside ActiveRecord's query cache.
+      # Inside a request the cache would answer the queries of a repeated
+      # build — or of a second rebuild later in the request — with the rows
+      # the first one read.
+      #
+      # The base entry (variant nil) is built from the unconditional sets and
+      # carries the conditional ones, and when the soonest assignment ends
+      # (EXPIRY_KEY); a variant from the unconditional sets plus those of the
+      # variant, and — when it is stored — carries what it was built for
+      # (ConditionalSets.variant_entry). The TTL is that of all the user's
+      # sets either way.
+      #
+      # @return [Array(Hash, Integer)] the entry and its TTL (nil for none)
+      def pf_build_permission_entry(variant)
+        PermissionForge::PermissionSet.uncached do
+          permission_sets = pf_active_non_expired_permission_sets
+          conditional = PermissionForge::ConditionalSets.of(permission_sets)
+
+          permission_data = PermissionForge::Services::PermissionHashBuilder.call(
+            user: self,
+            permission_sets: PermissionForge::ConditionalSets.build_sets(permission_sets, variant)
+          )
+
+          profile = PermissionForge.configuration.profile_builder.call(self)
+
+          soonest = pf_soonest_assignment_expiry
+          entry = { profile: profile, preferences: {}, permissions: permission_data }
+          if variant.nil?
+            pf_carry_in_base_entry(entry, conditional, soonest)
+          elsif variant.cached
+            entry = PermissionForge::ConditionalSets.variant_entry(entry, variant)
+          end
+          [entry, pf_permission_cache_ttl(permission_sets, soonest)]
+        end
+      end
+
+      # What the base entry carries beside the hash: the user's conditional
+      # sets (ConditionalSets::ENTRY_KEY) and when the soonest assignment
+      # ends (EXPIRY_KEY), each only when there is one.
+      def pf_carry_in_base_entry(entry, conditional, soonest)
+        entry[PermissionForge::ConditionalSets::ENTRY_KEY] = conditional.dump if conditional
+        entry[EXPIRY_KEY] = soonest.to_i if soonest
+      end
+
+      # The request context the activation conditions are evaluated against
+      # (config.request_context_resolver), resolved on every read of a user
+      # with conditional sets. A resolver that reads the permissions of the
+      # user it resolves for — a masked attribute of Current.user, a can_*?
+      # check — would be answered the hash being selected: one from another
+      # context, or {} (which switches row-level rules off). Neither is safe,
+      # so it raises instead — on every read of such a user.
+      #
+      # The context is a Hash; anything else the resolver returns (a Struct,
+      # an object with #to_h) is taken as its #to_h.
+      #
+      # @return [Hash]
+      # @raise [PermissionForge::ConfigurationError] when the resolver reads
+      #   this user's permissions
+      def pf_resolve_request_context(key)
+        building = PermissionForge::ExecutionState.fetch(BUILDING_KEY) { {} }
+        build = building[key]
+        if build&.[](:resolving)
+          raise PermissionForge::ConfigurationError,
+                "config.request_context_resolver read the permissions of the user it resolves the context for (#{key}): " \
+                'a resolver must not read permissions'
+        end
+
+        own = build.nil?
+        build = building[key] = {} if own
+        build[:resolving] = true
+        begin
+          pf_context_hash(PermissionForge.configuration.request_context_resolver.call)
+        ensure
+          own ? building.delete(key) : build.delete(:resolving)
+        end
+      end
+
+      def pf_context_hash(context)
+        context.is_a?(Hash) ? context : context.to_h
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/permissions_regenerator.rb

@@ -0,0 +1,43 @@
+module PermissionForge
+  module Concerns
+    # Invalidates the cached permission hash of every user affected by a change
+    # to the including permission model. The rebuild happens lazily on each
+    # user's next permissions_hash read (read-through in PermissionCacheAccessor),
+    # so activation conditions are evaluated in the affected user's own request
+    # context — not the context of whoever edited the permission records.
+    #
+    # Runs after commit through InvalidatesInBatch: the records written in one
+    # transaction invalidate each affected user once (per tenant), not once per
+    # record.
+    #
+    # @api private
+    module PermissionsRegenerator
+      extend ActiveSupport::Concern
+      include InvalidatesInBatch
+
+      # NOTE: The including model must define a private method `users_on_permission_set`
+      # that returns a collection of PermissionForge::PermissionSetUser records
+      # (or `user_ids_on_permission_set`, the ids of their users).
+
+      private
+
+      def invalidate_committed_caches
+        super
+        invalidate_permissions_for_users
+      end
+
+      def invalidate_permissions_for_users
+        invalidate_assigned_users(user_ids_on_permission_set, invalidation_batch, permission_record_tenant_id)
+      end
+
+      # The user ids of users_on_permission_set — plucked from a relation,
+      # without loading a row.
+      def user_ids_on_permission_set
+        holders = users_on_permission_set
+        return holders.distinct.pluck(:user_id) if holders.is_a?(ActiveRecord::Relation)
+
+        holders.filter_map(&:user_id).uniq
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/records_audit_events.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # Writes one audit event per create, update and destroy of a permission
+    # record (PermissionForge::Audit.record) — from after_create, after_update
+    # and after_destroy, inside the record's own transaction, so a change
+    # whose event cannot be written rolls back under the default
+    # `config.audit_change_failure_strategy = :raise`.
+    #
+    # What an event carries:
+    #   create  — data["snapshot"]: every attribute of the new row
+    #   update  — data["changes"]: saved_changes minus the bookkeeping columns
+    #             (created_at, updated_at, created_by_id, updated_by_id); a
+    #             save that changed nothing else writes no event. A model
+    #             adds keys of its own through #audit_update_details (an
+    #             assignment moved to another user: previous_subject_user_id)
+    #   destroy — data["snapshot"]: every attribute of the deleted row
+    # plus the record reference (#audit_reference): type, id, uuid, label, the
+    # Permission Set, the subject user of an assignment or membership, and
+    # the record's tenant. Everything written in one transaction shares a
+    # correlation id (a cascade delete, a Review-and-save).
+    #
+    # A caller that means something more specific by a save renames and
+    # enriches the row's own event instead of adding a second one:
+    #
+    #   assignment.audit_as('assignment.reviewed', data: { 'decision' => 'keep' }, reason: reason) do
+    #     assignment.update!(reviewed_at: Time.current, reviewed_by_id: admin.id)
+    #   end
+    #
+    # Paths that run no callbacks write no event: touch, update_column(s),
+    # update_all, delete_all, delete, insert_all, upsert_all. The gem's own
+    # code does not use them on these models; a test guards against new uses.
+    #
+    # Nothing is kept on the record outside a callback or an audit_as block:
+    # it can still be marshalled, and its associations are left as they were.
+    #
+    # @api private
+    module RecordsAuditEvents
+      extend ActiveSupport::Concern
+
+      BOOKKEEPING_COLUMNS = %w[created_at updated_at created_by_id updated_by_id].freeze
+      VERBS = { create: 'created', update: 'updated', destroy: 'destroyed' }.freeze
+
+      # Models whose events have their own names in the catalogue, by
+      # model key (base_class.model_name.element). Every other model's events
+      # are "<key>.created|updated|destroyed".
+      EVENT_NAMES = {
+        'permission_set_user' => { create: 'assignment.granted', update: 'assignment.changed', destroy: 'assignment.revoked' },
+        'permission_set_group_user' => { create: 'group_membership.added', update: 'group_membership.changed',
+                                         destroy: 'group_membership.removed' }
+      }.freeze
+
+      # The Permission Set an event about the record belongs to, by model key.
+      # Groups and memberships belong to none. Associations are read through
+      # #audit_associated: as loaded, else fetched in the record's own tenant.
+      OWN_SET = ->(record) { record.audit_associated(:permission_set) }
+      SET_OF_RESOURCE = ->(record) { record.audit_associated(:resource)&.audit_permission_set }
+      PERMISSION_SET = {
+        'permission_set' => ->(record) { record },
+        'resource' => OWN_SET, 'permission_set_rule' => OWN_SET, 'permission_set_user' => OWN_SET,
+        'resource_field' => SET_OF_RESOURCE, 'resource_action' => SET_OF_RESOURCE
+      }.freeze
+
+      # How the record is labelled, by model key; the default is its name.
+      QUALIFIED_NAME = ->(record) { [record.audit_associated(:resource)&.name, record.name].compact.join('.') }
+      PERSON_NAME = lambda { |record|
+        user = record.audit_associated(:user)
+        PermissionForge::Audit::Actor.label_for(user) if user
+      }
+      LABELS = {
+        'resource_field' => QUALIFIED_NAME, 'resource_action' => QUALIFIED_NAME,
+        'permission_set_user' => PERSON_NAME, 'permission_set_group_user' => PERSON_NAME
+      }.freeze
+
+      # The names #audit_as may give a model's own events, by model key and
+      # action — a more specific name for the same row change, never another
+      # model's event. Adding one is one entry.
+      AUDIT_AS_RENAMES = {
+        'permission_set_user' => { update: %w[assignment.reviewed] },
+        'resource_field' => { update: %w[field.sensitive_acknowledged] }
+      }.freeze
+
+      # Keys of an event's data that the concern computes (#audit_as cannot set them).
+      AUDIT_AS_COMPUTED_KEYS = %w[changes snapshot].freeze
+
+      included do
+        after_create :record_audit_event_for_create
+        after_update :record_audit_event_for_update
+        after_destroy :record_audit_event_for_destroy
+      end
+
+      class_methods do
+        # @param action [Symbol] :create, :update or :destroy
+        # @return [String] the catalogue name of the event
+        def audit_event_name(action)
+          action = action.to_sym
+          EVENT_NAMES.dig(audit_model_key, action) || "#{audit_model_key}.#{VERBS.fetch(action)}"
+        end
+
+        # 'permission_set', 'resource_field', ... — also for a subclass.
+        def audit_model_key
+          base_class.model_name.element
+        end
+      end
+
+      # Records this record's events inside the block under `event` instead
+      # of their own name, with `data` added to theirs and `reason` on them —
+      # only for the actions AUDIT_AS_RENAMES lists for the model and that
+      # event (a review or an acknowledgement is an update); any other
+      # action inside the block keeps its own event. Instance-scoped,
+      # block-only, restored when the block ends or raises. Nothing is set
+      # when the arguments are refused.
+      #
+      # @param event [String] a change event the model may be renamed to
+      # @param data [Hash] event-specific keys; the computed 'changes' /
+      #   'snapshot' cannot be replaced
+      # @param reason [String, nil]
+      # @return the value of the block
+      # @raise [Audit::EventCatalog::UnknownEventError, ArgumentError]
+      def audit_as(event, data: {}, reason: nil)
+        override = audit_as_override(event, data, reason) # raises before anything is set
+        previous = @pf_audit_as
+        @pf_audit_as = override
+        begin
+          yield
+        ensure
+          @pf_audit_as = previous
+        end
+      end
+
+      # The columns an event about this record carries (Audit::Recorder).
+      #
+      # @return [Hash] record_type, record_id, record_uuid, record_label,
+      #   permission_set_id, permission_set_uuid, subject_user_id, tenant_id
+      def audit_reference
+        with_audit_lookups do
+          set = audit_permission_set
+          {
+            record_type: self.class.base_class.name, record_id: id&.to_s, record_uuid: audit_uuid, record_label: audit_record_label,
+            permission_set_id: set&.id, permission_set_uuid: set&.uuid,
+            subject_user_id: audit_subject_user_id, tenant_id: audit_tenant_id
+          }
+        end
+      end
+
+      # Every attribute, JSON-ready.
+      def audit_snapshot
+        attributes.as_json
+      end
+
+      # saved_changes minus the bookkeeping columns, JSON-ready.
+      def audit_changes
+        saved_changes.except(*BOOKKEEPING_COLUMNS).as_json
+      end
+
+      # The Permission Set an event about this record belongs to, if any.
+      def audit_permission_set
+        PERMISSION_SET[self.class.audit_model_key]&.call(self)
+      end
+
+      # A belongs_to target as loaded, else fetched in this record's tenant
+      # and past every default scope — the ambient tenant may be another one
+      # or none (acts_as_tenant then raises under require_tenant), and the
+      # host's user model may hide the person behind a soft delete. What is
+      # fetched is not written to the association (the record would then
+      # answer with a hidden user, or with nothing for a row that is gone);
+      # inside #audit_reference it is looked up once.
+      #
+      # @param name [Symbol] a belongs_to association
+      # @return [ActiveRecord::Base, nil]
+      def audit_associated(name)
+        association = association(name)
+        return association.target if association.loaded?
+        return @pf_audit_lookups[name] if @pf_audit_lookups&.key?(name)
+
+        id = self[association.reflection.foreign_key]
+        found = id.nil? ? nil : audit_fetch(association.klass, id)
+        @pf_audit_lookups[name] = found if @pf_audit_lookups
+        found
+      end
+
+      private
+
+      # The validated #audit_as state: the event, the actions it renames, the
+      # data and the reason.
+      def audit_as_override(event, data, reason)
+        entry = PermissionForge::Audit::EventCatalog.fetch(event)
+        raise ArgumentError, "#{entry.name} is a #{entry.category} event: audit_as takes a change event" unless entry.category == 'change'
+
+        { event: entry.name, actions: audit_as_actions(entry.name), data: audit_as_data(data), reason: reason }
+      end
+
+      # The actions of this model that may be recorded as `name` (AUDIT_AS_RENAMES).
+      def audit_as_actions(name)
+        key = self.class.audit_model_key
+        actions = AUDIT_AS_RENAMES.fetch(key, {}).select { |_, names| names.include?(name) }.keys
+        raise ArgumentError, "#{key} events cannot be recorded as #{name}" if actions.empty?
+
+        actions
+      end
+
+      def audit_as_data(data)
+        data = data.as_json
+        reserved = data.keys & AUDIT_AS_COMPUTED_KEYS
+        raise ArgumentError, "audit_as data cannot set #{reserved.join(', ')}" if reserved.any?
+
+        data
+      end
+
+      # Memoizes association lookups for the duration of the block only.
+      def with_audit_lookups
+        @pf_audit_lookups = {}
+        yield
+      ensure
+        @pf_audit_lookups = nil
+      end
+
+      def audit_fetch(klass, id)
+        scope = klass.respond_to?(:of_tenant) ? klass.of_tenant(audit_tenant_id) : klass.unscoped
+        PermissionForge::Concerns::AutoPermissionScoping.internally_suspended { scope.find_by(klass.primary_key => id) }
+      end
+
+      def record_audit_event_for_create
+        record_audit_event(:create, 'snapshot' => audit_snapshot)
+      end
+
+      def record_audit_event_for_update
+        changes = audit_changes
+        return if changes.empty?
+
+        record_audit_event(:update, audit_update_details.merge('changes' => changes))
+      end
+
+      # Event data a model adds to its update events (the computed 'changes' wins).
+      def audit_update_details
+        {}
+      end
+
+      def record_audit_event_for_destroy
+        return unless audit_row_deleted?
+
+        record_audit_event(:destroy, 'snapshot' => audit_snapshot)
+      end
+
+      # Rails runs after_destroy also when the DELETE hit no row — an instance
+      # destroyed before, or already gone through a cascade. Nothing changed
+      # then, and the event for the row was written when it did go. Rails
+      # keeps the answer for its own commit callbacks (7.1 to 8.1).
+      def audit_row_deleted?
+        return true unless respond_to?(:_trigger_destroy_callback, true)
+
+        send(:_trigger_destroy_callback) ? true : false
+      end
+
+      # The row's own event, or the one an enclosing audit_as block asked for.
+      def record_audit_event(action, data)
+        override = @pf_audit_as if @pf_audit_as&.fetch(:actions)&.include?(action)
+        event = override ? override[:event] : self.class.audit_event_name(action)
+        data = override[:data].merge(data) if override # the computed keys win
+        PermissionForge::Audit.record(event, record: self, data: data, reason: override&.fetch(:reason))
+      end
+
+      def audit_uuid
+        has_attribute?(:uuid) ? self[:uuid] : nil
+      end
+
+      def audit_record_label
+        label = LABELS[self.class.audit_model_key]
+        label ? label.call(self) : try(:name)
+      end
+
+      def audit_subject_user_id
+        user_id&.to_s if respond_to?(:user_id)
+      end
+
+      def audit_tenant_id
+        config = PermissionForge.configuration
+        return unless config.tenant_enabled?
+
+        column = config.resolved_tenant_column
+        self[column] if has_attribute?(column)
+      end
+    end
+  end
+end