rigortype 0.3.6 → 0.3.8

data/lib/rigor/source/constant_path.rb

@@ -14,8 +14,18 @@ module Rigor
     # * {.qualified_name_or_nil} is STRICT — a dynamic base anywhere in the chain yields `nil`, so a caller
     #   that statically names constants can treat the path as opaque rather than guessing.
     #
-    # A leading `::` (absolute root, `::Foo`) renders as `"Foo"` under both policies. A node that is neither
-    # a `ConstantReadNode` nor a `ConstantPathNode` yields `nil` under both.
+    # A leading `::` (absolute root, `::Foo`) renders as `"Foo"` under both policies: the discovered-constant
+    # tables are keyed by un-rooted names, so a rendered `"::Foo"` would miss every one of them. The root
+    # marker is therefore carried OUT OF BAND by {.rooted?}, which a caller performing Ruby's lexical constant
+    # lookup MUST consult — `::Foo` names the top-level `Foo` and never a lexically nearer shadow
+    # ([#614](https://github.com/rigortype/rigor/issues/614)). A node that is neither a `ConstantReadNode`
+    # nor a `ConstantPathNode` yields `nil` under both policies.
+    #
+    # A `class` / `module` HEADER is a constant path too, and it has to consult the same marker — which is why
+    # {.declaration_prefix} and {.pushed_nesting} live here rather than in each of the two dozen walks that
+    # used to append the rendered name to their own prefix. `::` re-anchors a header at the top level exactly
+    # as it re-anchors a reference; reading only the rendered name filed `class ::Foo` inside `module MyApp`
+    # under `MyApp::Foo` ([#708](https://github.com/rigortype/rigor/issues/708)).
     module ConstantPath
       module_function
 
@@ -53,6 +63,73 @@ module Rigor
           "#{parent_name}::#{node.name}"
         end
       end
+
+      # True when the reference is written with a leading `::` — `::Foo`, `::Foo::Bar`. Prism spells the
+      # root as a `ConstantPathNode` with a nil `parent`, so the answer lives at the LEFTMOST segment of the
+      # chain and the walk has to reach it: `::Foo::Bar` is a path node whose parent is itself a path node.
+      # A `ConstantReadNode` is a bare name and is never rooted; a dynamic base (`expr::Bar`) is not a root
+      # either, so the recursion stops at any non-constant parent.
+      def rooted?(node)
+        return false unless node.is_a?(Prism::ConstantPathNode)
+
+        parent = node.parent
+        return true if parent.nil?
+
+        rooted?(parent)
+      end
+
+      # The qualified prefix a `class` / `module` header contributes to the body it opens, given the prefix of
+      # the body the header is WRITTEN in. `class Bar` inside `module Outer` is `Outer::Bar`; the compact
+      # `class Outer::Bar` written at the top level is the same name through one keyword instead of two.
+      #
+      # A ROOTED header RESETS the prefix. `class ::Rooted::Bar` names `Rooted::Bar` wherever it is written —
+      # Ruby's `::` re-anchors the header at the top level exactly as it does a reference — so the enclosing
+      # prefix is DROPPED rather than kept. Keeping it filed the class under `Outer::Rooted::Bar`, a name no
+      # caller writes, and the single-segment `class ::Foo` inside `module MyApp` became `MyApp::Foo`: not
+      # merely mis-keyed but undiscoverable, so a call on `Foo` typed opaque and reported nothing at all
+      # ([#708](https://github.com/rigortype/rigor/issues/708), [#638](https://github.com/rigortype/rigor/issues/638)).
+      #
+      # nil when the header names no constant — the same refusal {.qualified_name} makes, propagated so a
+      # caller keeps its own prefix rather than qualifying under a name it could not render.
+      def declaration_prefix(outer_prefix, constant_path)
+        name = qualified_name(constant_path)
+        return nil if name.nil?
+
+        rooted?(constant_path) ? [name] : outer_prefix + [name]
+      end
+
+      # Ruby's `Module.nesting` inside the body a `class` / `module` header opens, given the nesting of the
+      # body the header is written in. ONE entry per declaration keyword, qualified against the entry already
+      # on top, so a compact `class A::B` contributes the single `"A::B"` where `module A; class B` contributes
+      # two — the whole difference between the two spellings, and unrecoverable from the `"A::B"` they share
+      # afterwards ([#652](https://github.com/rigortype/rigor/issues/652)). This is the ONLY thing that pushes
+      # an entry: a `def`, a block, and a `class << expr` body each inherit the chain unchanged, because none
+      # of them pushes a cref in Ruby.
+      #
+      # A ROOTED header pushes its name UNQUALIFIED and leaves the enclosing entries beneath it, which is the
+      # one place this differs from {.declaration_prefix}: Ruby's nesting inside `class ::Rooted::Bar` written
+      # in `module Outer` is `[Rooted::Bar, Outer]`, so the class's own name resets while `Outer` stays on the
+      # ladder as a live rung ([#708](https://github.com/rigortype/rigor/issues/708)).
+      #
+      # The header is rendered by the LENIENT {.qualified_name}, which is total over every header Ruby parses —
+      # `class` and `module` require a constant path, so the only dynamic base the grammar admits is `self`, and
+      # `class self::Thing` inside `module Outer` renders `"Thing"` and records `["Outer::Thing", "Outer"]`,
+      # which is what Ruby's nesting is there. So there is no unnameable-header case to refuse, and the `nil`
+      # guards below are reachable only for a non-constant node (which a `ClassNode` / `ModuleNode` header
+      # never is) and for the nil chain a caller may thread in.
+      #
+      # Both nesting walks call THIS function — `Inference::StatementEvaluator`'s declaration walk and
+      # `Inference::ScopeIndexer`'s def-node walk — so a callee re-walk answers what the body's own walk
+      # answers by construction rather than by two mirrored implementations staying in step.
+      def pushed_nesting(nesting, constant_path)
+        return nil if nesting.nil?
+
+        name = qualified_name(constant_path)
+        return nil if name.nil?
+
+        outer = rooted?(constant_path) ? nil : nesting.first
+        [outer ? "#{outer}::#{name}" : name, *nesting].freeze
+      end
     end
   end
 end

data/lib/rigor/triage/catalogue.rb

@@ -327,7 +327,7 @@ module Rigor
           parser == :toplevel ? d.method_name : parse_undefined_method(d)&.fetch(:method)
         end
         names.tally.sort_by { |method, count| [-count, method] }
-                   .first(limit).map { |method, count| "#{method}×#{count}" }.join(" ")
+             .first(limit).map { |method, count| "#{method}×#{count}" }.join(" ")
       end
 
       def rule_of(diag)

data/lib/rigor/type/combinator.rb

@@ -369,6 +369,16 @@ module Rigor
         StructInstance.new(members, class_name)
       end
 
+      # ADR-3 amendment (ADR-20 slice 4) — generic Result[T, E] carrier constructor.
+      def result_of(ok_type, err_type)
+        Result.new(ok_type, err_type)
+      end
+
+      # ADR-3 amendment (ADR-20 slice 4) — generic Maybe[T] carrier constructor.
+      def maybe_of(value_type)
+        Maybe.new(value_type)
+      end
+
       # Normalized union. Flattens nested Unions, deduplicates structurally equal members, drops Bot, and
       # collapses 0/1-member results.
       def union(*types)

data/lib/rigor/type/maybe.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+require_relative "../value_semantics"
+require_relative "acceptance_router"
+require_relative "plain_lattice"
+
+module Rigor
+  module Type
+    # A generic Maybe carrier representing an optional value that either contains a value of type
+    # `value_type` or nothing.
+    #
+    # Models `Maybe[T]` (e.g. `Dry::Monads::Maybe[T]`).
+    #
+    # Subtyping is covariant: `Maybe[T1] <: Maybe[T2]` iff `T1 <: T2`.
+    class Maybe
+      attr_reader :value_type
+
+      def initialize(value_type)
+        raise ArgumentError, "value_type must not be nil" if value_type.nil?
+
+        @value_type = value_type
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        "Maybe[#{value_type.describe(verbosity)}]"
+      end
+
+      def erase_to_rbs
+        "::Dry::Monads::Maybe[#{value_type.erase_to_rbs}]"
+      end
+
+      include Rigor::Type::PlainLattice
+
+      include Rigor::Type::AcceptanceRouter
+
+      include Rigor::ValueSemantics
+
+      value_fields :value_type
+
+      def inspect
+        "#<Rigor::Type::Maybe #{describe(:short)}>"
+      end
+    end
+  end
+end

data/lib/rigor/type/refined.rb

@@ -77,14 +77,13 @@ module Rigor
       # Recognises a Ruby value against this carrier's predicate. The trinary return is intentional:
       # `true` / `false` when the predicate registry decides, `nil` when the predicate is unknown to the
       # registry, so callers (today {Inference::Acceptance}) can fall through to gradual-mode `:maybe`.
-      # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+      # rubocop:disable-next Style/ReturnNilInPredicateMethodDefinition
       def matches?(value)
         recogniser = PREDICATES[predicate_id]
         return nil if recogniser.nil?
 
         !!recogniser.call(value)
       end
-      # rubocop:enable Style/ReturnNilInPredicateMethodDefinition
 
       # `predicate_id => recogniser` table. The recogniser is called with a Ruby value (typically the
       # inner `value` of a `Constant`) and returns truthy when the value satisfies the predicate. The

data/lib/rigor/type/result.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+require_relative "../value_semantics"
+require_relative "acceptance_router"
+require_relative "plain_lattice"
+
+module Rigor
+  module Type
+    # A generic Result carrier representing a computation that either succeeded with a value of type
+    # `ok_type` or failed with an error of type `err_type`.
+    #
+    # Models `Result[T, E]` (e.g. `Dry::Monads::Result[T, E]`).
+    #
+    # Subtyping is covariant in both positions: `Result[T1, E1] <: Result[T2, E2]` iff `T1 <: T2` and
+    # `E1 <: E2`.
+    class Result
+      attr_reader :ok_type, :err_type
+
+      alias success_type ok_type
+      alias failure_type err_type
+
+      def initialize(ok_type, err_type)
+        raise ArgumentError, "ok_type must not be nil" if ok_type.nil?
+        raise ArgumentError, "err_type must not be nil" if err_type.nil?
+
+        @ok_type = ok_type
+        @err_type = err_type
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        "Result[#{ok_type.describe(verbosity)}, #{err_type.describe(verbosity)}]"
+      end
+
+      def erase_to_rbs
+        "::Dry::Monads::Result[#{ok_type.erase_to_rbs}, #{err_type.erase_to_rbs}]"
+      end
+
+      include Rigor::Type::PlainLattice
+
+      include Rigor::Type::AcceptanceRouter
+
+      include Rigor::ValueSemantics
+
+      value_fields :ok_type, :err_type
+
+      def inspect
+        "#<Rigor::Type::Result #{describe(:short)}>"
+      end
+    end
+  end
+end

data/lib/rigor/type.rb

@@ -28,6 +28,8 @@ require_relative "type/difference"
 require_relative "type/refined"
 require_relative "type/intersection"
 require_relative "type/app"
+require_relative "type/result"
+require_relative "type/maybe"
 require_relative "type/bound_method"
 require_relative "type/accepts_result"
 require_relative "type/combinator"

data/lib/rigor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rigor
-  VERSION = "0.3.6"
+  VERSION = "0.3.8"
 end

data/plugins/rigor-actioncable/lib/rigor/plugin/actioncable/analyzer.rb

@@ -56,7 +56,9 @@ module Rigor
           # not ActionCable — pass through silently to avoid flagging unrelated `broadcast_to` methods.
           return [] unless class_name.end_with?("Channel")
 
-          entry = channel_index.find(class_name) || channel_index.find("::#{class_name}")
+          # `ChannelIndex#find` de-roots the query itself (#621) — a `::ChatChannel.broadcast_to` receiver
+          # and a plain `ChatChannel.broadcast_to` reach the same entry with no retry arm here.
+          entry = channel_index.find(class_name)
           return [unknown_channel_violation(class_name, channel_index)] if entry.nil?
 
           [broadcast_target_info(entry)]

data/plugins/rigor-actioncable/lib/rigor/plugin/actioncable/channel_discoverer.rb

@@ -36,7 +36,11 @@ module Rigor
         def initialize(io_boundary:, search_paths:, base_classes:)
           @io_boundary = io_boundary
           @search_paths = search_paths
-          @base_classes = base_classes.to_set
+          # De-rooted for the same reason superclass names are ({#visit_class}): the match is by exact
+          # spelling, so a channel written `< ::ApplicationCable::Channel` — or a configured
+          # `channel_base_classes: ["::ApplicationCable::Channel"]` — would otherwise never match, and the
+          # channel would go undiscovered and its `broadcast_to` call sites report `unknown-channel`.
+          @base_classes = base_classes.to_set { |name| strip_root(name.to_s) }
         end
 
         # @return [ChannelIndex]
@@ -51,11 +55,39 @@ module Rigor
               entries << build_entry(class_name, path, body)
             end
           end
-          ChannelIndex.new(entries)
+          ChannelIndex.new(merge_redeclarations(entries))
         end
 
         private
 
+        # Collapses the entries that declare the SAME constant into one, so {ChannelIndex} — which keys its
+        # by-name view by `class_name` — receives at most one row per channel.
+        #
+        # A channel is routinely declared more than once: the real class in `app/channels/chat_channel.rb`
+        # and a second file reopening it (`class ::ChatChannel`, `class ChatChannel`) to add an action.
+        # Ruby's own semantics are ADDITIVE, so the rows are UNIONed: action methods and literal stream
+        # names union, and `dynamic_streams` ORs — any dynamic registration anywhere in the class means no
+        # literal name can be proven missing, which is the false-positive-safe reading. Taking the last row
+        # instead dropped the earlier declaration's actions and streams whenever it sorted later in the glob.
+        # `file_path` stays the earlier declaration's; nothing reads it by name.
+        def merge_redeclarations(entries)
+          return entries if entries.length < 2
+
+          entries.each_with_object({}) do |entry, acc|
+            name = entry.class_name
+            acc[name] = acc.key?(name) ? merged_entry(acc[name], entry) : entry
+          end.values
+        end
+
+        # `base` is the earlier declaration, `addition` the later one. See {#merge_redeclarations}.
+        def merged_entry(base, addition)
+          base.with(
+            action_methods: (base.action_methods | addition.action_methods).freeze,
+            stream_names: (base.stream_names | addition.stream_names).freeze,
+            dynamic_streams: base.dynamic_streams || addition.dynamic_streams
+          )
+        end
+
         def read_safely(path)
           @io_boundary.read_file(path)
         rescue Plugin::AccessDeniedError, Errno::ENOENT
@@ -65,7 +97,8 @@ module Rigor
         def ruby_files_under(roots)
           roots.flat_map do |root|
             absolute = File.expand_path(root)
-            next [] unless File.directory?(absolute)
+            # ADR-45 WD1b (#613) — boundary-probed: a root that appears later invalidates the warm run.
+            next [] unless @io_boundary.directory?(absolute)
 
             Dir.glob(File.join(absolute, "**", "*.rb"))
           end
@@ -86,22 +119,37 @@ module Rigor
           class_local_name = constant_path_name(node.constant_path)
           return if class_local_name.nil?
 
-          full_name = (lexical_path + [class_local_name]).join("::")
-          superclass = constant_path_name(node.superclass) if node.superclass
+          full_name = declared_constant_name(class_local_name, lexical_path)
+          superclass = strip_root(constant_path_name(node.superclass)) if node.superclass
           yield full_name, node.body if superclass && @base_classes.include?(superclass)
 
-          inner_path = lexical_path + [class_local_name]
-          walk_for_channels(node.body, inner_path, &) if node.body
+          walk_for_channels(node.body, [full_name], &) if node.body
         end
 
         def visit_module(node, lexical_path, &)
           module_local_name = constant_path_name(node.constant_path)
           return if module_local_name.nil?
 
-          inner_path = lexical_path + [module_local_name]
+          inner_path = [declared_constant_name(module_local_name, lexical_path)]
           walk_for_channels(node.body, inner_path, &) if node.body
         end
 
+        # The full constant name a `class` / `module` declaration defines, given the rendered local name
+        # and the enclosing lexical path. A ROOTED local name (`class ::ChatChannel`) names the top-level
+        # constant whatever the nesting, so the lexical path is dropped and the `::` with it; otherwise the
+        # name is appended to the path (`class ChatChannel` inside `module Admin` → `Admin::ChatChannel`).
+        def declared_constant_name(local_name, lexical_path)
+          return strip_root(local_name) if local_name.start_with?("::")
+
+          (lexical_path + [local_name]).join("::")
+        end
+
+        # `::ChatChannel` → `ChatChannel`; a name without the root marker is returned unchanged (nil stays
+        # nil).
+        def strip_root(name)
+          name&.delete_prefix("::")
+        end
+
         def build_entry(class_name, path, body)
           actions = []
           (body&.compact_child_nodes || []).each do |node|
@@ -154,6 +202,8 @@ module Rigor
           true
         end
 
+        # Renders a constant-path node as a String, KEEPING the leading `::` of a rooted path —
+        # {#declared_constant_name} reads it as "reset the lexical path" before the marker is dropped.
         def constant_path_name(node)
           return nil if node.nil?
 

data/plugins/rigor-actioncable/lib/rigor/plugin/actioncable/channel_index.rb

@@ -26,19 +26,27 @@ module Rigor
 
         attr_reader :entries
 
+        # `entries` is expected UNIQUE by `class_name`: the by-name Hash is keyed by it, so a second row for
+        # a channel would replace the first outright. {ChannelDiscoverer#merge_redeclarations} is the single
+        # home of that guarantee — a reopened class arrives as one merged row, never as two.
         def initialize(entries)
           @entries = entries.freeze
           @by_name = entries.to_h { |entry| [entry.class_name, entry] }.freeze
           freeze
         end
 
+        # Entries are keyed by the de-rooted constant path (`"ChatChannel"`, `"Admin::ChatChannel"` — never
+        # `"::ChatChannel"`; see {ChannelDiscoverer}), while a QUERY may legitimately arrive rooted:
+        # `::ChatChannel.broadcast_to(...)` renders its receiver as `"::ChatChannel"`. The root marker is
+        # dropped here, once, so no caller needs a `find(name) || find("::#{name}")` retry (#621).
+        #
         # @return [Entry, nil]
         def find(class_name)
-          @by_name[class_name.to_s]
+          @by_name[strip_leading_namespace(class_name.to_s)]
         end
 
         def known?(class_name)
-          @by_name.key?(class_name.to_s)
+          @by_name.key?(strip_leading_namespace(class_name.to_s))
         end
 
         def empty?
@@ -64,6 +72,11 @@ module Rigor
         def any_dynamic_streams?
           @entries.any?(&:dynamic_streams)
         end
+
+        private
+
+        # `::ChatChannel` → `ChatChannel`. The query-side half of the key contract — see {#find}.
+        def strip_leading_namespace(name) = name.delete_prefix("::")
       end
     end
   end

data/plugins/rigor-actioncable/lib/rigor/plugin/actioncable.rb

@@ -65,7 +65,10 @@ module Rigor
     class Actioncable < Rigor::Plugin::Base
       manifest(
         id: "actioncable",
-        version: "0.1.0",
+        # Bumped 2026-09-02 (#621) — channel keys and base-class names are de-rooted at the producer and a
+        # reopened class's actions and streams are UNIONed rather than clobbered, so a cached 0.1.0 index
+        # can be missing a whole channel (`< ::ApplicationCable::Channel`) or half its stream names.
+        version: "0.2.0",
         description: "Validates ActionCable broadcast call shape against discovered channels.",
         config_schema: {
           "channel_search_paths" => { kind: :array, default: ["app/channels"] },

data/plugins/rigor-actionmailer/lib/rigor/plugin/actionmailer/analyzer.rb

@@ -53,7 +53,9 @@ module Rigor
           return [] if class_name.nil?
           return [] if RESERVED_CLASS_METHODS.include?(call_node.name)
 
-          class_entry = mailer_index.find(class_name) || mailer_index.find("::#{class_name}")
+          # `MailerIndex#find` de-roots the query itself (#621) — a `::UserMailer.welcome` receiver and a
+          # plain `UserMailer.welcome` reach the same entry with no retry arm here.
+          class_entry = mailer_index.find(class_name)
           return [] if class_entry.nil?
 
           action_entry = class_entry.find_action(call_node.name)

data/plugins/rigor-actionmailer/lib/rigor/plugin/actionmailer/mailer_discoverer.rb

@@ -46,7 +46,10 @@ module Rigor
         def initialize(io_boundary:, search_paths:, base_classes:, views_root: DEFAULT_VIEWS_ROOT)
           @io_boundary = io_boundary
           @search_paths = search_paths
-          @base_classes = base_classes.to_set
+          # De-rooted for the same reason superclass names are ({#visit_class}): the match is by exact
+          # spelling, so a configured `mailer_base_classes: ["::ApplicationMailer"]` would otherwise never
+          # match anything a declaration can render.
+          @base_classes = base_classes.to_set { |name| strip_root(name.to_s) }
           @views_root = views_root
         end
 
@@ -86,7 +89,8 @@ module Rigor
         def ruby_files_under(roots)
           roots.flat_map do |root|
             absolute = File.expand_path(root)
-            next [] unless File.directory?(absolute)
+            # ADR-45 WD1b (#613) — boundary-probed: a root that appears later invalidates the warm run.
+            next [] unless @io_boundary.directory?(absolute)
 
             Dir.glob(File.join(absolute, "**", "*.rb"))
           end
@@ -107,16 +111,15 @@ module Rigor
           class_local_name = constant_path_name(node.constant_path)
           return if class_local_name.nil?
 
-          full_name = (lexical_path + [class_local_name]).join("::")
-          superclass = constant_path_name(node.superclass) if node.superclass
+          full_name = declared_constant_name(class_local_name, lexical_path)
+          superclass = strip_root(constant_path_name(node.superclass)) if node.superclass
           if superclass && @base_classes.include?(superclass)
             def_nodes = collect_action_defs(node.body)
             includes = collect_includes(node.body)
             yield full_name, def_nodes, includes
           end
 
-          inner_path = lexical_path + [class_local_name]
-          walk_for_mailers(node.body, inner_path, &) if node.body
+          walk_for_mailers(node.body, [full_name], &) if node.body
         end
 
         # Collects qualified-constant names passed to `include X` calls inside the class body. Used to
@@ -130,8 +133,8 @@ module Rigor
             next unless node.is_a?(Prism::CallNode) && node.receiver.nil? && node.name == :include
 
             (node.arguments&.arguments || []).each do |arg|
-              name = constant_path_name(arg)
-              names << name.delete_prefix("::") if name
+              name = strip_root(constant_path_name(arg))
+              names << name if name
             end
           end
           names
@@ -148,16 +151,19 @@ module Rigor
             local_name = constant_path_name(node.constant_path)
             return if local_name.nil?
 
-            full_name = (lexical_path + [local_name.delete_prefix("::")]).join("::")
+            full_name = declared_constant_name(local_name, lexical_path)
             if node.body
               def_nodes = collect_action_defs(node.body)
               entries = def_nodes.to_h { |def_node| [def_node.name, build_action_entry(def_node)] }
-              accumulator[full_name] = entries unless entries.empty?
-              collect_module_actions(node.body, lexical_path + [local_name.delete_prefix("::")], accumulator)
+              # UNIONed, never assigned: a concern module reopened in a second file adds actions rather
+              # than replacing the ones the first declaration spelled (same rule as {MailerIndex}'s
+              # per-class merge).
+              accumulator[full_name] = (accumulator[full_name] || {}).merge(entries) unless entries.empty?
+              collect_module_actions(node.body, [full_name], accumulator)
             end
           when Prism::ClassNode
             local_name = constant_path_name(node.constant_path)
-            inner = local_name ? lexical_path + [local_name.delete_prefix("::")] : lexical_path
+            inner = local_name ? [declared_constant_name(local_name, lexical_path)] : lexical_path
             collect_module_actions(node.body, inner, accumulator) if node.body
           else
             node.rigor_each_child { |child| collect_module_actions(child, lexical_path, accumulator) }
@@ -168,10 +174,27 @@ module Rigor
           module_local_name = constant_path_name(node.constant_path)
           return if module_local_name.nil?
 
-          inner_path = lexical_path + [module_local_name]
+          inner_path = [declared_constant_name(module_local_name, lexical_path)]
           walk_for_mailers(node.body, inner_path, &) if node.body
         end
 
+        # The full constant name a `class` / `module` declaration defines, given the rendered local name
+        # and the enclosing lexical path. A ROOTED local name (`class ::UserMailer`) names the top-level
+        # constant whatever the nesting, so the lexical path is dropped and the `::` with it; otherwise the
+        # name is appended to the path (`class UserMailer` inside `module Admin` → `Admin::UserMailer`).
+        def declared_constant_name(local_name, lexical_path)
+          return strip_root(local_name) if local_name.start_with?("::")
+
+          (lexical_path + [local_name]).join("::")
+        end
+
+        # `::UserMailer` → `UserMailer`; a name without the root marker is returned unchanged (nil stays nil).
+        def strip_root(name)
+          name&.delete_prefix("::")
+        end
+
+        # Renders a constant-path node as a String, KEEPING the leading `::` of a rooted path —
+        # {#declared_constant_name} reads it as "reset the lexical path" before the marker is dropped.
         def constant_path_name(node)
           return nil if node.nil?
 
@@ -334,7 +357,9 @@ module Rigor
           # ADR-39: the real ActiveSupport::Inflector resolves the mailer's view directory
           # (`Foo::BarMailer` → `foo/bar_mailer`), so a divergence from Rails' real underscore can't
           # point the missing-view check at the wrong directory.
-          underscore_path = Rigor::Plugin::Inflector.underscore(class_name.delete_prefix("::"))
+          # `class_name` is already de-rooted ({#declared_constant_name}), so no root marker can reach the
+          # inflection.
+          underscore_path = Rigor::Plugin::Inflector.underscore(class_name)
           mailer_dir = File.join(views_root_absolute, underscore_path)
 
           VIEW_FORMATS.any? do |format|

data/plugins/rigor-actionmailer/lib/rigor/plugin/actionmailer/mailer_index.rb

@@ -40,19 +40,32 @@ module Rigor
 
         attr_reader :entries
 
+        # `entries` holds one row PER DECLARATION — a mailer declared in two files contributes two — because
+        # {#find_by_file} anchors the `missing-view` diagnostics on the file each action's `def` lives in.
+        # The by-name view a call site consults is the UNION of a class's declarations ({.merge_entry}): a
+        # reopen ADDS actions rather than replacing the class, so keeping the last row alone reported
+        # `unknown-action` on every action the other declaration spelled (#621).
         def initialize(entries)
           @entries = entries.freeze
-          @by_name = entries.to_h { |entry| [entry.class_name, entry] }.freeze
+          @by_name = entries.each_with_object({}) do |entry, acc|
+            name = entry.class_name
+            acc[name] = acc.key?(name) ? self.class.merge_entry(acc[name], entry) : entry
+          end.freeze
           freeze
         end
 
+        # Entries are keyed by the de-rooted constant path (`"UserMailer"`, `"Admin::UserMailer"` — never
+        # `"::UserMailer"`; see {MailerDiscoverer}), while a QUERY may legitimately arrive rooted:
+        # `::UserMailer.welcome(u)` renders its receiver as `"::UserMailer"`. The root marker is dropped
+        # here, once, so no caller needs a `find(name) || find("::#{name}")` retry (#621).
+        #
         # @return [ClassEntry, nil]
         def find(class_name)
-          @by_name[class_name.to_s]
+          @by_name[strip_leading_namespace(class_name.to_s)]
         end
 
         def known?(class_name)
-          @by_name.key?(class_name.to_s)
+          @by_name.key?(strip_leading_namespace(class_name.to_s))
         end
 
         # @param file_path [String] absolute path of a mailer file (canonicalised — see plugin entry's
@@ -73,6 +86,26 @@ module Rigor
         def names
           @by_name.keys
         end
+
+        # Unions two declarations of the SAME mailer class. `base` is the earlier row, `addition` the later
+        # one; Ruby's own semantics are additive, so nothing either declaration spelled is lost. Actions are
+        # name-keyed (a redefinition in the later file wins, as it does at load time), `missing_views` and
+        # `unresolved_includes` union, and `file_path` stays the earlier declaration's — the merged row is
+        # only ever reached by name, never by {#find_by_file}, which reads the per-declaration `entries`.
+        def self.merge_entry(base, addition)
+          base.with(
+            actions: base.actions.merge(addition.actions),
+            missing_views: (base.missing_views | addition.missing_views).freeze,
+            unresolved_includes: (base.unresolved_includes | addition.unresolved_includes).freeze
+          )
+        end
+
+        # `::UserMailer` → `UserMailer`. The query-side half of the key contract — see {#find}.
+        def self.strip_leading_namespace(name) = name.delete_prefix("::")
+
+        private
+
+        def strip_leading_namespace(name) = self.class.strip_leading_namespace(name)
       end
     end
   end

data/plugins/rigor-actionmailer/lib/rigor/plugin/actionmailer.rb

@@ -47,7 +47,11 @@ module Rigor
         # `send` / `__send__` / `method` and friends so dynamic-dispatch idioms
         # (`Mailer.respond_to?(action)` / `Mailer.public_send(action)`) stop firing `unknown-action`
         # against the Ruby reflection method.
-        version: "0.4.0",
+        #
+        # Bumped 2026-09-02 (#621) — mailer keys are de-rooted at the producer and a reopened class's
+        # actions are UNIONed rather than clobbered, so a cached 0.4.0 index can be missing actions this
+        # version knows about.
+        version: "0.5.0",
         description: "Validates ActionMailer call shape and view template existence.",
         config_schema: {
           "mailer_search_paths" => { kind: :array, default: ["app/mailers"] },
@@ -120,7 +124,7 @@ module Rigor
             severity: :warning,
             rule: "missing-view",
             message: "`#{class_entry.class_name}##{action_name}` has no view template " \
-                     "under `#{@views_root}/#{Rigor::Plugin::Inflector.underscore(class_entry.class_name.delete_prefix('::'))}/`"
+                     "under `#{@views_root}/#{Rigor::Plugin::Inflector.underscore(class_entry.class_name)}/`"
           )
         end
       end