current_scope 0.5.0

data/lib/current_scope/schema_guard.rb

@@ -0,0 +1,223 @@
+module CurrentScope
+  # The #151 boot guard: does this database actually have the grant-column shape
+  # the fix requires, and may THIS command boot without it?
+  #
+  # Its own file rather than more of Engine, matching SodPreflight and
+  # ParentChain — Engine states when a check runs, the check itself lives here.
+  #
+  # #151 is fixed by a MIGRATION, and a gem upgrade does not run one. A host that
+  # bundles 0.5 and deploys without applying it keeps integer id columns and
+  # keeps the full escalation, silently, because every code path behaves
+  # correctly against whatever schema it is given. So check the schema itself and
+  # refuse to serve. This is the one check that cannot be a validation: the
+  # damage is in the column, not in the next write.
+  module SchemaGuard
+    def self.check!(allow_database_task: true)
+      return if allow_database_task && running_a_database_task?
+      # Escape hatch for tooling that must BOOT in order to migrate — our own
+      # bin/db does exactly that, because schema.rb cannot carry a MySQL
+      # collation. Deliberately an explicit opt-out and not a config flag: a host
+      # that sets this in production has chosen to run without the check.
+      return if ENV["CURRENT_SCOPE_SKIP_SCHEMA_CHECK"] == "1"
+
+      # Strict "1" on purpose — this switches OFF a security control, so it
+      # should be awkward to trip. But silence would be worse than strictness: a
+      # host who writes `=true` (which the gem's other env opt-out does accept)
+      # would otherwise believe the check was off while it was still armed.
+      if ENV.key?("CURRENT_SCOPE_SKIP_SCHEMA_CHECK")
+        Rails.logger&.warn(
+          "[CurrentScope] CURRENT_SCOPE_SKIP_SCHEMA_CHECK is set to " \
+          "#{ENV['CURRENT_SCOPE_SKIP_SCHEMA_CHECK'].inspect} and was IGNORED — the only " \
+          "value that disables the #151 schema check is the string \"1\"."
+        )
+      end
+
+      # BOTH halves of every grant predicate, not just the ids. The migration
+      # widens the id columns and then re-collates the type columns, and MySQL
+      # auto-commits each statement — so a migration that dies between the two
+      # leaves binary ids beside case-insensitive types, permanently. Checking
+      # only the ids blesses exactly that state, and a grant on `Widget#5` then
+      # matches a check for `WIDGET#5`. Same escalation, other column.
+      {
+        CurrentScope::RoleAssignment => { ids: %w[subject_id], types: %w[subject_type] },
+        CurrentScope::ScopedRoleAssignment => {
+          ids: %w[subject_id resource_id], types: %w[subject_type resource_type]
+        }
+      }.each do |model, groups|
+        next unless model.table_exists?
+
+        groups[:ids].each { |column| check_id_column!(model, column) }
+        # Type columns are varchar already; only their collation can be wrong.
+        groups[:types].each { |column| check_collation!(model, column) } if mysql?
+      end
+    rescue ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
+      # There is genuinely no database yet (a fresh checkout running db:create,
+      # a build step with no server). Nothing to judge, so stay quiet.
+      #
+      # Narrow ON PURPOSE. Rescuing ActiveRecordError broadly here would turn any
+      # transient error into a silent all-clear, which is a security guard
+      # failing open. Anything else propagates.
+      nil
+    end
+
+    def self.check_id_column!(model, column)
+      info = model.columns_hash[column]
+      return if info.nil?
+
+      if info.type.in?([ :string, :text ])
+        # STRING IS NOT ENOUGH — the width has to be right too. A varchar(32)
+        # passes "is it a string?" and then truncates every UUID written to it,
+        # which is the original collision with a different cause. A text column
+        # is unbounded and therefore wide enough.
+        if !info.limit.nil? && info.limit < CurrentScope::KEY_LIMIT
+          raise ConfigurationError,
+                "#{model.table_name}.#{column} holds #{info.limit} characters; CurrentScope " \
+                "needs #{CurrentScope::KEY_LIMIT}. A UUID is 36 and a narrower column would " \
+                "truncate it, so two keys sharing a prefix would name one record (#151). Run " \
+                "`bin/rails current_scope:repair_schema` to widen it."
+        end
+
+        if info.respond_to?(:null) && info.null
+          raise ConfigurationError,
+                "#{model.table_name}.#{column} allows NULL, so a grant may fail to name " \
+                "one record. Run `bin/rails current_scope:repair_schema` to restore the " \
+                "required NOT NULL constraint (#151)."
+        end
+
+        check_collation!(model, column) if mysql?
+        return
+      end
+
+      raise ConfigurationError,
+            "#{model.table_name}.#{column} is still #{info.type}. CurrentScope stores a " \
+            "record's primary key there, and an integer column silently truncates a " \
+            "UUID — two subjects collapse into one identity and one inherits the " \
+            "other's roles (#151). Run `bin/rails current_scope:install:migrations && " \
+            "bin/rails db:migrate` to widen it."
+    end
+
+    # Collation matters as much as type on MySQL: its default is case AND accent
+    # insensitive, so "ABC" and "abc" — or "jose" and "josé" — are the same
+    # record. A database built from schema.rb has the right column type and the
+    # wrong collation, which is the common case for a new app and for CI.
+    def self.check_collation!(model, column)
+      info = model.columns_hash[column]
+      return if info.nil?
+
+      # A security guard must not fail open. The column exists and we are on
+      # MySQL, so its collation should always be readable; if it is not, refuse
+      # rather than bless a column we cannot prove compares case-sensitively —
+      # the same fatal treatment roles_controller#candidate_key_as_text now gives
+      # missing collation.
+      if info.collation.nil?
+        raise ConfigurationError,
+              "#{model.table_name}.#{column}'s MySQL collation could not be read, so " \
+              "CurrentScope cannot prove \"ABC\" and \"abc\" are different records (#151). " \
+              "Run `bin/rails current_scope:repair_schema`."
+      end
+
+      if info.collation.end_with?("_bin")
+        # Binary, but not necessarily NO PAD. utf8mb4_bin is PAD SPACE, so it
+        # still compares "abc" equal to "abc " — a narrower relative of the same
+        # collision. The migration prefers utf8mb4_0900_bin for that reason and
+        # falls back only where the server (MySQL < 8.0.17) offers nothing
+        # better. Refusing to boot there would strand a host on a shortcoming
+        # they cannot fix, so say it plainly once instead.
+        # Every _bin collation EXCEPT the 0900 family is PAD SPACE, not just
+        # utf8mb4_bin — latin1_bin and friends fold trailing spaces too.
+        unless info.collation.start_with?("utf8mb4_0900")
+          Rails.logger&.warn(
+            "[CurrentScope] #{model.table_name}.#{column} uses #{info.collation}, which is " \
+            "case-sensitive but PAD SPACE — a key with a trailing space would still " \
+            "match one without. On MySQL 8.0.17+ run " \
+            "`bin/rails current_scope:repair_schema` to move to utf8mb4_0900_bin (#151)."
+          )
+        end
+        return
+      end
+
+      # NOT db:migrate. A database loaded from schema.rb has every migration
+      # version already stamped, so db:migrate finds nothing pending and prints
+      # nothing while the collation stays wrong — and schema.rb cannot carry a
+      # MySQL collation, so that is the normal state of a new app and of CI.
+      # Naming db:migrate here sent hosts to a command that could not work.
+      raise ConfigurationError,
+            "#{model.table_name}.#{column} uses the #{info.collation} collation, which " \
+            "is case and accent insensitive — \"ABC\" and \"abc\" would be the same " \
+            "record, so a grant on one reaches the other (#151). Run " \
+            "`bin/rails current_scope:repair_schema` to apply a binary collation " \
+            "(idempotent, and it works on a schema-loaded database where db:migrate " \
+            "has nothing pending)."
+    end
+
+    # The GRANT tables' connection, not ActiveRecord::Base's. The columns being
+    # judged come from RoleAssignment.columns_hash, so the adapter question has
+    # to be asked of the same database those columns live in — a host that puts
+    # the engine's tables on a second connection would otherwise be judged by the
+    # wrong server's collation rules.
+    def self.mysql?
+      CurrentScope.mysql?(CurrentScope::RoleAssignment.connection)
+    end
+
+    # Rake tasks that may BOOT even against an unrepaired schema.
+    #
+    # The check raises from after_initialize, which every Rails command runs —
+    # including `db:migrate`, the command its own error message tells the host to
+    # run. Without an exemption an upgrading host is stuck: the app refuses to
+    # boot and the repair refuses to run, for the same reason. `assets:` is the
+    # same trap one step less obvious — a deploy pipeline that precompiles before
+    # migrating dies before it ever reaches the fix.
+    #
+    # EXACT NAMES, not prefixes, and that distinction is load-bearing: matching
+    # `db:create` as a prefix also matches a host's `db:create_tenant`, and
+    # `db:migrate` matches `db:migrate_legacy_users`. Prefix matching turned an
+    # allow list back into the `db:` free-for-all it replaced. Namespaces that
+    # legitimately have children are listed separately, ending in a colon.
+    #
+    # Anything that serves traffic or runs host code — server, console, runner —
+    # is deliberately absent. db:setup, db:reset and db:prepare are present
+    # despite seeding: they are how a host REBUILDS a database, and refusing them
+    # would leave a broken schema with no way to replace it.
+    BOOT_EXEMPT_TASKS = %w[
+      db:create db:drop db:migrate db:rollback db:version db:prepare db:setup
+      db:reset db:abort_if_pending_migrations db:_dump
+      current_scope:install current_scope:repair_schema
+    ].freeze
+
+    # Namespaces whose children are all schema tooling (db:migrate:up,
+    # db:schema:load, assets:precompile, …).
+    BOOT_EXEMPT_NAMESPACES = %w[
+      db:migrate: db:schema: db:structure: db:test: db:environment:
+      current_scope:install: assets:
+    ].freeze
+
+    # …minus these, which the lists above would otherwise cover. A bare `db:seed`
+    # repairs nothing and runs host code, and seeds routinely create grants
+    # through this engine — on the pre-migration schema, exactly the writes that
+    # collapse two subjects into one. Prefixes here on purpose: db:seed:replant
+    # (which Rails ships) and a host's own db:seed_users are both host code, and
+    # over-refusing is the safe direction for a deny list.
+    BOOT_REFUSED_TASKS = %w[db:seed db:fixtures:].freeze
+
+    def self.running_a_database_task?
+      return false unless defined?(Rake) && Rake.respond_to?(:application)
+
+      # `app:` is how an engine's host tasks are namespaced from inside the
+      # engine (rails/tasks/engine.rake), so strip it once here instead of
+      # spelling every entry twice in both lists.
+      tasks = Rake.application.top_level_tasks.map { |task| task.delete_prefix("app:") }
+      return false if tasks.any? { |task| task.start_with?(*BOOT_REFUSED_TASKS) }
+
+      tasks.any? do |task|
+        BOOT_EXEMPT_TASKS.include?(task) || task.start_with?(*BOOT_EXEMPT_NAMESPACES)
+      end
+    rescue StandardError
+      # No rake application in scope (a server or console): not a database task.
+      false
+    end
+    private_class_method :check_id_column!, :check_collation!, :mysql?
+    # Public: Engine#validate_subject_key! asks the same "may this command boot
+    # without the schema?" question and reuses this rather than re-deriving it.
+    public_class_method :running_a_database_task?
+  end
+end

data/lib/current_scope/scopeable.rb

@@ -0,0 +1,38 @@
+module CurrentScope
+  # Include CurrentScope::Scopeable to make a model pickable in the scoped-role
+  # assignment UI's type dropdown. BROWSE-ONLY — it does NOT gate access: any
+  # model is still a valid GlobalID scoped-role target whether or not it opts in.
+  #
+  # The `included` hook self-registers the class by NAME (stored as a string and
+  # resolved lazily) so dev-mode class reloading never pins a stale constant;
+  # the engine rebuilds the registry on every to_prepare.
+  module Scopeable
+    extend ActiveSupport::Concern
+
+    included do
+      CurrentScope.register_scopeable(name) if name
+    end
+
+    # Default label for the picker. Defined as an ordinary instance method so a
+    # host that provides its own current_scope_label simply overrides it — the
+    # host class sits ahead of this module in the ancestor chain.
+    def current_scope_label
+      "#{model_name.human} ##{id}"
+    end
+
+    # OPTIONAL indexed search for the scoped-role picker. current_scope_label is
+    # a Ruby method with no backing column, so by default the picker scans the
+    # first 500 rows and filters the label in Ruby. Define this class method to
+    # search via indexed SQL instead — it receives the query term and must
+    # return an ActiveRecord::Relation:
+    #
+    #   class Project < ApplicationRecord
+    #     include CurrentScope::Scopeable
+    #     def self.current_scope_searchable_scope(term)
+    #       where("name ILIKE ?", "%#{term}%")
+    #     end
+    #   end
+    #
+    # No default is provided — the host knows which column is indexed.
+  end
+end

data/lib/current_scope/sod_preflight.rb

@@ -0,0 +1,380 @@
+module CurrentScope
+  # Finds, before traffic does, the separation-of-duties actions that are going
+  # to raise CurrentScope::ConfigurationError: an action listed in
+  # config.sod_actions reaching a model that defines no current_scope_initiator.
+  #
+  # The raise itself is correct and stays (a silently skipped veto is the hole
+  # #73/#74 exist to prevent). What was wrong is WHEN a host learns about it —
+  # per request, from real traffic, including in :report mode, which promises
+  # that nothing changes for users. This answers the same question as soon as
+  # the routes exist, where the fix is cheap. (#133)
+  #
+  # "As soon as the routes exist" is BOOT in an eager-loading environment
+  # (production and staging — where a bake runs) and the first request in
+  # development, whose route set is lazy. The engine initializer says why.
+  #
+  # ADVISORY AND PARTIAL BY CONSTRUCTION, for the reason #134 recorded: the
+  # record a member action decides about comes from current_scope_record, an
+  # instance method whose value exists only mid-request, so "which model does
+  # invoices#approve gate?" is not statically knowable. What IS declared is
+  # current_scope_model (#50) — the type a controller's collection actions deal
+  # in. Under Rails' resource conventions that is the type its member actions
+  # load too, which makes it a good signal and not a proof:
+  #
+  #   false negative — a controller declaring no current_scope_model is never
+  #                    inspected, so its 500 still arrives with traffic. That
+  #                    gap is why the report-mode ledger row exists as well
+  #                    (Guard#diagnose_report_sod_initiator).
+  #   false positive — a controller whose member action loads a DIFFERENT type
+  #                    than its collection lists gets named against the wrong
+  #                    model. Costs a look; it can never break an app.
+  #
+  # Both limits are stated in the output the operator reads, not in a guide they
+  # will not open — the rule GrantDiagnosis.untargeted_caveat set.
+  module SodPreflight
+    # One scan's answer, carried as a value instead of left on the module.
+    #
+    # Every honesty rule this feature has needed — "an empty list is not an
+    # all-clear", "a run that skipped checks under-reports", "a run that
+    # inspected nothing proves nothing" — is a question about ONE scan. Holding
+    # that on a singleton made the answers depend on call order, needed a
+    # fail-closed special case for "never run", and made the rake task capture a
+    # flag next to the call so 140 lines later it still meant the right run.
+    # A value has none of those problems: you cannot ask a result you do not
+    # have. (#133 review — cubic, ie-predictability, ie-architecture all landed
+    # on this seam.)
+    Result = Struct.new(:rows, :inspected, :in_scope, :skipped, keyword_init: true) do
+      # Some check could not be completed, so the list under-reports.
+      def degraded? = skipped.any?
+
+      # The list cannot be read as an all-clear: either a check failed, or there
+      # was nothing to read because no controller in scope declared a model.
+      def blind? = degraded? || (inspected.zero? && in_scope.positive?)
+
+      def any? = rows.any?
+    end
+
+    # The subject recorded when the walk itself failed, rather than one host
+    # controller or model. Paired with a NoMethodError it identifies a bug in
+    # this gem — every host call-out is wrapped by a helper and carries its own
+    # subject, so it can never produce this pair.
+    SCAN_ITSELF = "the scan itself".freeze
+
+    class << self
+      # Scan the routed SoD actions and return a Result. PURE: it reads routes,
+      # declarations and models, and returns; rendering and logging belong to the
+      # callers (warn! for the log, `rails current_scope:report` for stdout), so
+      # scanning twice cannot emit twice.
+      #
+      # Free for the default config: sod_actions is [] until a host opts in, and
+      # nothing here touches a controller until it is not.
+      def scan
+        rows = []
+        skipped = []
+        inspected = 0
+        in_scope = 0
+
+        unless CurrentScope.config.sod_actions.empty?
+          begin
+            reflection = CurrentScope::GatingReflection.new
+            models = {}
+
+            sod_permissions.each do |controller, permission|
+              in_scope += 1
+              model = models.fetch(controller) {
+                models[controller] = declared_model_for(controller, reflection, skipped)
+              }
+              next if model.nil?
+
+              inspected += 1
+              next if defines_initiator?(model, skipped)
+
+              rows << [ permission, model ]
+            end
+          rescue StandardError => e
+            # AN ADVISORY MUST NEVER BE THE THING THAT BREAKS A BOOT, and that
+            # includes when the bug is OURS.
+            #
+            # This used to re-raise NoMethodError, copying GrantDiagnosis on the
+            # theory that host failures are absorbed by the two helpers below, so
+            # one arriving here can only be a gem bug worth surfacing. The
+            # reasoning holds; the CONSEQUENCE did not survive review. That
+            # sibling is only ever called from a rake task and a console view.
+            # This module is called from an engine initializer, so re-raising
+            # took a host's boot down — over a diagnostic — and aborted
+            # `current_scope:report`, the survey they run mid-rollout. The
+            # convention was borrowed from a module that never runs at boot.
+            #
+            # The distinction it was protecting is kept without the crash: a
+            # NoMethodError whose subject is the scan itself is reported as OUR
+            # bug rather than blamed on host config (see skip_summary), because
+            # every call into host code is wrapped by the helpers and carries the
+            # controller or model as its subject. Loud, attributed, and
+            # survivable. (#133 — Devin, PR #141)
+            #
+            # KEEP WHAT WAS FOUND. `rows` is built outside the begin precisely so
+            # a failure partway through cannot discard the findings already
+            # collected — in a large app one bad controller would otherwise hide
+            # every earlier SoD miss from both surfaces, which is the exact case
+            # this check exists to surface. The run is still marked as skipped,
+            # so an incomplete list never reads as a clean one. (#133 — cubic)
+            skipped << [ SCAN_ITSELF, e ]
+          end
+        end
+
+        Result.new(rows: rows, inspected: inspected, in_scope: in_scope, skipped: skipped)
+      end
+
+      # One message listing every action that will raise, plus the coverage
+      # behind an empty list. Log-only.
+      def warn!(result = scan)
+        skips = skip_summary(result)
+        Rails.logger&.warn(skips) if skips
+
+        if result.rows.empty?
+          return unless result.blind?
+
+          return Rails.logger&.warn(blind_message(result))
+        end
+
+        listed = result.rows.map { |permission, model|
+          "  #{permission} — #{model.name} defines no #{Resolver::INITIATOR_METHOD}"
+        }
+
+        Rails.logger&.warn(
+          "[CurrentScope] separation-of-duties preflight: #{result.rows.size} routed action(s) " \
+          "will raise CurrentScope::ConfigurationError on the first request that reaches them — " \
+          "in config.enforcement = :report exactly as in :enforce.\n" \
+          "#{listed.join("\n")}\n" \
+          "#{fix_line}\n#{caveat}"
+        )
+      end
+
+      # The limits of the answer, in the output rather than in a guide. Shared by
+      # the boot warning and `rails current_scope:report` so the two cannot drift
+      # into different versions of the same hedge (the drift #134 fixed for the
+      # untargeted-grant caveat).
+      # LINE-BROKEN on purpose. All five limits are real and two were added by
+      # review, so the answer to "this is a wall" is never fewer limits — it is
+      # structure. An unread caveat protects nobody, and this one is the only
+      # thing standing between a fallible list and a host deleting a four-eyes
+      # control. Its sibling GrantDiagnosis.untargeted_caveat is short for the
+      # same reason. (#133 review)
+      def caveat
+        [
+          "This list is PARTIAL — a lead, not a verdict. Confirm against the model before " \
+          "you change config.sod_actions.",
+          "  Silent when: the controller declares no current_scope_model (ABSENT is not " \
+          "cleared), or the model cannot be instantiated right now (no database connection " \
+          "yet, a custom initialize).",
+          "  Names the wrong thing when: the declared type is what the COLLECTION lists and " \
+          "a member action loads a different one; or current_scope_model branches on " \
+          "action_name, which is read here with no action in hand.",
+          "  Cannot happen at all: a finding against an action that turns out to be a " \
+          "COLLECTION action — the veto never reaches those."
+        ].join("\n")
+      end
+
+      # The two remedies are NOT coequal here, and this message must not present
+      # them as if they were. Defining the hook restores a control; removing the
+      # action from config.sod_actions DELETES a fraud control. On the raise in
+      # Resolver#sod_decision the cause is proven, so offering both plainly is
+      # right. This list can be wrong — it reads a declaration, not the record —
+      # so leading with "or just turn the veto off" invites a host to disable
+      # four-eyes on a false accusation. Lead with the hook; qualify the rest.
+      #
+      # PUBLIC beside #caveat, and for the identical reason: `rails
+      # current_scope:report` renders the SAME finding, so a private copy here
+      # guaranteed the correction reached one surface and not the other. It did
+      # exactly that for one commit. (#133 review)
+      def fix_line
+        "Fix: define #{Resolver::INITIATOR_METHOD} on each model listed (return nil to exempt a " \
+        "record). Only if the action was never meant to be four-eyes gated should you remove it " \
+        "from config.sod_actions — that removes the control rather than wiring it, so confirm " \
+        "the finding first."
+      end
+
+      # One line per run, naming the count and the distinct causes — never one
+      # line per controller. The failure this class expects most is a
+      # current_scope_model hook that reads request-scoped state, and that one
+      # fails for EVERY affected controller on every routes load; a per-row line
+      # would flood exactly the host it is trying to help. Every sibling
+      # diagnostic in this engine throttles for the same reason
+      # (Guard.warn_ledger_failure_once, Event.warn_missing_events_table_once,
+      # the cross-controller nudge's once-per-site set).
+      #
+      # Broken controllers are called out separately because their fix differs:
+      # the controller does not LOAD, which the gate will hit too. Derived from
+      # the error class, not carried as a flag — a NameError can only arrive from
+      # inside a controller's own body, because a missing controller CONSTANT
+      # became MissingController and returned nil earlier. That is the
+      # distinction GatingReflection#controller_class exists to keep.
+      #
+      # Returns the string (nil when nothing was skipped) rather than logging, so
+      # `rails current_scope:report` can render the same facts to stdout — the
+      # operator reading a terminal must not be told to go and find a log.
+      def skip_summary(result)
+        return nil if result.skipped.empty?
+
+        # NameError is a subclass of NoMethodError's parent, so test the gem-bug
+        # pair FIRST: only the scan-itself subject can carry one, and calling
+        # that a broken controller would send a host after their own code for a
+        # bug in ours.
+        ours = result.skipped.select { |subject, error|
+          subject == SCAN_ITSELF && error.instance_of?(NoMethodError)
+        }
+        broken = result.skipped.select { |subject, error|
+          error.is_a?(NameError) && subject != SCAN_ITSELF
+        }
+        detail = result.skipped.map { |subject, error| "#{subject} (#{error.class})" }.uniq.join(", ")
+
+        message = +"[CurrentScope] SodPreflight skipped #{result.skipped.size} check(s), so its " \
+                   "list is INCOMPLETE — absence below is not an all-clear: #{detail}."
+        if ours.any?
+          message << " That NoMethodError came from the scan itself, not from your app — it is " \
+                     "a bug in current_scope. Please report it; nothing in your configuration " \
+                     "needs changing for it."
+        end
+        if broken.any?
+          message << " #{broken.size} of those did not LOAD (#{broken.map(&:first).uniq.join(', ')}) " \
+                     "— that is a broken controller, not a missing declaration, and the gate will " \
+                     "fail there too."
+        end
+        message
+      end
+
+      private
+
+      def blind_message(result)
+        reason =
+          # DEGRADED WINS, and the order is the whole finding. Both conditions
+          # are true when declared_model_for fails for every controller —
+          # `inspected` only counts a successfully READ declaration, so a run
+          # whose checks all blew up looks identical to one that found nothing
+          # to read. Leading with "none of those controllers declares
+          # current_scope_model" then sends an operator off to add declarations
+          # when their hook is raising. (#133 — qodo, PR #141)
+          if result.degraded?
+            "it was not able to look properly (some checks were skipped; see the lines above)"
+          elsif result.inspected.zero? && result.in_scope.positive?
+            "it inspected NONE of the #{result.in_scope} routed SoD action(s) — none of those " \
+            "controllers declares current_scope_model, so there was nothing to read"
+          else
+            "it was not able to look properly"
+          end
+
+        "[CurrentScope] separation-of-duties preflight found nothing, and #{reason}. Do NOT " \
+        "read that as an all-clear. Re-run `rails current_scope:report` once the app is fully " \
+        "up.\n#{caveat}"
+      end
+
+      # [[controller_path, permission], ...] for every ROUTED SoD action.
+      #
+      # routed?, not include?: the catalog also injects the break-glass key, and
+      # an injected key gates no request, so it can never raise. (The bypass
+      # permission is barred from sod_actions by Configuration#validate! anyway;
+      # asking the catalog costs one set lookup and removes the question.)
+      def sod_permissions
+        actions = CurrentScope.config.sod_actions
+        catalog = CurrentScope.catalog
+
+        catalog.grouped.flat_map do |controller, controller_actions|
+          (controller_actions & actions).filter_map do |action|
+            key = "#{controller}##{action}"
+            [ controller, key ] if catalog.routed?(key)
+          end
+        end
+      end
+
+      # The type this controller declared, or nil when it declared none, nothing
+      # is routed there, or asking failed. Mirrors Guard#resolve_current_scope_model
+      # — same private hook, same respond_to?(…, true) discovery — because a
+      # second spelling of "what did the host declare?" is a second spelling that
+      # drifts.
+      def declared_model_for(controller_path, reflection, skipped)
+        klass = reflection.controller_class(controller_path)
+        return nil if klass.nil?
+
+        instance = klass.new
+        return nil unless instance.respond_to?(:current_scope_model, true)
+
+        model = instance.send(:current_scope_model)
+        # ASK the resolver for the shape rule rather than re-spelling its three
+        # terms here: a concrete ActiveRecord class. Anything else cannot be the
+        # record an SoD veto measures, so there is nothing to prove and this
+        # stays silent — a mis-declared type is :model_invalid's job, not this
+        # one's. (An inline copy is the #74 re-derivation defect, and this file
+        # already avoids it for the initiator check.)
+        return nil unless CurrentScope.resolver.collection_type?(model)
+
+        model
+      rescue StandardError => e
+        # HOST CODE RUNS HERE — an instance method, on a controller built outside
+        # a request. A hook that reads params is the likeliest failure and must
+        # be absorbed, never raised: this is an advisory.
+        #
+        # A NameError is called out separately because GatingReflection was made
+        # public precisely to preserve Rails' triage — a missing controller
+        # constant became MissingController (already nil above), so a NameError
+        # arriving HERE came from inside the controller's own body. Folding that
+        # into the same "could not inspect" line as a params-reading hook would
+        # report a broken controller exactly like a fine one, which is the
+        # distinction that reflection exists to keep. (#133 review)
+        skipped << [ controller_path, e ]
+        nil
+      end
+
+      # ASKS an instance the same question the resolver asks the record, rather
+      # than re-deriving it as method_defined?: respond_to?(…, true) also honours
+      # protected/private definitions and respond_to_missing?, and re-deriving a
+      # condition another component owns is the defect this codebase keeps paying
+      # for (#74).
+      #
+      # When an instance IS built (only for a candidate finding, see below),
+      # Model.new issues no QUERY but is not connection-free: the first
+      # instantiation loads the schema to build the attribute set. On a boot with
+      # no reachable database (asset precompile, a container started before its
+      # DB) that raises, the model reads as compliant, and the list is quieter
+      # for a reason the operator cannot see — which is why the caveat names it
+      # and the Result reports it as skipped.
+      # CHEAP CHECK FIRST, exact check only before accusing.
+      #
+      # The resolver asks `record.respond_to?(INITIATOR_METHOD, true)`, and
+      # matching it exactly would mean instantiating every declared model at
+      # boot — running whatever the host put in `initialize` and
+      # `after_initialize`, for models that are almost all fine. So ask the CLASS
+      # first: for an ordinary `def`, an `alias`, or an association reader (all
+      # defined as real methods when the class body runs) the class-level answer
+      # and the instance-level answer are identical, and the overwhelming
+      # majority of models stop here having executed no host code at all.
+      #
+      # They diverge only for a hook reachable through respond_to_missing? /
+      # method_missing. That divergence can only produce a FALSE ACCUSATION —
+      # the class says "not defined" when an instance would say otherwise — so
+      # the instance check is kept exactly there, as the confirmation before this
+      # module names a model. A model that is fine is never built; a model about
+      # to be flagged is, because an accusation must be right. (#133 review —
+      # cubic)
+      def defines_initiator?(model, skipped)
+        return true if class_level_initiator?(model)
+
+        model.new.respond_to?(Resolver::INITIATOR_METHOD, true)
+      rescue StandardError => e
+        # Could not tell (a custom initialize, an after_initialize that needs a
+        # request, no database connection yet) ⇒ say nothing. Prove or stay
+        # silent, and mark the run so its silence is not read as a clean bill.
+        skipped << [ model.name || model.inspect, e ]
+        true
+      end
+
+      # All three visibilities, because the resolver's respond_to?(…, true) sees
+      # all three and a public-only check would flag a model whose hook is
+      # private — which is how the engine's own docs suggest writing host hooks.
+      def class_level_initiator?(model)
+        m = Resolver::INITIATOR_METHOD
+        model.method_defined?(m) || model.private_method_defined?(m) ||
+          model.protected_method_defined?(m)
+      end
+    end
+  end
+end