rigortype 0.3.8 → 0.3.9

data/lib/rigor/scope.rb

@@ -21,7 +21,7 @@ module Rigor
     attr_reader :environment, :locals, :fact_store, :self_type,
                 :ivars, :cvars, :globals,
                 :indexed_narrowings, :method_chain_narrowings,
-                :declaration_sourced,
+                :declaration_sourced, :published_constant_sourced,
                 :source_path, :discovery, :struct_fold_safe_locals,
                 :opaque_block_self, :lexical_nesting,
                 :dynamic_origins, :local_origins, :ivar_origins,
@@ -49,12 +49,21 @@ module Rigor
     def discovered_method_visibilities = @discovery.discovered_method_visibilities
     def discovered_superclasses = @discovery.discovered_superclasses
     def discovered_includes = @discovery.discovered_includes
+    def discovered_extends = @discovery.discovered_extends
     def discovered_class_sources = @discovery.discovered_class_sources
     # Issue #644 — `{qualified constant name => Set[declaring file]}`; seeded only on an ADR-46 recording run.
     def constant_sources = @discovery.constant_sources
     def published_constant_names = @discovery.published_constant_names
     def local_constant_names = @discovery.local_constant_names
 
+    # Issue #667 — the instance-variable names of `class_name` whose class-ivar seed comes from a foreign
+    # published constant (`@mode = AppConfig::MODE` in `initialize`, read in a sibling method).
+    # `StatementEvaluator#seed_instance_ivars` stamps the flow mark for these at method-body entry, the way
+    # ADR-58's seed stamps its own; a method-local write or narrowing then drops it through `with_ivar`.
+    def published_constant_ivars_for(class_name)
+      @discovery.published_constant_ivars[class_name] || EMPTY_PUBLISHED_CONSTANT_IVARS
+    end
+
     # Issue #644 — true when the constant reference `name` (as written: `MODE` or `AppConfig::MODE`) is
     # published by the cross-file value-constant table and is NOT assigned by the file being analysed: a
     # value this file's author cannot see the declaration of. {Analysis::CheckRules::PublishedConstantGuard}
@@ -76,14 +85,27 @@ module Rigor
     # over already-qualified names rather than a second lexical ladder: the engine's ladder
     # (`Reflection.resolve_constant_type`) answers with a TYPE and not with the candidate that won, and
     # reimplementing the walk here is the very thing that made the receiver resolution wrong once already.
+    #
+    # Issue #667 — a third answer sits beside those two. `MODE2 = AppConfig::MODE` is assigned by this file,
+    # so the exemption above releases it, yet its value is still one the author never saw: the alias only
+    # renames the foreign declaration. `published_constant_alias_names` holds the last segments of exactly
+    # those aliases, and matching on the last segment over-answers in the WITHHOLDING direction, which is the
+    # safe one.
     def published_constant?(name)
       names = @discovery.published_constant_names
+      return true if published_constant_alias?(name)
       return false if names.empty?
       return false unless names.include?(name.split("::").last)
 
       !locally_declared_constant?(name)
     end
 
+    def published_constant_alias?(name)
+      aliases = @discovery.published_constant_alias_names
+      !aliases.empty? && aliases.include?(name.split("::").last)
+    end
+    private :published_constant_alias?
+
     def locally_declared_constant?(reference_name)
       local = @discovery.local_constant_names
       return false if local.empty?
@@ -153,9 +175,21 @@ module Rigor
     # threaded by reference through transitions; reset per method body (a fresh entry scope drops it), so the
     # name keys never collide across bodies.
     EMPTY_ORIGINS = {}.freeze
+    # Issue #667 — the set of variable references currently bound to a value COPIED out of a constant the
+    # project published and this file does not declare. Members are frozen `[kind, name]` pairs, the same
+    # spelling {EMPTY_DECLARATION_SOURCED} uses, but a DELIBERATELY SEPARATE carrier: this mark joins by
+    # UNION where ADR-58's kinds intersect, and it answers a different question (what a value's *constancy*
+    # rests on, not what a binding's *optionality* rests on) for a different consumer. Folding it into the
+    # ADR-58 set would be the third establishing transition its *Non-transitivity* passage reserves as a
+    # decision, on a Set that already carries two opposite join policies.
+    EMPTY_PUBLISHED_CONSTANT_SOURCED = Set.new.freeze
+    # Issue #667 — the empty answer of {#published_constant_ivars_for}, so a class with no such ivar (every
+    # class in a project that publishes nothing) allocates none.
+    EMPTY_PUBLISHED_CONSTANT_IVARS = Set.new.freeze
     private_constant :EMPTY_VAR_BINDINGS, :EMPTY_INDEXED_NARROWINGS,
                      :EMPTY_CHAIN_NARROWINGS, :EMPTY_DECLARATION_SOURCED,
-                     :EMPTY_FOLD_SAFE, :EMPTY_ORIGINS
+                     :EMPTY_FOLD_SAFE, :EMPTY_ORIGINS, :EMPTY_PUBLISHED_CONSTANT_SOURCED,
+                     :EMPTY_PUBLISHED_CONSTANT_IVARS
 
     class << self
       def empty(environment: Environment.default, source_path: nil)
@@ -207,6 +241,7 @@ module Rigor
       indexed_narrowings: EMPTY_INDEXED_NARROWINGS,
       method_chain_narrowings: EMPTY_CHAIN_NARROWINGS,
       declaration_sourced: EMPTY_DECLARATION_SOURCED,
+      published_constant_sourced: EMPTY_PUBLISHED_CONSTANT_SOURCED,
       source_path: nil,
       struct_fold_safe_locals: EMPTY_FOLD_SAFE,
       opaque_block_self: false,
@@ -231,6 +266,7 @@ module Rigor
       @indexed_narrowings = indexed_narrowings
       @method_chain_narrowings = method_chain_narrowings
       @declaration_sourced = declaration_sourced
+      @published_constant_sourced = published_constant_sourced
       @source_path = source_path
       @struct_fold_safe_locals = struct_fold_safe_locals
       @opaque_block_self = opaque_block_self
@@ -314,6 +350,10 @@ module Rigor
               indexed_narrowings: new_indexed_narrowings,
               method_chain_narrowings: new_chain_narrowings,
               declaration_sourced: drop_declaration_sourced_for(:local, name),
+              # Issue #667 — rebinding is flow-live for the published-constant mark too: the new value need
+              # not be a copy of anything. `with_published_constant_mark` re-stamps afterward when the write's
+              # rvalue is one.
+              published_constant_sourced: drop_published_constant_sourced_for(:local, name),
               local_origins: drop_origin(@local_origins, name),
               optimistic_locals: drop_origin(@optimistic_locals, name))
     end
@@ -419,6 +459,7 @@ module Rigor
               indexed_narrowings: new_indexed_narrowings,
               method_chain_narrowings: new_chain_narrowings,
               declaration_sourced: drop_declaration_sourced_for(:ivar, name),
+              published_constant_sourced: drop_published_constant_sourced_for(:ivar, name),
               ivar_origins: drop_origin(@ivar_origins, name),
               optimistic_ivars: drop_origin(@optimistic_ivars, name))
     end
@@ -445,6 +486,22 @@ module Rigor
       rebuild(declaration_sourced: add_declaration_sourced(:local, name))
     end
 
+    # Issue #667 — record that `name` is currently bound to a value copied out of a foreign published
+    # constant. Always applied AFTER the `with_local` / `with_ivar` that binds the value (both drop the mark
+    # unconditionally), exactly as {#with_local_declaration_mark} is.
+    def with_published_constant_mark(kind, name)
+      rebuild(published_constant_sourced: add_published_constant_sourced(kind, name))
+    end
+
+    # Issue #667 — true when `(kind, name)`'s current binding is a copy of a constant the project published
+    # and this file does not declare. Asked through
+    # {Analysis::CheckRules::PublishedConstantGuard}, never directly from a rule.
+    def published_constant_sourced?(kind, name)
+      return false if @published_constant_sourced.empty?
+
+      @published_constant_sourced.include?([kind.to_sym, name.to_sym])
+    end
+
     # ADR-58 WD1 — true when `(kind, name)`'s binding optionality is purely declaration-sourced (no flow-live
     # write/narrowing has touched it).
     def declaration_sourced?(kind, name)
@@ -744,6 +801,34 @@ module Rigor
       @discovery.discovered_includes[class_name.to_s] || []
     end
 
+    # Issue #898 — the module names `extend`ed onto `class_name`'s SINGLETON, as written, gathered up the
+    # as-written superclass chain because a singleton class inherits its superclass's singleton class
+    # (`class Base; extend Comparable; end; class Widget < Base; end` leaves `Widget.is_a?(Comparable)`
+    # true). Empty for a class the project never extends, and for every scope that saw no seeding pass.
+    #
+    # This is EVIDENCE FOR a singleton ancestor, never against one: the walk sees only what a constant
+    # argument to a receiverless `extend` (or, since #915, a receiverless `include` / `prepend` inside a
+    # `class << self` body) written inside a declaration body spells, so a runtime `Widget.extend(m)` and an
+    # `extend` in a file outside the analysed set are both absent from it, as is an `extend` declared only
+    # in RBS — that one reaches the same consumer through `Environment#singleton_extended_modules` instead.
+    # Its one consumer ({Inference::Narrowing.narrow_class}) therefore reads it
+    # only to WITHHOLD a `Bot`, and never to assert that a guard matches.
+    def singleton_extends_of(class_name)
+      table = @discovery.discovered_extends
+      return [] if table.empty?
+
+      names = []
+      current = class_name.to_s
+      seen = {}
+      while current && !seen[current] && seen.size <= ANCESTOR_WALK_LIMIT
+        seen[current] = true
+        record_class_dependency(current) if Analysis::DependencyRecorder.active?
+        names.concat(table[current] || [])
+        current = @discovery.discovered_superclasses[current]
+      end
+      names.uniq
+    end
+
     # ADR-24 slice 2 — the user-side ancestor walk: resolves `method_name` against `class_name`'s own `def`s,
     # then breadth-first through its included / prepended modules (mixins first, as Ruby orders them) and its
     # superclass chain. Returns `[def_node, owner]`, or `[nil, nil]` when nothing in the project defines it.
@@ -810,9 +895,56 @@ module Rigor
       [nil, nil]
     end
 
+    # Issue #633 — the ancestors a project class reaches that the project itself does NOT declare: the
+    # `< StandardError` / `< Array` superclasses and the `include Comparable` mixins the two walks above
+    # deliberately drop, gathered breadth-first over the project ancestry so an inherited edge counts too.
+    #
+    # Each entry is the CANDIDATE LIST for one as-written name ({#ancestor_name_candidates}: the nesting
+    # spellings first, the bare name last), not a resolved class — resolving it means asking the RBS
+    # environment, which this frozen-index walk does not read. The caller takes the first candidate its own
+    # oracle knows and ignores the rest, the same "most-qualified first" order the project-side resolution
+    # uses.
+    def external_ancestor_name_candidates(class_name, name_memo: {})
+      groups = []
+      queue = [class_name.to_s]
+      seen = {}
+      visited = 0
+      until queue.empty?
+        current = queue.shift
+        next if current.nil? || seen[current]
+
+        seen[current] = true
+        visited += 1
+        break if visited > ANCESTOR_WALK_LIMIT
+
+        collect_external_ancestors(current, queue, groups, name_memo)
+      end
+      groups
+    end
+
+    # One node of {#external_ancestor_name_candidates}: the project-declared ancestors continue the walk,
+    # everything else is reported as a candidate list.
+    def collect_external_ancestors(current, queue, groups, name_memo)
+      raw_names = includes_of(current).dup
+      raw_super = superclass_of(current)
+      raw_names << raw_super if raw_super
+      raw_names.each do |raw|
+        resolved = resolve_ancestor_class_name(current, raw, name_memo)
+        if resolved
+          queue.push(resolved)
+        else
+          groups << ancestor_name_candidates(current, raw)
+        end
+      end
+    end
+    private :collect_external_ancestors
+
     # The BFS node cap; a hierarchy past it gives up rather than walking unboundedly (ADR-41 WD4).
     ANCESTOR_WALK_LIMIT = 100
 
+    EMPTY_HEADER_NESTING = [].freeze
+    private_constant :EMPTY_HEADER_NESTING
+
     def ancestor_walk_gave_up
       Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
       [nil, nil]
@@ -929,10 +1061,25 @@ module Rigor
       return [raw.delete_prefix("::")] if raw.start_with?("::")
 
       recorded = @discovery.discovered_header_nestings[subclass_qualified.to_s]
-      entries = recorded || peeled_header_nesting(subclass_qualified)
+      entries = recorded ? recorded_header_nesting(recorded, raw) : peeled_header_nesting(subclass_qualified)
       entries.map { |entry| "#{entry}::#{raw_ancestor}" } << raw_ancestor.to_s
     end
 
+    # Issue #728 — the chain of the declaration site that WROTE `raw`, which is the cref Ruby resolves that
+    # one name in. A class's sites need not agree: `class Foo < Base` at the top level and a rooted
+    # `class ::Foo; include Helper; end` inside `module Outer` are two sites of `Foo`, and the union of
+    # their chains put `Outer::Base` — a class Ruby never looks at — ahead of `::Base` for the superclass
+    # the top-level site wrote. That is a WRONG CLASS, not a wider candidate list.
+    #
+    # The unkeyed entry is the union, and answers a name no site recorded under its own key: an `include`
+    # attributed to this class from OUTSIDE its declaration (`Recv.class_eval { include M }`, which
+    # `Inference::ScopeIndexer#walk_class_includes` names but the header walk cannot see), or a dynamic
+    # mixin argument. It is the pre-#728 answer, so those are unchanged rather than degraded.
+    def recorded_header_nesting(bucket, raw)
+      bucket[raw] || bucket[DiscoveryIndex::UNKEYED_HEADER_NESTING] || EMPTY_HEADER_NESTING
+    end
+    private :recorded_header_nesting
+
     # The pre-#682 reading of a qualified class name: every proper prefix of it, innermost first, as if the
     # class had been declared one `module` keyword per segment.
     def peeled_header_nesting(subclass_qualified)
@@ -974,6 +1121,21 @@ module Rigor
     end
     private :record_class_dependency
 
+    # Issue #639 — the EXISTENCE edge for a bare class reference, `class:<last segment>`, the hit-side twin of
+    # the miss-side key `Inference::ExpressionTyper` already records. ADR-46 slice 1c left the existence hit
+    # edgeless on the reasoning that a file merely referencing `Post` depends on `Post`'s methods, not on its
+    # bare existence; that stops holding the moment the DECLARING FILE IS DELETED, because existence is then
+    # exactly what changed and a reference-only consumer had recorded nothing to be re-checked by.
+    #
+    # NAME-keyed rather than a positive edge to the declaring file, which is the distinction the ADR's cost
+    # argument turns on: the declared-class set of a file does not move when a method body in it is edited,
+    # so a bare referent is re-checked when the class appears or disappears and at no other time. A file edge
+    # would have re-checked every bare referent of every class the file declares on any edit to it.
+    def record_class_existence(class_name)
+      segment = class_name.to_s.delete_prefix("::").split("::").last
+      Analysis::DependencyRecorder.read_name(:class, segment) if segment
+    end
+
     # Issue #644 — the positive ADR-46 edge for a cross-file VALUE constant. `Reflection.constant_type_at`
     # calls this the moment a candidate resolves through `in_source_constants`, so the reader depends on the
     # file that wrote the constant: editing the literal, or deleting the file, re-checks the reader. Recorded
@@ -1125,7 +1287,8 @@ module Rigor
         @globals == other.globals &&
         @indexed_narrowings == other.indexed_narrowings &&
         @method_chain_narrowings == other.method_chain_narrowings &&
-        @declaration_sourced == other.declaration_sourced
+        @declaration_sourced == other.declaration_sourced &&
+        @published_constant_sourced == other.published_constant_sourced
     end
     alias eql? ==
 
@@ -1142,6 +1305,7 @@ module Rigor
       indexed_narrowings: @indexed_narrowings,
       method_chain_narrowings: @method_chain_narrowings,
       declaration_sourced: @declaration_sourced,
+      published_constant_sourced: @published_constant_sourced,
       source_path: @source_path,
       struct_fold_safe_locals: @struct_fold_safe_locals,
       opaque_block_self: @opaque_block_self,
@@ -1163,6 +1327,7 @@ module Rigor
         indexed_narrowings: indexed_narrowings,
         method_chain_narrowings: method_chain_narrowings,
         declaration_sourced: declaration_sourced,
+        published_constant_sourced: published_constant_sourced,
         source_path: source_path,
         struct_fold_safe_locals: struct_fold_safe_locals,
         opaque_block_self: opaque_block_self,
@@ -1208,6 +1373,12 @@ module Rigor
         # path made the binding flow-live (a method-local nil write / failed-guard narrowing), the merge is
         # flow-live and `possible-nil-receiver` fires as before.
         declaration_sourced: join_declaration_sourced(other),
+        # Issue #667 — UNION, the opposite of the line above, which is the first reason this mark does not
+        # ride the ADR-58 Set. The mark only ever WITHHOLDS a firing, so keeping it when either arm bound the
+        # name from a published constant is the false-positive-safe merge: `if c then m = MODE else m = MODE2
+        # end; m == :x` must not warn because one arm's copy is invisible to the reader's author. ADR-67
+        # WD6b's `:inferred_param` taint takes the same direction for the same reason.
+        published_constant_sourced: join_published_constant_sourced(other),
         source_path: source_path,
         # Issue #589 — the fold-safe set MUST survive a merge. It was simply absent from this constructor
         # call, so it fell back to the empty default and every `if` / `while` in a method silently revoked
@@ -1339,6 +1510,34 @@ module Rigor
     end
 
     # ADR-58 WD1 — set/clear the declaration-sourced provenance mark.
+    # Issue #667 — the #667 carrier's add/drop pair. Deliberately not reusing
+    # {#add_declaration_sourced} / {#drop_declaration_sourced_for}: the two sets are joined by opposite
+    # policies, so sharing the storage would make every future edit to either one a decision about both.
+    def add_published_constant_sourced(kind, name)
+      ref = [kind.to_sym, name.to_sym].freeze
+      return @published_constant_sourced if @published_constant_sourced.include?(ref)
+
+      (@published_constant_sourced.dup << ref).freeze
+    end
+
+    def drop_published_constant_sourced_for(kind, name)
+      return @published_constant_sourced if @published_constant_sourced.empty?
+
+      ref = [kind.to_sym, name.to_sym]
+      return @published_constant_sourced unless @published_constant_sourced.include?(ref)
+
+      (@published_constant_sourced - [ref]).freeze
+    end
+
+    def join_published_constant_sourced(other)
+      mine = @published_constant_sourced
+      theirs = other.published_constant_sourced
+      return mine if mine.equal?(theirs) || theirs.empty?
+      return theirs if mine.empty?
+
+      (mine | theirs).freeze
+    end
+
     def add_declaration_sourced(kind, name)
       ref = [kind.to_sym, name.to_sym]
       return @declaration_sourced if @declaration_sourced.include?(ref)

data/lib/rigor/sig_gen/generator.rb

@@ -4,9 +4,11 @@ require "prism"
 
 require_relative "../configuration"
 require_relative "../environment"
+require_relative "../project_environment"
 require_relative "../scope"
 require_relative "../reflection"
 require_relative "../type"
+require_relative "../source/constant_path"
 require_relative "../source/literals"
 require_relative "../source/node_children"
 require_relative "../inference/def_return_typer"
@@ -39,17 +41,23 @@ module Rigor
     # - Tighter-return detection compares the RBS-erased spellings only when the existing declared return
     #   strictly accepts the inferred one (acceptance check under the engine's current `:gradual` mode; ADR-14
     #   reserves the eventual `:strict` mode).
+    # - A declared `void` return is never compared as a value type. It is the author's statement that the
+    #   return is not part of the contract, which no inference can synthesize, so the method classifies
+    #   `equivalent` carrying `void` itself as the declared spelling (#836; see {#declares_void?}).
+    # - A proposal that erases to an RBS literal never tightens an existing declaration: the declared type is
+    #   the author's abstraction over the body and the literal is what it hides (#837; see
+    #   {#pins_literal_over_declaration?}). A method with no declaration is unaffected — clause 1 still emits
+    #   the strictest carrier the body proves.
     class Generator # rubocop:disable Metrics/ClassLength
       # Methods the generator rendered into RBS that `rbs` itself rejects. Populated by {#build_candidate}; each
       # one is a Rigor rendering DEFECT, not a property of the user's code, so the CLI reports them as such.
       UnrenderableMethod = Data.define(:path, :class_name, :method_name, :rbs, :error)
 
-      # @return [Array<UnrenderableMethod>] empty on a healthy run; read after {#run}.
+      # @return empty on a healthy run; read after {#run}.
       attr_reader :unrenderable, :unresolvable_superclasses
 
-      # @param configuration [Rigor::Configuration]
-      # @param paths [Array<String>] files / directories to scan.
-      # @param observations [Hash{[String, Symbol] => Array<Array<Rigor::Type>>}]
+      # @param paths — files / directories to scan.
+      # @param observations — => Array<Array<Rigor::Type>>}]
       #   ADR-14 slice 3 — per-target-method arg-tuple observations
       #   produced by {ObservationCollector}. An empty Hash (the default)
       #   means "no observations available; emit `untyped` for every
@@ -84,10 +92,9 @@ module Rigor
         map.transform_values { |entries| entries.map { |entry| ObservedCall.from(entry) } }
       end
 
-      # @return [Array<MethodCandidate>]
       def run
-        @environment = build_environment
         resolved = resolve_paths(@paths)
+        @environment = build_environment(resolved)
         candidates = resolved.flat_map { |path| analyse_file(path, @environment) }
         demote_overridden_base_methods(
           demote_unresolvable_superclasses(resolve_superclass_spellings(candidates))
@@ -311,11 +318,13 @@ module Rigor
         )
       end
 
-      def build_environment
-        Environment.for_project(
-          libraries: @configuration.libraries,
-          signature_paths: @configuration.signature_paths
-        )
+      # Issue #821 — the SAME type universe `rigor check` analyses against: the project's `sig/`, the plugins,
+      # the bundle's per-gem signatures and the `rbs collection`. Built with two keywords only, the generator
+      # could not see a gem-declared superclass, and the skip guard above (`record_unresolvable_superclass`)
+      # then declined to emit every class descending from one — every Rails model, on a project whose
+      # collection was installed and whose `check` read it.
+      def build_environment(source_files = [])
+        ProjectEnvironment.build(configuration: @configuration, source_files: source_files)
       end
 
       def resolve_paths(args)
@@ -413,14 +422,22 @@ module Rigor
         end
       end
 
+      # [#722](https://github.com/rigortype/rigor/issues/722) residue 3 — the qualified name is built by
+      # `Source::ConstantPath.declaration_prefix`, the same reader the engine's declaration walks use, so a
+      # ROOTED header re-anchors here too. Appending the rendered name to the enclosing prefix wrote
+      # `class ::Foo` inside `module MyApp` out as `MyApp::Foo` — sig-gen's own copy of #708, and the one
+      # copy that persists its answer into a file the user keeps.
+      #
+      # `prefix` stays the nesting the header is WRITTEN in for {#record_superclass}: `::` re-anchors the
+      # declaration, not the superclass expression beside it, which Ruby still evaluates in the enclosing cref.
       def descend_into_namespace?(node, prefix, out)
-        name = qualified_constant_path(node.constant_path)
-        return false unless name
+        child_prefix = Source::ConstantPath.declaration_prefix(prefix, node.constant_path)
+        return false unless child_prefix
 
-        full = (prefix + [name]).join("::")
+        full = child_prefix.join("::")
         @namespace_kinds[full] = node.is_a?(Prism::ClassNode) ? :class : :module
         record_superclass(node, full, prefix)
-        walk_namespace_body(node, prefix + [name], out)
+        walk_namespace_body(node, child_prefix, out)
         true
       end
 
@@ -836,7 +853,14 @@ module Rigor
         )
       end
 
+      # The RBS spelling carried for a `void`-declared method, so `--diff` shows the author's own word rather
+      # than the `top` the translator would erase it to.
+      VOID_RETURN_RBS = "void"
+      private_constant :VOID_RETURN_RBS
+
       def compare_against_declared(path, def_node, class_name, kind, inferred, method_def)
+        return equivalent(path, def_node, class_name, kind, inferred, VOID_RETURN_RBS) if declares_void?(method_def)
+
         declared = build_declared_return(method_def)
         declared_rbs = declared&.erase_to_rbs
         inferred_rbs = inferred.erase_to_rbs
@@ -845,7 +869,7 @@ module Rigor
           return equivalent(path, def_node, class_name, kind, inferred, declared_rbs)
         end
 
-        unless tighter?(declared, inferred) && !computed_literal_tightening?(inferred, def_node)
+        unless tighter?(declared, inferred) && !literal_decline?(inferred, def_node)
           return equivalent(path, def_node, class_name, kind, inferred, declared_rbs)
         end
 
@@ -861,6 +885,28 @@ module Rigor
         )
       end
 
+      # Issue #836 — a declared `void` is return INTENT, never a wide value type waiting to be narrowed, so it
+      # is not compared against the body at all.
+      #
+      # `void` says the return value is not part of the method's contract. No synthesis can produce it: a type
+      # built from a body is always the type of the body's last expression, so `void` exists only on the
+      # CHECKING side, against a declaration the author wrote. That puts it in the same position ADR-107 gives
+      # a parameter type — authored intent inference cannot derive — and proposing the body's value for it is
+      # a category error rather than a false positive to tune.
+      #
+      # Mechanically the misreading came from the translator: `docs/type-specification/special-types.md`
+      # § `void` records that the engine maps RBS `void` to `top`, `Type::Top` accepts everything, so
+      # {#tighter?} answered "yes" for every `void`-declared method whose body happens to return a typed
+      # value. Seven of the fifteen tighter-returns in Rigor's own `sig/` were this shape, and the ADR-107 G3
+      # provenance gate inherited the misclassification with them.
+      #
+      # ANY overload declaring `void` is enough. One proposal is rendered for the whole method, so an overload
+      # set that mixes `void` with a value return still has an author saying "not part of the contract" about
+      # the return sig-gen would rewrite.
+      def declares_void?(method_def)
+        method_def.method_types.any? { |mt| mt.type.return_type.is_a?(RBS::Types::Bases::Void) }
+      end
+
       def build_declared_return(method_def)
         translated = method_def.method_types.filter_map { |mt| translate_method_type_return(mt) }
         return nil if translated.empty?
@@ -943,6 +989,48 @@ module Rigor
         inferred.is_a?(Type::Tuple) || inferred.is_a?(Type::HashShape)
       end
 
+      # The two reasons a `Type::Constant` the body proves is not the method's contract. Both say the same
+      # thing from opposite ends: the precision is real about this body and says nothing about the promise
+      # the method makes to its callers.
+      def literal_decline?(inferred, def_node)
+        computed_literal_tightening?(inferred, def_node) || pins_literal_over_declaration?(inferred)
+      end
+
+      # Issue #837 — a proposal that erases to an RBS LITERAL type never tightens an existing declaration.
+      #
+      # `Type::Top#describe` really does return `"top"`, but `describe` is the surface every `Rigor::Type::*`
+      # class implements and every one of them declares `String`. The declared nominal is the author's
+      # abstraction over the body, and the literal is the implementation detail that abstraction deliberately
+      # hides — the same reading #836 gave a declared `void`. ADR-107 § Decision puts both on the intent
+      # side: no synthesis produces an abstraction, because a type built from a body is always the type of
+      # the body's last expression, so the choice to be wider than the body only ever exists in a declaration
+      # someone wrote.
+      #
+      # The generator already answered this way whenever the declaration happened to be a UNION.
+      # `Configuration.discover` declares `String?` against a body proving `".rigor.dist.yml" |
+      # ".rigor.yml" | nil` and {#loses_declared_union_member?} refuses it, because no literal covers the
+      # declared `String`. Whether the author wrote `String` or `String?` is not a decision about literals,
+      # so the two shapes now answer alike.
+      #
+      # Scoped by the ERASURE, not by the carrier. `Type::Constant` also carries values RBS has no literal
+      # spelling for (`Float`, `Regexp`, `Set`, `Pathname`, `Date`, …) and those erase to the class name, so
+      # `def pi: () -> Numeric` against a body of `3.14` still proposes the ordinary nominal `Float`. A union
+      # is refused when ANY member is a literal: a mixed `("a" | Float)` pins `"a"` just as a bare one does.
+      # A literal nested inside a shape carrier (`[1, 2]`, a `HashShape` value) is a different question,
+      # already answered for the collection declarations that matter by {#narrows_collection_to_shape?}.
+      def pins_literal_over_declaration?(inferred)
+        members = inferred.is_a?(Type::Union) ? inferred.members : [inferred]
+        members.any? { |member| rbs_literal?(member) }
+      end
+
+      # `Type::Constant#erase_to_rbs` spells the values RBS writes as literal types (`true` / `false` /
+      # `nil`, an Integer, a Symbol, a String) as that literal and every other carrier as its value's class
+      # name. Asking which of the two branches it took keeps the list of literal-spellable classes from
+      # forking a second copy into this file.
+      def rbs_literal?(type)
+        type.is_a?(Type::Constant) && type.erase_to_rbs != type.value.class.name
+      end
+
       # Heuristic added after the third-round self-dogfood: `FallbackTracer#size` body is `@events.size`, where
       # `@events` is initialised to `[]` and never assigned again at the class-ivar pre-pass level. The
       # `Type::Tuple[]` (size 0) folds `.size` to `Constant<0>` — the carrier knows the empty-tuple cardinality
@@ -950,6 +1038,11 @@ module Rigor
       # signal is "the body's last expression is NOT a directly-authored literal but the inferred type IS a
       # Constant"; in that case the precision came from inference over an internal computation, not the
       # author's contract, so refuse to tighten.
+      #
+      # Since #837 the literal-ERASING half of this is refused whichever expression produced it. What stays
+      # this guard's own is the `Constant` that erases to a class name: `def average = @total / 2.0` folds to
+      # `Constant<2.5>` and would propose the perfectly ordinary `Float`, which is still the fold's answer
+      # about one body rather than the method's contract.
       def computed_literal_tightening?(inferred, def_node)
         return false unless inferred.is_a?(Type::Constant)
 
@@ -1082,9 +1175,9 @@ module Rigor
 
         case node
         when Prism::ClassNode, Prism::ModuleNode
-          name = qualified_constant_path(node.constant_path)
-          if name
-            walk_attr_calls(node.body, prefix + [name], false, ctx) if node.body
+          child_prefix = Source::ConstantPath.declaration_prefix(prefix, node.constant_path)
+          if child_prefix
+            walk_attr_calls(node.body, child_prefix, false, ctx) if node.body
             return
           end
         when Prism::SingletonClassNode
@@ -1166,9 +1259,9 @@ module Rigor
 
         case node
         when Prism::ClassNode, Prism::ModuleNode
-          name = qualified_constant_path(node.constant_path)
-          if name
-            collect_init_ivar_obs(node.body, prefix + [name], result) if node.body
+          child_prefix = Source::ConstantPath.declaration_prefix(prefix, node.constant_path)
+          if child_prefix
+            collect_init_ivar_obs(node.body, child_prefix, result) if node.body
             return
           end
         when Prism::DefNode

data/lib/rigor/sig_gen/layout_index.rb

@@ -21,20 +21,19 @@ module Rigor
     # in multiple files for additive member contributions, but the writer only needs one canonical target per
     # class.
     class LayoutIndex
-      # @param signature_paths [Array<String, Pathname>, nil]
+      # @param signature_paths —
       #   the `.rigor.yml`-configured signature directories.
       #   When `nil` or empty, falls back to `<project_root>/sig`
       #   if it exists (matching `Environment.for_project`'s
       #   auto-detection convention).
-      # @param project_root [String, Pathname]
       def initialize(signature_paths:, project_root: Dir.pwd)
         @signature_paths = resolve_paths(signature_paths, project_root)
         @index = nil
       end
 
-      # @param class_name [String] fully-qualified Ruby class
+      # @param class_name — fully-qualified Ruby class
       #   name (e.g. `"Rigor::Type::Top"`).
-      # @return [Pathname, nil] absolute path of the sig file
+      # @return absolute path of the sig file
       #   that already declares this class, or `nil` when no
       #   existing declaration is found.
       def file_for(class_name)

data/lib/rigor/sig_gen/meta_class_shape.rb

@@ -29,11 +29,9 @@ module Rigor
 
       module_function
 
-      # @param kind [:data, :struct]
-      # @param members [Array<Symbol>] ordered member names from the ADR-48 layout.
-      # @param member_types [Hash{Symbol => String}] erased RBS spellings; a member with no entry renders `untyped`.
-      # @param keyword_init [Boolean] the `Struct.new(..., keyword_init: true)` flag; ignored for `:data`.
-      # @return [Shape]
+      # @param members — ordered member names from the ADR-48 layout.
+      # @param member_types — erased RBS spellings; a member with no entry renders `untyped`.
+      # @param keyword_init — the `Struct.new(..., keyword_init: true)` flag; ignored for `:data`.
       def of(kind:, members:, member_types: {}, keyword_init: false)
         types = members.to_h { |member| [member, member_types[member] || "untyped"] }
         accessors = kind == :struct ? struct_accessors(members, types) : readers(members, types)