rigortype 0.3.6 → 0.3.8

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

@@ -6,12 +6,14 @@ require_relative "railties/effects"
 
 module Rigor
   module Plugin
-    # rigor-railties — the Rails **framework core** as an effect vocabulary.
+    # rigor-railties — the Rails **framework core**: its effect vocabulary, and the type of the four
+    # `Rails.` singleton readers.
     #
-    # Unlike its siblings this plugin runs no analysis: it emits no diagnostic, types no receiver and
-    # declares no producer. What it contributes is the part of ADR-103's Rails layer that belongs to no
-    # single component gem — `Rails.cache`, `Rails.logger`, `Rails.env`, the application configuration and
-    # the credentials — plus the `rails` entry-point preset that `effects.snapshot.reach:` adopts by name.
+    # It emits no diagnostic and declares no producer. What it contributes is the part of ADR-103's Rails
+    # layer that belongs to no single component gem — `Rails.cache`, `Rails.logger`, `Rails.env`, the
+    # application configuration and the credentials — plus the `rails` entry-point preset that
+    # `effects.snapshot.reach:` adopts by name, plus the lenient nominals those same readers return
+    # ({RAILS_SINGLETON_READER_TYPES}).
     #
     # ## Why it is its own plugin
     #
@@ -38,15 +40,23 @@ module Rigor
     #
     # ## Cost when effects are off
     #
-    # None beyond the load. The manifest's effect fields are frozen arrays; nothing reads them unless the
-    # project has an `effects:` block ({Rigor::Plugin::Registry#effect_contributions} is lazy), and the
-    # plugin implements no per-call contribution path at all, so `ContributionIndex` never consults it.
+    # The manifest's effect fields are frozen arrays; nothing reads them unless the project has an
+    # `effects:` block ({Rigor::Plugin::Registry#effect_contributions} is lazy). The reader typing costs one
+    # `ContributionIndex` name-gate probe per dispatch of a method actually named `logger` / `cache` /
+    # `configuration` / `application` (ADR-52 WD1 compiles the `methods:` gate into the registry), and the
+    # block declines on the first check for anything whose receiver is not the `Rails` constant. The reader
+    # gate ({#project_defined_reader?}) runs only after that syntactic gate passes, so it is confined to
+    # `Rails.`-shaped sites. It runs identically for both spellings — bare `Rails` and root-qualified
+    # `::Rails` both resolve through `Scope#type_of` ({#resolved_rails_constant_name}), which the engine's
+    # own rooted constant resolution (#614) answers correctly on its own.
     class Railties < Rigor::Plugin::Base
       manifest(
         id: "railties",
-        version: "0.1.0",
-        description: "The Rails framework-core effect vocabulary: cache, logger, environment, " \
-                     "configuration, credentials, and the `rails` entry-point preset.",
+        # Bumped 2026-09-01 (#534 item 2) — the four `Rails.` singleton readers now return lenient
+        # nominals instead of `Dynamic[top]`.
+        version: "0.2.0",
+        description: "The Rails framework-core effect vocabulary and singleton-reader types: cache, " \
+                     "logger, environment, configuration, credentials, and the `rails` entry-point preset.",
         # ADR-103 WD2 — rigor-railties models Rails itself, so it opens the `rails.*` root. Granted only
         # because the engine bundles this plugin ({Rigor::Plugin::FirstParty}); the same declaration from a
         # third-party gem would open `railties.*` and earn a warning.
@@ -55,6 +65,141 @@ module Rigor
         effect_attributions: Effects.attributions,
         effect_entry_points: Effects.entry_points
       )
+
+      # Issue #534 item 2 — the four `Rails.` singleton readers, measured on the 2026-09-01 corpus sweep as
+      # 261 opaque sites on mastodon alone (`configuration` 108, `cache` 81, `logger` 50, `application` 22).
+      # Every one of them typed `Dynamic[top]`, so the whole `Rails.cache.fetch(...)` /
+      # `Rails.application.config...` surface was unprotected.
+      #
+      # Each value is a **lenient nominal**: a real Rails class name for which Rigor ships NO RBS. That is
+      # the same construction rigor-actionpack's `REQUEST_CONTEXT_READER_TYPES` uses, and it is chosen for
+      # the same reason — the site becomes a *concrete* receiver (`coverage --protection` counts it, the
+      # dispatch resolves against a named class) while the method surface stays engine-lenient, because
+      # `call.undefined-method` and the argument / arity rules all bail at
+      # `Rigor::Reflection.rbs_class_known?`. Shipping a partial RBS for any of these would invert that:
+      # a declared class drops every member its RBS omits, and `Rails.logger.tagged { }` becomes a false
+      # positive.
+      #
+      # ## Why these names, and why not `::Logger`
+      #
+      # - `logger` → **`ActiveSupport::BroadcastLogger`**, not `::Logger`. `::Logger` is the name the issue
+      #   suggested and it is the one name here that must NOT be used: it is a stdlib class, so Rigor knows
+      #   its RBS, so the leniency argument above evaporates and every ActiveSupport extension of the logger
+      #   — `tagged`, `silence`, `broadcast_to`, `local_level=` — becomes `call.undefined-method` on working
+      #   Rails code. Measured, not assumed (spec: "does not fire undefined-method on the ActiveSupport
+      #   logger surface"). `BroadcastLogger` is what `Rails.logger` actually returns on Rails 7.1+, which
+      #   is every Rails still supported; on 7.0 and earlier it was an `ActiveSupport::Logger`, and since
+      #   both names are RBS-less the difference is invisible to every rule — the accurate modern name is
+      #   preferred only so a project that later authors its own `sig/` for it gets the right class.
+      # - `cache` → `ActiveSupport::Cache::Store`, the declared return of `Rails.cache` and the base class
+      #   of every store implementation.
+      # - `application` → `Rails::Application`, the singleton the railtie builds.
+      # - `configuration` → `Rails::Application::Configuration`. This is the entry whose *leniency* matters
+      #   most rather than its accuracy: `config.x_service_url` works through `method_missing` into
+      #   `@custom`, so no RBS could ever be complete for it, and the RBS-less nominal is the only answer
+      #   that types the receiver without claiming to know the members.
+      #
+      # ## The nil question
+      #
+      # All four are non-nil nominals, and a non-nil type licenses the flow rules to fold `if Rails.logger`
+      # to always-truthy (the hazard that kept `Parameters#[]` out of rigor-actionpack's table, #578). The
+      # difference is that here the non-nil claim is TRUE: inside a booted application — the only state in
+      # which `app/` code runs — the railtie initializers have assigned all four, and `Rails.logger` is nil
+      # only in a bare `require "rails"` process. The paired specs pin both halves: no `undefined-method` on
+      # the extension surface, and no fold on a `Rails.cache.fetch { }` guard shape.
+      RAILS_SINGLETON_READER_TYPES = {
+        logger: "ActiveSupport::BroadcastLogger",
+        cache: "ActiveSupport::Cache::Store",
+        configuration: "Rails::Application::Configuration",
+        application: "Rails::Application"
+      }.freeze
+
+      # `logger` / `cache` / `configuration` / `application` are ordinary method names that any project may
+      # define on its own objects, so the receiver gate is syntactic and exact: the literal `Rails` constant,
+      # bare or root-qualified (`::Rails`). A `receivers:` gate cannot express it — the `Rails` constant is
+      # unresolved in a project with no Rails RBS, so the receiver type is `Dynamic` and
+      # `dynamic_return_receiver_class_name` yields nil. The one thing the type side CAN see is the opposite
+      # case — the project defining this very reader on its own `Rails` — and that is the second gate
+      # ({#project_defined_reader?}).
+      dynamic_return methods: RAILS_SINGLETON_READER_TYPES.keys do |call_node, scope|
+        next nil unless call_node.is_a?(Prism::CallNode)
+        next nil unless call_node.arguments.nil? # `Rails.logger`, not `Rails.logger(x)`
+        next nil unless call_node.block.nil?
+        next nil unless rails_constant_receiver?(call_node.receiver)
+        next nil if project_defined_reader?(call_node, scope)
+
+        class_name = RAILS_SINGLETON_READER_TYPES[call_node.name]
+        next nil if class_name.nil?
+
+        Rigor::Type::Combinator.nominal_of(class_name)
+      end
+
+      # ADR-88 WD1 — the reader types are a static table and the effect rows are built from the manifest, so
+      # the plugin holds no state of its own that a fingerprint would have to observe, and a project that
+      # enables it stays incremental-capable. The one project-derived input is the {#project_defined_reader?}
+      # gate's `discovered_methods` read, and that does NOT need to ride this sentinel: it goes through
+      # `Rigor::Reflection.discovered_method?`, which records the ADR-46 negative dependency on a miss, so a
+      # warm `--incremental` re-check invalidates the gated sites the same way the engine's own cross-file
+      # method reads are invalidated — per consumer and per symbol, not by refusing the snapshot wholesale.
+      def incremental_state_fingerprint
+        "static-rails-readers"
+      end
+
+      private
+
+      # True for the `Rails` constant written as a receiver — `Rails.logger` (`ConstantReadNode`) and
+      # `::Rails.logger` (a root-qualified `ConstantPathNode`). A nested `Foo::Rails` or `::Foo::Rails` is
+      # deliberately NOT matched: it is a different constant, and matching it would type someone else's
+      # `logger`. `Source::ConstantPath.qualified_name_or_nil` already renders both accepted spellings down
+      # to the bare `"Rails"` string, and any multi-segment path down to its full dotted name, so the single
+      # equality check below is the whole gate (#626).
+      def rails_constant_receiver?(receiver)
+        Rigor::Source::ConstantPath.qualified_name_or_nil(receiver) == "Rails"
+      end
+
+      # #588 — the syntactic gate cannot tell the framework's `Rails` from a `Rails` the project declares
+      # itself, and when the project declares `def self.logger` on it, retyping the site to
+      # `BroadcastLogger` buries the project's own answer for its own constant. Listing this plugin beside
+      # such a definition is a self-contradictory configuration (activation is the `plugins:` list alone —
+      # no lockfile gate notices the framework is absent), but the project's definition is the honest type.
+      #
+      # The gate is deliberately the READER, not the constant. "The project has a `Rails` constant" is far
+      # too wide: a real Rails app reopens `module Rails` to hang an initializer or an engine extension off
+      # it (mastodon's `lib/rails/engine_extensions.rb`), and a compact `class Rails::HealthController`
+      # synthesizes the namespace on its own (#528) — in both shapes NOTHING answers `Rails.logger` but the
+      # framework, so declining there would only drop the site back to `Dynamic[top]` and give up #534's
+      # 261 mastodon sites for nothing. Declining only when the project defines the very method being
+      # called keeps the reopen typed and still yields the constant to whoever owns it.
+      #
+      # Diagnostics-silent either way when the project's definition exists (both nominals are RBS-less), so
+      # this half is precision-honesty rather than a false-positive fix; the reader-not-constant narrowing
+      # is what keeps it from being a precision regression.
+      def project_defined_reader?(call_node, scope)
+        owner = resolved_rails_constant_name(call_node.receiver, scope)
+        return false if owner.nil?
+
+        Rigor::Reflection.discovered_method?(owner, call_node.name, kind: :singleton, scope: scope)
+      end
+
+      # The constant name this receiver ACTUALLY resolves to, or nil when it resolves to nothing the
+      # project declares (the ordinary case: the framework's `Rails` is unresolved without a Rails RBS, so
+      # it types `Dynamic` and no name comes back).
+      #
+      # Both spellings go through `Scope#type_of` — Ruby's lexical walk, `Module.nesting` innermost-first,
+      # then project ancestors, then top level ({Rigor::Reflection.resolve_constant_type}) — which is the
+      # engine's single implementation and not a second one here. A root-qualified `::Rails` used to be
+      # answered directly, bypassing the engine: `Source::ConstantPath.qualified_name_or_nil` renders a
+      # parent-less `ConstantPathNode` as the bare `"Rails"`, and before #614 `Scope#type_of` had no way to
+      # tell that path was rooted, so it walked LEXICALLY and answered `MyApp::Rails` for a `::Rails` written
+      # inside `module MyApp`. #614 taught the engine to carry rootedness alongside the name
+      # (`Reflection.resolve_constant_type(name, scope:, rooted:)`), so `::Rails` now resolves to the
+      # top-level constant through the very same call, and this method no longer needs its own copy (#626).
+      def resolved_rails_constant_name(receiver, scope)
+        return nil if scope.nil?
+
+        receiver_type = scope.type_of(receiver)
+        receiver_type.class_name if receiver_type.is_a?(Rigor::Type::Singleton)
+      end
     end
 
     Rigor::Plugin.register(Railties)

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rigor"
+require "rigor-ffi"
+
+module Rigor
+  module Plugin
+    class RbNaCl < Base
+      manifest(
+        id: "rbnacl",
+        version: "0.1.0",
+        description: "Rigor type support for RbNaCl libsodium bindings"
+      )
+
+      # Issue 2 & 5: use robust positional binding extractor and preserve module context
+      ffi_binding_recognizer :sodium_function do |node, module_name|
+        next [] unless node.is_a?(Prism::CallNode) && node.name == :sodium_function
+
+        receiver = module_name && !module_name.empty? ? module_name : "RbNaCl"
+        fact = FFI::Analyzer.extract_function_binding(
+          node,
+          method_name: :sodium_function,
+          module_name: receiver,
+          default_return: :int
+        )
+        fact ? [fact] : []
+      end
+    end
+  end
+end

data/plugins/rigor-rbnacl/lib/rigor-rbnacl.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "rigor/plugin/rbnacl"

data/plugins/rigor-rbnacl/sig/rbnacl.rbs

@@ -0,0 +1,22 @@
+module RbNaCl
+  class SecretBox
+    def initialize: (String key) -> void
+    def encrypt: (String nonce, String message) -> String
+    def decrypt: (String nonce, String ciphertext) -> String
+  end
+
+  module Signatures
+    module Ed25519
+      class SigningKey
+        def initialize: (String seed) -> void
+        def sign: (String message) -> String
+        def verify_key: () -> VerifyKey
+      end
+
+      class VerifyKey
+        def initialize: (String key) -> void
+        def verify: (String signature, String message) -> bool
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rigor/plugin"
+require "rigor-ffi"
+
+module Rigor
+  module Plugin
+    class SassC < Base
+      manifest(
+        id: "sassc",
+        version: "0.1.0",
+        description: "Models SassC native bindings, nominal pointer typedefs, and struct unions.",
+        signature_paths: ["sig"]
+      )
+
+      # Recognizer for sass prefix-stripped attach_function calls
+      ffi_binding_recognizer :sassc_function do |node, module_name|
+        next [] unless node.is_a?(Prism::CallNode) && node.name == :attach_function
+
+        args = node.arguments&.arguments || []
+        next [] if args.empty?
+
+        ruby_name = FFI::Analyzer.extract_symbol(args[0])
+        next [] if ruby_name.nil?
+
+        mod = module_name && !module_name.empty? ? module_name : "SassC::Native"
+
+        # If ruby_name starts with sass_, also register stripped version
+        c_name = ruby_name
+        stripped_name = ruby_name.to_s.sub(/^sass_/, "").to_sym
+
+        fact = FFI::Analyzer.extract_attach_function(node, module_name: mod)
+        next [] if fact.nil?
+
+        if stripped_name == ruby_name
+          [fact]
+        else
+          [
+            fact,
+            FFI::AttachFunctionFact.new(
+              ruby_name: stripped_name,
+              c_name: c_name,
+              arg_types: fact.arg_types,
+              return_type: fact.return_type,
+              node: node,
+              receiver_name: mod
+            )
+          ]
+        end
+      end
+    end
+  end
+end
+
+Rigor::Plugin.register(Rigor::Plugin::SassC)

data/plugins/rigor-sassc/lib/rigor-sassc.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "rigor/plugin/sassc"

data/plugins/rigor-sassc/sig/sassc.rbs

@@ -0,0 +1,24 @@
+module SassC
+  class Engine
+    def initialize: (String template, ?Hash[Symbol, untyped] options) -> void
+    def render: () -> String
+  end
+
+  module Native
+    class SassDataContextPtr < FFI::Pointer
+    end
+
+    class SassOptionsPtr < FFI::Pointer
+    end
+
+    class SassContextPtr < FFI::Pointer
+    end
+
+    def self.make_data_context: (String src) -> SassDataContextPtr
+    def self.compile_data_context: (SassDataContextPtr dctx) -> Integer
+    def self.data_context_get_options: (SassDataContextPtr dctx) -> SassOptionsPtr
+    def self.data_context_get_context: (SassDataContextPtr dctx) -> SassContextPtr
+    def self.context_get_output_string: (SassContextPtr ctx) -> String
+    def self.delete_data_context: (SassDataContextPtr dctx) -> void
+  end
+end

data/plugins/rigor-shoulda-matchers/lib/rigor/plugin/shoulda_matchers/analyzer.rb

@@ -30,8 +30,8 @@ module Rigor
       #   have_db_column(:col)
       #   have_db_index(:col)
       #
-      # All look up `:col` against the model's columns (`Entry#column?`). Unknown columns fire
-      # `unknown-column`.
+      # All look up `:col` against the model's `columns:` (the published `:model_index` fact's flat
+      # `Array<String>` per model — see `Analyzer#column_names`). Unknown columns fire `unknown-column`.
       #
       # ### Association matchers
       #
@@ -74,7 +74,10 @@ module Rigor
 
         # @param path [String]
         # @param root [Prism::Node]
-        # @param model_index [Object, nil] the `:model_index` fact value. When nil the analyzer falls silent.
+        # @param model_index [Hash{String => Hash}, nil] the `:model_index` fact value — the flat
+        #   `class_name => { table:, columns:, associations:, ... }` Hash `rigor-activerecord` publishes
+        #   (ADR-9's "the value is data, not objects" contract; see `Activerecord#index_to_published_hash`).
+        #   When nil the analyzer falls silent.
         # @return [Array<Diagnostic>]
         # The matcher violations for a single call node (0..1), or `[]` when it is not a shoulda matcher,
         # sits outside any `describe <ModelConst>` block, or the model is unknown. ADR-37: the engine owns
@@ -84,7 +87,7 @@ module Rigor
         #
         # @param matcher_call [Prism::Node]
         # @param ancestors [Array<Prism::Node>]
-        # @param model_index [Object, nil]
+        # @param model_index [Hash{String => Hash}, nil]
         # @return [Array<Violation>]
         def violations_for(matcher_call:, ancestors:, model_index:)
           return [] if model_index.nil?
@@ -93,7 +96,10 @@ module Rigor
           anchor = anchor_for(ancestors)
           return [] if anchor.nil?
 
-          entry = model_index.find(anchor)
+          # Keyed Hash lookup — NOT `ModelIndex#find`. The published fact is a plain Hash (`class_name =>
+          # entry Hash`), never the `ModelIndex` object `rigor-activerecord` builds internally (issue #573:
+          # `Hash#find(anchor)` with no block returns an Enumerator, not the entry).
+          entry = model_index[anchor]
           return [] if entry.nil?
 
           violation = diagnostic_for(matcher_call, anchor, entry)
@@ -137,6 +143,9 @@ module Rigor
           render_constant_path(arg)
         end
 
+        # The anchor is the constant path WITHOUT a leading `::` — `describe ::User` anchors on `"User"`,
+        # the same spelling `describe User` produces — because the `:model_index` fact is keyed by the
+        # de-rooted class name however the model was declared (#583; `Activerecord#index_to_published_hash`).
         def render_constant_path(node)
           case node
           when Prism::ConstantReadNode then node.name.to_s
@@ -148,7 +157,7 @@ module Rigor
               current = current.parent
             end
             case current
-            when nil then "::#{parts.join('::')}"
+            when nil then parts.join("::")
             when Prism::ConstantReadNode then "#{current.name}::#{parts.join('::')}"
             end
           end
@@ -170,19 +179,30 @@ module Rigor
           end
         end
 
+        # `entry` is the published fact's per-model Hash: `{ table:, columns:, associations:, ... }`.
+        # `columns:` is a flat `Array<String>` (`Activerecord#index_to_published_hash`); `associations:` is
+        # `Array<Hash>` with String `:name`, Symbol `:kind` (`:singular` | `:collection`), `:nullable`,
+        # `:polymorphic`, and a `:target` that is a String except on polymorphic rows, where it is nil —
+        # the row shape `ModelDiscoverer#build_association_row` publishes. Only `:name` and `:kind` are
+        # read here.
+        def column_names(entry) = entry[:columns] || []
+        def association_rows(entry) = entry[:associations] || []
+        def find_association(entry, name) = association_rows(entry).find { |a| a[:name] == name.to_s }
+
         def column_violation(matcher_call, anchor, entry, column_name)
-          return nil if entry.column?(column_name)
+          return nil if column_names(entry).include?(column_name.to_s)
 
           Violation.new(
             rule: "unknown-column",
             message: "#{matcher_call.name}(:#{column_name}) — no column `#{column_name}` on " \
-                     "#{anchor} (columns: #{entry.column_names.sort.join(', ')})"
+                     "#{anchor} (columns: #{column_names(entry).sort.join(', ')})"
           )
         end
 
         def association_violation(matcher_call, anchor, entry, assoc_name, expected_kind:)
-          if entry.association?(assoc_name)
-            actual = entry.association(assoc_name)[:kind]
+          association = find_association(entry, assoc_name)
+          if association
+            actual = association[:kind]
             return nil if actual == expected_kind
 
             Violation.new(
@@ -191,10 +211,11 @@ module Rigor
                        "a #{actual} association; #{matcher_call.name} expects #{expected_kind}"
             )
           else
+            known = association_rows(entry).map { |a| a[:name] }
             Violation.new(
               rule: "unknown-association",
               message: "#{matcher_call.name}(:#{assoc_name}) — no association `#{assoc_name}` on " \
-                       "#{anchor} (associations: #{entry.association_names.sort.join(', ')})"
+                       "#{anchor} (associations: #{known.sort.join(', ')})"
             )
           end
         end

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

@@ -44,7 +44,9 @@ module Rigor
           class_name = constant_receiver_name(call_node.receiver)
           return [] if class_name.nil?
 
-          entry = worker_index.find(class_name) || worker_index.find("::#{class_name}")
+          # `WorkerIndex#find` de-roots the query itself (#621) — a `::WelcomeWorker.perform_async` receiver
+          # and a plain `WelcomeWorker.perform_async` reach the same entry with no retry arm here.
+          entry = worker_index.find(class_name)
           return [] if entry.nil?
 
           violations = [info_violation(call_node, entry)]

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq/schedule_scan.rb

@@ -68,7 +68,10 @@ module Rigor
 
         def load_document(path)
           absolute = File.expand_path(path.to_s)
-          return nil unless File.file?(absolute)
+          # ADR-45 WD1b (#613) — the probe goes through the boundary so "there is no `config/sidekiq.yml`"
+          # is a recorded dependency; `File.file?` here left the warm run serving the no-schedule answer
+          # after the file appeared.
+          return nil unless @io_boundary.file?(absolute)
 
           contents = read_safely(absolute)
           contents && parse_safely(contents)

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq/worker_discoverer.rb

@@ -27,26 +27,60 @@ module Rigor
         def initialize(io_boundary:, search_paths:, marker_modules:)
           @io_boundary = io_boundary
           @search_paths = search_paths
-          @marker_modules = marker_modules.to_set
+          # De-rooted so the marker match is by exact spelling on both sides: a worker written
+          # `include ::Sidekiq::Job` — and a configured `worker_marker_modules: ["::Sidekiq::Job"]` —
+          # would otherwise never match anything the other side can render.
+          @marker_modules = marker_modules.to_set { |name| strip_root(name.to_s) }
         end
 
         # @return [WorkerIndex]
         def discover
-          entries = []
+          candidates = []
           ruby_files_under(@search_paths).each do |path|
             contents = read_safely(path)
             next if contents.nil?
 
             tree = Prism.parse(contents).value
             walk_for_workers(tree, []) do |class_name, perform_def|
-              entries << build_entry(class_name, perform_def)
+              candidates << [class_name, perform_def]
             end
           end
-          WorkerIndex.new(entries)
+          WorkerIndex.new(merge_redeclarations(candidates))
         end
 
         private
 
+        # Collapses the candidates that declare the SAME constant into one entry, so {WorkerIndex} — which
+        # keys its rows by `class_name` — receives at most one per worker.
+        #
+        # A worker is routinely declared more than once: the real class in `app/workers/welcome_worker.rb`
+        # and a second file reopening it (`class ::WelcomeWorker`, `class WelcomeWorker`) to add a method.
+        # Taking the last candidate dropped the real `#perform` envelope whenever the reopen sorted later in
+        # the glob — the reopen carries no `#perform`, so the worker silently became any-arity and every
+        # `perform_async` went unchecked. The rows are merged instead:
+        #
+        # - The declarations that actually spell `def perform` decide the envelope; a reopen that does not
+        #   contributes nothing rather than erasing it.
+        # - When two declarations BOTH spell it with different shapes, the envelope WIDENS (min of the mins,
+        #   max of the maxes). The glob order is not the load order, so pinning either shape would surface
+        #   `wrong-arity` on a call the definition Ruby actually loads accepts — ADR-5: a missed narrow case
+        #   costs precision, a wrong one costs correct code.
+        def merge_redeclarations(candidates)
+          candidates.group_by(&:first).map do |class_name, rows|
+            declared = rows.filter_map { |(_, perform_def)| perform_def }
+            entries = declared.empty? ? [build_entry(class_name, nil)] : declared.map { |d| build_entry(class_name, d) }
+            entries.reduce { |base, addition| widen(base, addition) }
+          end
+        end
+
+        # The arity envelope that accepts every call either declaration accepts. See {#merge_redeclarations}.
+        def widen(base, addition)
+          base.with(
+            min_arity: [base.min_arity, addition.min_arity].min,
+            max_arity: [base.max_arity, addition.max_arity].max
+          )
+        end
+
         def read_safely(path)
           @io_boundary.read_file(path)
         rescue Plugin::AccessDeniedError, Errno::ENOENT
@@ -56,7 +90,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
@@ -77,24 +112,40 @@ 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("::")
+          full_name = declared_constant_name(class_local_name, lexical_path)
           if includes_marker_module?(node.body)
             perform_def = lookup_perform_def(node.body)
             yield full_name, perform_def
           end
 
-          inner_path = lexical_path + [class_local_name]
-          walk_for_workers(node.body, inner_path, &) if node.body
+          walk_for_workers(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_workers(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 ::WelcomeWorker`) 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 WelcomeWorker` inside `module Admin` →
+        # `Admin::WelcomeWorker`).
+        def declared_constant_name(local_name, lexical_path)
+          return strip_root(local_name) if local_name.start_with?("::")
+
+          (lexical_path + [local_name]).join("::")
+        end
+
+        # `::WelcomeWorker` → `WelcomeWorker`; a name without the root marker is returned unchanged (nil
+        # stays nil).
+        def strip_root(name)
+          name&.delete_prefix("::")
+        end
+
         # Returns true if the class body contains a top-level `include <Module>` call where `<Module>`
         # matches one of the configured marker modules.
         def includes_marker_module?(body)
@@ -106,11 +157,13 @@ module Rigor
             next false unless node.receiver.nil?
 
             arg = node.arguments&.arguments&.first
-            module_name = constant_path_name(arg)
+            module_name = strip_root(constant_path_name(arg))
             module_name && @marker_modules.include?(module_name)
           end
         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-sidekiq/lib/rigor/plugin/sidekiq/worker_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 worker would replace the first outright. {WorkerDiscoverer#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 (`"WelcomeWorker"`, `"Admin::WelcomeWorker"` —
+        # never `"::WelcomeWorker"`; see {WorkerDiscoverer}), while a QUERY may legitimately arrive rooted:
+        # `::WelcomeWorker.perform_async(1)` renders its receiver as `"::WelcomeWorker"`. 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?
@@ -52,6 +60,11 @@ module Rigor
         def names
           @by_name.keys
         end
+
+        private
+
+        # `::WelcomeWorker` → `WelcomeWorker`. The query-side half of the key contract — see {#find}.
+        def strip_leading_namespace(name) = name.delete_prefix("::")
       end
     end
   end