permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/operators/value_casters/temporal.rb

@@ -12,8 +12,9 @@ module PermissionForge
       # offset is converted to it, and SQLite gets the text it compares with.
       # A date column takes the day of a date-time, a time column the time of
       # day. Anything else — another notation, `now`, `tomorrow`, the id that
-      # `current_user` stands for — is UNUSABLE, unless the caster is the one
-      # for a database that reads such text itself ({#as_written}).
+      # `current_user` stands for — is UNUSABLE. (On PostgreSQL, which reads
+      # date and time text itself, such text is asked of it:
+      # PostgresqlTypes::ReadBack.)
       class Temporal
         DAY = /(?<year>\d{4})-(?<month>\d\d?)-(?<day>\d\d?)/
         CLOCK = /(?:[01]?\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?/
@@ -23,28 +24,13 @@ module PermissionForge
 
         # @param format [Regexp] what the text has to look like
         # @param type [ActiveModel::Type::Value] casts the text and serializes the result
-        # @param as_written [Boolean] hand text of another notation over as it is
-        def initialize(format, type, as_written: false)
+        def initialize(format, type)
           @format = format
           @type = type
-          @as_written = as_written
         end
 
         def call(value)
-          return UNUSABLE unless value.is_a?(String)
-
-          recognised(value.strip) || (@as_written ? value : UNUSABLE)
-        end
-
-        # The same caster for a database that reads date and time text itself
-        # and raises on what it cannot read (PostgreSQL). Text this caster does
-        # not recognise is handed over as it is written, as it was before
-        # values were typed: `today`, a date in a local notation. What is not
-        # text stays UNUSABLE.
-        #
-        # @return [Temporal]
-        def as_written
-          self.class.new(@format, @type, as_written: true)
+          recognised(value) || UNUSABLE
         end
 
         DATE = new(DAY_AND_CLOCK, ActiveRecord::Type::Date.new)
@@ -53,7 +39,10 @@ module PermissionForge
 
         private
 
-        def recognised(text)
+        def recognised(value)
+          return unless value.is_a?(String)
+
+          text = value.strip
           parts = @format.match(text)
           @type.serialize(@type.cast(text)) if parts && real_day?(parts)
         end

data/lib/permission_forge/operators/value_casters.rb

@@ -2,6 +2,7 @@
 
 require_relative 'value_casters/number'
 require_relative 'value_casters/temporal'
+require_relative 'value_casters/postgresql_types'
 
 module PermissionForge
   module Operators
@@ -30,33 +31,61 @@ module PermissionForge
       # Compared as written; the id `current_user` stands for, as its text.
       TEXT = ->(value) { value.nil? ? UNUSABLE : value.to_s }
 
-      # A column type without a caster (uuid, json, an array column, ...) or a
-      # field name that names no known column: the value is left to the database.
+      # A column type without a caster (hstore, money, xml, ...) or a field
+      # name that names no known column: the value is left to the database.
       UNTYPED = ->(value) { value }
 
+      # A json, jsonb or array column: no rule value is one of its values.
+      # PostgreSQL raised on most texts compared with one, and the others
+      # (an array or JSON literal) compare a whole document; MySQL and SQLite
+      # compare text. A rule on such a column matches nothing under every
+      # built-in operator that takes a value — the null checks take none and
+      # work — and a custom operator gets the value as written.
+      OPAQUE = ->(_value) { UNUSABLE }
+
       BY_TYPE = {
         integer: NUMBER, float: NUMBER, decimal: NUMBER,
         boolean: BOOLEAN,
         string: TEXT, text: TEXT,
         date: Temporal::DATE, time: Temporal::TIME,
-        datetime: Temporal::DATETIME, timestamp: Temporal::DATETIME, timestamptz: Temporal::DATETIME
+        datetime: Temporal::DATETIME, timestamp: Temporal::DATETIME, timestamptz: Temporal::DATETIME,
+        json: OPAQUE, jsonb: OPAQUE,
+        # Types only PostgreSQL has (PostgresqlTypes); no other adapter reports them.
+        uuid: PostgresqlTypes::UUID, inet: PostgresqlTypes::INET, cidr: PostgresqlTypes::CIDR,
+        enum: PostgresqlTypes::NativeEnum
       }.freeze
 
-      # PostgreSQL is typed like the others, with two things left the way it
-      # always did them, so that no rule that works there stops working:
+      # PostgreSQL is typed like the others, with three differences:
       #
       # - It reads date and time text itself and raises on what it cannot
-      #   read. Text the Temporal casters do not recognise is left to it
-      #   (`due_on less_than '31 Jan 2026'`, `due_on equal 'today'`); on SQLite
-      #   and MySQL, which compare or convert such text, it stays UNUSABLE.
+      #   read. Text the Temporal casters do not recognise is asked of it
+      #   (PostgresqlTypes::ReadBack): what it reads is handed over
+      #   (`due_on less_than '31 Jan 2026'`, `due_on equal 'today'`), anything
+      #   else is UNUSABLE. On SQLite and MySQL, which compare or convert such
+      #   text, it is UNUSABLE.
+      # - A column type no caster knows (hstore, money, interval, ...) is
+      #   asked of it the same way ({ADAPTER_RULES}); `citext` is text.
       # - A `real` column is compared in single precision (Number::SINGLE_PRECISION).
       #   The SQL type is the key: its ActiveRecord type is `float` as well.
-      POSTGRESQL = BY_TYPE.transform_values { |caster| caster.is_a?(Temporal) ? caster.as_written : caster }
-                          .merge('real' => Number::SINGLE_PRECISION).freeze
+      POSTGRESQL = BY_TYPE.transform_values { |caster| caster.is_a?(Temporal) ? PostgresqlTypes::ReadBack.wrapping(caster) : caster }
+                          .merge('real' => Number::SINGLE_PRECISION, 'citext' => TEXT).freeze
 
       # Adapter name => the casters of that database, where they are not BY_TYPE.
       BY_ADAPTER = { 'PostgreSQL' => POSTGRESQL, 'PostGIS' => POSTGRESQL }.freeze
 
+      # What a database's casters decide apart from the column types:
+      # - `unknown_type`: the caster of a column type none of its casters
+      #   knows. UNTYPED (the value is left to the database) where a value of
+      #   another notation is compared or converted; read back where the
+      #   database raises on one.
+      # - `patterns`: the casters a LIKE pattern can be matched against, where
+      #   not every type has LIKE. PostgreSQL has it for text alone (an
+      #   integer, a date, a boolean raise there) — and a column nothing is
+      #   known about (an alias a join gives) is left to it.
+      ADAPTER_RULES = {}.compare_by_identity.merge!(
+        POSTGRESQL => { unknown_type: PostgresqlTypes::ReadBack.wrapping(nil), patterns: [TEXT, UNTYPED].freeze }.freeze
+      ).freeze
+
       # The casters that read the two bounds of `between` together, where the
       # others cast one bound at a time. With nothing known about the column
       # the pair is read as it was before values were typed: both integers,
@@ -68,12 +97,31 @@ module PermissionForge
 
       # @param column [ActiveRecord::ConnectionAdapters::Column, nil]
       # @param adapter_name [String, nil] the adapter of the column's model
+      # @param model [Class, nil] the model whose table the column is in (a
+      #   native enum's labels are read through it)
       # @return [#call] the caster for the column
-      def self.for(column, adapter_name = nil)
-        return UNTYPED if column.nil? || column.try(:array?)
+      def self.for(column, adapter_name = nil, model = nil)
+        return UNTYPED if column.nil?
+        return OPAQUE if column.try(:array?)
 
         casters = BY_ADAPTER.fetch(adapter_name, BY_TYPE)
-        casters.fetch(column.sql_type) { casters.fetch(column.type, UNTYPED) }
+        caster = casters.fetch(column.sql_type) { casters.fetch(column.type) { ADAPTER_RULES.dig(casters, :unknown_type) || UNTYPED } }
+        caster.respond_to?(:of) ? caster.of(column, model) : caster
+      end
+
+      # Whether a LIKE pattern can be matched against a column of the
+      # caster's type. Not a json or array column, nor one of the PostgreSQL
+      # types without LIKE (uuid, inet, cidr, a native enum), nor — on
+      # PostgreSQL — anything but text ({ADAPTER_RULES}): a rule with a LIKE
+      # operator on one matches nothing.
+      #
+      # @param caster [#call] a caster {.for} returned
+      # @param adapter_name [String, nil] the adapter of the column's model
+      def self.pattern?(caster, adapter_name = nil)
+        only = ADAPTER_RULES.dig(BY_ADAPTER[adapter_name], :patterns)
+        return only.any? { |allowed| allowed.equal?(caster) } if only
+
+        !caster.equal?(OPAQUE) && PostgresqlTypes.pattern?(caster)
       end
     end
   end

data/lib/permission_forge/operators/value_typing.rb

@@ -23,8 +23,16 @@ module PermissionForge
     # Only the built-in operators are typed, each by the shape of its value
     # ({SHAPES}). A custom operator's value is returned as it came, and a
     # column nothing is known about leaves the value to the database. A rule
-    # whose field_name is not a name (RuleColumn#malformed?) has no column to
-    # compare with: its value is UNUSABLE whatever the operator.
+    # with no column to compare with ({.no_column?}) is UNUSABLE: one whose
+    # field_name is not a name, whatever the operator, and one that names a
+    # column its table does not have, under a built-in operator. So is a
+    # value with a NUL byte, under any operator ({.unquotable?}): no SQL
+    # literal carries one — the database reads the statement cut short, and
+    # every holder's query failed instead of being denied. So is any value
+    # under a built-in operator that takes one, on a column that holds
+    # ciphertext ({.encrypted?}): the statement compares the stored
+    # ciphertext with the rule's text (Active Record's own query rewriting
+    # never runs on a raw comparison). Why a value is UNUSABLE is {.problem}.
     module ValueTyping
       UNUSABLE = ValueCasters::UNUSABLE
       CURRENT_USER = 'current_user'
@@ -50,12 +58,73 @@ module PermissionForge
       # @return [Object] what the operator's strategy binds: one value, an Array
       #   for `in` / `not_in` / `between`, or {UNUSABLE}
       def call(operator, value, target)
-        return UNUSABLE if target.malformed?
+        return UNUSABLE if no_column?(operator, target) || unquotable?(value) || encrypted?(operator, target)
 
         shape = SHAPES[operator]
         shape ? send(shape, value, target) : value
       end
 
+      # Whether the value cannot be written into a statement as a literal: a
+      # String with a NUL byte (a row written past the model; ParamShapes
+      # drops NUL bytes from request parameters).
+      #
+      # @param value [Object] the rule's value
+      def unquotable?(value)
+        value.is_a?(String) && value.include?("\0")
+      end
+
+      # Whether the rule has no column to compare with: its field_name is not a
+      # name (RuleColumn#malformed?), or — under a built-in operator — it names
+      # a column its table does not have (RuleColumn#missing?), which the
+      # database would reject. A custom operator's strategy decides what it
+      # does with the name, so a missing column is left to it.
+      #
+      # @param operator [String] the rule's operator
+      # @param target [RuleColumn] the column the rule names
+      def no_column?(operator, target)
+        target.malformed? || (target.missing? && Constants::OPERATORS.include?(operator))
+      end
+
+      # Whether a built-in operator that takes a value ({SHAPES}) compares a
+      # column that holds ciphertext (RuleColumn#encrypted?). The null checks
+      # take no value and work: the ciphertext is NULL exactly when the value
+      # is. A custom operator's strategy decides for itself (a `where(attr:
+      # value)` of its own goes through the attribute's type).
+      #
+      # @param operator [String] the rule's operator
+      # @param target [RuleColumn] the column the rule names
+      def encrypted?(operator, target)
+        SHAPES.key?(operator) && target.encrypted?
+      end
+
+      # Why the value is {UNUSABLE} for the column it is compared with, nil
+      # when it is not: the operator and the column alone decide the first
+      # two — :encrypted_column ({.encrypted?}), :pattern_on_non_text (a LIKE
+      # operator on a column no pattern can be matched against,
+      # RuleColumn#pattern?) —, else :unusable_value (a value the column
+      # cannot hold). For a column that was found (RuleProblem judges a
+      # missing one first).
+      #
+      # @param operator [String] the rule's operator
+      # @param value [Object] the rule's value, as {.call} takes it
+      # @param target [RuleColumn] the column it is compared with
+      # @return [Symbol, nil]
+      def problem(operator, value, target)
+        operator_problem(operator, target) || (:unusable_value if call(operator, value, target).equal?(UNUSABLE))
+      end
+
+      # The reason the operator cannot be used on the column whatever the
+      # value (see {.problem}), or nil.
+      #
+      # @param operator [String] the rule's operator
+      # @param target [RuleColumn] the column it is compared with
+      # @return [Symbol, nil] :encrypted_column or :pattern_on_non_text
+      def operator_problem(operator, target)
+        return :encrypted_column if encrypted?(operator, target)
+
+        :pattern_on_non_text if SHAPES[operator] == :pattern && !target.column.nil? && !target.pattern?
+      end
+
       # `current_user` stands for the user's id wherever one value is compared.
       # In a list it is an element like any other.
       def current_user?(operator, value)
@@ -78,9 +147,10 @@ module PermissionForge
         caster(target).call(value)
       end
 
-      # A LIKE pattern is built from the text of the value, whatever the column.
-      def pattern(value, _target)
-        ValueCasters::TEXT.call(value)
+      # A LIKE pattern is built from the text of the value, on a column a
+      # pattern can be matched against (ValueCasters.pattern?).
+      def pattern(value, target)
+        target.pattern? ? ValueCasters::TEXT.call(value) : UNUSABLE
       end
 
       # Every element has to be a value of the column; a list of none is no list.
@@ -100,6 +170,12 @@ module PermissionForge
         together ? together.call(bounds) : all_typed(bounds, typed)
       end
 
+      # The elements of a list or a range as written: the text split at every
+      # comma, each stripped (a trailing comma adds none). The rule's
+      # sentence splits them the same way.
+      #
+      # @param value [Object]
+      # @return [Array<String>]
       def split(value)
         value.to_s.split(',').map(&:strip)
       end
@@ -109,7 +185,7 @@ module PermissionForge
         typed.include?(UNUSABLE) ? UNUSABLE : typed
       end
 
-      private_class_method :caster, :single, :pattern, :list, :pair, :split, :all_typed
+      private_class_method :caster, :single, :pattern, :list, :pair, :all_typed
     end
   end
 end

data/lib/permission_forge/query_scoping_warnings.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module PermissionForge
-  # Boot warnings for the three query-scoping levels (called by BootChecks).
+  # Boot warnings for the three query-scoping levels (called by BootChecks;
+  # each goes through Warnings.emit).
   #
   # @api private
   module QueryScopingWarnings
@@ -13,9 +14,10 @@ module PermissionForge
       return unless pf_config.unscoped_query_detection == :raise
       return unless pf_config.unscoped_query_detection_environments.include?('production')
 
-      Rails.logger&.warn '[PermissionForge] WARNING: unscoped_query_detection = :raise is enabled ' \
-                         'for production. A single unscoped query will raise UnscopedQueryError ' \
-                         'in live traffic — prefer :log in production and :raise in test/CI.'
+      Warnings.emit(:unscoped_detection_raise_in_production,
+                    'WARNING: unscoped_query_detection = :raise is enabled for production. A single unscoped ' \
+                    'query will raise UnscopedQueryError in live traffic — prefer :log in production and ' \
+                    ':raise in test/CI.')
     end
 
     # Level 1 applies filter-type rules only; join-type rules still require
@@ -23,13 +25,15 @@ module PermissionForge
     def warn_join_rules_not_auto_scoped(pf_config)
       return unless pf_config.auto_query_scoping_enabled?
 
-      join_rules = PermissionForge::PermissionSetRule.join_type_rules
-      return unless join_rules.exists?
+      # The join rules (PermissionSetRule#join_rule?, the one definition; the scope is the SQL pre-filter).
+      count = PermissionForge::PermissionSetRule.join_type_rules.pluck(:join_type)
+                                                .count { |join_type| !PermissionForge::PermissionSetRule.filter_join_type?(join_type) }
+      return if count.zero?
 
-      Rails.logger&.warn '[PermissionForge] SECURITY warning: auto_query_scoping is enabled but ' \
-                         "#{join_rules.count} join-type rule(s) exist. Join rules are NOT applied " \
-                         'by auto-scoping — queries relying on them must go through ' \
-                         'Model.permission_scoped.'
+      Warnings.emit(:join_rules_not_auto_scoped,
+                    "auto_query_scoping is enabled but #{count} join-type rule(s) exist. Join rules " \
+                    'are NOT applied by auto-scoping — queries relying on them must go through ' \
+                    'Model.permission_scoped.', severity: :security)
     rescue ActiveRecord::StatementInvalid
       # Tables don't exist yet (pre-migration)
     end
@@ -42,9 +46,10 @@ module PermissionForge
       return unless pf_config.database_row_level_security
 
       unless PermissionForge::RLS.postgres?
-        Rails.logger&.warn '[PermissionForge] WARNING: database_row_level_security is enabled but ' \
-                           'the database adapter is not PostgreSQL. RLS policies cannot be enforced — ' \
-                           'row-level security falls back to application-level scoping only.'
+        Warnings.emit(:rls_not_postgresql,
+                      'database_row_level_security is enabled but the database adapter is not ' \
+                      'PostgreSQL. RLS policies cannot be enforced — row-level security falls back to ' \
+                      'application-level scoping only.', severity: :security)
         return
       end
 
@@ -57,10 +62,10 @@ module PermissionForge
       stale = PermissionForge::RLS.drift_report.reject { |report| report[:in_sync] }
       return if stale.empty?
 
-      Rails.logger&.warn '[PermissionForge] SECURITY warning: RLS policies are missing or stale for ' \
-                         "table(s): #{stale.map { |report| report[:table] }.join(', ')}. " \
-                         'Rule rows have changed since the last policy sync (or policies were never ' \
-                         'installed) — run `rake permission_forge:rls:sync`.'
+      Warnings.emit(:rls_policy_drift,
+                    "RLS policies are missing or stale for table(s): #{stale.map { |report| report[:table] }.join(', ')}. " \
+                    'Rule rows have changed since the last policy sync (or policies were never installed) — ' \
+                    'run `rake permission_forge:rls:sync`.', severity: :security)
     rescue ActiveRecord::StatementInvalid
       # Tables don't exist yet (pre-migration)
     end

data/lib/permission_forge/rake_audit.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
+require_relative 'rake_output'
+
 module PermissionForge
   # What every rake task of the gem does about the audit log: names who ran it
   # (ACTOR=, stored as actor_label with actor_type 'system' and source 'rake'),
   # records `report.generated` for the read-only ones, and logs through
-  # Rails.logger. The tasks' own output is untouched.
+  # Rails.logger. What the tasks print is RakeOutput's.
   #
   #   PermissionForge::RakeAudit.changing('permission_forge:erasure') { ... }   # warns without ACTOR
   #   PermissionForge::RakeAudit.reporting('permission_forge:audit', counts: ->(r) { r.counts }) { report }
@@ -52,9 +54,8 @@ module PermissionForge
       def run(task, env, &)
         actor = label(task, env)
         log(task, "run by #{actor}")
-        PermissionForge::Audit::Context.with(
-          actor: PermissionForge::Audit::Actor.system(actor), source: 'rake', reason: env['REASON'].presence, &
-        )
+        context = { actor: PermissionForge::Audit::Actor.system(actor), source: 'rake', reason: env['REASON'].presence }
+        PermissionForge::Audit::Context.with(**context, &)
       end
 
       def missing_actor_warning(task)

data/lib/permission_forge/rake_dry_run.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # The one reading of DRY_RUN= for the gem's rake tasks that delete data
+  # (`permission_forge:erasure`, `permission_forge:audit_events:purge`). Only
+  # an explicit false (`false`, `0`, `no`, any case) runs for real; any other
+  # value (`true`, `1`, `yes`, a typo) is a dry run. Unset or empty, the task
+  # keeps its own default: the erasure is a dry run, the purge deletes (a
+  # scheduled purge must not silently stop).
+  #
+  #   dry_run = PermissionForge::RakeDryRun.dry_run?(ENV.fetch('DRY_RUN', nil), default: true)
+  #
+  # The task reads the variable itself, so the rake lints see it read.
+  #
+  # @api private
+  module RakeDryRun
+    # The values that run a task for real.
+    EXECUTE = %w[false 0 no].freeze
+
+    module_function
+
+    # @param value [String, nil] what DRY_RUN= was set to
+    # @param default [Boolean] the answer when it is unset or empty
+    # @return [Boolean] whether the task only counts
+    def dry_run?(value, default:)
+      given = value.to_s.strip.downcase
+      return default if given.empty?
+
+      !EXECUTE.include?(given)
+    end
+  end
+end

data/lib/permission_forge/rake_output.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # What the gem's rake tasks print: one presenter for a run's result, so the
+  # terminal says what the summary audit event records — one line per key,
+  # named — the cache outcome (Cache::Outcome: confirmed, scope, unconfirmed)
+  # where the result carries one, and people named as the admin names them
+  # (Admin::PersonLabel), never "User 2". Rake output stays English.
+  #
+  #   PermissionForge::RakeOutput.report("Erasure complete for #{RakeOutput.person(user)}:", result)
+  #   PermissionForge::RakeOutput.people(ids)   # => { "12" => "Rae Rake (id 12)" }
+  #
+  # @api private
+  module RakeOutput
+    # The label of each key a service answers or an event records — one
+    # table: a key whose label says a change was made carries its dry-run
+    # form as a second label ([done, would]), so a dry run never prints
+    # "Audit events deleted" (field test round 7, E#55). The event key and
+    # the result key of one fact share a label (set_names / permission_sets),
+    # so a reader finds every event key in the output. A key without one is
+    # printed as its words.
+    LABELS = {
+      'assignments_removed' => ['Permission set assignments removed', 'Permission set assignments that would be removed'],
+      'assignments_count' => 'Permission set assignments',
+      'group_assignments_removed' => ['Group memberships removed', 'Group memberships that would be removed'],
+      'group_assignments_count' => 'Group memberships',
+      'assignments_remaining_elsewhere' => 'Assignments remaining in other tenants',
+      'group_assignments_remaining_elsewhere' => 'Group memberships remaining in other tenants',
+      'permission_sets' => 'Permission sets', 'set_names' => 'Permission sets',
+      'groups' => 'Groups', 'group_names' => 'Groups',
+      'actor_labels_cleared' => ['Audit log name labels cleared as actor', 'Audit log name labels that would be cleared as actor'],
+      'record_labels_cleared' => ['Audit log name labels cleared as subject', 'Audit log name labels that would be cleared as subject'],
+      'actor_labels_to_clear' => 'Audit log name labels to clear as actor',
+      'record_labels_to_clear' => 'Audit log name labels to clear as subject',
+      'events_scrubbed' => ['Audit events with a name label cleared', 'Audit events whose name label would be cleared'],
+      'callback_invoked' => 'on_erasure callback',
+      'removed' => ['Expired assignments removed', 'Expired assignments that would be removed'],
+      'expired_count' => 'Expired assignments',
+      'invalidated' => ['People whose cached permissions were invalidated', 'People whose cached permissions would be invalidated'],
+      'affected_user_ids' => 'People affected',
+      'strategy' => 'Strategy', 'users' => ['User visits invalidated', 'User visits that would be invalidated'], 'tenants' => 'Tenants',
+      'purged' => ['Audit events deleted', 'Audit events that would be deleted'],
+      'count' => ['Audit events deleted', 'Audit events that would be deleted'],
+      'cutoff' => ['Deleted when older than', 'Would delete the events older than'],
+      'period' => 'Retention period', 'period_seconds' => 'Retention period',
+      'retention_configured' => 'Retention configured',
+      'cache_confirmed' => ['Cached permissions removed', 'Cached permissions that would be removed'],
+      'process_local' => 'Cache scope', 'in_request' => 'Ran in',
+      'unconfirmed' => 'People the cache store did not confirm'
+    }.freeze
+
+    # Keys of a result the cache lines or the title say already.
+    SILENT = %w[cache_cleared dry_run].freeze
+    # Keys printed as people.
+    PEOPLE_KEYS = %w[affected_user_ids].freeze
+    PEOPLE_SHOWN = 50
+    STRATEGIES = { 'pattern' => 'pattern (the store removed the keys by pattern; users not counted)',
+                   'enumerated' => 'enumerated (every user invalidated, in slices)' }.freeze
+    # "Cached permissions removed", by confirmed and by the store's scope: one
+    # outcome reads as one message, never as a success line contradicted by
+    # the scope line.
+    # :none — an operation that did no cache work (Cache::Outcome#none?: a dry run).
+    CONFIRMED = { true => 'yes (the cache store confirmed it)',
+                  false => 'NO — the cache store did not confirm it; the old permissions may be served until cache_ttl',
+                  nil => 'not known yet — the invalidation follows the commit of the surrounding transaction',
+                  none: 'none — no cache work was done (a dry run changes nothing)' }.freeze
+    CONFIRMED_HERE = 'yes, in this process (its own store confirmed it; see Cache scope)'
+    CALLBACK = { true => 'ran', false => 'none configured', nil => 'runs when the surrounding transaction commits' }.freeze
+    # The "Cache scope" line of a process-local store (Cache::Outcome#process_local?) and of a shared one.
+    PROCESS_LOCAL_NOTE = 'this process only — an in-memory store (cache_backend :memory, or :memory_store) lives in each ' \
+                         'process, so the web and job processes keep their cached permissions until they restart or the ' \
+                         'entries expire (cache_ttl). Invalidate the users from inside those processes, or restart them.'
+    SHARED_NOTE = 'a shared store — every process sees the change; each user rebuilds on their next request.'
+    RAN_IN = { true => 'a request served by a web process', false => 'a process of its own (rake, runner, console or job)' }.freeze
+    NOT_IN_LIST = 'not in the people list'
+
+    module_function
+
+    # Prints the title and one line per key of `data` (a service's result,
+    # symbol or string keys); `cache:` (a Cache::Outcome or its Hash) prints
+    # as the cache lines. A dry run (the result's `dry_run: true`) prints
+    # each label in its "would" form.
+    #
+    # @param title [String]
+    # @param data [Hash]
+    # @param io [IO]
+    # @return [void]
+    def report(title, data, io: $stdout)
+      io.puts title
+      lines(data).each { |line| io.puts "  #{line}" }
+    end
+
+    # @return [Array<String>] "Label: value" per key
+    def lines(data)
+      data = data.transform_keys(&:to_s)
+      dry_run = data['dry_run'] == true
+      data.except(*SILENT).flat_map do |key, value|
+        key == 'cache' ? cache_lines(value, data, dry_run: dry_run) : ["#{label(key, dry_run: dry_run)}: #{format_value(key, value)}"]
+      end
+    end
+
+    # @param key [String, Symbol]
+    # @param dry_run [Boolean] the label's "would" form, when it has one
+    # @return [String]
+    def label(key, dry_run: false)
+      labels = Array(LABELS.fetch(key.to_s) { key.to_s.tr('_', ' ').then { |words| words[0].to_s.upcase + words[1..].to_s } })
+      dry_run ? labels.last : labels.first
+    end
+
+    # @param user [Object, String, Integer] a host user, or an id
+    # @return [String] "Rae Rake (id 12)"
+    def person(user)
+      return people([user]).values.first if user.is_a?(String) || user.is_a?(Integer)
+
+      "#{person_name(user)} (id #{user.id})"
+    end
+
+    # The people `ids` name, within config.user_list_resolver
+    # (Admin::PeopleDirectory, as the admin looks people up).
+    #
+    # @param ids [Array]
+    # @return [Hash{String => String}] id → "Name (id N)", or "id N (not in the people list)"
+    def people(ids)
+      found = Admin::PeopleDirectory.new.find_all(ids).index_by { |user| user.id.to_s }
+      ids.map(&:to_s).uniq.to_h do |id|
+        user = found[id]
+        [id, user ? person(user) : "id #{id} (#{NOT_IN_LIST})"]
+      end
+    end
+
+    def person_name(user)
+      label = Admin::PersonLabel.new(user)
+      name = label.name
+      name == I18n.t('permission_forge.shared.user_fallback', id: user.id) ? 'no name or email on record' : name
+    end
+
+    # The outcome's lines: what the store confirmed (in this process, when
+    # the store is process-local), the store's scope, where it ran, and the
+    # unconfirmed count unless the result prints its own — or, for an
+    # operation that did no cache work (Outcome#none?), that one line.
+    def cache_lines(value, data, dry_run: false)
+      outcome = Cache::Outcome.wrap(value)
+      removed = label('cache_confirmed', dry_run: dry_run)
+      return ["#{removed}: #{CONFIRMED.fetch(:none)}"] if outcome.none?
+
+      lines = ["#{removed}: #{confirmed_text(outcome)}",
+               "#{label('process_local')}: #{outcome.process_local? ? PROCESS_LOCAL_NOTE : SHARED_NOTE}",
+               "#{label('in_request')}: #{RAN_IN.fetch(outcome.in_request?)}"]
+      lines << "#{label('unconfirmed')}: #{plain(outcome.unconfirmed)}" unless data.key?('unconfirmed')
+      lines
+    end
+
+    # What the store confirmed: in this process when the store is process-local.
+    def confirmed_text(outcome)
+      outcome.confirmed? && outcome.process_local? ? CONFIRMED_HERE : CONFIRMED.fetch(outcome.confirmed)
+    end
+
+    # One table of value shapes.
+    def format_value(key, value)
+      case key
+      when 'callback_invoked' then CALLBACK.fetch(value)
+      when 'strategy' then STRATEGIES.fetch(value.to_s, value.to_s)
+      when 'users' then value.nil? ? 'not counted (removed by key pattern)' : value.to_s
+      when 'period', 'period_seconds' then "#{value} seconds (#{(value.to_i / 86_400.0).round(1)} days)"
+      when *PEOPLE_KEYS then people_list(Array(value))
+      else plain(value)
+      end
+    end
+
+    def people_list(ids)
+      return 'none' if ids.empty?
+
+      names = people(ids.first(PEOPLE_SHOWN)).values
+      names << "and #{ids.size - PEOPLE_SHOWN} more" if ids.size > PEOPLE_SHOWN
+      "#{ids.size} — #{names.join(', ')}"
+    end
+
+    def plain(value)
+      case value
+      when true then 'yes'
+      when false then 'no'
+      when nil then 'not known'
+      when Array then value.empty? ? 'none' : value.join(', ')
+      when Time, DateTime, ActiveSupport::TimeWithZone then value.iso8601
+      else value.to_s
+      end
+    end
+  end
+end