permission_forge 0.14.1

data/lib/permission_forge/audit/context.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # The per-request (per-thread, or per-fiber under Rails' fiber isolation:
+    # ExecutionState) store of what every event recorded inside a block
+    # carries: the actor, the source, the request id and IP, a reason, and a
+    # correlation id.
+    #
+    #   Audit::Context.with(source: 'admin_ui', request_id: request.request_id, ip: request.remote_ip) do
+    #     ...
+    #   end
+    #
+    # Blocks nest: an inner value overrides the outer one for the block, a
+    # nil leaves the outer one in place, and the outer context is restored
+    # when the block ends — also when it raises. Nothing is ever set outside
+    # a block, so nothing can leak to the next request; as a second line of
+    # defence the end of every executor run empties a context that was empty
+    # when the run started (ExecutionState::RunHook): a request or a job ends
+    # with none, and a block that wraps the run keeps its own
+    # (with_audit_actor around an inline job keeps its actor after the job).
+    #
+    # @api public
+    module Context
+      KEY = :pf_audit_context
+      TRANSACTION_KEY = :pf_audit_transaction_correlation
+      SLOTS = %i[actor source request_id ip reason correlation_id].freeze
+      EMPTY = {}.freeze
+
+      class << self
+        # @return [Hash] frozen; empty when nothing is set
+        def current
+          state[KEY] || EMPTY
+        end
+
+        # @param slot [Symbol] one of SLOTS
+        # @return [Object, nil] the value of that slot in the current context
+        def [](slot)
+          current[slot]
+        end
+
+        # @param slots [Hash] actor: (an Actor, a user or a Hash), source:,
+        #   request_id:, ip:, reason:, correlation_id:
+        # @return the value of the block
+        # @raise [ArgumentError] for an unknown slot, actor type or source
+        def with(**slots, &)
+          ExecutionState.with(KEY, current.merge(normalize(slots)).freeze, &)
+        end
+
+        # Empties the context of this thread (tests, the end of a request).
+        def reset!
+          state.delete(KEY)
+          state.delete(TRANSACTION_KEY)
+        end
+
+        # One id per outermost open transaction (OpenTransaction), minted the
+        # first time an event asks for it inside that transaction: a cascade
+        # delete or a Review-and-save then shares one id.
+        #
+        # @return [String, nil] nil when no transaction is open
+        def transaction_correlation_id
+          transaction = OpenTransaction.current
+          return unless transaction
+
+          handle, id = state[TRANSACTION_KEY]
+          return id if handle && !handle.finished?
+
+          id = Audit.new_id
+          state[TRANSACTION_KEY] = [transaction, id]
+          id
+        end
+
+        private
+
+        def state
+          ExecutionState
+        end
+
+        def normalize(slots)
+          slots.each_with_object({}) do |(slot, value), out|
+            raise ArgumentError, "unknown audit context slot #{slot.inspect} (slots: #{SLOTS.join(', ')})" unless SLOTS.include?(slot)
+            next if value.nil?
+
+            out[slot] = cast(slot, value)
+          end
+        end
+
+        def cast(slot, value)
+          case slot
+          when :actor then Actor.coerce(value)
+          when :source then Source.validate!(value)
+          else value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/detached.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # Records an event that must outlive the transaction it was noticed in:
+    # a failed sign-in, a refused change. Those are evidence of something
+    # that did NOT happen, so a rollback of whatever the caller had open must
+    # not take them with it.
+    #
+    #   Audit::Detached.record('admin.lock_refused', record: set)
+    #
+    # No transaction open (OpenTransaction): written at once, like
+    # Audit.record. Inside one: written once that transaction has ended,
+    # committed or rolled back (a savepoint that rolls back hands it to the
+    # transaction around it). Who, where, the request and the reason are
+    # taken at the moment of the call.
+    #
+    # @api private
+    module Detached
+      class << self
+        # @param event [String] an admin, change or system event of the catalogue
+        # @param payload [Hash] see Audit::Recorder
+        # @return [AuditEvent, nil] the stored event; nil when it was deferred
+        #   or auditing is off
+        def record(event, **payload)
+          transaction = OpenTransaction.current(PermissionForge::AuditEvent)
+          return Audit.record(event, **payload) unless transaction
+
+          defer(transaction, event, pinned(payload))
+          nil
+        end
+
+        private
+
+        # Who, where and the tenant of the moment of the call: a tenant
+        # switched (or lost) before the transaction ends does not move it.
+        def pinned(payload)
+          { actor: Actor.current, source: Source.current, ambient_tenant_id: PermissionForge.ambient_tenant_id }.merge(payload)
+        end
+
+        # OpenTransaction#after_end: once, when the outermost transaction has
+        # ended either way (a savepoint that rolls back hands it on).
+        def defer(transaction, event, payload)
+          context = Context.current
+          transaction.after_end { Context.with(**context) { write_later(event, payload) } }
+        end
+
+        # Runs from Rails' commit or rollback of the caller's transaction:
+        # raising there would replace the caller's own exception, or fail a
+        # transaction that has already committed. Nothing can be kept from
+        # happening any more, so a failure is reported (or logged) and never
+        # raised, whatever the strategy.
+        def write_later(event, payload)
+          Audit.record(event, **payload)
+        rescue StandardError => e
+          strategy = PermissionForge.configuration.audit_hook_failure_strategy
+          Failure.handle(e, strategy: strategy == :raise ? :report : strategy, operation: :store, event: event)
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/event_catalog.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # The registry of audit events: name → category, and for runtime (access)
+    # events the group that `config.audit_runtime_events` switches storage on
+    # for. Adding an event is one `register` call; an event that is not here
+    # cannot be recorded or published (a typo fails loudly, not silently).
+    #
+    # Notification name: "<event>.permission_forge".
+    #
+    # @api public
+    class EventCatalog
+      # @api private
+      class UnknownEventError < ArgumentError; end
+
+      # `notification` is computed once: Audit.instrument asks for it on hot paths.
+      #
+      # @api private
+      Entry = Struct.new(:name, :category, :runtime_group, :notification, keyword_init: true) do
+        # Runtime events are published by Audit.instrument and stored per group.
+        def runtime? = category == 'access'
+      end
+
+      CATEGORIES = %w[change admin system access].freeze
+      RUNTIME_GROUPS = PermissionForge::Configuration::AuditSettings::RUNTIME_GROUPS
+
+      REGISTRY_MUTEX = Mutex.new
+
+      @entries = {}
+
+      class << self
+        # @param name [String, Symbol] e.g. 'assignment.revoked'
+        # @param category [String] change, admin, system or access
+        # @param runtime_group [Symbol, nil] required for access events, refused
+        #   for the others
+        # @return [Entry]
+        def register(name, category:, runtime_group: nil)
+          entry = Entry.new(name: name.to_s, category: category.to_s, runtime_group: runtime_group&.to_sym,
+                            notification: "#{name}.permission_forge").freeze
+          validate!(entry)
+          REGISTRY_MUTEX.synchronize { @entries[entry.name] = entry }
+        end
+
+        # Removes an event from the catalog (for tests that register their own).
+        # @param name [String, Symbol]
+        def unregister(name)
+          REGISTRY_MUTEX.synchronize { @entries.delete(name.to_s) }
+        end
+
+        # @raise [UnknownEventError] for a name that is not registered
+        def fetch(name)
+          @entries[name.to_s] || raise(UnknownEventError, "unknown audit event #{name.inspect}: register it with " \
+                                                          'PermissionForge::Audit::EventCatalog.register')
+        end
+
+        def registered?(name)
+          @entries.key?(name.to_s)
+        end
+
+        # @return [Hash{String => Entry}] a copy
+        def entries
+          @entries.dup.freeze
+        end
+
+        # @return [Array<String>] the names of every registered event
+        def names
+          @entries.keys
+        end
+
+        private
+
+        def validate!(entry)
+          raise ArgumentError, "audit event category must be one of #{CATEGORIES.join(', ')} (got #{entry.category.inspect})" \
+            unless CATEGORIES.include?(entry.category)
+
+          if entry.runtime?
+            raise ArgumentError, "access event #{entry.name} needs a runtime group (#{RUNTIME_GROUPS.join(', ')})" \
+              unless RUNTIME_GROUPS.include?(entry.runtime_group)
+          elsif entry.runtime_group
+            raise ArgumentError, "#{entry.name} is a #{entry.category} event: only access events have a runtime group"
+          end
+        end
+      end
+
+      # --- the catalogue of the first release ------------------------------------------
+
+      %w[permission_set resource resource_field resource_action permission_set_rule permission_set_group]
+        .product(%w[created updated destroyed]).each { |model, verb| register("#{model}.#{verb}", category: 'change') }
+
+      %w[permission_set.cloned permission_set_group.cloned assignment.granted assignment.changed assignment.revoked assignment.reviewed
+         group_membership.added group_membership.changed group_membership.removed field.sensitive_acknowledged]
+        .each { |name| register(name, category: 'change') }
+
+      %w[erasure.performed consent.withdrawn cleanup.expired_assignments cache.cleared audit.purged audit.settings_observed
+         report.generated].each { |name| register(name, category: 'system') }
+
+      %w[admin.effective_access_viewed audit.viewed audit.exported admin.auth_failed api.auth_failed admin.lock_refused]
+        .each { |name| register(name, category: 'admin') }
+
+      {
+        'access.denied' => :denied, 'action.denied' => :denied,
+        'rule.bypassed' => :bypass, 'query.unscoped' => :bypass,
+        'field.access' => :field_read,
+        'params.filtered' => :params_filtered, 'write.masked_skipped' => :params_filtered,
+        'permissions.rebuilt' => :cache, 'permissions.invalidated' => :cache
+      }.each { |name, group| register(name, category: 'access', runtime_group: group) }
+    end
+  end
+end

data/lib/permission_forge/audit/event_query.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # Turns filter parameters (the API endpoint, the HTML audit log) into a
+    # relation of audit events. Knows nothing of controllers.
+    # Every value reaches the database as a bound value through `where`
+    # (never interpolated); a value that is not a plain string, a timestamp
+    # that is not ISO 8601, or a name that is not in the catalogue is an
+    # error naming the parameter, not a silently empty result.
+    #
+    # @api private
+    class EventQuery
+      class Invalid < StandardError
+        attr_reader :errors
+
+        # @param errors [Hash{Symbol => Array<String>}] parameter => messages
+        def initialize(errors)
+          @errors = errors
+          super(errors.inspect)
+        end
+      end
+
+      DATE_ONLY = /\A(\d{4})-(\d{2})-(\d{2})\z/
+      TIMESTAMP = /\A(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(\.\d{1,9})?)?(Z|[+-]\d{2}(?::?\d{2})?)?\z/
+
+      # @param params [ActionController::Parameters, Hash] from to event category actor_type actor_id
+      #   subject_user_id permission_set record_type record_id correlation_id (others are ignored)
+      # @param scope [ActiveRecord::Relation] the events visible to the caller
+      # @return [ActiveRecord::Relation] newest first
+      # @raise [Invalid] with #errors, parameter => messages
+      def self.call(params, scope: PermissionForge::AuditEvent.all)
+        new(params, scope).call
+      end
+
+      def initialize(params, scope)
+        @params = params
+        @scope = scope
+        @errors = Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      # @return [ActiveRecord::Relation] newest first
+      # @raise [Invalid]
+      def call
+        filter_times
+        filter_events
+        filter_inclusion(:category, PermissionForge::AuditEvent::CATEGORIES)
+        filter_inclusion(:actor_type, PermissionForge::AuditEvent::ACTOR_TYPES)
+        %i[actor_id subject_user_id correlation_id record_type].each { |name| filter_equal(name) }
+        filter_permission_set
+        filter_record
+        raise Invalid, @errors.to_h if @errors.any?
+
+        @scope.newest_first
+      end
+
+      private
+
+      def invalid(name)
+        problem(name, :invalid)
+      end
+
+      # Rails' own validation messages (errors.messages.<kind>), like the
+      # 422 bodies of the other endpoints.
+      def problem(name, kind)
+        @errors[name] << I18n.t("errors.messages.#{kind}")
+      end
+
+      # A parameter's value as a String, nil when absent; an array or hash
+      # (`?actor_id[]=1`, `?actor_id[a]=1`) is invalid.
+      def value(name)
+        raw = @params[name]
+        return nil if raw.nil? || raw == ''
+        return raw if plain?(raw)
+
+        invalid(name)
+        nil
+      end
+
+      def plain?(raw)
+        raw.is_a?(String) && !raw.include?("\0")
+      end
+
+      def filter_equal(name)
+        found = value(name)
+        @scope = @scope.where(name => found) if found
+      end
+
+      def filter_inclusion(name, allowed)
+        found = value(name)
+        return unless found
+
+        allowed.include?(found) ? @scope = @scope.where(name => found) : invalid(name)
+      end
+
+      def filter_events
+        raw = @params[:event]
+        return if raw.nil? || raw == ''
+
+        names = event_names(raw)
+        return invalid(:event) unless names&.all? { |name| PermissionForge::Audit::EventCatalog.registered?(name) }
+
+        @scope = @scope.where(event: names.uniq)
+      end
+
+      # nil when anything in the list is not a plain, non-blank string.
+      def event_names(raw)
+        items = Array.wrap(raw)
+        return nil unless items.all? { |item| plain?(item) }
+
+        names = items.flat_map { |item| item.split(',').map(&:strip) }
+        names.any?(&:blank?) ? nil : names
+      end
+
+      def filter_times
+        from = parse_time(:from, end_of_day: false)
+        to = parse_time(:to, end_of_day: true)
+        @scope = @scope.where(PermissionForge::AuditEvent.arel_table[:occurred_at].gteq(from)) if from
+        @scope = @scope.where(PermissionForge::AuditEvent.arel_table[:occurred_at].lteq(to)) if to
+      end
+
+      # ISO 8601, read in UTC unless the text carries an offset; an impossible
+      # calendar date or clock time is invalid (never rolled over).
+      def parse_time(name, end_of_day:)
+        text = value(name)
+        return nil unless text
+
+        time = DATE_ONLY.match(text) ? parse_day(text, end_of_day) : parse_timestamp(text)
+        invalid(name) unless time
+        time
+      end
+
+      def parse_day(text, end_of_day)
+        year, month, day = text.scan(/\d+/).map(&:to_i)
+        return nil unless year.positive? && Date.valid_date?(year, month, day)
+
+        moment = Time.utc(year, month, day)
+        end_of_day ? moment.end_of_day : moment
+      end
+
+      def parse_timestamp(text)
+        match = TIMESTAMP.match(text)
+        offset = match && utc_offset(match[8])
+        return nil unless offset
+
+        year, month, day, hour, minute = match.captures.first(5).map(&:to_i)
+        second = Rational("#{match[6] || 0}#{match[7]}")
+        return nil unless real_moment?([year, month, day], hour, minute, second)
+
+        Time.new(year, month, day, hour, minute, second, offset)
+      end
+
+      def real_moment?(date, hour, minute, second)
+        date.first.positive? && Date.valid_date?(*date) && hour < 24 && minute < 60 && second < 60
+      end
+
+      # "UTC" for Z or no offset; "+HH:MM" otherwise; nil when out of range.
+      def utc_offset(text)
+        return 'UTC' if text.nil? || text == 'Z'
+
+        sign, hours, minutes = text.match(/([+-])(\d{2}):?(\d{2})?/).captures
+        return nil unless hours.to_i < 24 && minutes.to_i < 60
+
+        format('%<sign>s%<hours>s:%<minutes>s', sign: sign, hours: hours, minutes: minutes || '00')
+      end
+
+      # A numeric value is the id, anything else the uuid: one indexed column each.
+      def filter_permission_set
+        found = value(:permission_set)
+        return unless found
+
+        @scope = if found.match?(/\A\d{1,18}\z/)
+                   @scope.where(permission_set_id: found.to_i)
+                 else
+                   @scope.where(permission_set_uuid: found)
+                 end
+      end
+
+      # record_type alone, or with record_id or record_uuid (each one column, so
+      # (record_type, record_id, occurred_at) serves the first). Either id needs
+      # record_type.
+      def filter_record
+        ids = { record_id: value(:record_id), record_uuid: value(:record_uuid) }.compact
+        return if ids.empty?
+
+        return problem(:record_type, :blank) if @params[:record_type].blank?
+
+        @scope = @scope.where(ids)
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/failure.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # What happens when an audit write, a notification subscriber or a hook
+    # fails, per the configured strategy:
+    #   :raise  — the error propagates (a change event then rolls the change back)
+    #   :report — logged at error level and handed to Rails.error as handled;
+    #             execution continues
+    #   :log    — logged only
+    #
+    # @api private
+    module Failure
+      SOURCE = 'permission_forge.audit'
+
+      class << self
+        # @param error [Exception]
+        # @param strategy [Symbol] :raise, :report or :log
+        # @param operation [Symbol] :store or :publish
+        # @param details [Hash] event: and anything else worth knowing
+        # @return [nil]
+        def handle(error, strategy:, operation:, **details)
+          raise error if strategy == :raise
+
+          log(error, operation, details)
+          report(error, operation, details) if strategy == :report
+          nil
+        end
+
+        private
+
+        def log(error, operation, details)
+          return unless defined?(Rails) && Rails.logger
+
+          what = details.map { |key, value| "#{key}=#{value}" }.join(' ')
+          Rails.logger.error("[PermissionForge] audit #{operation} failed (#{what}) — #{error.class}: #{error.message}")
+        end
+
+        def report(error, operation, details)
+          return unless defined?(Rails) && Rails.respond_to?(:error)
+
+          Rails.error.report(error, handled: true, severity: :error, source: SOURCE, context: { operation: operation, **details })
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/field_access.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # field.access — one event per record read, listing the fields that were
+    # hidden, masked, unconfigured or bypassed (no user), and the fields read
+    # in the clear (`passed_fields`, with their count in `passed`).
+    #
+    # A read is the outermost guarded access to one record: a getter, `[]` /
+    # `read_attribute`, `attributes`, `serializable_hash` (`as_json`,
+    # `to_json`), a virtual or store reader. While it runs, every decision
+    # AttributeAccessGuard makes about that record goes into one Frame, kept
+    # in a fiber-local ExecutionState slot (never on the record), and the
+    # event is published when the read returns. A read nested inside another record's
+    # read (an association serialized with `include:`) gets its own frame and
+    # event. Three getters called one after the other are three reads, so
+    # three events: the gem cannot know when a view or serializer is done
+    # with a record. FiltersResponseAttributes publishes one per hash it
+    # filters.
+    #
+    # Nothing is collected unless the event is stored (config.audit_runtime_events
+    # includes :field_read) or someone listens: the read then costs one
+    # Audit::Gate check. When the legacy on_field_filtered hook is the only
+    # listener and nothing is stored, no event is built either: each decision
+    # goes straight to the hook (Direct), as before the audit event log. The frame records every decision, passed ones too —
+    # the legacy on_field_filtered hook is called for each of them
+    # (payload[:objects][:decisions]); the stored row keeps the field names
+    # of each kind of decision (never a value). The names are gathered only
+    # when the event is built.
+    #
+    # @api private
+    module FieldAccess
+      EVENT = 'field.access'
+      # The ExecutionState slot of the read in progress (its Frame).
+      KEY = :pf_audit_field_access
+
+      # One AttributeAccessGuard decision. `hook` is false for a decision the
+      # legacy on_field_filtered hook was never called for (an unconfigured
+      # field in FiltersResponseAttributes, a response filtered without user).
+      Decision = Struct.new(:resource_name, :field_name, :action, :user, :hook)
+
+      LISTED = %i[hidden masked unconfigured bypassed].freeze
+
+      ENTRY = EventCatalog.fetch(EVENT)
+      # Asked on every guarded read.
+      GATE = Gate.for(EVENT)
+
+      # The decisions of one read.
+      class Frame
+        attr_reader :owner
+
+        # @param owner [Object] what is read: a record, or the Hash a
+        #   response filter works on
+        # @param resource_name [String]
+        # @param record [ActiveRecord::Base, nil] the record, when there is one
+        # @param record_id [Object, nil] the id, when there is no record
+        def initialize(owner, resource_name, record = nil, record_id = nil)
+          @owner = owner
+          @resource_name = resource_name.to_s
+          @record = record
+          @record_id = record_id
+          @decisions = []
+        end
+
+        # @return [void]
+        def add(resource_name, field_name, action, user, hook: true)
+          return if Audit.emitting?
+
+          @decisions << Decision.new(resource_name.is_a?(Symbol) ? resource_name.name : resource_name.to_s, field_name, action, user, hook)
+        end
+
+        # Publishes the read's event (nothing when no field was decided).
+        def emit
+          return if @decisions.empty?
+
+          decisions = @decisions.freeze
+          # the legacy hook alone needs only the decisions (Gate#direct_listeners)
+          light = GATE.direct_listeners
+          return Audit.emit_light(ENTRY, light, { event: EVENT, data: nil, objects: objects(decisions) }) if light
+
+          Audit.instrument(EVENT) { payload(decisions) }
+        end
+
+        private
+
+        def payload(decisions)
+          user = decisions.first.user
+          reference = @record ? { record: @record } : { record_type: @resource_name, record_id: @record_id }
+          reference.merge(subject_user_id: Runtime.user_id(user), data: data(decisions), objects: objects(decisions))
+        end
+
+        def objects(decisions)
+          { user: decisions.first.user, record: @record, decisions: decisions }
+        end
+
+        def data(decisions)
+          lists = LISTED.to_h { |action| [action.to_s, []] }
+          passed = []
+          decisions.each { |decision| add_name(decision.action == :passed ? passed : lists[decision.action.to_s], decision) }
+          { 'model' => @resource_name }.merge(lists).merge('passed' => passed.size, 'passed_fields' => passed)
+        end
+
+        def add_name(names, decision)
+          name = decision.field_name.to_s
+          names << name if names && !names.include?(name)
+        end
+      end
+
+      # Where decisions go when the legacy on_field_filtered hook is the only
+      # listener and nothing is stored (Gate#direct_listeners): straight to
+      # the hook, one call per decision as before the audit event log — no
+      # frame, no event. Re-entrancy guarded like any emission.
+      module Direct
+        def self.add(resource_name, field_name, action, user, hook: true)
+          return unless hook
+
+          listeners = GATE.direct_listeners
+          Audit.emit_decision(listeners, resource_name, field_name, action, user) if listeners
+        end
+      end
+
+      class << self
+        # Runs the block as one read of `owner`, and publishes its event.
+        # Yields the frame to record decisions in, or nil when nobody listens.
+        # A read inside a read of the same owner joins it.
+        #
+        # @param owner [Object] the record (or Hash) being read
+        # @param resource_name [String]
+        # @param record [Object, nil] the record, for the event's reference
+        # @param record_id [Object, nil] the id when there is no record
+        # @return the block's value
+        def read(owner, resource_name, record: nil, record_id: nil)
+          return yield(nil) unless GATE.open?
+
+          outer = ExecutionState[KEY]
+          return yield(outer) if outer&.owner.equal?(owner)
+          return yield(Audit.emitting? ? nil : Direct) if GATE.direct_listeners
+          return yield(nil) unless Audit.instrument?(EVENT)
+
+          frame = Frame.new(owner, resource_name, record, record_id)
+          run(frame) { yield(frame) }
+        end
+
+        # Fields a serialization leaves out because they are hidden
+        # (attribute_names_for_serialization): decided without the guard, so
+        # the legacy hook was never called for them. They join the read of
+        # `owner` in progress, if any.
+        #
+        # @return [void]
+        def omitted(owner, resource_name, names, user)
+          frame = ExecutionState[KEY]
+          return unless frame&.owner.equal?(owner)
+
+          names.each { |name| frame.add(resource_name, name, :hidden, user, hook: false) }
+        end
+
+        # A decision made outside any read (AttributeAccessGuard called by
+        # the host app): it joins the read in progress, or is a read of its own.
+        #
+        # @return [void]
+        def note(resource_name, field_name, action, user)
+          return unless GATE.open?
+
+          frame = ExecutionState[KEY]
+          return frame.add(resource_name, field_name, action, user) if frame
+          return Direct.add(resource_name, field_name, action, user) if GATE.direct_listeners && !Audit.emitting?
+          return unless Audit.instrument?(EVENT)
+
+          single = Frame.new(nil, resource_name)
+          single.add(resource_name, field_name, action, user)
+          single.emit
+        end
+
+        private
+
+        # The frame is the read in progress while the block runs; the outer
+        # read (or none) is put back before the event is published.
+        def run(frame, &)
+          result = ExecutionState.with(KEY, frame, &)
+          frame.emit
+          result
+        end
+      end
+    end
+  end
+end