rigortype 0.3.4 → 0.3.5

data/lib/rigor/effects/propagator.rb

@@ -53,23 +53,49 @@ module Rigor
         return EffectTable.empty if collection.summaries.empty?
 
         summaries = collection.summaries
-        edges = resolve_edges(collection)
         state = seed(summaries, discharge)
+        edges = resolve_edges(collection, state)
         iterate(state, edges)
         EffectTable.new(build_entries(summaries, edges, state))
       rescue StandardError
         EffectTable.empty
       end
 
-      # `{caller_key => [callee_key]}`, sorted and de-duplicated.
-      def resolve_edges(collection)
+      # `{caller_key => [callee_key]}`, sorted and de-duplicated. Seeds the `unresolved-super` taint in
+      # the same pass, because whether a `super` resolved is exactly what this resolution answers.
+      def resolve_edges(collection, state)
         index = Index.new(collection)
         collection.edges.each_with_object({}) do |(caller_key, list), out|
-          targets = list.flat_map { |edge| index.targets_for(edge) }.uniq.sort
+          targets = list.flat_map do |edge|
+            resolved = index.targets_for(edge)
+            taint_unresolved_super(state, caller_key, edge) if edge.super_call && resolved.empty?
+            resolved
+          end.uniq.sort
           out[caller_key] = targets.freeze unless targets.empty?
         end
       end
 
+      # A `super` the project's own ancestry does not answer — the implementation is in a gem, in Ruby's
+      # core, or in a module prepended at run time — is the case the taint exists for (#446). Silence
+      # would be the one thing the effect model must never say: that the list is complete when a call in
+      # the body was not read. An unresolved ORDINARY edge is dropped instead, because most such calls
+      # are inherited ones the catalogue simply has no row for and the site's own taint was already
+      # decided from the typer's verdict; a `super` has no site verdict to fall back on, and it always
+      # dispatches to something.
+      #
+      # Decided here rather than in the collector because only the merged ancestry can say whether the
+      # parent resolves, and written into the SEED rather than into the direct summary so the fixpoint
+      # carries it to this method's callers exactly as it carries any other cause. A snapshot's
+      # `methods:` table records direct summaries and so does not show it; `reach:`, the report and the
+      # judgment all read the closure and do.
+      def taint_unresolved_super(state, caller_key, edge)
+        entry = state[caller_key]
+        return if entry.nil?
+
+        entry[:exhaustive] = false
+        entry[:causes] << ["unresolved-super", edge.selector].freeze
+      end
+
       # Causes are carried as a Set through the fixpoint and flattened back to a sorted Array in
       # {build_entries}. A Set is what {absorb} needs: unioning one along an edge must cost the source's
       # size and allocate NOTHING when it adds nothing, and the array-concat-and-uniq it replaces
@@ -170,8 +196,8 @@ module Rigor
         end
       end
 
-      private_class_method :resolve_edges, :seed, :iterate, :reverse_edges, :absorb, :join_lane,
-                           :build_entries
+      private_class_method :resolve_edges, :taint_unresolved_super, :seed, :iterate, :reverse_edges,
+                           :absorb, :join_lane, :build_entries
 
       # The class graph a run's collections describe, and the edge resolution over it. Built once per
       # propagation; every lookup is a Hash read.
@@ -189,25 +215,43 @@ module Rigor
         # Every project method key `edge` may reach: the definition its ancestry resolves to, plus every
         # override of the same selector in a project subclass of the receiver's class.
         #
-        # Memoised on `(receiver class, kind, selector)` — the answer depends on nothing else, and one
-        # such triple is asked for once per call site in the project. `ApplicationRecord#save` alone is
+        # Memoised on `(receiver class, kind, selector, super?)` — the answer depends on nothing else, and
+        # one such tuple is asked for once per call site in the project. `ApplicationRecord#save` alone is
         # thousands of sites on a Rails app, each of which used to re-walk the whole subclass forest.
         def targets_for(edge)
-          @targets[[edge.receiver_class, edge.kind, edge.selector]] ||= begin
+          @targets[[edge.receiver_class, edge.kind, edge.selector, edge.super_call]] ||= begin
             separator = edge.kind == :singleton ? "." : "#"
-            targets = []
-            owner = resolve_owner(edge.receiver_class, separator, edge.selector)
-            targets << owner if owner
-            descendant_closure(edge.receiver_class).each do |subclass|
-              key = "#{subclass}#{separator}#{edge.selector}"
-              targets << key if @summaries.key?(key)
-            end
-            targets.freeze
+            edge.super_call ? super_targets(edge, separator) : call_targets(edge, separator)
           end
         end
 
         private
 
+        def call_targets(edge, separator)
+          targets = []
+          owner = resolve_owner(edge.receiver_class, separator, edge.selector)
+          targets << owner if owner
+          descendant_closure(edge.receiver_class).each do |subclass|
+            key = "#{subclass}#{separator}#{edge.selector}"
+            targets << key if @summaries.key?(key)
+          end
+          targets.freeze
+        end
+
+        # A `super` reaches **one** definition, and the closed-world override join every other edge gets
+        # is deliberately absent from it (#446). `super` in `C#m` dispatches into the ancestry above `C`
+        # in the receiver's chain, and a subclass of `C` is never in it however the receiver was
+        # constructed — so joining `D#m` would put a proven label on `C#m` that no execution of `C#m` can
+        # produce. Ruby's lack of `final` is the argument for the join at an ordinary call site and says
+        # nothing here.
+        def super_targets(edge, separator)
+          target = resolve_super(edge.receiver_class, separator, edge.selector)
+          target ? [target].freeze : NO_TARGETS
+        end
+
+        NO_TARGETS = [].freeze
+        private_constant :NO_TARGETS
+
         # The transitive subclass closure, memoised per class. A deep hierarchy's root is asked for it
         # once, not once per selector reaching it.
         def descendant_closure(class_name)
@@ -220,8 +264,24 @@ module Rigor
         # enqueued and the most-qualified one comes first, so the right constant wins the race and a
         # spelling that names nothing simply matches no key.
         def resolve_owner(class_name, separator, selector)
-          seen = Set.new
-          queue = [class_name]
+          walk_ancestors([class_name], Set.new, separator, selector)
+        end
+
+        # Where `super` from `class_name#selector` lands: the same ancestor walk, started one step up —
+        # the modules the class includes, then its superclass chain — with the class itself already in
+        # `seen`, because a method never `super`s into itself.
+        #
+        # The includes are instance-side only. `include M` puts `M#m` between the class and its
+        # superclass, which is exactly where `super` looks, while `M.m` is a singleton method `include`
+        # never contributes; a singleton `super` that really does reach a module went through `extend` or
+        # a `class << self` include, neither of which is collected, so it resolves to nothing and taints.
+        def resolve_super(class_name, separator, selector)
+          queue = separator == "#" ? @includes.fetch(class_name, []).dup : []
+          queue.concat(@superclasses.fetch(class_name, []))
+          walk_ancestors(queue, Set.new([class_name]), separator, selector)
+        end
+
+        def walk_ancestors(queue, seen, separator, selector)
           until queue.empty?
             current = queue.shift
             next if current.nil? || !seen.add?(current)

data/lib/rigor/effects/registry.rb

@@ -74,14 +74,16 @@ module Rigor
         new(
           vocabulary_version: raw.fetch("vocabulary", 0),
           labels: raw.fetch("labels", nil) || [],
-          retired: raw.fetch("retired", nil) || {}
+          retired: raw.fetch("retired", nil) || {},
+          descriptions: raw.fetch("descriptions", nil) || {}
         )
       end
 
       attr_reader :vocabulary_version
 
-      def initialize(vocabulary_version:, labels:, retired: {})
+      def initialize(vocabulary_version:, labels:, retired: {}, descriptions: {})
         @vocabulary_version = vocabulary_version
+        @descriptions = descriptions.to_h { |root, text| [root.to_s, text.to_s.gsub(/\s+/, " ").strip] }.freeze
         @labels = labels.map(&:to_s).uniq.sort.freeze
         @known = build_known(@labels)
         @roots = @known.select { |label| Label.parent(label).nil? }.sort.freeze
@@ -96,6 +98,10 @@ module Rigor
       # The roots of the vocabulary — the outermost segments {#with} treats as already owned.
       attr_reader :roots
 
+      # One line per root, from the data file's `descriptions:` — what `rigor effects --list-labels`
+      # prints beside a root (#429). A root nothing describes (a plugin's, a project's) has no entry.
+      attr_reader :descriptions
+
       # Whether the vocabulary recognises `label`: an exact row, or an ancestor of one. A declared
       # `io` is recognised because `io.net` exists, so a bound may name an interior node the data
       # file never spells out on its own line.
@@ -142,7 +148,8 @@ module Rigor
 
           check_ownership(label, owner)
         end
-        self.class.new(vocabulary_version: @vocabulary_version, labels: @labels + added, retired: @retired)
+        self.class.new(vocabulary_version: @vocabulary_version, labels: @labels + added, retired: @retired,
+                       descriptions: @descriptions)
       end
 
       private

data/lib/rigor/effects/scanner.rb

@@ -116,12 +116,20 @@ module Rigor
       end
 
       def enter_def(node, prefix, singleton)
-        instance_method = !singleton && node.receiver.nil?
-        harvest_for(prefix)[:defs] << node.name.to_s if @harvest && instance_method && !prefix.empty?
-        add_unit(
-          class_name_for(prefix), node.name.to_s, singleton || !node.receiver.nil?,
-          node.body, node.parameters
-        )
+        own_singleton = singleton || !node.receiver.nil?
+        scan = add_unit(class_name_for(prefix), node.name.to_s, own_singleton, node.body, node.parameters)
+        harvest_def(prefix, node.name.to_s, own_singleton, scan) if @harvest && !prefix.empty?
+      end
+
+      # What the framework strategies need to know about a `def` the class body spelled out itself: that it
+      # exists, and whether it reaches `super`. `:defs` stays instance-only, because a mailer action is an
+      # instance method; `:units` is keyed by the suffix a synthetic unit key carries, so both sides of the
+      # `#` / `.` split are answerable (#440). A body the collector could not finish reads as delegating,
+      # which keeps the framework's claim — the fail-soft direction for an upper bound.
+      def harvest_def(prefix, name, singleton, scan)
+        entry = harvest_for(prefix)
+        entry[:defs] << name unless singleton
+        entry[:units]["#{singleton ? '.' : '#'}#{name}"] = scan.nil? || scan.delegates_upward?
       end
 
       # ADR-103 WD10 — a receiver-less call in a class body, recorded as `macro => [literal symbol
@@ -156,7 +164,7 @@ module Rigor
       end
 
       def harvest_for(prefix)
-        @harvest[class_name_for(prefix)] ||= { defs: [], macros: {}, uniqueness: false }
+        @harvest[class_name_for(prefix)] ||= { defs: [], units: {}, macros: {}, uniqueness: false }
       end
 
       # Files the units the framework contributes for each class this file declares. Runs after the walk,
@@ -168,7 +176,7 @@ module Rigor
         @harvest.each do |class_name, entry|
           FrameworkUnits.synthesize(
             class_name: class_name, instance_methods: entry[:defs], macros: entry[:macros],
-            uniqueness: entry[:uniqueness], plugin_facts: @plugin_facts
+            uniqueness: entry[:uniqueness], plugin_facts: @plugin_facts, own_units: entry[:units]
           ).each { |key, summary, edges| merge_unit(key, summary, edges) }
         end
       end
@@ -176,6 +184,8 @@ module Rigor
       # Scans one unit and files its summary, then recurses into the units its body declared. Fail-soft
       # per unit (ADR-103 WD13): a unit the scanner cannot finish is recorded as non-exhaustive with
       # `collector-error` and its siblings are unaffected.
+      #
+      # @return [UnitScan, nil] the finished scan, or nil when the unit failed soft
       def add_unit(class_name, method_name, singleton, body, parameters)
         key = "#{class_name}#{singleton ? '.' : '#'}#{method_name}"
         names = parameter_names(parameters)
@@ -184,15 +194,17 @@ module Rigor
           block_parameter: block_parameter_name(parameters),
           owned_locals: LocalOwnership.owned(body, names), calls: @calls,
           attribution: @attribution, envelopes: @envelopes, plugin_facts: @plugin_facts,
-          owner_class: class_name
+          owner_class: class_name, method_name: method_name
         )
         summary, edges = scan.run(body)
         merge_unit(key, summary, edges)
         scan.nested.each do |name, nested_singleton, nested_body, nested_parameters|
           add_unit(class_name, name, singleton || nested_singleton, nested_body, nested_parameters)
         end
+        scan
       rescue StandardError
         merge_unit(key, Summary.tainted("collector-error", method_name), [])
+        nil
       end
 
       # A receiver-less call in a class / module body that declares units or ancestry. Class bodies are

data/lib/rigor/effects/signature_sources.rb

@@ -58,6 +58,22 @@ module Rigor
         signature_paths.nil? || signature_paths.empty? ? DEFAULT_ROOTS : signature_paths
       end
 
+      # The FIRST annotated virtual entry, as a `collect`-shaped one-element array (or an empty one).
+      #
+      # #441 — the analysis paths use this to hand the annotations-unchecked residual the inline stratum
+      # of a run that resolved an environment but never stored it. Reduced to one entry on purpose: the
+      # residual reports one annotation per run, so the carrier a run holds past the environment's own
+      # lifetime is a single synthesized buffer rather than the project's whole virtual tree.
+      #
+      # @param virtual_rbs [Array<Array(String, String)>, nil]
+      # @return [Array<Array(String, String)>] zero or one pair.
+      def annotated_carrier(virtual_rbs)
+        Array(virtual_rbs).each do |name, content|
+          return [[name.to_s, content.to_s]] if ANNOTATION_HINT.match?(content)
+        end
+        [].freeze
+      end
+
       # The first `[name, content, line]` carrying an effect annotation, or nil. Line numbers are
       # 1-based and count into `content`, which for a `virtual:` buffer is the SYNTHESIZED text — the
       # caller re-anchors it against the Ruby file when that matters.

data/lib/rigor/effects/snapshot.rb

@@ -164,11 +164,7 @@ module Rigor
           entries.flat_map do |entry|
             next [entry] if EntryPoints.glob?(entry)
 
-            EntryPoints.globs_for(entry) ||
-              raise(EntryPoints::Error,
-                    "effects.snapshot.reach names no registered entry-point preset: #{entry.inspect} " \
-                    "(registered: #{EntryPoints.names.inspect}; a preset is named by the plugin that " \
-                    "models the framework, so listing that plugin is what registers it)")
+            EntryPoints.resolve!(entry)
           end.uniq.sort.freeze
         end
 
@@ -335,6 +331,25 @@ module Rigor
       # Renders the file. Hand-rolled rather than `YAML.dump`ed so the leading comment, the key order and
       # the flow sequences are ours: two runs over one tree must be byte-identical, and a snapshot written
       # by a pooled run must equal the sequential one bit for bit.
+      # The hint goes in the artefact, not only in the run's output (#436): `reach:` is the half of the
+      # snapshot that answers what an entry point *causes*, and a project that never configured one
+      # commits the less interesting half with no way to know it. The run also names the presets its own
+      # plugin set registered, which this file cannot — a committed artefact must not carry a list that
+      # goes stale when the plugin list changes.
+      EMPTY_REACH_NOTE = [
+        "",
+        "# `reach:` is empty. It records the TRANSITIVE footprint at your entry points — what a",
+        "# controller action or a job causes, rather than what its own body does — and it is the half of",
+        "# this file most worth reviewing. Fill it in by naming entry points in `.rigor.yml`:",
+        "#",
+        "#   effects:",
+        "#     snapshot:",
+        "#       reach: [rails]          # a preset a plugin registered, or a project-relative file glob",
+        "#",
+        "# `rigor effects update` prints the presets this project's plugins actually register."
+      ].freeze
+      private_constant :EMPTY_REACH_NOTE
+
       def to_yaml
         lines = [HEADER]
         lines << "schema: #{@header.fetch('schema')}"
@@ -342,6 +357,7 @@ module Rigor
         lines << "vocabulary: #{@header.fetch('vocabulary')}"
         lines << "config_digest: #{scalar(@header.fetch('config_digest'))}"
         render_table(lines, "methods", @methods)
+        lines.concat(EMPTY_REACH_NOTE) if @reach.empty?
         render_table(lines, "reach", @reach)
         "#{lines.join("\n")}\n"
       end

data/lib/rigor/effects/taint_cause.rb

@@ -18,6 +18,7 @@ module Rigor
         dynamic-send
         method-missing
         unresolved-self-call
+        unresolved-super
         opaque-callable
         unknown-ownership
         plugin-attribution

data/lib/rigor/effects/unit_scan.rb

@@ -110,9 +110,12 @@ module Rigor
       # @param plugin_facts [PluginFacts] the loaded plugins' `effect_attributions:` (#387)
       # @param owner_class [String, nil] the class this unit is defined on — the carrier an
       #   implicit-self call's envelope is looked up under, since the syntax spells `Kernel#name`
+      # @param method_name [String, nil] this unit's own selector — what a `super` in its body names as
+      #   the target the propagator resolves above `owner_class` (#446). With no name to state, a `super`
+      #   taints instead.
       def initialize(singleton:, parameters:, block_parameter:, owned_locals:, calls:, # rubocop:disable Metrics/ParameterLists
                      attribution: Attribution.empty, envelopes: EnvelopeIndex.empty,
-                     plugin_facts: PluginFacts.empty, owner_class: nil)
+                     plugin_facts: PluginFacts.empty, owner_class: nil, method_name: nil)
         @singleton = singleton
         @block_parameter = block_parameter
         @calls = calls
@@ -120,6 +123,7 @@ module Rigor
         @envelopes = envelopes
         @plugin_facts = plugin_facts
         @owner_class = owner_class
+        @method_name = method_name
         @mutation = MutationClassifier.new(
           singleton: singleton, parameters: parameters, owned_locals: owned_locals
         )
@@ -128,12 +132,24 @@ module Rigor
         @causes = []
         @edges = []
         @nested = []
+        @delegates_upward = false
       end
 
       # Units discovered inside this one — a nested `def`, or a `define_method` with a literal name whose
       # block becomes that method's body. Each is `[name, singleton, body_node, parameters_node]`.
       attr_reader :nested
 
+      # Whether this body reaches `super` — an override that delegates upward still runs whatever the
+      # superclass does. Nested `def`s are unit boundaries, so a `super` counted here is this unit's.
+      #
+      # A separate reading of the same node from the edge {#visit_super} records: what this bit answers is
+      # whether a framework's claim about the selector survives the class having written a body for it
+      # ({FrameworkUnits.replaced?}, #440), which is a question about the *class*, not about what the
+      # parent implementation does.
+      def delegates_upward?
+        @delegates_upward
+      end
+
       # Walks `body` and returns `[Summary, edges]`.
       def run(body)
         walk(body)
@@ -214,9 +230,31 @@ module Rigor
         when Prism::IndexOperatorWriteNode, Prism::IndexOrWriteNode, Prism::IndexAndWriteNode,
              Prism::CallOperatorWriteNode, Prism::CallOrWriteNode, Prism::CallAndWriteNode
           classify_mutation(node.receiver)
+        when Prism::SuperNode, Prism::ForwardingSuperNode
+          visit_super
         end
       end
 
+      # `super` in every shape — bare, `super()`, `super(args)`, and each of those inside a block or a
+      # rescue, since the walk descends into both (#446).
+      #
+      # It is a dispatch and must contribute like one. What the scan can settle from the syntax is the
+      # *identity* of the target — this unit's own class and selector — and nothing more: which definition
+      # sits above the class is a question about the whole project, so it goes out as an edge and the
+      # propagator resolves it against the merged ancestry, tainting when nothing there answers.
+      #
+      # A unit with no class or no name has no target to state. That is not a shape the scanner produces,
+      # and the taint is what a "cannot say" must read as rather than a silently dropped call.
+      def visit_super
+        @delegates_upward = true
+        return taint("unresolved-super", @method_name) if @owner_class.nil? || @method_name.nil?
+
+        @edges << FileCollection::Edge.new(
+          receiver_class: @owner_class, kind: @singleton ? :singleton : :instance,
+          selector: @method_name, self_call: true, super_call: true
+        )
+      end
+
       def visit_call(node)
         record = @calls[node]
         attribute(node, record)
@@ -285,14 +323,30 @@ module Rigor
 
       # The class whose call produced this receiver, for an `on_result:` row: the constant in
       # `UserMailer.welcome(u).deliver_now`, the receiver class the typer had otherwise. Nil unless the
-      # receiver is itself a call with a receiver — a bare local variable says nothing about what made it.
+      # receiver is itself a call — a bare local variable says nothing about what made it.
+      #
+      # Two shapes beyond the constant, because between them they are how mail is actually sent (#456):
+      #
+      # - **an implicit-self producing call** — `issue_add(user, issue).deliver_later`, which is what a
+      #   mailer's own `def self.deliver_issue_add` wrapper looks like in Redmine, 97 call sites of it.
+      #   The producer is the unit's own class, which is exactly what an unqualified name resolves
+      #   against;
+      # - **a builder one link further out** — `AdminMailer.with(recipient: a).new_trends(…).deliver_later!`,
+      #   ActionMailer's parameterized form and the spelling Mastodon uses. `with` returns a lazy
+      #   `Parameterized::Mailer` no project declares a type for, so the constant is two calls away rather
+      #   than one, and stopping at the first link found nothing.
+      #
+      # The walk is the same heuristic the `on_result:` row already is — "the class that produced this" —
+      # applied transitively rather than once. A row still has to match the producer's ancestry AND the
+      # selector, so a chain that ends somewhere unrelated contributes nothing rather than a wrong label.
       def producer_class(receiver)
         return nil unless receiver.is_a?(Prism::CallNode)
 
         inner = receiver.receiver
-        return nil if inner.nil?
+        return @owner_class if inner.nil?
 
-        Source::ConstantPath.qualified_name(inner) || @calls[receiver]&.receiver_class
+        Source::ConstantPath.qualified_name(inner) || producer_class(inner) ||
+          @calls[receiver]&.receiver_class
       end
 
       # The receiver expression as the syntax spells it — `"Rails.cache"`, `"self.flash.now"` — or nil when
@@ -379,12 +433,12 @@ module Rigor
       # receiver mutation; `Time#localtime` is both). A **posture** states nothing about this selector,
       # so the uncatalogued path's own mutation rule applies to it unchanged.
       def claimed_by_catalogue?(node, record)
-        owner, singleton, implicit = catalog_target(node, record)
+        owner, singleton, implicit, named = catalog_target(node, record)
         return false if owner.nil?
 
         entry = Catalog.default.lookup(
           owner, node.name.to_s, singleton: singleton, call_node: node,
-                                 posture: posture_allowed?(node, record, implicit)
+                                 posture: posture_allowed?(node, record, implicit, named)
         )
         return false if entry.nil?
 
@@ -426,8 +480,26 @@ module Rigor
       #   it would be a proven label with nothing proving it (the `dynamic-receiver` taint is the right
       #   answer, and the uncatalogued path records it);
       # - `send` / `call`, whose own taints are the more specific reading ({DEFERRED_SELECTORS}).
-      def posture_allowed?(node, record, implicit)
-        !implicit && !record&.dynamic && !DEFERRED_SELECTORS.include?(node.name)
+      #
+      # **Unless the syntax named the class** (#463). The `Dynamic` exclusion exists because a projected
+      # receiver class is a guess; a written constant path is not one, and {#catalog_target} already
+      # trusts it for the row lookup. Refusing the posture there made the catalogue's reach a function of
+      # whether the bundled rbs happens to ship a signature for the constant: `Net::HTTP.get` proves
+      # `io.net.http` and `Net::IMAP.new` proved nothing, because rbs ships `net-http` and not
+      # `net-imap`. That is why the `Net::FTP` row has never once fired, and why Redmine's IMAP and POP3
+      # pollers proved no network at all.
+      #
+      # The site is then **claimed**, and so discharges, like every other catalogue answer. That is not a
+      # softening of the `dynamic-receiver` rule but its premise failing: the taint says the class the
+      # typer projected is a guess, and on a constant path there is no projection — the receiver of
+      # `Net::IMAP.new` is that constant, exactly. What the posture asserts on top is the hand-audited
+      # claim the catalogue is made of, the same one `Socket#connect` rests on when the typer did name
+      # the receiver. `implicit` and {DEFERRED_SELECTORS} keep their exclusions, which are about what the
+      # syntax means rather than about what the typer knew.
+      def posture_allowed?(node, record, implicit, named)
+        return false if implicit || DEFERRED_SELECTORS.include?(node.name)
+
+        named || !record&.dynamic
       end
 
       def visit_uncatalogued(node, record, bound = nil)
@@ -550,18 +622,21 @@ module Rigor
       # The class the catalogue would look this call up under, as `[owner, singleton, implicit_self]`.
       # Spelled from the syntax where the syntax settles it and from the typer's receiver otherwise;
       # `[nil, …]` when neither does.
+      # `[owner, singleton, implicit, named]`. `named` says the owner came from a **constant path the
+      # author wrote**, which is what licenses the posture on a receiver the typer could not resolve
+      # ({#posture_allowed?}).
       def catalog_target(node, record)
         receiver = node.receiver
-        return ["Kernel", false, true] if receiver.nil? || receiver.is_a?(Prism::SelfNode)
+        return ["Kernel", false, true, false] if receiver.nil? || receiver.is_a?(Prism::SelfNode)
 
         constant = Source::ConstantPath.qualified_name(receiver)
-        return [constant, !Catalog.default.object_constant?(constant), false] if constant
+        return [constant, !Catalog.default.object_constant?(constant), false, true] if constant
         return NO_TARGET if record.nil? || record.receiver_class.nil?
 
-        [record.receiver_class, record.kind == :singleton, false]
+        [record.receiver_class, record.kind == :singleton, false, false]
       end
 
-      NO_TARGET = [nil, false, false].freeze
+      NO_TARGET = [nil, false, false, false].freeze
       private_constant :NO_TARGET
 
       def positional_arity(node)

data/lib/rigor/plugin/base.rb

@@ -734,6 +734,10 @@ module Rigor
         manifest.effect_entry_points
       end
 
+      def effect_ancestry
+        manifest.effect_ancestry
+      end
+
       # ADR-7 § "Slice 6-A/6-B" — per-plugin {IoBoundary}. Memoised so the boundary's accumulated `FileEntry`
       # rows persist across producer invocations within the same plugin instance and feed cache invalidation
       # via `cache_for`.

data/lib/rigor/plugin/box.rb

@@ -32,14 +32,30 @@ module Rigor
       # Requires `feature` into the shared box exactly once. Returns true when the feature is available in the
       # box, false when it could not be loaded (the caller then declines — never falls back to loading into the
       # main space, which would defeat the boundary).
+      #
+      # The rescue is `::`-qualified and covers `::ScriptError`, matching {Isolation::Process.run_worker_loop}:
+      # a failed box require raises `::LoadError` — a ScriptError, not a StandardError — and a plain
+      # `rescue StandardError` lets it escape and abort the whole run instead of the clean decline.
       def require_feature(feature)
         @required ||= {}
         return @required[feature] if @required.key?(feature)
 
         shared.require(feature)
         @required[feature] = true
-      rescue StandardError
-        @required[feature] = false
+      rescue ::StandardError, ::ScriptError
+        @required[feature] = eval_require(feature)
+      end
+
+      # The gem-resolving fallback: `Ruby::Box#require` resolves against the raw `$LOAD_PATH` only (it
+      # calls the C-level require directly), so a target library installed as a gem is reachable only
+      # through the box's own RubyGems — the `Kernel#require` *inside* the box. `feature` is a fixed,
+      # plugin-declared name rendered via `String#inspect` (a safe Ruby literal), so the eval carries no
+      # free input. Returns false when the box cannot load the feature either way (the caller declines).
+      def eval_require(feature)
+        shared.eval("require #{feature.inspect}") # require "active_support/inflector"
+        true
+      rescue ::StandardError, ::ScriptError
+        false
       end
 
       # Evaluates `code` inside the shared box and returns the result across the box boundary. The caller MUST

data/lib/rigor/plugin/effect_ancestry.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "effect_attribution"
+
+module Rigor
+  module Plugin
+    # One entry of a plugin's `effect_ancestry:` — an ancestry edge the plugin's own gem introduces and
+    # the project's source never writes down (ADR-103 WD17; [#465](https://github.com/rigortype/rigor/issues/465)).
+    #
+    # `Effects::PluginFacts` walks the project's own `class … <` and `include` lines and nothing else,
+    # deliberately: reading the RBS ancestor chain instead would make a row's reach a function of whether
+    # anyone happened to run `rbs prototype`. The cost is that a chain which leaves project source never
+    # comes back. `class UserMailer < Devise::Mailer` is the measured case — `Devise::Mailer <
+    # ActionMailer::Base` is a line in the devise gem, so `rigor-actionmailer`'s rows stop one step short
+    # of every mailer a Devise application writes, and the five `Auth::*Controller < Devise::*Controller`
+    # subclasses beside it are entry points.
+    #
+    # A plugin that models a gem knows that gem's own inheritance. Declaring it here keeps the rule that
+    # Rigor reads *declarations* rather than RBS: the declaration simply comes from the plugin instead of
+    # from project source.
+    #
+    # ## What a claim may say
+    #
+    # `parent:` need only be a **true ancestor**, not the immediate superclass. The sole use of the
+    # ancestry is to make a row reachable, and no plugin row is ever keyed on a project class, so
+    # skipping intermediate links loses nothing — while insisting on the immediate parent would force a
+    # claim that is sometimes false: `Devise::SessionsController`'s real parent is `DeviseController`,
+    # whose own parent is `Devise.parent_controller` and therefore configurable per project. A claim that
+    # skips links MUST say so in its `why:`.
+    #
+    # ## Who may make one
+    #
+    # Bundled plugins only ({Rigor::Plugin::FirstParty}), enforced in `PluginFacts`. An ancestry claim
+    # carries no labels of its own, so it looks harmless — but it makes *other* plugins' rows reachable,
+    # and a third-party plugin asserting `Foo < ActiveRecord::Base` would pull rigor-activerecord's
+    # first-party discharging rows onto `Foo`. The `effect_root:` demotion and the `discharge:` grant
+    # both answer their own version of that question the same way.
+    class EffectAncestry
+      attr_reader :child, :parent, :why
+
+      def initialize(child:, parent:, why:)
+        @child = validate_class_name!(child, "child")
+        @parent = validate_class_name!(parent, "parent")
+        @why = validate_why!(why)
+        freeze
+      end
+
+      def to_h
+        { "child" => @child, "parent" => @parent }
+      end
+
+      def ==(other)
+        other.is_a?(EffectAncestry) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate_class_name!(value, role)
+        name = value.to_s
+        unless EffectAttribution::CLASS_NAME.match?(name)
+          raise ArgumentError, "effect ancestry #{role} must be a class name, got #{value.inspect}"
+        end
+
+        name.dup.freeze
+      end
+
+      def validate_why!(why)
+        value = why.to_s
+        raise ArgumentError, "effect ancestry #{@child} < #{@parent} needs a `why:` justification" if value.empty?
+
+        value.dup.freeze
+      end
+    end
+  end
+end