current_scope 0.5.0

data/lib/current_scope/engine.rb

@@ -0,0 +1,202 @@
+module CurrentScope
+  class Engine < ::Rails::Engine
+    isolate_namespace CurrentScope
+
+    # An AccessDenied that escapes any Guard rescue (PORO, Context-only
+    # controller, re-raise) must 403, not 500. Never turns a deny into an
+    # allow — the exception already blocked the action (#39).
+    #
+    # ||= so a host that already set this mapping (e.g. :not_found to hide
+    # existence) in config/application.rb is not clobbered. before:
+    # action_dispatch.configure so ExceptionWrapper.rescue_responses picks the
+    # entry up when it merge!s the config hash.
+    initializer "current_scope.rescue_responses", before: "action_dispatch.configure" do |app|
+      app.config.action_dispatch.rescue_responses["CurrentScope::AccessDenied"] ||= :forbidden
+    end
+
+    # Belt for Rails upgrades: if action_dispatch.configure is renamed/reordered
+    # and the config merge is missed, still pin the class map. Use key? — the
+    # ExceptionWrapper hash defaults missing keys to :internal_server_error
+    # (truthy), so ||= would never write.
+    initializer "current_scope.rescue_responses_apply", after: "action_dispatch.configure" do
+      map = ActionDispatch::ExceptionWrapper.rescue_responses
+      map["CurrentScope::AccessDenied"] = :forbidden unless map.key?("CurrentScope::AccessDenied")
+    end
+
+    # The `current_scope_parent` declaration (#108). on_load rather than a
+    # host-included concern: it is an acts_as_*-style class macro, and hanging it
+    # off CurrentScope::Scopeable would both contradict that module's BROWSE-ONLY
+    # contract and register every parent-declaring model in the scoped-role
+    # picker as a side effect. instance_accessor: false because the declaration is
+    # a class-level fact and is only ever read through the class; an instance
+    # reader would blur that. (It does NOT collide with the method-form mistake
+    # ParentChain.reject_method_form! catches — that one is named
+    # current_scope_parent, a different method entirely.)
+    initializer "current_scope.parent_chain" do
+      ActiveSupport.on_load(:active_record) do
+        class_attribute :current_scope_parent_association,
+                        instance_accessor: false,
+                        default: nil
+        extend CurrentScope::ParentChain::Declaration
+      end
+    end
+
+    # Cross-field config invariants (e.g. bypass permission ∉ sod_actions) must
+    # run AFTER the host initializer has assigned every field — a writer on
+    # either attr alone is order-dependent. once, not on to_prepare (config
+    # does not change on code reload). #40.
+    config.after_initialize do
+      CurrentScope.config.validate!
+      # Two separate checks. The schema guard asks whether the DATABASE has the
+      # shape #151 requires (SchemaGuard); this one asks whether the configured
+      # subject CLASS can be named by one id. Different questions, different
+      # failure messages, so they are not folded together.
+      CurrentScope::SchemaGuard.check!
+    end
+
+    # Routes (and therefore the derived permission catalog) can change on
+    # every code reload in development, and reloaded host models must re-register
+    # as scopeable rather than pile up stale/duplicate entries. Both reset here,
+    # ahead of eager-load, so the registry rebuilds cleanly.
+    config.to_prepare do
+      # Resolve the host's reloadable subject model only from the reload-safe
+      # callback, not after_initialize. The write validation remains the
+      # fail-closed guarantee; this is the early diagnostic.
+      CurrentScope::Engine.validate_subject_key!
+      CurrentScope.reset_catalog!
+      CurrentScope.reset_scopeable_registry!
+      # The cross-controller nudge warns once per site; a reload can change what's
+      # routed, so a stale latch would hide a divergence the edit just created.
+      CurrentScope.reset_cross_controller_warnings!
+      # Same reason for the tripwire's :warn latch: a reload can change whether a
+      # controller#action is gated, and a stale latch would hand a dev running
+      # :warn a false all-clear right after the edit.
+      CurrentScope::GatingTripwire.reset_warnings!
+      # Same reason: a reload can change a declared chain, and a latched
+      # truncation warning would hide the one the edit just created.
+      CurrentScope::ParentChain.reset_warnings!
+      # Declaration validation that needs reflection.klass runs HERE, not on the
+      # request path, so a bad declaration is caught before traffic. This pass is
+      # the DEVELOPMENT one: to_prepare runs before :eager_load!, so it sees only
+      # models something else already loaded — but it re-runs on every reload, so
+      # a dev's coverage grows as they work. The authoritative pass is the
+      # eager-load one below. (#139)
+      CurrentScope::ParentChain.validate_declarations!
+    end
+
+    # #139: the pass that sees every declaring model that was eager-loaded.
+    #
+    # Railties runs :run_prepare_callbacks (the to_prepare above) BEFORE
+    # :eager_load!, with the source comment "This needs to happen before eager
+    # load so it happens in exactly the same point regardless of
+    # config.eager_load". So that pass reads a registry holding only whatever
+    # was already loaded — in production, close to nothing — and the ONE check
+    # it performs could be skipped entirely for a model nobody had touched yet.
+    #
+    # That check is not cosmetic. validate_key! is the only guard anywhere
+    # against a current_scope_parent on a belongs_to with a custom
+    # `primary_key:`, and nothing on the request path repeats it. Unvalidated,
+    # both scope_for and the unloaded load_parent walk key the parent on its
+    # primary key — comparing values from different columns. Both hide records
+    # the grant should reach AND surface / open unrelated ones whose
+    # foreign-key value happens to collide with a granted parent's id. With a
+    # numeric custom key that collision space is dense. See the
+    # characterization test in test/parent_chain_test.rb.
+    #
+    # Gated on eager_load, which is the whole point: where it is on, declaring
+    # models that were eager-loaded are already in the registry, so this pass
+    # does not walk the autoloader looking for *new* declarers. Where it is off
+    # (development), the registry is partial anyway and running this would
+    # safe_constantize reloadable names during initialization — the thing Rails
+    # tells you not to do, and which pins constants that the first reload then
+    # makes stale. Development keeps the to_prepare pass, which re-runs and
+    # catches up.
+    #
+    # Residual autoload of association TARGETS still exists: validate_key!
+    # resolves reflection.klass, so a parent model kept off the eager-load
+    # surface can load on first validation. That is the same partial-coverage
+    # bargain as do_not_eager_load for declaring models, and it is named in
+    # UPGRADING.md rather than implied away by "nothing here autoloads".
+    #
+    # after_initialize (not after: :eager_load!) so we sit in the same finisher
+    # window as other boot checks. Order among after_initialize blocks is
+    # registration order: a host that first loads a declaring model from a
+    # *later* after_initialize still misses this pass — same residual family,
+    # documented in UPGRADING.md.
+    config.after_initialize do |app|
+      CurrentScope::ParentChain.validate_declarations! if app.config.eager_load
+    end
+
+    # #133: a deploy must not boot green and 500 on the first gated request. An
+    # SoD action whose model defines no current_scope_initiator raises per
+    # request — in :report mode too, which is where it hurts most, because
+    # report mode is what a host turns on to survey live traffic without
+    # changing anything for users.
+    #
+    # WHEN this fires is "as soon as the routes exist", which is boot only where
+    # routes load during initialization. Railties ends set_routes_reloader_hook
+    # with `reloader.execute_unless_loaded if !app.routes.is_a?(Engine::
+    # LazyRouteSet) || app.config.eager_load` — so an eager-loading environment
+    # (production, staging, the environments a bake actually runs in) warns at
+    # boot, while development's lazy route set defers it to the first request or
+    # reload. Forcing the routes early to make "boot" literally true would
+    # defeat LazyRouteSet for every host to make one log line punctual.
+    #
+    # after_routes_loaded, NOT to_prepare, and that is load-bearing. The
+    # preflight reads CurrentScope.catalog, and the catalog MEMOIZES its
+    # derivation — so asking it before the routes are drawn caches an EMPTY
+    # permission set for the life of the process, and every gated request then
+    # raises "not in the permission catalog". Measured, not reasoned: the dummy
+    # app booted with 44 catalog keys and 0 with the check on to_prepare. This
+    # hook is the one place Rails guarantees the route set is complete, and it
+    # re-runs on every routes reload, so a dev edit is re-checked.
+    #
+    # WHAT THIS ACTUALLY EXECUTES, because "log-only" undersold it: one
+    # `klass.new` per routed SoD controller, to read its current_scope_model
+    # declaration (an instance method — there is no other way to ask). Declared
+    # MODELS are answered from the class and are NOT instantiated unless the
+    # scan is about to name one, so a host's `after_initialize` runs only for a
+    # model that is already a candidate finding. Failures are absorbed and surfaced through
+    # the scan Result's skipped list, so the risk is not a crash — it is that a side
+    # effect in a host constructor has already happened by the time the rescue
+    # runs. Nothing here writes to the database, and it is a no-op until a host
+    # opts into SoD (config.sod_actions defaults to []).
+    initializer "current_scope.sod_preflight" do |app|
+      app.config.after_routes_loaded do
+        CurrentScope::SodPreflight.warn!
+      end
+    end
+
+    # #151. subject_id/resource_id are string columns now, so an integer key and a
+    # UUID both store whole and there is nothing left to scan stored rows for.
+    # What a config value CAN still name is a subject class whose primary key is
+    # not one value — composite, or absent — which no grant could ever identify.
+    # Cheap early warning; the write validations are the guarantee.
+    #
+    # Silent when it cannot introspect (no connection, no table, unresolved
+    # class): "unknown" must not become "broken", or `rails db:create` on a fresh
+    # checkout would raise.
+    def self.validate_subject_key!
+      # Skip during database tasks, exactly as SchemaGuard does. This runs from
+      # to_prepare, which also fires during `rails db:migrate`; a composite or
+      # absent subject key would otherwise raise BEFORE the host can run the very
+      # migration that fixes it. The write-path validation stays the fail-closed
+      # guarantee, so skipping the early diagnostic here loses nothing.
+      return if CurrentScope::SchemaGuard.running_a_database_task?
+
+      klass = CurrentScope.config.subject_class
+      klass = klass.to_s.safe_constantize if klass.is_a?(String) || klass.is_a?(Symbol)
+      return unless klass.respond_to?(:primary_key)
+      return if CurrentScope.storable_key?(klass)
+
+      raise ConfigurationError, CurrentScope.unstorable_key_error(klass, role: "subject")
+    rescue ActiveRecord::ActiveRecordError
+      # This rescue is scoped to THIS check on purpose. It exists to keep an
+      # unknown subject class quiet; the schema guard must never share it, or a
+      # transient database error at boot would read as "all clear" and the host
+      # would serve with the escalation live — a security guard failing open.
+      Rails.logger&.warn("[CurrentScope] subject key check skipped — could not introspect the database (#151).")
+      nil
+    end
+  end
+end

data/lib/current_scope/gating_reflection.rb

@@ -0,0 +1,113 @@
+module CurrentScope
+  # Answers one question about a controller path: is it PROVEN that
+  # current_scope_check! never runs there? True only when the callback is
+  # ABSENT from the class's callback chain — the one thing the chain states
+  # unconditionally. Everything else is false:
+  #
+  #   - callback present and unconditional → gated → false
+  #   - callback present wearing a condition (skip_before_action only:) →
+  #     UNPROVABLE without evaluating ActionFilter internals, which this class
+  #     must never do (KTD-3) → false. The naive any?/none? presence check
+  #     inverts exactly here — see the ProblemFrame characterization in
+  #     test/gating_reflection_test.rb — and per-action guessing is how a
+  #     fail-open gets reported as gated.
+  #   - no controller class routed at that path → nothing to prove → false
+  #
+  # Absence is an EFFECT, not a cause: a bare skip_before_action, an inherited
+  # bare skip (#62), and never including Guard at all are the same verdict,
+  # because the chain looks the same. That is deliberate — the question is
+  # "does the gate run?", not "why not?".
+  #
+  # Named beside GatingTripwire: both interrogate the same subject (is this
+  # action gated?), the tripwire at request time, this one by reflection.
+  class GatingReflection
+    def ungated?(controller_path)
+      klass = controller_class_for(controller_path)
+      # A controller without the callbacks API at all (a bare ActionController::
+      # Metal without AbstractController::Callbacks) cannot run a before_action
+      # — the gate PROVABLY never runs there. Without this check the reflection
+      # would raise NoMethodError instead of answering. (#79 review)
+      return true unless klass.respond_to?(:_process_action_callbacks)
+
+      klass
+        ._process_action_callbacks
+        .none? { |callback| callback.kind == :before && callback.filter == :current_scope_check! }
+    rescue ActionDispatch::MissingController
+      # A routed path with no controller class (a scaffolding leftover, a
+      # not-yet-written controller) proves nothing about gating. Silent false,
+      # matching the prove-or-stay-silent discipline of
+      # warn_on_cross_controller_derivation. Surface that shape via
+      # #missing_controller? instead — the grid badges it (#43).
+      false
+    end
+
+    # True when the path is routed but no controller class loads (stale route /
+    # typo). Distinct from ungated?: there is nothing to gate. Hitting the
+    # route is ActionDispatch::MissingController (a 500 in production), so the
+    # role grid flags the row (#43). Uses the same Rails path→class rule as
+    # #ungated? so the two answers cannot disagree on loadability.
+    def missing_controller?(controller_path)
+      controller_class_for(controller_path)
+      false
+    rescue ActionDispatch::MissingController
+      true
+    end
+
+    # Reason from current_scope_skip_gate!(reason:), or nil when ungated without
+    # a declaration (bare skip / never included). Meaningful when #ungated?
+    # is true (#76).
+    def declared_skip_reason(controller_path)
+      klass = controller_class_for(controller_path)
+      return nil unless klass.respond_to?(:current_scope_gate_skip_reason)
+
+      klass.current_scope_gate_skip_reason.presence
+    rescue ActionDispatch::MissingController
+      nil
+    end
+
+    # The controller class routed at this path, or nil when none is (a stale
+    # route, a not-yet-written controller). PUBLIC because SodPreflight (#133)
+    # asks the same path→class question, and a second copy would have to
+    # reimplement the NameError triage described below — the one thing that
+    # keeps a broken controller from being reported as a clean one.
+    #
+    # This is not a second way to ask the same question, and the difference is
+    # the whole point: `controller_class_for` RAISES MissingController — every
+    # private caller above rescues it into its own answer (`ungated?` → false,
+    # `missing_controller?` → true, `declared_skip_reason` → nil), because those
+    # three mean different things by "no class here". This one is the fourth such
+    # answer, spelled nil, and it delegates rather than reimplements, so there is
+    # still exactly one path→class rule. What must NOT be added is a public
+    # method that swallows the NameError too. (#133 review — cubic)
+    def controller_class(controller_path)
+      controller_class_for(controller_path)
+    rescue ActionDispatch::MissingController
+      nil
+    end
+
+    private
+
+    # Rails owns the path→class rule — camelize, namespacing, the Controller
+    # suffix, and crucially the NameError triage: a missing CONTROLLER constant
+    # becomes MissingController (rescued above), while a NameError raised from
+    # inside the controller's own broken body re-raises as-is and must
+    # PROPAGATE out of ungated? (a blanket rescue NameError would silently
+    # report a broken controller as gated). Hand-rolling camelize+constantize
+    # would have to reimplement that triage and would drift. (KTD-2)
+    #
+    # controller_class_for lives on Request, so a throwaway request object is
+    # the price of asking. Built lazily and memoized here, NEVER in initialize:
+    # the role-save path constructs a GatingReflection it may never ask — any
+    # failure in construction would 500 role saves. (KTD-8)
+    # Memoize path→class for the life of this reflection instance. The role
+    # editor asks ungated? and missing_controller? per row; without a cache
+    # that is two constantizes per controller (cubic P2 on #43).
+    def controller_class_for(controller_path)
+      @class_for ||= {}
+      return @class_for[controller_path] if @class_for.key?(controller_path)
+
+      @request ||= ActionDispatch::Request.new({})
+      @class_for[controller_path] = @request.controller_class_for(controller_path)
+    end
+  end
+end

data/lib/current_scope/gating_tripwire.rb

@@ -0,0 +1,84 @@
+module CurrentScope
+  # A4: an opt-in dev/test tripwire that catches an action which completed
+  # WITHOUT being gated by Guard's current_scope_check!. Include it on a base
+  # controller you want verified — INCLUDING one that never includes Guard (an
+  # API base, a hand-rolled ActionController::Base), which is exactly the
+  # ungated case Guard's own after_action could never see.
+  #
+  #   class ApiController < ActionController::Base
+  #     include CurrentScope::GatingTripwire
+  #     current_scope_skip_tripwire! only: :health   # mark genuinely-public actions
+  #   end
+  #
+  # It owns its skip API on purpose: it can NOT reuse
+  # `skip_before_action :current_scope_check!`, because on a controller that
+  # never included Guard that callback is undefined and skip_before_action
+  # raises ArgumentError at class load — self-defeating on the very controllers
+  # the tripwire targets. `current_scope_skip_tripwire!` skips the tripwire's own
+  # after_action instead.
+  #
+  # Known blind spot: an after_action does not run when a before_action halts the
+  # chain (render/redirect) — so an action that renders straight from a
+  # before_action escapes the tripwire. It is a strong dev/test aid, not total
+  # coverage (Grape/Rack endpoints are out of reach for the same reason).
+  # What a catch DOES is config.gating_tripwire (:raise in dev/test, :warn
+  # elsewhere) — :warn logs each ungated controller#action once instead of
+  # 500ing, so a real app can inventory its ungated surface.
+  module GatingTripwire
+    extend ActiveSupport::Concern
+
+    class << self
+      # The :warn latch. ponytail: a plain Set, not a Mutex — worst case under
+      # a race is one extra line, and a flood is the thing being prevented.
+      # Per-SITE, not per-process (unlike Guard.ledger_warning_emitted?): the
+      # point of :warn is an inventory, so every distinct controller#action
+      # must get its own line.
+      def warning_unseen?(site)
+        @warned ||= Set.new
+        @warned.add?(site) ? true : false
+      end
+
+      # Cleared on engine to_prepare — a reload can change whether a site is
+      # gated, so a stale latch is a false all-clear — and by tests.
+      def reset_warnings!
+        @warned = nil
+      end
+    end
+
+    included do
+      after_action :current_scope_verify_gated!
+    end
+
+    class_methods do
+      # The tripwire's OWN exempt marker. Accepts the usual callback filters
+      # (only:/except:) and simply skips the tripwire after_action for them.
+      def current_scope_skip_tripwire!(**options)
+        skip_after_action :current_scope_verify_gated!, **options
+      end
+    end
+
+    private
+
+    def current_scope_verify_gated!
+      # Guard sets @current_scope_checked when current_scope_check! runs. A
+      # controller carrying only this mixin (no Guard) never sets it.
+      return if instance_variable_defined?(:@current_scope_checked) && @current_scope_checked
+
+      raise CurrentScope::ConfigurationError, current_scope_tripwire_message if CurrentScope.config.gating_tripwire == :raise
+
+      # :warn — same remediation text, once per controller#action. The latch
+      # check comes first so an already-warned site (every request after the
+      # first, on a fail-open that keeps serving traffic) pays no string build.
+      return unless GatingTripwire.warning_unseen?("#{controller_path}##{action_name}")
+
+      Rails.logger&.warn("[CurrentScope] #{current_scope_tripwire_message}")
+    end
+
+    def current_scope_tripwire_message
+      "\"#{controller_path}##{action_name}\" completed without running current_scope_check! — " \
+        "this controller is not gated by CurrentScope::Guard. Include CurrentScope::Guard on its " \
+        "base controller, or mark this action public with " \
+        "`current_scope_skip_tripwire! only: :#{action_name}`."
+    end
+  end
+end

data/lib/current_scope/grant_diagnosis.rb

@@ -0,0 +1,216 @@
+module CurrentScope
+  # Judges a scoped grant. Two methods, two certainties:
+  #
+  #   verdict_for      PROVEN — the grant cannot match anything, for any type.
+  #   type_untargeted? ADVISORY — suggestive only; the host's runtime hooks
+  #                    decide what a controller resolves to, so this can be
+  #                    wrong and says so where the operator reads it.
+  #
+  # Neither is #90's "inert" (the RECORD is gone; different fix).
+  # Design rationale: docs/plans/2026-07-28-032-feat-unresolvable-grant-guardrail-plan.md
+  module GrantDiagnosis
+    class << self
+      # Proven, or nil. Never guesses.
+      def verdict_for(grant)
+        return nil if orphaned?(grant)
+
+        role = grant.role
+        return nil if role.nil? || role.full_access?
+
+        keys = persisted_keys(role)
+        # Checked BEFORE the catalog guard: a role with nothing ticked can never
+        # match whatever the catalog says, so deferring to "no verdict" here
+        # would downgrade a proven finding to an advisory.
+        return :no_permissions if keys.empty?
+
+        # An empty catalog means routes are not derived yet, not that every key
+        # is dead. Only the unrouted claim depends on it.
+        return nil if CurrentScope.catalog.keys.empty?
+        return :unrouted_permissions if keys.none? { |key| live?(key, resource_class(grant)) }
+
+        nil
+      rescue NameError, ActiveRecord::ActiveRecordError => e
+        raise if e.instance_of?(NoMethodError)
+
+        log_degrade(e)
+        nil
+      end
+
+      # `verdict:` lets a caller that already has it skip the recompute (three
+      # role_permissions plucks per grant otherwise).
+      def type_untargeted?(grant, verdict: :__unset)
+        verdict = verdict_for(grant) if verdict == :__unset
+        return false unless verdict.nil?
+        return false if orphaned?(grant)
+
+        role = grant.role
+        return false if role.nil? || role.full_access?
+
+        return false unless ensure_models_loaded!
+
+        klass = resource_class(grant)
+        return false if klass.nil? # unresolvable class is #90's inert, not ours
+
+        keys = persisted_keys(role)
+        return false if keys.any? { |key| routed?(key) && targets_any_route_key?(key, klass) }
+
+        # #108: a grant on a PARENT legitimately reaches its children, so stay
+        # silent when any declared chain reaches this class.
+        !reachable_through_declared_chain?(klass, keys)
+      rescue NameError, ActiveRecord::ActiveRecordError => e
+        raise if e.instance_of?(NoMethodError)
+
+        log_degrade(e)
+        false
+      end
+
+      # The advisory's caveat, centralised for the same reason the proven wording
+      # is: the console and the CLI had drifted into two versions of it.
+      def untargeted_caveat
+        "This is NOT a verdict. Only your current_scope_record hooks decide which " \
+        "records a controller resolves to, and that is not knowable statically. A " \
+        "controller serving this type under a different name is a false alarm here. " \
+        "Check the hook before removing anything."
+      end
+
+      # One wording, so the task and the view cannot drift.
+      def verdict_label(verdict)
+        case verdict
+        when :no_permissions       then "role ticks no permissions"
+        when :unrouted_permissions then "role ticks only unrouted keys"
+        end
+      end
+
+      def verdict_fix(verdict)
+        case verdict
+        when :no_permissions
+          "Tick at least one permission on this role, or remove the grant."
+        when :unrouted_permissions
+          "Every key on this role is absent from the route-derived catalog, so " \
+          "nothing can ever gate them. Re-tick the role against current routes."
+        end
+      end
+
+      private
+
+      # #90's state, not ours — two badges naming different remedies on one
+      # grant is the confusion this feature exists to end.
+      # Never the STAGED keys Role#permission_keys returns after a failed save.
+      def persisted_keys(role)
+        role.role_permissions.pluck(:permission_key)
+      end
+
+      def log_degrade(error)
+        Rails.logger&.warn(
+          "[CurrentScope] GrantDiagnosis could not judge a scoped grant " \
+          "(#{error.class}: #{error.message}); reporting no finding for it."
+        )
+      end
+
+      def orphaned?(grant)
+        grant.respond_to?(:orphaned_resource?) && grant.orphaned_resource?
+      end
+
+      # A polymorphic grant stores the STI BASE class, but the routed controller
+      # is named after the SUBCLASS — so a grant on an Invoice (stored
+      # "Document") whose role ticks "invoices#show" WORKS and must not be
+      # flagged. Check every route key in the hierarchy.
+      def targets_any_route_key?(key, klass)
+        ([ klass ] + klass.descendants).any? do |candidate|
+          targets_route_key?(key, candidate.model_name.route_key)
+        end
+      rescue StandardError
+        true # unknown hierarchy: stay silent, never flag on a guess
+      end
+
+      # declared_names fills as model classes LOAD. With eager loading off (the
+      # default in development, where this task is run) the chain lookup is
+      # blind and would flag the very #108 grants it exists to protect — and
+      # order-dependently, since an earlier row could load the model. Force the
+      # load once.
+      # Returns false when the registry may be incomplete, so the caller stays
+      # silent rather than negating a partial answer into an advisory. Latches
+      # only on success, so a transient failure can retry.
+      def ensure_models_loaded!
+        return true if @models_loaded
+
+        Rails.application.eager_load! unless Rails.application.config.eager_load
+        @models_loaded = true
+      rescue StandardError => e
+        log_degrade(e)
+        false
+      end
+
+      # Walks the same declared reflections the resolver walks, so the two
+      # cannot disagree about what a chain reaches.
+      def reachable_through_declared_chain?(klass, keys)
+        CurrentScope::ParentChain.declared_names.any? do |name|
+          child = name.safe_constantize
+          next false if child.nil?
+          next false unless keys.any? { |key| routed?(key) && targets_any_route_key?(key, child) }
+
+          chain_reaches?(child, klass)
+        end
+      end
+
+      def chain_reaches?(child, klass)
+        current = child
+        CurrentScope::ParentChain::MAX_PARENT_DEPTH.times do
+          reflection = CurrentScope::ParentChain.reflection_for(current)
+          return false if reflection.nil?
+          return true if reflection.klass.base_class == klass.base_class
+
+          current = reflection.klass
+        end
+        false
+      end
+
+      def resource_class(grant)
+        klass = grant.resource_type&.safe_constantize
+        klass.respond_to?(:model_name) ? klass : nil
+      end
+
+      # Can this key ever open anything for THIS grant? Routed keys can. So can
+      # the catalog's injected break-glass key — but only on the rows it was
+      # injected onto, so the exemption is row-local: a bypass key for another
+      # type cannot lift anything here.
+      def live?(key, klass)
+        return true if CurrentScope.catalog.routed?(key)
+
+        return false unless injected?(key)
+
+        # A FULL sod_bypass_permission ("claims#bypass_sod") is the key the
+        # resolver checks for every record, so it is live on any grant and the
+        # row-local heuristic must not apply. Only a bare action is per-row.
+        configured = CurrentScope.config.sod_bypass_permission.to_s
+        return key == configured if configured.include?("#")
+
+        !klass.nil? && targets_any_route_key?(key, klass)
+      end
+
+      def injected?(key)
+        CurrentScope.catalog.include?(key) && !CurrentScope.catalog.routed?(key)
+      end
+
+      def routed?(key)
+        CurrentScope.catalog.routed?(key)
+      end
+
+      # Wider than CurrentScope.permission_key's comparison: a controller segment
+      # CONTAINING the route key counts, and both the namespaced and collapsed
+      # forms are tried. Biased toward false negatives on purpose. Pins:
+      # test/grant_diagnosis_test.rb (nested_reports, namespaced).
+      def targets_route_key?(key, route_key)
+        controller = key.split("#").first.to_s
+        # BOTH forms: a namespaced model keeps its namespace in the route key
+        # (Billing::Invoice -> "billing_invoices") while the controller path
+        # splits it ("billing/invoices"), so comparing only the last segment
+        # falsely flags the conventional Rails layout.
+        [ controller.tr("/", "_"), controller.split("/").last.to_s ].any? do |segment|
+          segment == route_key ||
+            segment.end_with?("_#{route_key}") || segment.start_with?("#{route_key}_")
+        end
+      end
+    end
+  end
+end