rigortype 0.2.5 → 0.2.6

data/lib/rigor/cli/plugins_command.rb

@@ -37,7 +37,7 @@ module Rigor
     #   `source_rbs_synthesizer:`);
     # - the ADR-37 narrow extension protocols read off the plugin
     #   class — `node_rule` node types, `dynamic_return` receivers,
-    #   `type_specifier` methods.
+    #   `narrowing_facts` methods.
     #
     # `--capabilities` switches to a focused catalogue of just the
     # narrow-protocol gate values + produced/consumed facts (ADR-37
@@ -194,7 +194,7 @@ module Rigor
 
       # ADR-37 narrow extension protocols. Unlike the 10 declarative
       # manifest fields, these are class-level DSLs (`node_rule` /
-      # `dynamic_return` / `type_specifier`), so they are read off the
+      # `dynamic_return` / `narrowing_facts`), so they are read off the
       # plugin class rather than the manifest. The gate values — node
       # types, receiver class names, specified method names — are the
       # greppable, enumerable surface the capability catalogue exposes.

data/lib/rigor/cli/plugins_renderer.rb

@@ -170,7 +170,7 @@ module Rigor
       end
 
       # ADR-37 narrow extension protocols (node_rule / dynamic_return /
-      # type_specifier). Surfaced in the full report alongside the
+      # narrowing_facts). Surfaced in the full report alongside the
       # declarative surfaces; `--capabilities` is the focused view.
       def narrow_protocol_lines(row)
         lines = []

data/lib/rigor/cli/protection_renderer.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require_relative "../inference/dynamic_origin"
+
 module Rigor
   class CLI
     # Renders an {ProtectionReport} (ADR-63 Tier 1) as text or JSON. The text
@@ -12,6 +14,15 @@ module Rigor
       TOP_CALLS = 15
       TOP_FILES = 10
 
+      # ADR-73 P6 / ADR-75 WD2 — the actionable axis for each tractability
+      # category, shown next to a hole's origin so a user knows whether (and
+      # how) a type can close it.
+      TRACTABILITY_HINTS = {
+        Inference::DynamicOrigin::ADD_RBS => "add RBS",
+        Inference::DynamicOrigin::ENABLE_PLUGIN => "enable a plugin / pre_eval",
+        Inference::DynamicOrigin::ENGINE_GAP => "engine gap — report it"
+      }.freeze
+
       def initialize(out:)
         @out = out
       end
@@ -40,13 +51,32 @@ module Rigor
         return if calls.empty?
 
         @out.puts "\nAdd a type here — methods most often called on an untyped receiver:"
+        render_tractability_summary(report)
         calls.first(TOP_CALLS).each do |call|
-          @out.puts format("  %<count>-5d #%<method>s   e.g. %<sites>s",
-                           count: call.count, method: call.method_name, sites: call.examples.join("  "))
+          label = origin_label(call.dynamic_origin)
+          @out.puts format("  %<count>-5d #%<method>s   e.g. %<sites>s%<label>s",
+                           count: call.count, method: call.method_name,
+                           sites: call.examples.join("  "), label: label)
         end
         @out.puts "  (#{calls.size - TOP_CALLS} more)" if calls.size > TOP_CALLS
       end
 
+      def render_tractability_summary(report)
+        summary = report.tractability_summary
+        return if summary.empty?
+
+        parts = summary.sort_by { |_, n| -n }.map { |axis, n| "#{n} #{axis.to_s.tr('_', '-')}" }
+        @out.puts "  by tractability: #{parts.join(' · ')}  (add-rbs = closable with a type)"
+      end
+
+      def origin_label(origin)
+        return "" if origin.nil?
+
+        tractability = Inference::DynamicOrigin.tractability(origin)
+        hint = tractability ? " → #{TRACTABILITY_HINTS[tractability]}" : ""
+        "  [#{origin.to_s.tr('_', '-')}#{hint}]"
+      end
+
       def render_files(report)
         worst = report.files.reject { |f| f.unprotected_count.zero? }.sort_by(&:ratio).first(TOP_FILES)
         return if worst.empty?

data/lib/rigor/cli/protection_report.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../inference/dynamic_origin"
+
 module Rigor
   class CLI
     # ADR-63 Tier 1 — aggregates per-file {Inference::ProtectionScanner}
@@ -9,7 +11,7 @@ module Rigor
     # untyped dispatches, where a receiver annotation buys the most catching
     # power.
     FileProtection = Data.define(:path, :protected_count, :unprotected_count, :ratio)
-    UntypedCall = Data.define(:method_name, :count, :examples)
+    UntypedCall = Data.define(:method_name, :count, :examples, :dynamic_origin)
 
     ProtectionReport = Data.define(:files, :untyped_calls, :parse_errors) do
       def total_protected = files.sum(&:protected_count)
@@ -17,17 +19,37 @@ module Rigor
       def grand_total = total_protected + total_unprotected
       def ratio = grand_total.zero? ? 1.0 : total_protected.to_f / grand_total
 
+      # ADR-73 P6 — total dispatch-site count per tractability axis across
+      # the classified holes (those with a recorded `dynamic_origin`), so a
+      # user sees at a glance how much of the untyped surface a type can
+      # actually close (`add_rbs`) vs. needs a plugin (`enable_plugin`) vs.
+      # is an engine gap. Keys are omitted when zero; an all-unclassified
+      # run yields `{}`.
+      def tractability_summary
+        untyped_calls.each_with_object(Hash.new(0)) do |c, acc|
+          axis = c.dynamic_origin && Inference::DynamicOrigin.tractability(c.dynamic_origin)
+          acc[axis] += c.count if axis
+        end
+      end
+
       def to_h
         {
           "protected" => total_protected,
           "unprotected" => total_unprotected,
           "protection_ratio" => ratio.round(4),
+          "tractability_summary" => tractability_summary.transform_keys(&:to_s),
           "files" => files.map do |f|
             { "path" => f.path, "protected" => f.protected_count,
               "unprotected" => f.unprotected_count, "ratio" => f.ratio.round(4) }
           end,
           "add_a_type_here" => untyped_calls.map do |c|
-            { "method" => c.method_name, "count" => c.count, "examples" => c.examples }
+            entry = { "method" => c.method_name, "count" => c.count, "examples" => c.examples }
+            if c.dynamic_origin
+              entry["dynamic_origin"] = c.dynamic_origin
+              tractability = Inference::DynamicOrigin.tractability(c.dynamic_origin)
+              entry["tractability"] = tractability if tractability
+            end
+            entry
           end,
           "parse_errors" => parse_errors
         }
@@ -37,7 +59,7 @@ module Rigor
     class ProtectionAccumulator
       def initialize
         @files = []
-        @calls = Hash.new { |h, k| h[k] = { count: 0, examples: [] } }
+        @calls = Hash.new { |h, k| h[k] = { count: 0, examples: [], origins: Hash.new(0) } }
         @parse_errors = []
       end
 
@@ -50,6 +72,7 @@ module Rigor
           bucket = @calls[site.method_name]
           bucket[:count] += 1
           bucket[:examples] << "#{path}:#{site.line}" if bucket[:examples].size < 3
+          bucket[:origins][site.dynamic_origin] += 1 if site.dynamic_origin
         end
       end
 
@@ -58,9 +81,12 @@ module Rigor
       end
 
       def to_report
-        untyped = @calls
-                  .map { |method, v| UntypedCall.new(method_name: method, count: v[:count], examples: v[:examples]) }
-                  .sort_by { |c| [-c.count, c.method_name] }
+        calls = @calls.map do |method, v|
+          origin = v[:origins].max_by { |_, count| count }&.first
+          UntypedCall.new(method_name: method, count: v[:count], examples: v[:examples],
+                          dynamic_origin: origin)
+        end
+        untyped = calls.sort_by { |c| [-c.count, c.method_name] }
         ProtectionReport.new(files: @files, untyped_calls: untyped, parse_errors: @parse_errors)
       end
     end

data/lib/rigor/cli/upgrade_command.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module Rigor
+  class CLI
+    # `rigor upgrade` — the ADR-50 WD7 migration command skeleton.
+    #
+    # The real body lands when a concrete backwards-compatibility break
+    # gives it a target (e.g. re-running `baseline regenerate` against a
+    # strengthened default profile, surfacing renamed suppression ids,
+    # reporting `bleeding_edge:` graduations).  Until then it prints the
+    # current version and notes that upgrade is queued.
+    class UpgradeCommand < Command
+      USAGE = "Usage: rigor upgrade [options]"
+
+      # @return [Integer] CLI exit status.
+      def run
+        @out.puts("rigor upgrade: No migration target available yet (ADR-50 WD7, queued).")
+        @out.puts("Current version: #{Rigor::VERSION}")
+        0
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -43,7 +43,9 @@ module Rigor
       "skill" => :run_skill,
       "describe" => :run_describe,
       "docs" => :run_docs,
-      "show-bleedingedge" => :run_show_bleedingedge
+      "show-bleedingedge" => :run_show_bleedingedge,
+      "doctor" => :run_doctor,
+      "upgrade" => :run_upgrade
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -317,6 +319,18 @@ module Rigor
       CLI::ShowBleedingedgeCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_doctor
+      require_relative "cli/doctor_command"
+
+      CLI::DoctorCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
+    def run_upgrade
+      require_relative "cli/upgrade_command"
+
+      CLI::UpgradeCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def help
       <<~HELP
         Usage: rigor <command> [options]
@@ -342,6 +356,8 @@ module Rigor
           skill      Recommend the next skill + list/print bundled Agent Skills (skill describe, skill <name>)
           docs       Print the bundled docs offline (docs <name>, docs --list)
           show-bleedingedge  Show the bleeding-edge overlay + what your config adopts (ADR-50)
+          doctor     Classify setup problems vs clean run with routed next actions (ADR-77)
+          upgrade    Migration command skeleton (ADR-50 WD7, queued)
           version    Print the Rigor version
           help       Print this help
       HELP

data/lib/rigor/flow_contribution/fact.rb

@@ -18,7 +18,7 @@ module Rigor
     #    (`Rigor::RbsExtended::PredicateEffect`).
     # 3. RBS::Extended `assert*` directives
     #    (`Rigor::RbsExtended::AssertEffect`).
-    # 4. Plugin contributions via `type_specifier` DSL (ADR-52).
+    # 4. Plugin contributions via `narrowing_facts` DSL (ADR-52).
     #
     # Each of those four carriers translates to / from Fact at
     # its boundary; downstream of {Rigor::FlowContribution#to_element_list}

data/lib/rigor/inference/dynamic_origin.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # ADR-75 v1 cause set — precision-additive provenance for Dynamic[T]
+    # introduction sites.  Each symbol identifies a distinct family of
+    # reason that an expression widened to Dynamic, surfaced by
+    # `rigor coverage --protection` so users can distinguish tractable
+    # holes (e.g. an explicit `untyped` RBS signature) from intractable
+    # ones (e.g. unsupported syntax).
+    #
+    # Provenance is a side-channel: it never participates in subtyping,
+    # consistency, normalization, or erasure, and no diagnostic fires
+    # from it.
+    module DynamicOrigin
+      # A gem with no resolvable RBS.
+      EXTERNAL_GEM_WITHOUT_RBS = :external_gem_without_rbs
+      # Value across macro/DSL expansion or plugin-declared dynamic return.
+      FRAMEWORK_DSL_BOUNDARY  = :framework_dsl_boundary
+      # Budget/fuel guard widened to Dynamic.
+      ANALYZER_BUDGET_CUTOFF  = :analyzer_budget_cutoff
+      # Authored `untyped` contract.
+      EXPLICIT_UNTYPED        = :explicit_untyped
+      # Inference fallback on unmodeled construct.
+      UNSUPPORTED_SYNTAX      = :unsupported_syntax
+
+      CAUSES = [
+        EXTERNAL_GEM_WITHOUT_RBS,
+        FRAMEWORK_DSL_BOUNDARY,
+        ANALYZER_BUDGET_CUTOFF,
+        EXPLICIT_UNTYPED,
+        UNSUPPORTED_SYNTAX
+      ].freeze
+
+      # ADR-73 P6 / ADR-75 WD2 — tractability: given the cause, can a user
+      # close this `Dynamic` hole, and on which axis. `coverage --protection`
+      # surfaces it so a user does not chase a hole a hand-written type
+      # cannot fix. Three coarse, action-oriented categories:
+      #
+      # - `:add_rbs`      — write or install RBS (a missing gem signature,
+      #                     or an authored `untyped` to tighten).
+      # - `:enable_plugin`— a framework / DSL boundary; needs a plugin or
+      #                     `pre_eval:`, not a hand-written type.
+      # - `:engine_gap`   — not user-closable (a budget cutoff or unmodeled
+      #                     syntax); report it.
+      ADD_RBS       = :add_rbs
+      ENABLE_PLUGIN = :enable_plugin
+      ENGINE_GAP    = :engine_gap
+
+      TRACTABILITY = {
+        EXTERNAL_GEM_WITHOUT_RBS => ADD_RBS,
+        EXPLICIT_UNTYPED => ADD_RBS,
+        FRAMEWORK_DSL_BOUNDARY => ENABLE_PLUGIN,
+        ANALYZER_BUDGET_CUTOFF => ENGINE_GAP,
+        UNSUPPORTED_SYNTAX => ENGINE_GAP
+      }.freeze
+
+      module_function
+
+      # @return [Symbol, nil] the tractability category for a cause, or nil
+      #   when the cause is unknown / absent.
+      def tractability(cause)
+        TRACTABILITY[cause]
+      end
+    end
+  end
+end

data/lib/rigor/inference/expression_typer.rb

@@ -9,6 +9,7 @@ require_relative "../analysis/self_call_resolution_recorder"
 require_relative "block_parameter_binder"
 require_relative "body_fixpoint"
 require_relative "budget_trace"
+require_relative "dynamic_origin"
 require_relative "fallback"
 require_relative "flow_tracer"
 require_relative "indexed_narrowing"
@@ -224,15 +225,20 @@ module Rigor
       def initialize(scope:, tracer: nil)
         @scope = scope
         @tracer = tracer
+        @typing_node = nil
       end
 
       def type_of(node)
-        return untraced_type_of(node) unless FlowTracer.active?
-
-        # `rigor trace` — bracket the recursion with enter/result events.
-        # The tracer is observational only: the inferred type flows
-        # through unchanged (see FlowTracer's contract).
-        FlowTracer.trace_node(node) { untraced_type_of(node) }
+        previous = @typing_node
+        @typing_node = node
+        result = if FlowTracer.active?
+                   FlowTracer.trace_node(node) { untraced_type_of(node) }
+                 else
+                   untraced_type_of(node)
+                 end
+        result
+      ensure
+        @typing_node = previous
       end
 
       def untraced_type_of(node)
@@ -1011,11 +1017,12 @@ module Rigor
 
       def fallback_for(node, family:)
         inner = dynamic_top
-        record_fallback(node, family: family, inner_type: inner)
+        record_fallback(node, family: family, inner_type: inner, origin: DynamicOrigin::UNSUPPORTED_SYNTAX)
+        scope.record_dynamic_origin(node, DynamicOrigin::UNSUPPORTED_SYNTAX)
         inner
       end
 
-      def record_fallback(node, family:, inner_type:)
+      def record_fallback(node, family:, inner_type:, origin: nil)
         return unless tracer
 
         location = node.respond_to?(:location) ? node.location : nil
@@ -1023,7 +1030,8 @@ module Rigor
           node_class: node.class,
           location: location,
           family: family,
-          inner_type: inner_type
+          inner_type: inner_type,
+          origin: origin
         )
         tracer.record_fallback(event)
       end
@@ -2128,6 +2136,7 @@ module Rigor
       # this signature's summary sees the floor, not the stale `bot` seed.
       def degrade_entangled_fixpoint(summaries, plain_signature)
         BudgetTrace.hit(BudgetTrace::RECURSION_GUARD)
+        scope.record_dynamic_origin(@typing_node, DynamicOrigin::ANALYZER_BUDGET_CUTOFF) if @typing_node
         summaries[plain_signature][:assumption] = Type::Combinator.untyped
         Type::Combinator.untyped
       end
@@ -2152,6 +2161,7 @@ module Rigor
           # Out of iterations and still unstable — collapse to today's
           # widening behaviour.
           BudgetTrace.hit(BudgetTrace::RECURSION_FIXPOINT_CAP)
+          scope.record_dynamic_origin(@typing_node, DynamicOrigin::ANALYZER_BUDGET_CUTOFF) if @typing_node
           summaries[plain_signature][:assumption] = Type::Combinator.untyped
           return Type::Combinator.untyped
         end
@@ -2244,6 +2254,7 @@ module Rigor
         return type unless would_have_been_guarded && !fully_value_pinned?(type)
 
         BudgetTrace.hit(BudgetTrace::RECURSION_GUARD)
+        scope.record_dynamic_origin(@typing_node, DynamicOrigin::ANALYZER_BUDGET_CUTOFF) if @typing_node
         # ADR-55 WD1 clamp: a guarded extended frame whose body is non-pinned
         # must be byte-identical to the plain guard's `untyped`. This path
         # deliberately does NOT route to the in-progress fixpoint summary:
@@ -2363,7 +2374,8 @@ module Rigor
           locals: locals.freeze,
           self_type: receiver,
           discovery: scope.discovery,
-          struct_fold_safe_locals: struct_fold_safe_locals_for(def_node.body)
+          struct_fold_safe_locals: struct_fold_safe_locals_for(def_node.body),
+          dynamic_origins: scope.dynamic_origins
         )
       end
 

data/lib/rigor/inference/fallback.rb

@@ -20,8 +20,8 @@ module Rigor
     # - inner_type: the Rigor::Type returned to the caller (currently
     #   always Dynamic[Top]; later slices may carry richer fallback
     #   types).
-    class Fallback < Data.define(:node_class, :location, :family, :inner_type)
-      def initialize(node_class:, location:, family:, inner_type:)
+    class Fallback < Data.define(:node_class, :location, :family, :inner_type, :origin)
+      def initialize(node_class:, location:, family:, inner_type:, origin: nil)
         raise ArgumentError, "node_class must be a Class, got #{node_class.class}" unless node_class.is_a?(Class)
 
         unless FALLBACK_FAMILIES.include?(family)

data/lib/rigor/inference/method_dispatcher/constant_folding.rb

@@ -218,11 +218,27 @@ module Rigor
         # is what ultimately limits how wide an inferred type gets.
         UNION_FOLD_OUTPUT_LIMIT = 8
 
+        # ADR-78 — reflexive over-fold guard.
+        # Reflective dispatch (`public_send` / `send` / `__send__`) must
+        # NOT constant-fold unless the method-name argument is itself a
+        # value-pinned literal `Constant[Symbol]`. With a runtime-variable
+        # method name the dispatched method is not statically determined,
+        # so the call degrades to the RBS result (`untyped`) — exactly as
+        # it does without the guard, but explicit so a later shape-carrier
+        # preservation tier (ADR-76 WD2) cannot surface an over-fold as a
+        # spurious `flow.always-truthy-condition`.
+        REFLECTIVE_SEND_METHODS = %i[public_send send __send__].to_set.freeze
+
         # @return [Rigor::Type::Constant, Rigor::Type::Union, Rigor::Type::IntegerRange, nil]
         def try_dispatch(context)
           receiver = context.receiver
           method_name = context.method_name
           args = context.args
+
+          if REFLECTIVE_SEND_METHODS.include?(method_name)
+            first_arg = args.first
+            return nil unless first_arg.is_a?(Type::Constant) && first_arg.value.is_a?(Symbol)
+          end
           # v0.0.7 — `String#%` against a `Tuple` / `HashShape`
           # argument runs Ruby's format-string engine when both
           # sides are statically constant. The standard

data/lib/rigor/inference/method_dispatcher/shape_dispatch.rb

@@ -102,7 +102,11 @@ module Rigor
           find_index: :tuple_find_index,
           rindex: :tuple_rindex,
           flatten: :tuple_flatten,
-          join: :tuple_join
+          join: :tuple_join,
+          freeze: :shape_self,
+          dup: :shape_self,
+          clone: :shape_self,
+          itself: :shape_self
         }.freeze
 
         # Byte cap on a folded `tuple.join` result — a huge tuple times a
@@ -151,7 +155,23 @@ module Rigor
           :< => :hash_compare,
           :<= => :hash_compare,
           :> => :hash_compare,
-          :>= => :hash_compare
+          :>= => :hash_compare,
+          # ADR-76 WD2 / ADR-78 WD3 — pure self-returners preserve the
+          # `HashShape` carrier instead of degrading to the nominal `Hash`
+          # via the RBS `() -> self` signature, so
+          # `MESSAGES = {…}.freeze; MESSAGES[reason]` folds the value union
+          # rather than reading `Dynamic`. `dup` / `clone` produce a fresh
+          # object, but Rigor's shape carriers are immutable values, so
+          # preserving the carrier is sound for reads; a later in-place
+          # mutation routes through `MutationWidening`. (The `Tuple` table
+          # carries the same four entries; both became safe once the
+          # block-form over-fold guard landed in `try_dispatch` — ADR-78
+          # WD1 — so `CONST = [...].freeze; CONST.any? { … }` no longer
+          # folds the no-block result and fires a reflexive always-truthy.)
+          freeze: :shape_self,
+          dup: :shape_self,
+          clone: :shape_self,
+          itself: :shape_self
         }.freeze
 
         # @return [Rigor::Type, nil] the precise element/value type, or
@@ -189,6 +209,17 @@ module Rigor
           method_name = context.method_name
           args = context.args
           args ||= []
+          # ADR-78 WD1 — every shape handler folds *no-block* semantics; none
+          # evaluates a passed block. So a block-form call (`tuple.any? { … }`,
+          # `tuple.sum { … }`, `tuple.count { … }`) must NOT fold the no-block
+          # result — doing so ignores the block (an over-fold: `any? { false }`
+          # would still fold `Constant[true]`). Declining defers to BlockFolding
+          # / RBS. This is the over-fold class the Tuple shape-carrier
+          # preservation (ADR-76 WD2) surfaced as reflexive `always-truthy` on
+          # `CONST = [...].freeze; CONST.any? { … }`; fixing it at the fold (not
+          # the rule) unblocks that preservation.
+          return nil unless context.block_type.nil?
+
           handler = RECEIVER_HANDLERS[receiver.class]
           return nil unless handler
 
@@ -236,6 +267,14 @@ module Rigor
             send(handler, shape, method_name, args)
           end
 
+          # ADR-76 WD2 / ADR-78 WD3 — a pure self-returner
+          # (`freeze` / `dup` / `clone` / `itself`) returns the receiver
+          # carrier unchanged, preserving the shape that the nominal
+          # `() -> self` RBS signature would otherwise drop.
+          def shape_self(carrier, _method_name, _args)
+            carrier
+          end
+
           def dispatch_nominal_size(nominal, method_name, args)
             projection = nominal_projection(nominal, method_name, args)
             return projection if projection

data/lib/rigor/inference/method_dispatcher.rb

@@ -6,6 +6,7 @@ require_relative "../flow_contribution"
 require_relative "../flow_contribution/merger"
 require_relative "../builtins/hkt_builtins"
 require_relative "../builtins/static_return_refinements"
+require_relative "dynamic_origin"
 require_relative "flow_tracer"
 require_relative "method_dispatcher/call_context"
 require_relative "method_dispatcher/constant_folding"
@@ -83,7 +84,7 @@ module Rigor
         result
       end
 
-      def resolve(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def resolve(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
                   block_type: nil, environment: nil,
                   call_node: nil, scope: nil)
         return nil if receiver_type.nil?
@@ -114,7 +115,12 @@ module Rigor
         # are supplied — the dispatcher's own internal callers
         # (per-element block fold, etc.) skip this tier.
         plugin_result = try_plugin_contribution(call_node, scope, receiver_type)
-        return plugin_result if plugin_result
+        if plugin_result
+          if plugin_result.is_a?(Type::Dynamic)
+            scope&.record_dynamic_origin(call_node, DynamicOrigin::FRAMEWORK_DSL_BOUNDARY)
+          end
+          return plugin_result
+        end
 
         # ADR-20 slice 3 — Rigor-bundled HKT-builtin return-
         # type tier. Sits ABOVE `RbsDispatch.try_dispatch` so
@@ -145,6 +151,9 @@ module Rigor
         rbs_result = RbsDispatch.try_dispatch(context)
         if rbs_result
           record_boundary_cross_if_applicable(receiver_type, method_name, rbs_result, environment)
+          if rbs_result.is_a?(Type::Dynamic) && rbs_result.static_facet.is_a?(Type::Top)
+            scope&.record_dynamic_origin(call_node, DynamicOrigin::EXPLICIT_UNTYPED)
+          end
           return rbs_result
         end
 
@@ -174,7 +183,10 @@ module Rigor
         # `Dynamic[top]` so the patched call resolves
         # cross-file without `call.undefined-method`.
         patched_result = try_project_patched_method(receiver_type, method_name, environment)
-        return patched_result if patched_result
+        if patched_result
+          scope&.record_dynamic_origin(call_node, DynamicOrigin::EXTERNAL_GEM_WITHOUT_RBS)
+          return patched_result
+        end
 
         # ADR-10 slice 2b-ii — dependency-source inference tier.
         # Sits BELOW RBS dispatch (RBS / RBS::Inline / generated
@@ -186,7 +198,10 @@ module Rigor
         # dynamic-origin envelope; per-method return-type
         # precision is queued for a later slice.
         dep_source_result = try_dependency_source(receiver_type, method_name, environment)
-        return dep_source_result if dep_source_result
+        if dep_source_result
+          scope&.record_dynamic_origin(call_node, DynamicOrigin::EXTERNAL_GEM_WITHOUT_RBS)
+          return dep_source_result
+        end
 
         # v0.1.3 — discovered-method dispatch tier. When the
         # receiver class has no RBS BUT scope_indexer recorded

data/lib/rigor/inference/mutation_widening.rb

@@ -102,8 +102,22 @@ module Rigor
         replace
       ].to_set.freeze
 
+      # Methods that return the receiver (or a shallow copy) and
+      # cannot mutate it. They must not trigger widening or any
+      # other receiver-fact invalidation. The list is intentionally
+      # narrow — only methods whose purity is unconditional and
+      # whose return value is the receiver itself (or a copy that
+      # leaves the original untouched).
+      PURE_SELF_RETURNERS = %i[freeze dup clone itself].freeze
+
       module_function
 
+      # True when `method_name` is a pure self-returner that must
+      # not invalidate the receiver's facts.
+      def pure_self_returner?(method_name)
+        PURE_SELF_RETURNERS.include?(method_name)
+      end
+
       # Returns a scope with the call's receiver widened, when the
       # receiver is a local-/instance-variable read whose current
       # binding is a literal-shape carrier (`Tuple` / `HashShape`)
@@ -114,6 +128,8 @@ module Rigor
       # @param current_scope [Rigor::Scope]
       # @return              [Rigor::Scope]
       def widen_after_call(call_node:, current_scope:)
+        return current_scope if pure_self_returner?(call_node.name)
+
         receiver = call_node.receiver
         return current_scope if receiver.nil?
 
@@ -181,6 +197,8 @@ module Rigor
       end
 
       def widen_for_outer_receiver(call_node, scope)
+        return scope if pure_self_returner?(call_node.name)
+
         receiver = call_node.receiver
         return scope if receiver.nil?
 

data/lib/rigor/inference/protection_scanner.rb

@@ -19,7 +19,7 @@ module Rigor
     # (does a diagnostic fire) is the phased mutation tier.
     class ProtectionScanner
       # A single unprotected call site.
-      Site = Data.define(:line, :receiver, :method_name)
+      Site = Data.define(:line, :receiver, :method_name, :dynamic_origin)
 
       FileResult = Data.define(:protected_count, :unprotected_count, :sites) do
         def total = protected_count + unprotected_count
@@ -43,14 +43,17 @@ module Rigor
         Source::NodeWalker.each(root) do |node|
           next unless dispatch_site?(node)
 
-          receiver_type = index[node.receiver].type_of(node.receiver)
+          scope = index[node.receiver]
+          receiver_type = scope.type_of(node.receiver)
           if concrete_receiver?(receiver_type)
             protected_count += 1
           else
+            origin = scope.dynamic_origins[node.receiver]
             sites << Site.new(
               line: node.location.start_line,
               receiver: safe_describe(receiver_type),
-              method_name: node.name.to_s
+              method_name: node.name.to_s,
+              dynamic_origin: origin
             )
           end
         end