permission_forge 0.14.1

data/app/helpers/permission_forge/sentences_helper.rb

@@ -0,0 +1,175 @@
+module PermissionForge
+  # Plain-language sentences for activation conditions and record rules
+  # (audit events: AuditSentencesHelper; "Review and save" change
+  # descriptions: ChangesHelper).
+  #
+  # @api private
+  module SentencesHelper
+    NULLABLE_OPERATORS = %w[equal not_equal in not_in].freeze
+    LIST_OPERATORS = %w[in not_in].freeze
+    NO_VALUE_OPERATORS = %w[is_null is_not_null].freeze
+    USER_OPERATORS = %w[equal not_equal in not_in is_null is_not_null].freeze
+    CURRENT_USER = 'current_user'.freeze
+
+    # --- activation conditions ------------------------------------------------
+
+    def pf_condition_parts(permission_set)
+      [pf_condition_ips(permission_set), pf_condition_hours(permission_set), pf_condition_flag(permission_set)].compact
+    end
+
+    def pf_condition_ips(permission_set)
+      ips = pf_ip_list(permission_set.allowed_ips)
+      return if ips.empty?
+
+      connector = pf_ui('conditions.or')
+      pf_ui('conditions.from_ips', ips: ips.to_sentence(two_words_connector: connector, last_word_connector: connector))
+    end
+
+    def pf_condition_hours(permission_set)
+      from = permission_set.allowed_hours_start
+      to = permission_set.allowed_hours_end
+      return unless from.present? && to.present?
+
+      key = to.to_i <= from.to_i ? 'hours_overnight' : 'hours'
+      pf_ui("conditions.#{key}", from: pf_hour(from), to: pf_hour(to))
+    end
+
+    def pf_condition_flag(permission_set)
+      flag = permission_set.requires_session_flag
+      pf_flag_phrase(flag) if flag.present?
+    end
+
+    def pf_condition_sentence(permission_set)
+      parts = pf_condition_parts(permission_set)
+      return pf_ui('conditions.always') if parts.empty?
+
+      pf_ui('conditions.only_works', parts: parts.join(', '))
+    end
+
+    def pf_ip_list(value)
+      value.to_s.split(/[,\n]/).map(&:strip).reject(&:empty?)
+    end
+
+    def pf_flag_label(flag)
+      configured = PermissionForge.configuration.admin_session_flags || {}
+      configured[flag.to_s] || configured[flag.to_sym] ||
+        t("permission_forge.ui.flags.#{flag}", default: flag.to_s.humanize)
+    end
+
+    def pf_flag_phrase(flag)
+      t("permission_forge.ui.conditions.flags.#{flag}",
+        default: pf_ui('conditions.flag_generic', flag: pf_flag_label(flag)))
+    end
+
+    # --- record rules ---------------------------------------------------------
+
+    def pf_operator_label(operator)
+      t("permission_forge.ui.operators.#{operator}", default: operator.to_s.humanize.downcase)
+    end
+
+    # Labels along a rule's relationship path and the final field, e.g.
+    # ["Organization", "Members", "User"].
+    def pf_rule_field_labels(model_name, rule)
+      klass = model_name.to_s.safe_constantize
+      labels = rule.field_accessor_path.to_s.split('.').map do |assoc|
+        label = pf_attribute_label(klass, assoc)
+        klass = pf_association_class(klass, assoc)
+        label
+      end
+      labels << pf_attribute_label(klass, rule.field_name)
+    end
+
+    def pf_attribute_label(klass, attribute)
+      klass ? klass.human_attribute_name(attribute) : attribute.to_s.humanize
+    end
+
+    # Target class of an association, or nil (unknown or polymorphic).
+    def pf_association_class(klass, assoc)
+      reflection = klass&.reflect_on_association(assoc.to_sym)
+      begin
+        reflection&.klass
+      rescue StandardError
+        nil
+      end
+    end
+
+    def pf_rule_value_text(rule)
+      value = rule.field_value.to_s
+      return '…' if value.strip.empty? # builder preview before a value is entered
+      return pf_ui('rules.current_user') if value == CURRENT_USER
+
+      pf_rule_value_parts(rule.operator, value)
+    end
+
+    # List values as "a, b"; ranges as "a and b"; anything else verbatim.
+    def pf_rule_value_parts(operator, value)
+      return value.split(',').map(&:strip).join(', ') if LIST_OPERATORS.include?(operator)
+      return value.split(',', 2).map(&:strip).join(" #{pf_ui('rules.and')} ") if operator == 'between'
+
+      value
+    end
+
+    def pf_rule_nullable?(rule)
+      rule.include_nulls && NULLABLE_OPERATORS.include?(rule.operator)
+    end
+
+    # Plural model label. model_name.human(count: 2) falls back to the singular
+    # when the host app has no model translations, so pluralize English then.
+    def pf_resource_plural(name)
+      klass = name.to_s.safe_constantize
+      return name.to_s.demodulize.pluralize unless klass.respond_to?(:model_name)
+
+      plural = klass.model_name.human(count: 2)
+      plural == klass.model_name.human && I18n.locale.to_s == 'en' ? plural.pluralize : plural
+    end
+
+    def pf_resource_label(resource_or_name)
+      name = resource_or_name.respond_to?(:name) ? resource_or_name.name : resource_or_name.to_s
+      return resource_or_name.label if resource_or_name.respond_to?(:label) && resource_or_name.label.present?
+
+      klass = name.safe_constantize
+      klass.respond_to?(:model_name) ? klass.model_name.human : name.demodulize.titleize
+    end
+
+    # Token sentence: Only show [Customers] where [Owner] [is] [the current user], or Owner is empty
+    def pf_rule_sentence(rule, model_name = rule.resource&.name)
+      field = pf_rule_field_labels(model_name, rule).join(' › ')
+      sentence = safe_join(pf_rule_tokens(rule, model_name, field), ' ')
+      sentence = safe_join([sentence, content_tag(:span, ", #{pf_ui('rules.or_empty', field: field)}")]) if pf_rule_nullable?(rule)
+      content_tag(:p, sentence, class: 'pf-sentence')
+    end
+
+    def pf_rule_tokens(rule, model_name, field)
+      [
+        content_tag(:span, pf_ui('rules.only_show')),
+        content_tag(:span, pf_resource_plural(model_name), class: 'pf-token'),
+        content_tag(:span, pf_ui('rules.where')),
+        content_tag(:span, field, class: 'pf-token'),
+        content_tag(:span, pf_operator_label(rule.operator), class: 'pf-token'),
+        pf_rule_value_token(rule)
+      ].compact
+    end
+
+    def pf_rule_value_token(rule)
+      return if NO_VALUE_OPERATORS.include?(rule.operator)
+
+      content_tag(:span, pf_rule_value_text(rule), class: 'pf-token pf-token--value')
+    end
+
+    def pf_rule_text(rule, model_name = rule.resource&.name)
+      field = pf_rule_field_labels(model_name, rule).join(' › ')
+      text = "#{pf_ui('rules.only_show')} #{pf_resource_plural(model_name)} #{pf_ui('rules.where')} #{field} " \
+             "#{pf_operator_label(rule.operator)}"
+      text += " #{pf_rule_value_text(rule)}" unless NO_VALUE_OPERATORS.include?(rule.operator)
+      text += ", #{pf_ui('rules.or_empty', field: field)}" if pf_rule_nullable?(rule)
+      text
+    end
+
+    # Short form used in matrix cells: "Owner is the current user".
+    def pf_rule_summary(rule, model_name = rule.resource&.name)
+      field = pf_rule_field_labels(model_name, rule).join(' › ')
+      value = NO_VALUE_OPERATORS.include?(rule.operator) ? nil : pf_rule_value_text(rule)
+      [field, pf_operator_label(rule.operator), value].compact.join(' ')
+    end
+  end
+end

data/app/helpers/permission_forge/settings_helper.rb

@@ -0,0 +1,152 @@
+module PermissionForge
+  # Renders configuration values on the read-only Settings page by type.
+  # Secrets show only "Set"/"Not set"; code hooks only default/custom/not set.
+  #
+  # @api private
+  module SettingsHelper
+    SECONDS_UNITS = [[86_400, :days], [3600, :hours], [60, :minutes]].freeze
+
+    # Current-value renderer per setting type (private methods taking the row);
+    # any other type renders as a scalar.
+    VALUE_RENDERERS = {
+      bool: :pf_setting_bool, enum: :pf_setting_enum, num: :pf_setting_number,
+      list: :pf_setting_list, names: :pf_setting_list, map: :pf_setting_map,
+      secret: :pf_setting_secret, hook: :pf_setting_hook
+    }.freeze
+
+    # Default-value text per setting type; any other type renders as a scalar.
+    DEFAULT_RENDERERS = {
+      bool: :pf_setting_default_bool, secret: :pf_setting_default_secret, hook: :pf_setting_default_hook,
+      list: :pf_setting_default_list, names: :pf_setting_default_list, map: :pf_setting_default_list,
+      num: :pf_setting_default_number
+    }.freeze
+
+    def pf_setting_value(row)
+      send(VALUE_RENDERERS.fetch(row.type, :pf_setting_scalar), row)
+    end
+
+    def pf_setting_default(row)
+      send(DEFAULT_RENDERERS.fetch(row.type, :pf_setting_default_scalar), row)
+    end
+
+    # Compact "key = value" form for the health summary.
+    def pf_setting_inline_value(row)
+      case row.type
+      when :secret then row.value ? t('permission_forge.settings.values.set') : t('permission_forge.settings.values.not_set')
+      when :hook then t("permission_forge.settings.values.hook_#{row.hook_state}")
+      when :enum then ":#{row.value}"
+      else row.value.inspect
+      end
+    end
+
+    private
+
+    def pf_setting_bool(row)
+      if row.value
+        content_tag(:span, "● #{t('permission_forge.settings.values.on')}", class: 'pf-pill pf-pill--on')
+      else
+        content_tag(:span, "○ #{t('permission_forge.settings.values.off')}", class: 'pf-pill')
+      end
+    end
+
+    def pf_setting_enum(row)
+      options = Array(row.definition.options).map(&:to_s)
+      options << row.value unless options.include?(row.value.to_s)
+      pills = options.map do |opt|
+        current = opt == row.value.to_s
+        content_tag(:span, opt, class: "pf-pill pf-pill--opt#{' pf-pill--current' if current}", 'aria-current': (current ? 'true' : nil))
+      end
+      content_tag(:span, safe_join(pills, ' '), class: 'pf-row pf-row--tight')
+    end
+
+    def pf_setting_number(row)
+      value = row.value
+      return content_tag(:span, t('permission_forge.settings.values.nil'), class: 'pf-text-3') if value.nil?
+
+      content_tag(:span, pf_setting_number_text(value, row.definition.unit), class: 'pf-tabular pf-fw-600')
+    end
+
+    def pf_setting_number_text(value, unit)
+      return t('permission_forge.settings.values.nil') if value.nil?
+      return "#{value} #{t("permission_forge.settings.units.#{unit}", count: value)}" unless unit == :seconds
+
+      human = SECONDS_UNITS.find { |secs, _| (value % secs).zero? && value >= secs }
+      text = "#{value} s"
+      human ? "#{text} (#{t("permission_forge.settings.units.#{human.last}", count: value / human.first)})" : text
+    end
+
+    def pf_setting_list(row)
+      value = row.value
+      return content_tag(:span, pf_setting_nil_text(row), class: 'pf-text-3') if value.nil?
+      return content_tag(:span, t('permission_forge.settings.values.empty'), class: 'pf-text-3') if value.empty?
+
+      content_tag(:span, safe_join(value.map { |v| content_tag(:code, v, class: 'pf-pill pf-pill--opt') }, ' '),
+                  class: 'pf-row pf-row--tight')
+    end
+
+    def pf_setting_map(row)
+      value = row.value
+      return content_tag(:span, t('permission_forge.settings.values.empty'), class: 'pf-text-3') if value.blank?
+
+      content_tag(:span, safe_join(value.map { |k, v| content_tag(:span, "#{k} → #{v}") }), class: 'pf-map')
+    end
+
+    def pf_setting_secret(row)
+      if row.value
+        content_tag(:span, "● #{t('permission_forge.settings.values.set')}", class: 'pf-pill pf-pill--on')
+      else
+        content_tag(:span, "○ #{t('permission_forge.settings.values.not_set')} · #{t('permission_forge.settings.values.never_displayed')}",
+                    class: 'pf-pill')
+      end
+    end
+
+    def pf_setting_hook(row)
+      state = row.hook_state
+      css = state == :custom ? 'pf-pill pf-pill--on' : 'pf-pill'
+      content_tag(:span, t("permission_forge.settings.values.hook_#{state}"), class: css)
+    end
+
+    def pf_setting_scalar(row)
+      value = row.value
+      return content_tag(:span, pf_setting_nil_text(row), class: 'pf-text-3') if value.nil?
+
+      content_tag(:code, value.to_s, class: 'pf-mono')
+    end
+
+    def pf_setting_default_bool(row)
+      row.default ? t('permission_forge.settings.values.on') : t('permission_forge.settings.values.off')
+    end
+
+    def pf_setting_default_secret(_row)
+      t('permission_forge.settings.values.not_set')
+    end
+
+    def pf_setting_default_hook(row)
+      t("permission_forge.settings.values.hook_#{row.default}")
+    end
+
+    def pf_setting_default_list(row)
+      values = Array(row.default)
+      return t('permission_forge.settings.values.empty') if values.empty?
+
+      values.map { |v| Array(v).join(' → ') }.join(', ')
+    end
+
+    def pf_setting_default_number(row)
+      pf_setting_number_text(row.default, row.definition.unit)
+    end
+
+    def pf_setting_default_scalar(row)
+      value = row.default
+      value.nil? ? pf_setting_nil_text(row) : value.to_s
+    end
+
+    def pf_setting_nil_text(row)
+      case row.definition.nil_label
+      when :disabled then t('permission_forge.settings.values.disabled')
+      when :default then t('permission_forge.settings.values.hook_default')
+      else t('permission_forge.settings.values.nil')
+      end
+    end
+  end
+end

data/app/helpers/permission_forge/ui_helper.rb

@@ -0,0 +1,184 @@
+module PermissionForge
+  # Building blocks shared by every admin screen: assets, text, dates, state
+  # cells, banners, footers, tabs, frames. Badges/chips live in BadgesHelper,
+  # people/assignment cells in PeopleHelper.
+  # Every class is pf- prefixed; no inline styles (strict-CSP friendly).
+  #
+  # @api private
+  module UiHelper
+    STATE_GLYPHS = { granted: '✓', blocked: '⊘', none: '–' }.freeze
+
+    # --- assets ---------------------------------------------------------------
+
+    def pf_asset_url(file)
+      permission_forge.pf_asset_path(file: file, v: PermissionForge::AssetsController.digest(file))
+    end
+
+    # ` nonce="…"` when the host app runs a CSP with nonces, else nothing.
+    def pf_nonce_attribute(_kind = :script)
+      nonce = respond_to?(:content_security_policy_nonce) ? content_security_policy_nonce : nil
+      nonce.present? ? tag.attributes(nonce: nonce) : ''
+    rescue StandardError
+      ''
+    end
+
+    def pf_lock_icon
+      tag.svg(class: 'pf-lock', viewBox: '0 0 16 16', fill: 'none', stroke: 'currentColor', 'stroke-width': '1.6',
+              'aria-hidden': 'true', focusable: 'false') do
+        safe_join([tag.rect(x: 3, y: 7, width: 10, height: 7, rx: 1.5), tag.path(d: 'M5.5 7V5a2.5 2.5 0 0 1 5 0v2')])
+      end
+    end
+
+    # The attributes, only when the condition holds: `<input <%= pf_attrs_when(error, aria: { invalid: true }) %>>`.
+    # Built by `tag.attributes`, so every value is escaped; nothing is marked safe by hand.
+    def pf_attrs_when(condition, **attributes)
+      condition ? tag.attributes(**attributes) : ''
+    end
+
+    # --- text helpers ---------------------------------------------------------
+
+    def pf_ui(key, **)
+      t("permission_forge.ui.#{key}", **)
+    end
+
+    def pf_people_text(count)
+      pf_ui('people_count', count: count)
+    end
+
+    MONTH_KEYS = %w[jan feb mar apr may jun jul aug sep oct nov dec].freeze
+
+    # "12 Mar 2026" / "12 Mar" using the engine's own month names (no
+    # dependency on rails-i18n being installed in the host app).
+    def pf_date(value, year: true)
+      return pf_ui('dates.never') if value.nil?
+
+      date = value.to_date
+      month = t("permission_forge.ui.months.#{MONTH_KEYS[date.month - 1]}")
+      year ? "#{date.day} #{month} #{date.year}" : "#{date.day} #{month}"
+    end
+
+    def pf_datetime(value)
+      return pf_ui('dates.never') if value.nil?
+
+      "#{pf_date(value)} · #{value.in_time_zone.strftime('%H:%M')}"
+    end
+
+    # "today", "yesterday", "3 days ago", or a date for anything older than 30 days.
+    def pf_relative(value)
+      return pf_ui('dates.never') if value.nil?
+
+      days = (Time.zone.today - value.to_date).to_i
+      return pf_ui('dates.today') if days <= 0
+      return pf_ui('dates.yesterday') if days == 1
+      return pf_ui('dates.days_ago', count: days) if days < 30
+
+      pf_date(value)
+    end
+
+    def pf_hour(hour)
+      format('%02d:00', hour.to_i)
+    end
+
+    # Read-only state cell (effective access grid, across-sets lists).
+    def pf_state_cell(state, aria:, href: nil, why: nil, current: false)
+      state = state.to_sym
+      label = pf_ui("states.#{state}")
+      content = safe_join([content_tag(:span, STATE_GLYPHS.fetch(state), class: 'pf-cell__glyph', 'aria-hidden': true),
+                           content_tag(:span, label)], ' ')
+      opts = { class: "pf-state pf-state--#{state}", 'aria-label': "#{aria}: #{label}" }
+      opts[:'aria-current'] = 'true' if current
+      opts[:data] = { pf_why: why } if why
+      href ? link_to(content, href, opts) : content_tag(:span, content, opts)
+    end
+
+    # --- banners & footers ----------------------------------------------------
+
+    def pf_help_banner(key, term:, text:)
+      return unless pf_help_visible?(key)
+
+      render 'permission_forge/shared/help_banner', key: key, term: term, text: text
+    end
+
+    def pf_audit_footer(record, prefix: nil)
+      render 'permission_forge/shared/audit_footer', record: record, prefix: prefix
+    end
+
+    def pf_tech_details(record, extras: {}, &block)
+      render 'permission_forge/shared/tech_details', record: record, extras: extras,
+                                                     extra_html: (capture(&block) if block)
+    end
+
+    def pf_setting_path(key)
+      permission_forge.settings_path(focus: key, anchor: "set-#{key}")
+    end
+
+    def pf_setting_link(key, text = nil)
+      link_to(text || pf_ui('open_setting'), pf_setting_path(key), class: 'pf-fs-12')
+    end
+
+    # Tab link with ARIA state, plus count.
+    def pf_tab(label, href, selected:, count: nil)
+      text = count.nil? ? label : "#{label} (#{count})"
+      link_to(text, href, class: 'pf-tab', role: 'tab', 'aria-selected': selected.to_s)
+    end
+
+    def pf_filter_chip(label, href, selected:, count: nil)
+      body = [content_tag(:span, label)]
+      body << content_tag(:span, count, class: 'pf-filter__count') unless count.nil?
+      link_to(safe_join(body), href, class: 'pf-filter', 'aria-current': (selected ? 'true' : nil))
+    end
+
+    # A section heading inside a drawer or confirmation page. The page's own title is the h1 when
+    # the page stands alone and an h2 inside the dialog (the page behind has the h1), so a section
+    # is one level below that.
+    def pf_section_heading(text, id: nil)
+      content_tag(pf_fragment? ? :h3 : :h2, text, class: 'pf-h3', id: id)
+    end
+
+    # Breadcrumb from [[label, path], ..., label]
+    def pf_breadcrumb(*items)
+      parts = items.map do |item|
+        item.is_a?(Array) ? link_to(item.first, item.last) : content_tag(:span, item, 'aria-current': 'page')
+      end
+      content_tag(:nav, safe_join(parts, content_tag(:span, '/', 'aria-hidden': true)),
+                  class: 'pf-breadcrumb', 'aria-label': pf_ui('breadcrumb'))
+    end
+
+    # Re-emits nested params as hidden inputs (the review step re-posts the
+    # exact edits that were reviewed).
+    def pf_hidden_params(prefix, value)
+      value = value.to_unsafe_h if value.respond_to?(:to_unsafe_h)
+      case value
+      when Hash
+        safe_join(value.map { |k, v| pf_hidden_params("#{prefix}[#{k}]", v) })
+      when Array
+        safe_join(value.map { |v| pf_hidden_params("#{prefix}[]", v) })
+      when nil then safe_join([])
+      else
+        tag.input(type: 'hidden', name: prefix, value: value.to_s)
+      end
+    end
+
+    # Drawer / dialog frames. The body is captured here (not via `render
+    # layout:`) so lazy t('.key') lookups inside it resolve against the
+    # calling view, not the frame partial.
+    def pf_sheet_frame(locals = {}, &)
+      render 'permission_forge/shared/sheet_frame', **locals, body: capture(&)
+    end
+
+    def pf_dialog_frame(locals = {}, &)
+      render 'permission_forge/shared/dialog_frame', **locals, body: capture(&)
+    end
+
+    # Modal/drawer link: real page without JS, loaded into <dialog> with JS.
+    def pf_modal_link(text = nil, href = nil, kind: 'dialog', **opts, &block)
+      if block
+        opts = (href.is_a?(Hash) ? href : {}).merge(opts)
+        href = text
+        text = capture(&block)
+      end
+      opts[:data] = (opts[:data] || {}).merge(pf_modal: kind)
+      link_to(text, href, opts)
+    end
+  end
+end

data/app/models/permission_forge/audit_event.rb

@@ -0,0 +1,159 @@
+module PermissionForge
+  # One audit event: who did what, to what, when, and what it was before.
+  # Written by PermissionForge::Audit only; insert-only once persisted
+  # (update, destroy and delete raise). The purge service deletes through a
+  # relation (`delete_all`), past the retention period, and records that.
+  #
+  # `data` is JSON text in the database and a Hash with string keys here:
+  # { "changes" => { attr => [from, to] } } on an update, { "snapshot" => {...} }
+  # on a create or destroy, plus event-specific keys.
+  #
+  # @api public
+  class AuditEvent < ActiveRecord::Base
+    # The table name, with the configured prefix (read on every call, so a prefix set at runtime applies).
+    def self.table_name = "#{PermissionForge.table_name_prefix}audit_events"
+
+    include PermissionForge::Concerns::HasTenantScoping
+
+    # A system event of a cross-tenant task (a rake clean-up, a report) has
+    # no tenant; it is visible while none is set, like any untenanted row.
+    def self.tenant_scoping_options
+      { optional: true }
+    end
+
+    CATEGORIES = PermissionForge::Audit::EventCatalog::CATEGORIES
+    ACTOR_TYPES = PermissionForge::Audit::Actor::TYPES
+    SOURCES = PermissionForge::Audit::Source::SOURCES
+
+    # JSON text that works on SQLite, PostgreSQL and MySQL alike; times are
+    # written in ISO 8601 (ActiveSupport::JSON), nothing reads as nil.
+    #
+    # @api private
+    class DataCoder
+      def self.dump(value)
+        ActiveSupport::JSON.encode(value.nil? ? {} : value)
+      end
+
+      def self.load(value)
+        value.blank? ? {} : ActiveSupport::JSON.decode(value)
+      end
+    end
+
+    serialize :data, coder: DataCoder
+
+    # The tenant of the record the event is about. acts_as_tenant writes the
+    # ambient tenant to every new row (before_validation); an event follows
+    # its subject instead (before_create runs after validation).
+    attr_accessor :subject_tenant_id
+
+    before_validation :assign_uuid, on: :create
+    before_create :follow_subject_tenant
+
+    validates :uuid, :event, :category, :actor_type, :source, :occurred_at, presence: true
+    validates :category, inclusion: { in: CATEGORIES }
+    validates :actor_type, inclusion: { in: ACTOR_TYPES }
+    validates :source, inclusion: { in: SOURCES }
+
+    scope :newest_first, -> { order(occurred_at: :desc, id: :desc) }
+    scope :for_record, ->(record) { where(record_type: record.class.base_class.name, record_id: record.id.to_s) }
+    scope :for_subject, ->(user_id) { where(subject_user_id: user_id.to_s) }
+    scope :between, ->(from, to) { where(occurred_at: from..to) }
+
+    apply_tenant_scoping! # from the configuration, as the class loads (HasTenantScoping)
+
+    # The tenant column of the events: nil when tenancy is off or the table
+    # has no such column (installed before tenancy), where events cannot be
+    # told apart by tenant.
+    #
+    # @return [Symbol, nil]
+    def self.tenant_column
+      column = PermissionForge.configuration.resolved_tenant_column
+      column if column && column_names.include?(column.to_s)
+    end
+
+    # The events of one tenant, on the relation it is called on; every event
+    # when there is no tenant id or no tenant column. Used by the services
+    # that work past the default scope (`unscoped`): erasure, the purge.
+    #
+    # @param tenant_id [Object, nil]
+    # @return [ActiveRecord::Relation]
+    def self.in_tenant(tenant_id)
+      column = tenant_column
+      tenant_id && column ? where(column => tenant_id) : all
+    end
+
+    # The one write (Audit::Recorder). Built under `unscoped`: instantiating
+    # a model that has a default scope evaluates it (Rails fills in scope
+    # attributes), and acts_as_tenant's raises under require_tenant when no
+    # tenant is ambient — a job, a rake task. The tenant comes from the
+    # subject (subject_tenant_id), else from the ambient tenant.
+    #
+    # @param attributes [Hash] columns plus subject_tenant_id:
+    # @return [AuditEvent] persisted
+    # @raise [ActiveRecord::RecordInvalid, ActiveRecord::StatementInvalid]
+    def self.store!(attributes)
+      event = unscoped { new(attributes) }
+      event.save!
+      event
+    end
+
+    # Insert-only. On a persisted event these raise ActiveRecord::ReadOnlyRecord:
+    # save, save!, update, update!, update_attribute, update_column(s), touch,
+    # toggle!, increment!, decrement! (through update_counters), destroy,
+    # destroy!, delete, becomes + save, Class.update(id), Class.destroy(id),
+    # Class.update_counters and relation.update_counters, Class.upsert and Class.upsert_all,
+    # relation.destroy_all. Still reachable, on purpose: relation.update_all
+    # (the erasure service clears label snapshots of an erased person — the
+    # one sanctioned mutation, recorded itself), relation.delete_all and
+    # Class.delete(id) (the purge service, past the retention period). Protect
+    # the table at the database level too (REVOKE UPDATE, DELETE).
+    def readonly?
+      persisted?
+    end
+
+    # `delete` skips the read-only check Rails makes elsewhere.
+    def delete
+      raise ActiveRecord::ReadOnlyRecord, "#{self.class} is marked as readonly" if persisted?
+
+      super
+    end
+
+    # upsert / upsert_all would rewrite an existing row through its uuid, and
+    # update_counters is how increment! / decrement! write, past the
+    # instance (through the class up to Rails 8.1, through a relation —
+    # `unscoped.where(id:).update_counters` — on Rails main). Class methods
+    # on Rails 7.1; Relation methods the class delegates to from 7.2 on —
+    # refused in both places.
+    #
+    # @api private
+    module InsertOnly
+      def update_counters(*, **)
+        raise ActiveRecord::ReadOnlyRecord, 'PermissionForge::AuditEvent is insert-only: counters cannot be updated'
+      end
+
+      def upsert_all(*, **)
+        raise ActiveRecord::ReadOnlyRecord, 'PermissionForge::AuditEvent is insert-only: rows cannot be upserted'
+      end
+
+      def upsert(*, **)
+        raise ActiveRecord::ReadOnlyRecord, 'PermissionForge::AuditEvent is insert-only: rows cannot be upserted'
+      end
+    end
+    singleton_class.prepend(InsertOnly)
+    relation_delegate_class(ActiveRecord::Relation).prepend(InsertOnly)
+
+    private
+
+    # No uniqueness validation (a query per insert): the unique index holds.
+    def assign_uuid
+      self.uuid = PermissionForge.configuration.uuid_generator.call if uuid.blank?
+    end
+
+    def follow_subject_tenant
+      column = PermissionForge.configuration.resolved_tenant_column
+      return if subject_tenant_id.nil? || column.nil? || !has_attribute?(column)
+
+      write_attribute(column, subject_tenant_id)
+    end
+  end
+end