current_scope 0.2.0 → 0.3.1

data/app/controllers/current_scope/role_assignments_controller.rb

@@ -16,16 +16,35 @@ module CurrentScope
       # only the subjects that ACTUALLY changed so the notice can't over-report
       # (a re-set to the same role, or a clear on a subject with no role, is a
       # no-op and shouldn't be counted).
+      #
+      # Lock full-access holders inside the same transaction as the writes so
+      # concurrent clears cannot both observe "another holder remains" and then
+      # both proceed to zero holders.
       changed = 0
+      refused = false
       RoleAssignment.transaction do
-        subjects.each do |subject|
-          assignment = RoleAssignment.find_or_initialize_by(subject: subject)
-          prior_role = assignment.role # nil for a brand-new assignment
-          did = clearing ? clear_org_role(subject, assignment, prior_role) : set_org_role(subject, assignment, prior_role)
-          changed += 1 if did
+        lock_full_access_org_holders!
+
+        if would_remove_last_full_access_holders?(subjects, clearing: clearing)
+          refused = true
+        else
+          subjects.each do |subject|
+            assignment = RoleAssignment.find_or_initialize_by(subject: subject)
+            prior_role = assignment.role # nil for a brand-new assignment
+            did = clearing ? clear_org_role(subject, assignment, prior_role) : set_org_role(subject, assignment, prior_role)
+            changed += 1 if did
+          end
         end
       end
 
+      if refused
+        redirect_back_or_to subjects_path,
+                            alert: "Refusing to remove the last full-access org-wide assignment — " \
+                                   "it would lock everyone out of this UI. Grant full access to " \
+                                   "another subject first, then retry."
+        return
+      end
+
       # Return to wherever the action was invoked (the subjects page or a role's
       # members page); falls back to subjects when there's no referrer.
       redirect_back_or_to subjects_path, notice: org_notice(clearing, changed)
@@ -37,14 +56,32 @@ module CurrentScope
     # clean up an orphaned assignment whose subject was deleted (the subject-keyed
     # clear on `create` can't target a subject that no longer resolves).
     def destroy
-      assignment = RoleAssignment.find(params[:id])
-      subject = resolve_subject(assignment)
-      role_name = assignment.role.name
-
+      refused = false
       RoleAssignment.transaction do
-        assignment.destroy!
-        Event.record!(event: "org_role.removed", target: subject || assignment, details: { role: role_name })
+        # Lock FA state BEFORE the target assignment so order matches create/
+        # role demote/delete (FA roles → FA holders → target row). Locking the
+        # assignment first inverted that order and could deadlock.
+        lock_full_access_org_holders!
+        assignment = RoleAssignment.lock.find(params[:id])
+        subject = resolve_subject(assignment)
+        role_name = assignment.role.name
+
+        if last_full_access_org_assignment?(assignment)
+          refused = true
+        else
+          assignment.destroy!
+          Event.record!(event: "org_role.removed", target: subject || assignment, details: { role: role_name })
+        end
       end
+
+      if refused
+        redirect_back_or_to subjects_path,
+                            alert: "Refusing to remove the last full-access org-wide assignment — " \
+                                   "it would lock everyone out of this UI. Grant full access to " \
+                                   "another subject first, then retry."
+        return
+      end
+
       redirect_back_or_to subjects_path, notice: "Org-wide role removed."
     rescue ActiveRecord::RecordNotFound
       redirect_back_or_to subjects_path, notice: "That org-wide role was already removed."
@@ -68,15 +105,64 @@ module CurrentScope
       count == 1 ? "Org-wide role #{verb}." : "Org-wide role #{verb} for #{count} subjects."
     end
 
+    # True when this assignment is a live full_access org holder and no other
+    # full_access org assignment exists. Orphan rows (deleted subject → nil)
+    # must not permanently block cleanup of the last FA assignment.
+    def last_full_access_org_assignment?(assignment)
+      return false unless assignment.role&.full_access?
+      return false if resolve_subject(assignment).nil?
+
+      !full_access_org_assignments.where.not(id: assignment.id).exists?
+    end
+
+    # True when applying clear (or reassign to a non-full_access role) to these
+    # subjects would leave zero full_access org holders.
+    def would_remove_last_full_access_holders?(subjects, clearing:)
+      holders = full_access_org_assignments.to_a
+      return false if holders.empty?
+
+      affected_ids = holders.select { |a| subjects.any? { |s| same_subject?(a, s) } }.map(&:id)
+      return false if affected_ids.empty?
+
+      unless clearing
+        new_role = Role.find_by(id: params[:role_id])
+        return false if new_role&.full_access?
+      end
+
+      remaining = holders.reject { |a| affected_ids.include?(a.id) }
+      remaining.empty?
+    end
+
+    def full_access_org_assignments
+      RoleAssignment.joins(:role).where(current_scope_roles: { full_access: true })
+    end
+
+    # Lock full-access holder rows (and their roles) so concurrent remove/demote
+    # paths serialize on the same set the precheck reads. Call only inside a
+    # transaction. Prefer locking by id after a join pluck — FOR UPDATE with
+    # joins is adapter-fragile.
+    def lock_full_access_org_holders!
+      Role.where(full_access: true).lock.load
+      ids = full_access_org_assignments.pluck(:id)
+      RoleAssignment.where(id: ids).lock.load if ids.any?
+    end
+
+    def same_subject?(assignment, subject)
+      # Match the polymorphic storage name the subjects page uses (not only
+      # base_class.name — hosts can customize polymorphic_name).
+      assignment.subject_type == subject.class.polymorphic_name && assignment.subject_id == subject.id
+    end
+
     # Returns true when a role was actually cleared, false when there was nothing
-    # to clear (so the caller's count stays accurate).
+    # to clear (so the caller's count stays accurate). Atomicity comes from
+    # create's outer bulk transaction — only called from inside it. (No inner
+    # transaction: without requires_new it would be a bare yield, and it isn't
+    # wanted — a failure anywhere rolls back the whole batch by design.)
     def clear_org_role(subject, assignment, prior_role)
       return false unless assignment.persisted? # nothing to clear ⇒ no event
 
-      RoleAssignment.transaction do
-        assignment.destroy!
-        Event.record!(event: "org_role.removed", target: subject, details: { role: prior_role.name })
-      end
+      assignment.destroy!
+      Event.record!(event: "org_role.removed", target: subject, details: { role: prior_role.name })
       true
     end
 
@@ -88,16 +174,15 @@ module CurrentScope
       new_role = Role.find(params.expect(:role_id))
       changed = prior_role.nil? || prior_role.id != new_role.id
 
-      RoleAssignment.transaction do
-        assignment.update!(role: new_role)
-        if prior_role.nil?
-          Event.record!(event: "org_role.assigned", target: subject, details: { role: new_role.name })
-        elsif prior_role.id != new_role.id
-          Event.record!(event: "org_role.changed", target: subject,
-                        details: { from: prior_role.name, to: new_role.name })
-        end
-        # same role re-set ⇒ no change ⇒ no event
+      # Atomicity comes from create's outer bulk transaction (see clear_org_role).
+      assignment.update!(role: new_role)
+      if prior_role.nil?
+        Event.record!(event: "org_role.assigned", target: subject, details: { role: new_role.name })
+      elsif prior_role.id != new_role.id
+        Event.record!(event: "org_role.changed", target: subject,
+                      details: { from: prior_role.name, to: new_role.name })
       end
+      # same role re-set ⇒ no change ⇒ no event
       changed
     end
   end

data/app/controllers/current_scope/roles_controller.rb

@@ -1,7 +1,8 @@
 module CurrentScope
   class RolesController < ApplicationController
     def index
-      @roles = Role.order(:name)
+      # Includes for delete-confirm holder counts (cascade warning).
+      @roles = Role.order(:name).includes(:role_assignments, :scoped_role_assignments)
     end
 
     def new
@@ -55,12 +56,36 @@ module CurrentScope
     end
 
     def update
-      @role = Role.find(params[:id])
-      previous_name = @role.name
+      permitted = role_params
+      previous_name = nil
       saved = false
+      refused = false
+
+      # Lock full-access roles + holders inside the write transaction so two
+      # concurrent demotions of the last held full-access roles cannot both pass
+      # a pre-transaction check and then both commit.
       Role.transaction do
-        saved = @role.update(role_params)
-        record_role_update(@role, previous_name) if saved
+        # Lock FA console state before the target role so concurrent demote/delete
+        # of two FA roles cannot invert lock order (roles first, then assignments).
+        lock_full_access_console_state!
+        @role = Role.lock.find(params[:id])
+
+        if demoting_would_lock_console?(@role, permitted)
+          refused = true
+        else
+          previous_name = @role.name
+          previous_full_access = @role.full_access?
+          saved = @role.update(permitted)
+          record_role_update(@role, previous_name, previous_full_access) if saved
+        end
+      end
+
+      if refused
+        redirect_to edit_role_path(@role),
+                    alert: "Refusing to remove full access — this is the last full-access role " \
+                           "any subject holds and would lock everyone out of this UI. Grant " \
+                           "full access to another subject first, then retry."
+        return
       end
 
       if saved
@@ -71,44 +96,81 @@ module CurrentScope
     end
 
     def destroy
-      role = Role.find(params[:id])
+      refused = false
+
+      Role.transaction do
+        lock_full_access_console_state!
+        role = Role.lock.find(params[:id])
+
+        if would_lock_console_by_removing_role?(role)
+          refused = true
+        else
+          # Snapshot WITHOUT polymorphic includes — includes(:subject)/:resource
+          # can raise NameError for stale types at preload (members page avoids
+          # this for the same reason). Resolve each row inside the helpers.
+          org_removed = role.role_assignments.to_a
+          scoped_revoked = role.scoped_role_assignments.to_a
+
+          role.destroy!
+          Event.record!(event: "role.deleted", target: role, details: { name: role.name })
+          org_removed.each do |a|
+            Event.record!(event: "org_role.removed", target: cascade_subject(a), details: { role: role.name })
+          end
+          scoped_revoked.each do |a|
+            Event.record!(event: "scoped_role.revoked", target: cascade_subject(a),
+                          details: { role: role.name, resource: cascade_resource_label(a) })
+          end
+        end
+      end
 
-      if last_full_access?(role)
+      if refused
         redirect_to roles_path,
-                    alert: "Refusing to delete the last full-access role — it would lock everyone out of this UI."
+                    alert: "Refusing to delete this full-access role — it is the last one held by any " \
+                           "subject and would lock everyone out of this UI. Grant full access to " \
+                           "another subject first, then retry."
         return
       end
 
-      # Snapshot the cascade BEFORE destroy! — dependent: :destroy takes the
-      # assignments with the role, so they can't be read afterwards.
-      org_removed = role.role_assignments.includes(:subject).to_a
-      scoped_revoked = role.scoped_role_assignments.includes(:subject, :resource).to_a
-
-      Role.transaction do
-        role.destroy!
-        Event.record!(event: "role.deleted", target: role, details: { name: role.name })
-        org_removed.each do |a|
-          Event.record!(event: "org_role.removed", target: a.subject, details: { role: role.name })
-        end
-        scoped_revoked.each do |a|
-          Event.record!(event: "scoped_role.revoked", target: a.subject,
-                        details: { role: role.name, resource: helpers.current_scope_label(a.resource) })
-        end
-      end
       redirect_to roles_path, notice: "Role deleted."
     end
 
     private
 
+    # Polymorphic subject/resource may be deleted or unresolvable — never 500
+    # the cascade audit. Deleted records return nil without raising (especially
+    # after includes preload), so use || assignment, not rescue-only.
+    def cascade_subject(assignment)
+      assignment.subject || assignment
+    rescue ActiveRecord::RecordNotFound, NameError
+      assignment
+    end
+
+    def cascade_resource_label(assignment)
+      resource = begin
+        assignment.resource
+      rescue ActiveRecord::RecordNotFound, NameError
+        nil
+      end
+      return "#{assignment.resource_type}##{assignment.resource_id}" if resource.nil?
+
+      helpers.current_scope_label(resource)
+    rescue StandardError
+      "#{assignment.resource_type}##{assignment.resource_id}"
+    end
+
     # One event per save: role.renamed when the name changed (carries old/new
-    # name AND the grid diff), else role.updated for a pure grid change. Emits
-    # nothing when neither the name nor the grid moved.
-    def record_role_update(role, previous_name)
-      diff = role.permission_keys_change || { added: [], removed: [] }
+    # name AND the grid/full_access diff), else role.updated. Emits nothing on
+    # a pure no-op (same name, same grid, same full_access).
+    def record_role_update(role, previous_name, previous_full_access)
+      diff = role.permission_keys_change || { added: [], removed: [], rejected: [] }
       renamed = previous_name != role.name
-      return unless renamed || diff[:added].any? || diff[:removed].any?
+      full_access_changed = previous_full_access != role.full_access?
+      return unless renamed || full_access_changed || diff[:added].any? || diff[:removed].any?
 
       details = { added: diff[:added], removed: diff[:removed] }
+      if full_access_changed
+        details.merge!(full_access_from: previous_full_access, full_access_to: role.full_access?)
+      end
       event = "role.updated"
       if renamed
         event = "role.renamed"
@@ -117,8 +179,40 @@ module CurrentScope
       Event.record!(event: event, target: role, details: details)
     end
 
-    def last_full_access?(role)
-      role.full_access? && !Role.where(full_access: true).where.not(id: role.id).exists?
+    # True when removing/demoting this full_access role would leave zero
+    # full_access org holders. An unassigned full_access role is always safe
+    # to delete/demote (cubic). An empty spare full_access role must NOT
+    # authorize demoting the held Owner (CE) — check holders, not role rows.
+    def would_lock_console_by_removing_role?(role)
+      return false unless role.full_access?
+      return false unless RoleAssignment.where(role: role).exists?
+
+      !RoleAssignment.joins(:role)
+        .where(current_scope_roles: { full_access: true })
+        .where.not(role_id: role.id)
+        .exists?
+    end
+
+    # True when the update would turn off full_access and lock the console.
+    # Only treats an EXPLICIT full_access=false as demotion — a missing key
+    # would not change the column and must not false-positive refuse.
+    def demoting_would_lock_console?(role, permitted)
+      return false unless role.full_access?
+      return false unless permitted.key?(:full_access)
+      return false if ActiveModel::Type::Boolean.new.cast(permitted[:full_access])
+
+      would_lock_console_by_removing_role?(role)
+    end
+
+    # Serialize demote/delete against concurrent last-holder removal. Lock FA
+    # role rows and their org-wide holder assignments (by id — FOR UPDATE + join
+    # is adapter-fragile). Call only inside a transaction.
+    def lock_full_access_console_state!
+      Role.where(full_access: true).lock.load
+      ids = RoleAssignment.joins(:role)
+        .where(current_scope_roles: { full_access: true })
+        .pluck(:id)
+      RoleAssignment.where(id: ids).lock.load if ids.any?
     end
 
     def role_params
@@ -126,7 +220,11 @@ module CurrentScope
       # Grid group columns (CRUD checkboxes) submit "controller:group" tokens on
       # a separate, optional channel — permitted leniently so a raw permission_keys
       # post (no groups) still works. Expand them into action keys; the model's
-      # permission_keys= dedups and drops anything not in the catalog.
+      # permission_keys= dedups, and REJECTS anything not in the catalog (the
+      # save fails and `edit` re-renders with the error). The grid can't submit
+      # such a key — cells are built from routed actions only — so a rejection
+      # here means a hand-crafted request, which is worth saying out loud rather
+      # than dropping silently.
       groups = params.fetch(:role, {}).permit(permission_groups: [])[:permission_groups]
       permitted[:permission_keys] = Array(permitted[:permission_keys]) + PermissionGrid.new.expand(groups)
       permitted

data/app/helpers/current_scope/application_helper.rb

@@ -1,15 +1,13 @@
 module CurrentScope
   module ApplicationHelper
-    # Best-effort human label for any host subject/resource. Prefers a record's
-    # own current_scope_label (the Scopeable mixin gives every pickable model
-    # one) so the label a model declares is the label shown everywhere — the
-    # picker, the chips, and the ledger (see Event.label_for) all agree.
+    # Best-effort human label for any host subject/resource. Delegates to the
+    # one shared chain (CurrentScope.label_for) — the same definition the audit
+    # ledger denormalizes (see Event.label_for), so the picker, the chips, and
+    # the ledger agree by construction, not by parallel maintenance.
     def current_scope_label(record)
       return "(none)" if record.nil?
-      return record.current_scope_label if record.respond_to?(:current_scope_label)
 
-      name = record.try(:name) || record.try(:email) || record.try(:title)
-      name || "#{record.class.name} ##{record.id}"
+      CurrentScope.label_for(record)
     end
 
     # Human label for a subject (user/account), honouring config.subject_label
@@ -36,14 +34,49 @@ module CurrentScope
     end
 
     # The configured subject_label (Symbol or Proc) applied to a subject, or nil
-    # when unset or when it resolves to a blank value.
+    # when unset, when it resolves to a blank value, or when it fails.
+    #
+    # subject_label is arbitrary host code running once per row on the admin's
+    # main tool for granting and reviewing roles. One subject with incomplete
+    # data (a Proc doing `u.email.upcase` on a subject whose email is nil) must
+    # not take the whole page down — the same intent the holder-label helpers
+    # below already encode for stale polymorphic types. A failure here costs one
+    # label; a raise costs the page.
     def configured_subject_label(subject)
       label = CurrentScope.config.subject_label
-      if label.respond_to?(:call)
-        label.call(subject).to_s.presence
-      elsif label && subject.respond_to?(label)
-        subject.public_send(label).to_s.presence
+      return if label.nil?
+      return resolve_subject_label(label) { label.call(subject) } if label.respond_to?(:call)
+
+      # Only a Symbol or String names a method. Checked BEFORE respond_to?,
+      # which raises TypeError on anything else ("false is not a symbol nor a
+      # string") — and that raise would land outside the rescue below and 500
+      # the page, which is the bug this method exists to prevent, reached
+      # through a different door.
+      unless label.is_a?(Symbol) || label.is_a?(String)
+        CurrentScope::ApplicationHelper.warn_unusable_subject_label_once(label)
+        return
+      end
+
+      if subject.respond_to?(label)
+        resolve_subject_label(label) { subject.public_send(label) }
+      else
+        # Not a mistake we can render around: this config does nothing for EVERY
+        # subject, silently, which is why it needs saying out loud once.
+        CurrentScope::ApplicationHelper.warn_unknown_subject_label_once(label)
+        nil
       end
+    rescue StandardError => e
+      # Last resort, and the reason it exists: every branch above calls a method
+      # ON the host's config value to classify it — `nil?`, `respond_to?`,
+      # `is_a?`. A pathological value breaks the classification itself, before
+      # any specific guard can classify it, so the guards cannot be where this
+      # is caught. A BasicObject has no #nil?; a delegator can raise from
+      # respond_to?.
+      #
+      # Deliberately does NOT touch `label`: it is the thing that just proved it
+      # cannot be touched. The warning is keyed off the error alone.
+      CurrentScope::ApplicationHelper.warn_subject_label_broken_once(e)
+      nil
     end
 
     # Members-list labels that survive a stale/renamed polymorphic type — a
@@ -67,6 +100,129 @@ module CurrentScope
     def current_scope_gid_label(gid)
       record = GlobalID::Locator.locate(gid)
       record ? current_scope_label(record) : gid
+    rescue ActiveRecord::RecordNotFound, NameError
+      # locate RAISES for a deleted record or renamed class (nil is only for
+      # unparseable strings) — same contract the holder helpers rescue above.
+      gid
+    end
+
+    private
+
+    # ponytail: display fallback only — NEVER a decision path. This rescue makes
+    # a label degrade instead of erroring; the resolver, Guard and catalog are
+    # untouched, so it relaxes no fail-closed guarantee. (The same `rescue
+    # StandardError` on a decision path would be a fail-open bug.)
+    #
+    # StandardError rather than the NameError family the holder helpers catch:
+    # those wrap OUR call into a known-shaped record, while this runs a host's
+    # arbitrary Proc, which can raise anything. Catching only NameError would
+    # fix the reported NoMethodError and leave the same page-down bug for a
+    # differently-broken Proc.
+    #
+    # nil rejoins the existing "resolved blank -> default chain" path in
+    # current_scope_subject_label, so no caller learns a new branch.
+    def resolve_subject_label(label)
+      yield.to_s.presence
+    rescue StandardError => e
+      CurrentScope::ApplicationHelper.warn_subject_label_raised_once(label, e)
+      nil
+    end
+
+    class << self
+      # Warn ONCE per (reason, label): a misconfigured subject_label is the same
+      # mistake on every row, so one line is a signal and one-per-subject is
+      # noise the admin will scroll past. Keyed by the label value, so changing
+      # the config in dev warns again for the new value.
+      #
+      # Always-on rather than behind a warn_on_* flag (cf. warn_on_nil_sod_record,
+      # which defaults off because a nil record is often legitimate): a label the
+      # subject can't answer, or one that raises, is unambiguously a mistake.
+      # Mirrors Event.warn_missing_events_table_once.
+      #
+      # Says "this subject" rather than "subjects": under STI some subclasses may
+      # answer and others not, and warn-once means the first non-responder would
+      # otherwise speak for all of them.
+      def warn_unknown_subject_label_once(label)
+        return unless new_subject_label_warning?(:unknown, label)
+
+        Rails.logger&.warn(
+          "[CurrentScope] config.subject_label is #{label.inspect}, but this subject does not " \
+          "respond to it — it is falling back to the default label. If no subject responds to it, " \
+          "this config does nothing. Set it to a method the subject responds to (e.g. :email), a " \
+          "Proc, or nil."
+        )
+      end
+
+      # Not a Symbol, String, Proc, or nil — so it can't name a method and can't
+      # be called. Reports the TYPE, not the value: this is the one warning whose
+      # subject is an arbitrary host object, and calling `inspect` on it could
+      # itself raise — inside the very path that exists to stop a raise.
+      def warn_unusable_subject_label_once(label)
+        return unless new_subject_label_warning?(:unusable, label.class)
+
+        Rails.logger&.warn(
+          "[CurrentScope] config.subject_label is a #{label.class} — it can't name a method and " \
+          "can't be called, so every subject is falling back to the default label. Set it to a " \
+          "Symbol (e.g. :email), a Proc taking the subject, or nil."
+        )
+      end
+
+      def warn_subject_label_raised_once(label, error)
+        return unless new_subject_label_warning?(:raised, label)
+
+        Rails.logger&.warn(
+          "[CurrentScope] config.subject_label raised #{safe_class(error)}: #{safe_message(error)} " \
+          "— that subject fell back to the default label rather than erroring the page. A " \
+          "subject_label must be total: it runs for every subject, including ones with nil or " \
+          "blank attributes."
+        )
+      end
+
+      # The configured value could not even be classified — see the rescue in
+      # configured_subject_label. Keyed by the error's class, and says nothing
+      # about the label itself, because reading the label is what failed.
+      def warn_subject_label_broken_once(error)
+        return unless new_subject_label_warning?(:broken, safe_class(error))
+
+        Rails.logger&.warn(
+          "[CurrentScope] config.subject_label could not be read — #{safe_class(error)}: " \
+          "#{safe_message(error)}. Every subject is falling back to the default label. Set it to " \
+          "a Symbol (e.g. :email), a Proc taking the subject, or nil."
+        )
+      end
+
+      private
+
+      # A host exception's message is arbitrary text produced by arbitrary code:
+      # it may carry newlines that split one warning across several log records,
+      # run to any length, or raise from #message itself. All three would land
+      # in the rescue this runs inside — reporting the failure must not become
+      # the failure.
+      def safe_message(error)
+        error.message.to_s.gsub(/\s+/, " ").strip.truncate(200)
+      rescue StandardError
+        "(message unavailable)"
+      end
+
+      # Same reason as safe_message, one step earlier: `#class` is interpolated
+      # before safe_message is even called, and an exception raised by a host
+      # Proc can override it. The method-level rescue in configured_subject_label
+      # does stop that reaching the page — but at the cost of the accurate
+      # warning, replaced by a misattributed one about the secondary failure.
+      # The diagnostic is the whole point of warning at all, so protect it.
+      def safe_class(error)
+        error.class.name.presence || "an exception"
+      rescue StandardError
+        "an exception"
+      end
+
+      # Set is a core built-in on this gem's Ruby floor (>= 3.2, no require
+      # needed — the codebase already uses bare Set elsewhere), so nothing here
+      # can raise inside the rescue this runs under.
+      def new_subject_label_warning?(reason, label)
+        @subject_label_warnings ||= Set.new
+        !!@subject_label_warnings.add?([ reason, label ])
+      end
     end
   end
 end

data/app/models/current_scope/current.rb

@@ -14,6 +14,16 @@ module CurrentScope
     # each event; nil when the host hasn't set it. Additive — no reader override.
     attribute :user, :actor, :request_id
 
+    # #50: the collection type the request's controller declared via
+    # current_scope_model, and the controller_path it was declared for. The
+    # Guard stashes both once per request so the advisory path (allowed_to? in
+    # a view) can bind the record-less gate the same way the controller gate
+    # did — but the PATH is stored so a cross-controller advisory question
+    # (allowed_to?(:index, controller: "reports") from a projects view) does
+    # NOT borrow the wrong controller's type (KTD-6). Request-scoped, reset
+    # with everything else, so it never leaks between requests.
+    attribute :collection_model, :collection_model_path
+
     # Per-request memo for the resolver's org-role lookup. A view with N
     # permission-gated elements calls the gate N times, each otherwise re-running
     # the same `RoleAssignment.find_by(subject:)`; caching it here collapses that
@@ -24,10 +34,24 @@ module CurrentScope
 
     # Falls back to the effective subject, so actor is never nil when user is
     # set — callers attribute to `actor` without a nil branch.
+    #
+    # ROUND-TRIP HAZARD: the reader answers with the fallback, not stored
+    # state. Snapshot/restore code (Current.set, Object#with, anything that
+    # reads #actor to write it back) would pin the fallback as an explicit
+    # actor and restore a stale identity once user changes — read the raw
+    # `attributes` hash instead, as TestHelpers#with_current_user does.
     def actor
       super || user
     end
 
+    # True only while a distinct real actor stands behind the effective
+    # subject (act-as). THE definition of "impersonating" — the Permissions
+    # mixin and the mutation guard both delegate here, so the view-level
+    # read-only signal and the write gate can never drift apart.
+    def impersonating?
+      user.present? && actor != user
+    end
+
     # Memoize the org-role lookup for `subject` for the rest of this request/job.
     # Keyed by subject so a check that spans several subjects stays correct.
     # Caches nil (no role) too, so a repeated "no grant" check is one query, not N.

data/app/models/current_scope/event.rb

@@ -90,13 +90,11 @@ module CurrentScope
         )
       end
 
-      # Prefer a record's own view-agnostic label; then the AR default; then
-      # a plain to_s for anything else.
+      # The shared chain (CurrentScope.label_for) — the same label the UI
+      # renders is the one denormalized into target_label, so the ledger and
+      # the screen can't disagree about what a record was called.
       def label_for(record)
-        return record.current_scope_label if record.respond_to?(:current_scope_label)
-        return "#{record.model_name.human} ##{record.id}" if record.respond_to?(:model_name)
-
-        record.to_s
+        CurrentScope.label_for(record)
       end
 
       # Recognizes "table is missing" across adapters and Rails' own schema
@@ -112,6 +110,12 @@ module CurrentScope
           !message.match?(/\bcolumn\b/i) &&
           message.match?(/no such table|could not find table|does(?:n't| not) exist|unknown table|undefined table/i)
       end
+      # PUBLIC: report mode's ledger warning asks this too (#37). It is one
+      # question — "is this the un-migrated-table case?" — and one adapter-shaped
+      # answer, so it gets one definition. A second opinion elsewhere is a second
+      # opinion that drifts, and this one decides which fix an operator is sent
+      # after. (#59 review)
+      public :missing_events_table?
     end
   end
 end