current_scope 0.5.0

data/app/controllers/current_scope/scoped_role_assignments_controller.rb

@@ -0,0 +1,165 @@
+module CurrentScope
+  # Grants/revokes a role on ONE specific record. `new` is a guided cascade
+  # (Role → Subject → Resource type → Record); `create` grants; `destroy`
+  # revokes. A record page can still deep-link straight to a target with:
+  #
+  #   current_scope.new_scoped_role_assignment_path(resource_gid: record.to_gid)
+  class ScopedRoleAssignmentsController < ApplicationController
+    # ponytail: record search scans only the first SCAN_CAP rows of a type and
+    # renders at most DISPLAY_LIMIT matches. current_scope_label is a Ruby
+    # method with no backing column, so the filter runs in Ruby (not SQL LIKE);
+    # a dedicated indexed label column is the upgrade path for large tables.
+    SCAN_CAP = 500
+    DISPLAY_LIMIT = 50
+    # Offer a search box (instead of listing every record) past this many.
+    SEARCH_THRESHOLD = 20
+
+    def new
+      @assignment = ScopedRoleAssignment.new
+      @roles = Role.order(:name)
+      @subjects = subject_class.order(:id)
+      @scopeable = CurrentScope.scopeable_resources
+      @bulk_subjects = resolve_bulk_subjects # [] unless a multi-select bulk grant
+
+      @resource = deep_linked_resource
+      @resource_type = resolve_type(params[:resource_type]) || @resource&.class
+      @searchable = searchable?(@resource_type)
+      @records = candidate_records(@resource_type, params[:q])
+    end
+
+    def create
+      resource = GlobalID::Locator.locate(params.expect(:resource_gid))
+      role = Role.find(params.expect(:role_id))
+      subjects = locate_subjects(submitted_subject_gids)
+      if subjects.empty?
+        redirect_to subjects_path, alert: "No subjects selected."
+        return
+      end
+
+      granted = 0
+      # One transaction for the whole bulk grant — all-or-nothing, like the
+      # org-wide sibling. A per-subject savepoint (grant_one) absorbs the
+      # concurrent-duplicate race without poisoning the outer transaction, while
+      # a genuine RecordInvalid rolls the entire batch back.
+      ScopedRoleAssignment.transaction do
+        subjects.each { |subject| granted += 1 if grant_one(subject, resource, role) }
+      end
+
+      redirect_to subjects_path, notice: grant_notice(granted, subjects.size)
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to subjects_path, alert: e.message
+    rescue ActiveRecord::RecordNotFound, NameError
+      redirect_to subjects_path,
+                  alert: "Couldn't grant that scoped role — the subject, role, or record is no longer available."
+    end
+
+    def destroy
+      assignment = ScopedRoleAssignment.find(params[:id])
+      # Resolve the subject through the canonical guard, else fall back to the
+      # assignment itself as the audit target — never the unrelated live record a
+      # non-canonical stored id would cast into (#151). Mirrors cascade_subject.
+      subject = assignment.current_scope_resolved_record("subject") || assignment
+      role = assignment.role
+
+      ScopedRoleAssignment.transaction do
+        assignment.destroy!
+        Event.record!(event: "scoped_role.revoked", target: subject,
+                      details: { role: role.name, resource: assignment_resource_label(assignment) })
+      end
+      redirect_to subjects_path, notice: "Scoped role revoked."
+    rescue ActiveRecord::RecordNotFound
+      redirect_to subjects_path, notice: "That scoped role was already revoked."
+    end
+
+    private
+
+    # The scoped record may be deleted (nil) or its class renamed (NameError) by
+    # the time we revoke — label from the record when it's still there, else from
+    # the stored type/id, so the audit event never 500s on a stale reference.
+    def assignment_resource_label(assignment)
+      resource = assignment.current_scope_resolved_record("resource")
+      resource ? helpers.current_scope_label(resource) : "#{assignment.resource_type} ##{assignment.resource_id}"
+    rescue StandardError
+      # A host current_scope_label that raises must not 500 the revoke audit —
+      # fall back to the stored type/id, matching cascade_resource_label.
+      "#{assignment.resource_type} ##{assignment.resource_id}"
+    end
+
+    # Deep-link prefill: a record page links here with resource_gid. A stale
+    # link (deleted record → RecordNotFound, renamed class → NameError) must
+    # not 500 — fall back to the blank picker with a friendly alert.
+    def deep_linked_resource
+      GlobalID::Locator.locate(params[:resource_gid]) if params[:resource_gid].present?
+    rescue ActiveRecord::RecordNotFound, NameError
+      flash.now[:alert] = "That linked record is no longer available — pick one below."
+      nil
+    end
+
+    # Grant one scoped role inside its own savepoint. Returns true when a new
+    # grant was recorded, false when the subject already had it (or a concurrent
+    # grant won the race). A RecordInvalid propagates to roll the whole bulk back.
+    def grant_one(subject, resource, role)
+      ScopedRoleAssignment.transaction(requires_new: true) do
+        assignment = ScopedRoleAssignment.find_or_create_by!(subject: subject, resource: resource, role: role)
+        if assignment.previously_new_record?
+          Event.record!(event: "scoped_role.granted", target: subject,
+                        details: { role: role.name, resource: helpers.current_scope_label(resource) })
+          true
+        else
+          false
+        end
+      end
+    rescue ActiveRecord::RecordNotUnique
+      false # a concurrent grant slipped past the validation to the DB index — already done
+    rescue ActiveRecord::RecordInvalid => e
+      # A concurrent grant of the same triple usually trips the uniqueness
+      # VALIDATION first (RecordInvalid, not RecordNotUnique). Absorb only that
+      # case per-subject; any other validation failure rolls the whole batch back.
+      raise unless e.record.errors.of_kind?(:role_id, :taken)
+
+      false
+    end
+
+    # Resolve the bulk subject_gids for display (dead links and non-subject GIDs
+    # drop out — same boundary the grant enforces).
+    def resolve_bulk_subjects
+      locate_subjects(params[:subject_gids])
+    end
+
+    def grant_notice(granted, attempted)
+      return "Those subjects already have that scoped role." if granted.zero?
+      return "Scoped role granted." if granted == 1 && attempted == 1
+
+      "Scoped role granted to #{granted} #{'subject'.pluralize(granted)}."
+    end
+
+    # Only registered Scopeable types are resolvable from params — never
+    # constantize arbitrary visitor input.
+    def resolve_type(name)
+      CurrentScope.scopeable_resources.find { |model| model.name == name } if name.present?
+    end
+
+    def searchable?(klass)
+      klass.respond_to?(:count) && klass.count > SEARCH_THRESHOLD
+    end
+
+    def candidate_records(klass, query)
+      return unless klass.respond_to?(:limit) # tableless / nil type ⇒ nothing to pick
+
+      # A14: if the host model opts in with a class-level current_scope_searchable_scope,
+      # search via that indexed relation — no SCAN_CAP, no in-Ruby label filter.
+      if query.present? && klass.respond_to?(:current_scope_searchable_scope)
+        return klass.current_scope_searchable_scope(query).limit(DISPLAY_LIMIT).to_a
+      end
+
+      # Fallback: current_scope_label is a Ruby method with no backing column, so
+      # scan the first SCAN_CAP rows and filter the label in Ruby.
+      records = klass.limit(SCAN_CAP).to_a
+      if query.present?
+        needle = query.downcase
+        records = records.select { |record| helpers.current_scope_label(record).downcase.include?(needle) }
+      end
+      records.first(DISPLAY_LIMIT)
+    end
+  end
+end

data/app/controllers/current_scope/subjects_controller.rb

@@ -0,0 +1,75 @@
+module CurrentScope
+  class SubjectsController < ApplicationController
+    PER_PAGE = 50
+
+    # Identity columns searched by ?q=, in the same preference order as
+    # current_scope_subject_label's default chain. Intersected with the subject
+    # table's real column_names before use, so a query never spans a page.
+    SEARCH_COLUMNS = %w[email email_address name first_name last_name].freeze
+
+    def index
+      @query = params[:q].to_s.strip
+      scope = filter_subjects(subject_class.order(:id), @query)
+
+      @page = [ params[:page].to_i, 1 ].max
+      @subjects = scope.limit(PER_PAGE).offset((@page - 1) * PER_PAGE)
+      @has_next_page = scope.offset(@page * PER_PAGE).exists?
+
+      @roles = Role.order(:name)
+      # Match on the ids as strings: `where(subject: @subjects)` would build
+      # `subject_id IN (SELECT id ...)`, comparing a varchar column to a bigint
+      # subquery, which PostgreSQL refuses (#151).
+      # Group by each subject's OWN polymorphic_name, not the configured class's:
+      # an STI subclass that overrides it stores grants under a different token, so
+      # a single where(subject_type:) would omit them (#151). One type in the
+      # common case; the per-type OR keeps the STI case correct for one extra WHERE.
+      subject_ids_by_type = @subjects.group_by { |subject| subject.class.polymorphic_name }
+                                     .transform_values { |subjects| subjects.map { |subject| subject.id.to_s } }
+      assignment_scope = subject_ids_by_type.reduce(RoleAssignment.none) do |relation, (type, ids)|
+        relation.or(RoleAssignment.where(subject_type: type, subject_id: ids))
+      end
+      @assignments = assignment_scope
+                                   .index_by { |a| [ a.subject_type, a.subject_id.to_s ] }
+      # Safe polymorphic resource preload (resolvable types only) — full
+      # includes(:resource) NameErrors on a stale resource_type and 500s the
+      # page; skip-unresolvable + label as inert instead (#90 / PR #104).
+      scoped_scope = subject_ids_by_type.reduce(ScopedRoleAssignment.none) do |relation, (type, ids)|
+        relation.or(ScopedRoleAssignment.where(subject_type: type, subject_id: ids))
+      end
+      scoped_rows = scoped_scope.includes(:role).to_a
+      ScopedRoleAssignment.preload_resolvable_resources!(scoped_rows)
+      # to_s to match the view's key: subject_id is a string column (#151).
+      @scoped = scoped_rows.group_by { |a| [ a.subject_type, a.subject_id.to_s ] }
+    end
+
+    private
+
+    # Server-side search across the subject's human-identity columns, so a query
+    # matches EVERY subject rather than only the current page's client-side
+    # filter. Columns come from the table's real column_names (never interpolate
+    # user input as a column name), so this is injection-safe. A Proc
+    # subject_label can't be expressed in SQL; when the model exposes none of the
+    # searchable columns this returns the scope unfiltered and the per-page
+    # client filter remains the only narrowing.
+    def filter_subjects(scope, query)
+      return scope if query.blank?
+
+      columns = subject_search_columns(scope.klass)
+      return scope if columns.empty?
+
+      conn    = scope.klass.connection
+      clause  = columns.map { |c| "LOWER(#{conn.quote_column_name(c)}) LIKE ?" }.join(" OR ")
+      # ponytail: % / _ in the query pass through as LIKE wildcards — fine for an
+      # admin search; add ESCAPE handling if that ever surprises someone.
+      scope.where(clause, *([ "%#{query.downcase}%" ] * columns.size))
+    end
+
+    def subject_search_columns(klass)
+      configured = CurrentScope.config.subject_label
+      candidates = []
+      candidates << configured.to_s if configured.is_a?(Symbol)
+      candidates.concat(SEARCH_COLUMNS)
+      candidates.uniq.select { |c| klass.column_names.include?(c) }
+    end
+  end
+end

data/app/helpers/current_scope/application_helper.rb

@@ -0,0 +1,261 @@
+module CurrentScope
+  module ApplicationHelper
+    # 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?
+
+      CurrentScope.label_for(record)
+    end
+
+    # Human label for a subject (user/account), honouring config.subject_label
+    # so a host on UUID keys can show email or a full name instead of an
+    # opaque id. Falls back to the best-effort current_scope_label.
+    def current_scope_subject_label(subject)
+      return "(none)" if subject.nil?
+
+      # A configured label that resolves to nil/blank (e.g. :email on a subject
+      # with no email yet) must not render as an empty row — fall through to the
+      # default human-identifier chain rather than showing "".
+      configured = configured_subject_label(subject)
+      return configured if configured
+
+      # Default: a subject is a person, so prefer human identifiers over a
+      # generic "Class #id" — including when the model includes Scopeable, whose
+      # current_scope_label is id-based. Covers `email` and Rails 8 auth's
+      # `email_address`. Config overrides this entirely.
+      full_name = [ subject.try(:first_name), subject.try(:last_name) ].compact.join(" ").presence
+      # .presence on each identifier: a stored empty/whitespace email ("") is
+      # truthy in Ruby and would otherwise short-circuit to a blank label.
+      subject.try(:email).presence || subject.try(:email_address).presence ||
+        subject.try(:name).presence || full_name || current_scope_label(subject)
+    end
+
+    # The configured subject_label (Symbol or Proc) applied to a subject, or nil
+    # 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
+      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
+    # removed subject or resource class must not 500 the page; fall back to
+    # "Type #id" the way the audit ledger does.
+    def current_scope_holder_subject_label(assignment)
+      # Through the canonical guard, not assignment.subject: a non-canonical
+      # stored subject_id (a pre-#151 collapsed value, or a host insert_all) would
+      # otherwise cast "7f00…" to integer record 7 and label the row a live,
+      # unrelated subject. nil falls back to "Type #id" like the audit ledger.
+      subject = assignment.current_scope_resolved_record("subject")
+      subject ? current_scope_subject_label(subject) : "#{assignment.subject_type} ##{assignment.subject_id}"
+    rescue NameError, ActiveRecord::RecordNotFound
+      "#{assignment.subject_type} ##{assignment.subject_id}"
+    end
+
+    # #134: the console's one read of GrantDiagnosis. Returns
+    # [css_class, badge_text, caveat] or nil. Never the word "inert" (#90's
+    # badge, different state, different fix).
+    def current_scope_grant_diagnosis_badge(scoped_assignment)
+      verdict = CurrentScope::GrantDiagnosis.verdict_for(scoped_assignment)
+      if verdict
+        return [
+          "cs-dead-badge", "cannot match",
+          "#{CurrentScope::GrantDiagnosis.verdict_label(verdict).capitalize}. " \
+          "#{CurrentScope::GrantDiagnosis.verdict_fix(verdict)}"
+        ]
+      end
+
+      return nil unless CurrentScope::GrantDiagnosis.type_untargeted?(scoped_assignment, verdict: verdict)
+
+      [
+        "cs-check-badge", "check hooks",
+        "No permission on this role names a controller for this record's type. " +
+          CurrentScope::GrantDiagnosis.untargeted_caveat
+      ]
+    end
+
+    def current_scope_holder_resource_label(scoped_assignment)
+      if scoped_assignment.respond_to?(:orphaned_resource?) && scoped_assignment.orphaned_resource?
+        return "#{scoped_assignment.resource_type} ##{scoped_assignment.resource_id} (unavailable — inert)"
+      end
+
+      current_scope_label(scoped_assignment.resource)
+    rescue NameError, ActiveRecord::RecordNotFound
+      # Labeler failed — not proof the resource is orphaned. Raw type#id only
+      # (orphaned_resource? above owns the inert wording) — PR #104 review.
+      "#{scoped_assignment.resource_type} ##{scoped_assignment.resource_id}"
+    end
+
+    # Best-effort label for a stored GID string (event actor/subject). Falls
+    # back to the raw GID when the record is gone — the ledger outlives the
+    # identities it names.
+    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/concerns/current_scope/storable_keys.rb

@@ -0,0 +1,101 @@
+module CurrentScope
+  # One definition of the #151 key policy, shared by both assignment models.
+  #
+  # Since the ids are string columns, an integer key and a UUID both store whole.
+  # What remains unstorable is a key that is not ONE value: a composite key is an
+  # array, and a model with no primary key names no record. A grant on either
+  # would identify the wrong row or none, so it is refused.
+  module StorableKeys
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # `sides` are the polymorphic association names ("subject", "resource").
+      def validates_storable_polymorphic_keys(*sides)
+        validate { current_scope_check_storable_keys(sides) }
+      end
+    end
+
+    # Associations cast their stored id through the target model's key type.
+    # For a legacy collapsed row that can turn a UUID-shaped string into integer
+    # record 7. Every engine path that labels or audits an existing grant uses
+    # this checked reader so an inert grant never names an unrelated live record.
+    def current_scope_resolved_record(side)
+      klass = CurrentScope.polymorphic_class(public_send("#{side}_type"), owner: self.class)
+      return if klass.nil?
+      return unless CurrentScope.canonical_key?(klass, public_send("#{side}_id"))
+
+      public_send(side)
+    rescue ActiveRecord::RecordNotFound, NameError
+      nil
+    end
+
+    private
+
+    def current_scope_check_storable_keys(sides)
+      # db:setup/reset/prepare must boot before a schema exists, but they later
+      # run host seeds in that same process. Re-check at the actual write so a
+      # schema-loaded MySQL database cannot create grants before its collation is
+      # repaired. Database-task exemptions are only for bootstrapping tooling.
+      CurrentScope::SchemaGuard.check!(allow_database_task: false)
+
+      sides.each do |side|
+        # LENGTH FIRST, and it ends this side. An id too long for the column is
+        # also, necessarily, not a canonical key for its model — checking both
+        # would hand the reader two errors for one value, the second one
+        # explaining a cast when the real problem is the width.
+        next if too_long?(side)
+
+        # The stored TYPE column, not the association: on an already-collapsed row
+        # the association resolves to nothing, and reading it would skip exactly
+        # the rows this guard exists for. Resolved through this model, which is
+        # what wrote the token, so an overridden polymorphic_name still matches.
+        klass = CurrentScope.polymorphic_class(public_send("#{side}_type"), owner: self.class)
+        next if klass.nil?
+
+        # A write fails CLOSED either way, but the two causes get different
+        # messages: claiming a model has a composite key when the truth is "its
+        # table is missing" sends the reader hunting the wrong problem. Only
+        # ActiveRecord errors are converted — a NoMethodError here is a bug in
+        # this gem and must surface as one, not as a validation message.
+        begin
+          unless CurrentScope.storable_key?(klass)
+            errors.add(:base, CurrentScope.unstorable_key_error(klass, role: side))
+            next
+          end
+
+          next if CurrentScope.canonical_key?(klass, public_send("#{side}_id"))
+
+          # The column takes any string, so a value that is not a legal key for
+          # this model stores happily — and the resolver then casts it back into
+          # that model's key type, where "7f00aaaa-…" becomes 7 and the grant
+          # reaches record 7. The resolver drops such ids too; refusing the WRITE
+          # is what stops them existing at all.
+          errors.add(:base,
+            "#{public_send("#{side}_id").inspect} is not a valid #{klass.name} primary key " \
+            "(#{klass.name}.#{klass.primary_key} is #{klass.type_for_attribute(klass.primary_key).type}). " \
+            "Stored as-is it would be cast back to a DIFFERENT record's id, so the grant would " \
+            "open a record it does not name (#151).")
+        rescue ActiveRecord::ActiveRecordError => e
+          errors.add(:base,
+            "#{klass.name}'s primary key could not be read (#{e.class}: #{e.message}), so " \
+            "CurrentScope cannot prove this #{side} names one record. Refusing the grant " \
+            "rather than storing something unverified.")
+        end
+      end
+    end
+
+    # Length is a correctness guard, not cosmetics: a truncated key is a key that
+    # names the wrong record (#151). Returns whether it failed, so the caller can
+    # stop looking at a side whose value is already disqualified.
+    def too_long?(side)
+      value = public_send("#{side}_id")
+      return false unless CurrentScope.key_too_long?(value)
+
+      errors.add(:base,
+        "#{side} id is #{value.to_s.length} characters; CurrentScope stores it in a " \
+        "#{CurrentScope::KEY_LIMIT}-character column, and a truncated key would name the " \
+        "wrong record. Use a shorter primary key.")
+      true
+    end
+  end
+end

data/app/models/current_scope/application_record.rb

@@ -0,0 +1,5 @@
+module CurrentScope
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end