current_scope 0.2.0 → 0.3.1

data/lib/current_scope/permission_grid.rb

@@ -1,3 +1,7 @@
+# The gating: default below constructs one at call time — a caller requiring
+# this file directly (not via the current_scope entrypoint) must not NameError.
+require "current_scope/gating_reflection"
+
 module CurrentScope
   # Presents the route-derived permission catalog as an ALIGNED matrix for the
   # role editor: fixed columns, one row per controller, blank cells where a
@@ -13,15 +17,31 @@ module CurrentScope
     Column = Struct.new(:label, :actions, :group, keyword_init: true)
     Cell   = Struct.new(:blank, :group, :name, :value, :checked, :partial, :granted_keys, keyword_init: true)
 
-    def initialize(catalog: CurrentScope.catalog, groups: CurrentScope.config.permission_grid_groups)
+    # The gating default is evaluated at CALL time, so every bare
+    # PermissionGrid.new (the edit view AND role_params on every role save)
+    # constructs a GatingReflection. That is fine only because its constructor
+    # is inert by contract — all reflection work happens inside #ungated?, and
+    # nothing here calls it during initialize or #expand (KTD-8; pinned by the
+    # spy test).
+    def initialize(catalog: CurrentScope.catalog, groups: CurrentScope.config.permission_grid_groups,
+                   gating: GatingReflection.new)
       @grouped = catalog.grouped # { "controller" => ["action", ...] }
       @groups  = groups || {}
+      @gating  = gating
     end
 
     def controllers
       @grouped.keys.sort
     end
 
+    # Is this row's controller provably never gated? Advisory only — a pure
+    # delegation the view reads to annotate the row; no other grid method
+    # consults the reflection, so the answer cannot affect a cell or an
+    # expansion (pinned byte-identical in the tests).
+    def ungated?(controller)
+      @gating.ungated?(controller)
+    end
+
     # Ordered columns: config groups that apply to at least one controller (in
     # config order), then leftover actions not covered by any group (sorted).
     def columns
@@ -61,14 +81,24 @@ module CurrentScope
     end
 
     # Expand submitted "controller:group" tokens into routed permission keys.
-    # Unknown groups/controllers and unrouted actions drop out.
+    #
+    # A token the grid could not have produced (unknown group, unknown
+    # controller, nothing routed) passes through RAW so the model's catalog
+    # validation rejects it BY NAME — the same loud contract a hand-crafted
+    # permission_keys[] entry gets. One save, one error story: the grid's two
+    # submission channels must not differ on whether a crafted request is
+    # reported or silently swallowed. (The form's blank hidden padding is the
+    # one legitimate non-grid value; it alone drops out.)
     def expand(tokens)
       Array(tokens).flat_map do |token|
+        next [] if token.blank?
+
         controller, label = token.to_s.split(":", 2)
         actions = @groups[label]
-        next [] if actions.nil?
+        routed = actions ? (actions & actions_for(controller)) : []
+        next [ token.to_s ] if routed.empty?
 
-        (actions & actions_for(controller)).map { |action| "#{controller}##{action}" }
+        routed.map { |action| "#{controller}##{action}" }
       end
     end
 

data/lib/current_scope/permissions.rb

@@ -13,14 +13,28 @@ module CurrentScope
     def allowed_to?(action, record = nil, controller: nil)
       controller ||= controller_path if respond_to?(:controller_path)
       CurrentScope.allowed?(action, subject: current_scope_user, record: record,
-        controller_path: controller, actor: current_scope_actor)
+        controller_path: controller, actor: current_scope_actor,
+        model: ambient_collection_model(action, controller))
     end
 
     # The list-side companion to allowed_to?: "which records of `model` may the
-    # effective subject act on?". Same grants, keys, and fail-closed rules as
-    # the gate, so a list can't drift from the per-record decision. Returns a
-    # chainable relation (.where/.order/.page on it). `permission` defaults to
-    # the model's index context and accepts a bare action or a full key.
+    # effective subject act on?". Same grants and keys as the gate, resolved
+    # fail-closed (nil subject / no grant → none) — but scope_for answers ROW
+    # MEMBERSHIP only, never action reachability. Gate checks that sit on top
+    # of the grant do not filter this list:
+    #   - the separation-of-duties veto — for an SoD-listed action the list CAN
+    #     include the subject's own initiated records, which the per-record
+    #     gate then refuses;
+    #   - the impersonation mutation gate — a REQUEST-level guard, not a
+    #     per-record one: it blocks any non-GET/HEAD request while
+    #     impersonating, collection actions included;
+    #   - record-less gate paths (a hookless controller's NO_RECORD decision).
+    # So a listed row can still 403 when acted on. Per-row affordances for
+    # SoD-listed actions must check allowed_to?(action, record); mutation
+    # affordances while impersonating should key off impersonating?.
+    # Returns a chainable relation (.where/.order/.page on it). `permission`
+    # defaults to the model's index context and accepts a bare action or a
+    # full key.
     #
     #   scope_for(Project)                 # projects#index — what a list shows
     #   scope_for(Report, permission: :approve)
@@ -37,6 +51,15 @@ module CurrentScope
       )
     end
 
+    # The type the controller handling THIS request declared for its collection
+    # actions (#50), so a bare allowed_to?(:index) in its own view binds the
+    # record-less gate the same way the gate did — otherwise the fix would hide
+    # a link the gate allows. Only for the request's OWN controller: a
+    # cross-controller question resolves a key about a different controller than
+    # the ambient type answers, so it gets nil and falls to the fail-closed
+    # default — the class form allowed_to?(:index, Report) is how you ask about
+    # another controller, and it binds from its argument (R5). (KTD-6)
+    #
     def current_scope_user
       CurrentScope::Current.user
     end
@@ -48,10 +71,24 @@ module CurrentScope
     end
 
     # True only while a distinct real actor stands behind the effective
-    # subject (act-as). Views use it as the read-only-state signal.
+    # subject (act-as). Views use it as the read-only-state signal. Delegates
+    # to the one definition on Current, shared with the mutation guard.
     def impersonating?
-      CurrentScope::Current.user.present? &&
-        CurrentScope::Current.actor != CurrentScope::Current.user
+      CurrentScope::Current.impersonating?
+    end
+
+    private
+
+    # Internal binding for gate/view agreement (#50 KTD-6) — not host API.
+    # Private so it does not appear in controller action_methods. Matches on
+    # the KEY's controller, not just the controller: kwarg: a full
+    # "reports#index" key from a projects view must not borrow the projects
+    # ambient. A bare action uses the resolved controller. (#50 review, cubic)
+    def ambient_collection_model(action, controller)
+      key_controller = action.to_s.include?("#") ? action.to_s.split("#").first : controller
+      return nil unless key_controller && key_controller == CurrentScope::Current.collection_model_path
+
+      CurrentScope::Current.collection_model
     end
   end
 end

data/lib/current_scope/resolver.rb

@@ -10,7 +10,15 @@ module CurrentScope
   #                      present and future.
   #   3. org-wide role — the role's permission set includes this permission.
   #   4. scoped role   — a role held on THIS record grants the permission.
-  #   5. default-deny  — nothing granted means denied.
+  #   5. scoped role,  — the target is record-less (nil for a collection action,
+  #      record-less     a Class for a class-form check), so no specific record
+  #                      can be named. An action in config.collection_read_actions
+  #                      asks scope_for — the id-narrowed list query — so the gate
+  #                      opens exactly when the list would show records
+  #                      (full_access included, #65); any other action needs a
+  #                      scoped grant EXPLICITLY ticking the key. scope_for then
+  #                      narrows the list to those records.
+  #   6. default-deny  — nothing granted means denied.
   class Resolver
     INITIATOR_METHOD = :current_scope_initiator
     # Host-defined per-record opt-in for break-glass. Absent ⇒ never bypassed
@@ -21,8 +29,8 @@ module CurrentScope
     # Public contract: boolean. `actor` is the REAL principal behind the
     # request (defaults to the subject — no impersonation); it only widens the
     # SoD veto under config.sod_identity == :either.
-    def allow?(subject:, permission:, record: nil, actor: nil)
-      decide(subject: subject, permission: permission, record: record, actor: actor).first
+    def allow?(subject:, permission:, record: nil, actor: nil, model: nil)
+      decide(subject: subject, permission: permission, record: record, actor: actor, model: model).first
     end
 
     # Internal decision: returns [allowed_bool, reason_or_nil]. The reason is a
@@ -30,7 +38,13 @@ module CurrentScope
     # denial, and :sod_bypassed on the one AUDITED allow (break-glass). Ordinary
     # allows carry nil. The resolver — shared across threads — holds no
     # per-decision state; the reason rides in the return tuple, not on self.
-    def decide(subject:, permission:, record: nil, actor: nil)
+    #
+    # `model:` (#50) is the type the controller's current_scope_model hook
+    # declared for its collection actions, or nil when unknown. Only the
+    # record-less branch reads it, to bind that otherwise type-unbound grant
+    # check; every other branch ignores it. It stays a parameter, never state,
+    # per the purity rule above.
+    def decide(subject:, permission:, record: nil, actor: nil, model: nil)
       return [ false, :no_grant ] if subject.nil?
 
       case sod_decision(subject: subject, actor: actor, permission: permission, record: record)
@@ -42,6 +56,21 @@ module CurrentScope
       return [ true, nil ] if role&.full_access?
       return [ true, nil ] if role&.grants?(permission)
       return [ true, nil ] if scoped_grant?(subject: subject, permission: permission, record: record)
+      return [ true, nil ] if record_less_scoped_grant?(subject: subject, permission: permission, record: record, model: model)
+
+      # A LABEL, not a decision (R7a): this deny would have been an ALLOW had
+      # the controller declared current_scope_model and the grant ticked the
+      # key of that type. Without the distinct reason it is indistinguishable
+      # from an ordinary :no_grant, and the dev nudge that explains it is
+      # dev/test-only — so the production host who most needs the cause
+      # (403s after an upgrade) would be the one who cannot see it. Two labels
+      # for the two ways the declaration can be wrong: absent
+      # (:model_undeclared) vs present-but-unusable (:model_invalid — a
+      # String, PORO, or abstract class the shape guard refused). Same cell,
+      # different fix, so the label says which.
+      if record_less_denied_for_unknown_type?(subject: subject, permission: permission, record: record, model: model)
+        return [ false, model.nil? ? :model_undeclared : :model_invalid ]
+      end
 
       [ false, :no_grant ]
     end
@@ -65,6 +94,10 @@ module CurrentScope
     # host list can never drift from the per-record decision. Fail-closed (nil
     # subject / no grant → none) and flat — no parent/child cascade. SoD does
     # NOT apply: it vetoes record-targeted actions, not list membership.
+    #
+    # Since #65 the record-less gate asks this same query (.exists?) for
+    # actions in config.collection_read_actions, so gate and list cannot
+    # drift for listed reads — they are one query.
     def scope_for(subject:, model:, permission:)
       return model.none if subject.nil?
 
@@ -85,14 +118,110 @@ module CurrentScope
       )
     end
 
+    # Whether the separation-of-duties veto is in a position to decide about this
+    # pair at all: the action must be SoD-listed AND there must be an actual
+    # record instance to name an initiator from. The veto is defined in terms of
+    # who raised a record, so with no record it has nothing to measure and is
+    # skipped — that covers a collection action's nil, a class-form check like
+    # allowed_to?(:approve, Report), and equally a host hook that handed back
+    # something that isn't a record at all (`params[:id]`, a String).
+    #
+    # PUBLIC because "the veto did not run" and "the veto passed" are different
+    # facts, and a caller that acts on the difference must be able to ASK rather
+    # than infer it. It is not inferable from the decision: a skipped veto falls
+    # through to the ordinary grant check, so it surfaces as :no_grant or an
+    # ordinary allow — never as anything that says "SoD abstained". Report mode
+    # (#37) has to know, because :no_grant is the one reason it downgrades.
+    #
+    # This is the single definition of the condition, deliberately: sod_decision
+    # reads it too. Two copies of "did the veto run" is two copies that drift,
+    # and the copy that drifts is the one guarding the fraud control. (#59 review)
+    def sod_veto_applies?(permission:, record:)
+      sod_action?(permission) && record.respond_to?(:new_record?)
+    end
+
+    # The blind spot: an SoD-listed action whose veto could NOT run. The decision
+    # that comes back for one of these is :no_grant or an ordinary allow — the
+    # veto contributed nothing to it. Anyone treating that :no_grant as "SoD was
+    # fine with this" is reading a silence as an answer.
+    #
+    # The same hazard the record-less scoped branch already refuses (see
+    # sod_action? below) and that config.warn_on_nil_sod_record surfaces on the
+    # allow path: a host mis-gating a member SoD action. In :enforce this costs
+    # nothing — :no_grant is a 403 regardless, so the skipped veto never decides
+    # anything. Report mode is what makes it matter, because :no_grant is exactly
+    # what it downgrades. (#37, #59 review)
+    def sod_veto_skipped?(permission:, record:)
+      sod_action?(permission) && !sod_veto_applies?(permission: permission, record: record)
+    end
+
+    # Does this subject hold a scoped grant that satisfies `permission` on ANY
+    # record? Read-only, and deliberately unfiltered by resource — that absence
+    # IS the question: the grant exists, but the gate never got a record for it
+    # to apply to.
+    #
+    # DIAGNOSTICS ONLY (#41). It answers a COUNTERFACTUAL — "had the controller
+    # declared its record hook, would a scoped grant have allowed this?" — and
+    # must never decide anything. The record it would need in order to BE a
+    # decision is exactly what's missing; that's the bug it reports.
+    #
+    # Reads roles_granting (full_access ∪ ticking), and that is right BECAUSE
+    # the counterfactual binds to a record: with a real record, scoped_grant?
+    # honors a scoped full_access role, so an honest "would it have been
+    # allowed?" must honor it too. The same reuse in a branch that binds to NO
+    # record was #49's P0 escalation — one scoped grant passing every
+    # collection gate in the app. The binding is the entire difference, which is
+    # why this is a question and not a gate.
+    def scoped_grant_exists?(subject:, permission:)
+      return false if subject.nil?
+
+      ScopedRoleAssignment.where(subject: subject, role_id: roles_granting(permission)).exists?
+    end
+
     private
 
     # Role ids that satisfy `permission`: full_access (grants everything) or an
     # explicit grant of the key. The one place "does this role grant it?" is
-    # expressed for scoped grants — shared by the gate and scope_for.
+    # expressed for scoped grants. Including full_access is only safe while no
+    # caller turns an unbound match into a PERMIT. Four callers, each safe for
+    # its own reason: scoped_grant? binds `resource:` to the exact record;
+    # scope_for binds `resource_type:` and answers in record ids
+    # (.select(:resource_id)) for the caller to narrow, never a boolean permit
+    # — which is also why the record-less read gate (#65) is safe: it asks
+    # scope_for and takes .exists? of the id-narrowed relation, so its answer
+    # is still derived from the records the subject holds, not from the grant
+    # row alone; scoped_grant_exists? binds nothing and is therefore
+    # diagnostics-only — its own comment says why it must never decide;
+    # record_less_denied_for_unknown_type?'s listed-read arm (#65) is the same
+    # diagnostics-only shape — it labels a deny, it never decides. A new
+    # caller must fit one of those shapes or use roles_ticking. (#65 cites
+    # this comment as the safety condition; it is load-bearing, keep it true.)
     def roles_granting(permission)
-      Role.where(full_access: true)
-          .or(Role.where(id: RolePermission.where(permission_key: permission).select(:role_id)))
+      Role.where(full_access: true).or(Role.where(id: roles_ticking(permission)))
+    end
+
+    # Role ids that EXPLICITLY tick `permission` — full_access roles deliberately
+    # excluded, whether or not they also carry a RolePermission row. Only for the
+    # record-less branch, which binds the grant to no record at all: honoring
+    # full_access there would mean one scoped full_access grant on one record
+    # ("Owner of Report #7") opened EVERY record-less gate in the host app —
+    # every #index and #create on every controller — since a full_access role
+    # satisfies every key. That is the `resource:` bound scoped_grant? applies
+    # and the record-less branch cannot.
+    #
+    # The `where.not` is load-bearing, not belt-and-braces: a role can be
+    # full_access AND retain explicit rows (tick grid cells, then flip the
+    # full-access toggle), and matching on the leftover row alone would walk it
+    # straight back through the branch full_access is barred from.
+    #
+    # roles_granting's set is unchanged by this exclusion — it unions
+    # full_access back in, so full_access ∪ (ticking − full_access) == the same
+    # roles it always matched.
+    def roles_ticking(permission)
+      RolePermission
+        .where(permission_key: permission)
+        .where.not(role_id: Role.where(full_access: true).select(:id))
+        .select(:role_id)
     end
 
     # The separation-of-duties outcome for this decision: :none (no conflict, or
@@ -100,11 +229,7 @@ module CurrentScope
     # the veto stands), or :bypass (a conflict exists but break-glass lifts it).
     # Pure — reads only; the audit write for a :bypass happens at the Guard.
     def sod_decision(subject:, actor:, permission:, record:)
-      action = permission.split("#").last
-      return :none unless CurrentScope.config.sod_actions.include?(action)
-      # No veto without an actual record instance (collection actions get nil,
-      # class-form checks like allowed_to?(:approve, Report) get the class).
-      return :none unless record.respond_to?(:new_record?)
+      return :none unless sod_veto_applies?(permission: permission, record: record)
 
       # SoD is a structural guarantee — "cannot determine the initiator" must
       # never mean "permit". A record type where SoD genuinely doesn't apply
@@ -114,7 +239,7 @@ module CurrentScope
               "#{record.class.name}##{INITIATOR_METHOD} is not defined, but " \
               "\"#{permission}\" is a separation-of-duties action (config.sod_actions). " \
               "Define #{INITIATOR_METHOD} on #{record.class.name} (return nil to exempt " \
-              "a record), or remove \"#{action}\" from config.sod_actions."
+              "a record), or remove \"#{permission.split('#').last}\" from config.sod_actions."
       end
 
       initiator = record.send(INITIATOR_METHOD)
@@ -167,5 +292,184 @@ module CurrentScope
         .where(subject: subject, resource: record, role_id: roles_granting(permission))
         .exists?
     end
+
+    # A record-less target is allowed in one of two ways (#19, #65):
+    #
+    #   - an action in config.collection_read_actions asks scope_for — the
+    #     id-narrowed query the list renders from — so the gate opens exactly
+    #     when the subject's list would show records, full_access included.
+    #     Gate and list agree by construction; an empty list (no grant, or a
+    #     grant whose record was destroyed) is a deny, fail-closed.
+    #   - any other action needs a scoped grant whose role EXPLICITLY ticks
+    #     the key. scope_for then narrows the collection to the granted records.
+    #
+    # Without this, the two halves of the per-record feature contradict each
+    # other: the gate turns a scoped-only subject away from their index, and
+    # the org-wide grant that gets them past it makes scope_for return every
+    # record.
+    #
+    # "Record-less" is a CLOSED set of exactly two shapes, tested positively:
+    #
+    #   nil     — a collection action; the Guard's hook returns nil when there is
+    #             no record (guard.rb), which is the documented contract.
+    #   a Class — the class form, allowed_to?(:index, Report).
+    #
+    # Positive, never `unless record.respond_to?(:new_record?)`: a negative test
+    # admits an OPEN set, so a host whose current_scope_record wrongly returns
+    # params[:id] (a String) or any other non-record would land here and be
+    # ALLOWED on the strength of a grant held over some *other* record — a
+    # fail-open in a fail-closed engine, and a breach of this branch's own
+    # invariant that a grant on X must not act on Y. Anything that is not
+    # literally nil-or-a-Class is not a record-less target and gets no say here.
+    #
+    # Consequence, deliberate: an UNPERSISTED instance (Report.new) is not
+    # record-less by this test, and scoped_grant? needs persisted? — so it is
+    # denied, while the class form is allowed. That asymmetry is only reachable
+    # by gating a collection action with Model.new instead of the documented nil,
+    # and it fails CLOSED (a 403 the host sees immediately), which is the safe
+    # direction to be wrong in.
+    #
+    # Binds by TYPE (#50). The target names no record, but the controller can
+    # name the type its collection lists via current_scope_model (record when
+    # it is a Class — the allowed_to?(:index, Report) form — else the model:
+    # kwarg the Guard threads). resource_type filters the grant to that type,
+    # normalized through base_class exactly as scope_for does, so "a Report
+    # grant" cannot open a Documents gate. UNKNOWN type ⇒ this branch does not
+    # fire (fail-closed): before #50 an unbound grant of any type opened every
+    # record-less gate, and for a key with no list side (#create) that let a
+    # Report-scoped subject create Documents — a live escalation, not a
+    # cosmetic empty list. A loud, documented deny is the safe direction.
+    #
+    # full_access and the two arms (#65): the read arm honors a scoped
+    # full_access grant because scope_for's answer is DERIVED FROM RECORD IDS —
+    # which records the subject holds, joined against the live table — the one
+    # shape roles_granting's safety condition names as safe. The non-read arm
+    # answers with a boolean off a type-bound match, strictly weaker (the id is
+    # discarded), so full_access stays barred there: one scoped grant on one
+    # Report must not create Reports. "Owner of Report #7" means full access to
+    # Report #7 — and, since #65, to the lists that would show it. (#65 records
+    # in full why a type-bound boolean over roles_granting is never the answer;
+    # 029's R4 was withdrawn over exactly that.)
+    #
+    # TRUST NOTE: the declared type is trusted the way current_scope_record is.
+    # A wrong current_scope_model plus a scoped full_access grant of the
+    # declared type opens that controller's listed reads — review the
+    # declaration like the record hook. Before #65 that misconfiguration
+    # failed closed; the trade is deliberate and documented (README, #65 plan
+    # KTD-5).
+    #
+    # Deliberately NOT memoized, unlike org_role. The memo there caches one
+    # lookup keyed by subject, invalidated by RoleAssignment writes alone. This
+    # predicate's answer derives from three tables (scoped assignments, roles,
+    # role permissions) — four on the read arm, whose scope_for joins the model
+    # table itself — so a memo would need invalidation hooks on all of them,
+    # and a stale entry here is a stale ALLOW. Only record-less checks by
+    # scoped-only subjects reach this line (org and full_access short-circuit
+    # above), so the cost is one query — on the read arm an id-subquery EXISTS
+    # against the model table — on a handful of nav-level checks per page, not
+    # the per-row gate. Revisit if that ever shows up in a profile.
+    def record_less_scoped_grant?(subject:, permission:, record:, model: nil)
+      # R3a: the record-less shape test stays FIRST — a declared model never
+      # rescues a non-record-less target. A host whose current_scope_record
+      # wrongly returns params[:id] (a String) must still fail closed here, not
+      # be allowed off a grant held over some other record.
+      return false unless record.nil? || record.is_a?(Class)
+      return false if sod_action?(permission)
+
+      # The class form (allowed_to?(:index, Report)) carries the type as the
+      # record; otherwise it comes from the model: hook. Unknown ⇒ deny (R3).
+      type = record.is_a?(Class) ? record : model
+      return false if type.nil?
+
+      # Shape guard, mirroring R3a's on the record: a type that is not an
+      # ActiveRecord model class (a String from a mis-declared
+      # current_scope_model, a non-record-storing PORO passed to the class form
+      # — the gem's own Scopeable Gadget is one) cannot name a base_class to
+      # normalize by. Require an actual AR subclass, not just anything answering
+      # base_class — a class whose base_class returns nil would still crash on
+      # .name. Deny (fail-closed) rather than raise NoMethodError: a garbage
+      # type is not a grant, and denying also preserves the pre-#50 boolean the
+      # class form returned for a non-AR argument. This guard must stay ABOVE
+      # the read arm — scope_for calls type.base_class and type.where, so a
+      # non-AR type would 500 instead of denying. (#50 review, #65)
+      #
+      # ABSTRACT classes are excluded too (#65 review): ApplicationRecord
+      # passes `< ActiveRecord::Base` but has no table, so the read arm's
+      # scope_for would raise TableNotSpecified where the ticking arm's
+      # resource_type match simply found nothing. An abstract class stores no
+      # rows, so no scoped grant can name it — deny, don't 500.
+      return false unless collection_type?(type)
+
+      if collection_read_action?(permission)
+        scope_for(subject: subject, model: type, permission: permission).exists?
+      else
+        ScopedRoleAssignment
+          .where(subject: subject, resource_type: type.base_class.name, role_id: roles_ticking(permission))
+          .exists?
+      end
+    end
+
+    # A usable collection type: an actual concrete ActiveRecord subclass —
+    # the one shape whose base_class/where the two record-less arms may call.
+    # The full rationale lives on the shape guard in record_less_scoped_grant?
+    # above; this predicate exists so the diagnostic labeler below refuses the
+    # exact same shapes the gate refused, and cannot drift from it.
+    def collection_type?(type)
+      type.is_a?(Class) && type < ActiveRecord::Base && !type.abstract_class?
+    end
+
+    # Would a (correct) current_scope_model declaration have given this
+    # record-less deny a chance? True only for the exact cell the #50
+    # fail-closed default created: a DECLARED collection action (record nil —
+    # the class form always carries its type, so it never lands here), no
+    # USABLE declared model — absent, or present but refused by the shape
+    # guard (a String, PORO, or abstract class) — not an SoD action (those
+    # are refused whatever the type), and a scoped grant EXPLICITLY ticking
+    # the key exists. Pure — reads only; decide labels the deny
+    # :model_undeclared / :model_invalid off this, changing no allow/deny.
+    #
+    # The role set follows the arm the deny came from (#65): a listed read
+    # matches a full_access-INCLUSIVE set, because a declared type would honor
+    # full_access there through scope_for — the label stays honest by saying
+    # so. Off the read list the set stays roles_ticking: naming a full_access
+    # grant :model_undeclared on #create would send the host to a fix that
+    # fixes nothing. Diagnostics-only either way — this labels a deny, it
+    # never decides (the scoped_grant_exists? shape, named in roles_granting's
+    # safety comment) — and it runs without a model, so it cannot check record
+    # liveness: a grant on a destroyed record makes "declare the model and
+    # this allows" false, which is why the nudge says "may fix", never
+    # promises.
+    def record_less_denied_for_unknown_type?(subject:, permission:, record:, model:)
+      return false unless record.nil? && !collection_type?(model)
+      return false if sod_action?(permission)
+
+      roles = collection_read_action?(permission) ? roles_granting(permission) : roles_ticking(permission)
+      ScopedRoleAssignment.where(subject: subject, role_id: roles).exists?
+    end
+
+    # An SoD action is record-targeted BY DEFINITION — "the subject who
+    # initiated a record can never approve THAT record". So a record-less SoD
+    # check is a contradiction in terms: there is no record for the veto to
+    # measure, and `sod_decision` returns :none for exactly that reason. Opening
+    # such a gate off a scoped grant would let a host that mis-gates a member
+    # SoD action (current_scope_record returning nil on `reports#approve` —
+    # precisely what warn_on_nil_sod_record exists to catch) hand out the action
+    # with the four-eyes veto silently skipped. The veto is a structural
+    # guarantee, so it must not rest on an opt-in dev warning; deny instead.
+    #
+    # This does NOT close the older org-grant asymmetry — a nil record on an SoD
+    # action still passes for an org-wide grant, which is characterized and
+    # pinned in test/sod_nil_record_test.rb. It only stops the record-less scoped
+    # branch from widening that hole to scoped grants too.
+    def sod_action?(permission)
+      CurrentScope.config.sod_actions.include?(permission.split("#").last)
+    end
+
+    # An action whose record-less gate derives from the scoped list (#65).
+    # Matched like sod_action?: the action segment of the key against a config
+    # list (config.collection_read_actions normalizes to strings on write).
+    def collection_read_action?(permission)
+      CurrentScope.config.collection_read_actions.include?(permission.split("#").last)
+    end
   end
 end

data/lib/current_scope/version.rb

@@ -1,3 +1,3 @@
 module CurrentScope
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end